[docs] Re: on makefiles

[Oleg A.Paraschenko]

  Всем привет,

  при дальнейшем изучении make-файлов мне показалось, что ответы на вопросы теряются в рассылке. Глядя на код, я смутно вспоминаю, что видел его обсуждение в рассылке, но копаться в архивах нет никакого желания.

  Поэтому предлагаю завести что-нибудь простое для упорядочивания "коллективного знания", хотя бы, например, какой-нибудь WiKi. И это даже не предложение, а утверждение, которое вскоре получит default owner продукта "4. Docs" багзиллы.

  В частности, эта система позволит улучшить комментарии. Они достаточно хорошие, но описывают только что и как сделано, но не объясняют, зачем. Эту проблему решает ссылка на страницу с пояснениями, почему это сделано так а не иначе, какие мнения были, на какие жертвы пришлось пойти и т.д.

On Fri, 26 Sep 2003 17:15:09 +0400
Vitaly Ostanin <vyt на vzljot.ru> wrote:

> On Fri, 26 Sep 2003 16:42:01 +0400
> Oleg A.Paraschenko <olpa на xmlhack.ru> wrote:
> 
> >   Здравствуйте,
> > 
> >   я сейчас разбираюсь с системой make-файлов и хочу поговорить
> >   о
> > 
> > * цели "tuned";
> > * basename == dirname.
> > 
> >   Все конечные цели проходят через этап "tuned", который из
> >   файла "xxx.xml" создаёт "xxx.xml-tuned.1". Проблема в том,
> >   что этот шаг достаточно ресурсоёмок и результат не
> >   кешируется. После выполнения, например,
> 
> tuned не повторяется только при запуске нескольких целей сразу
> make html-dir pdf
> 
> Это ограничение исторически сложившейся нешаблонной схемы
> Makefile. Я тогда не разобрался с шаблонной :(
> 
> Однако делать кеширование tuned-файлов (IMHO) пока рано - сначала
> нужно сделать работающую поддержку profiling:
> http://docbook.sourceforge.net/release/xsl/current/doc/tools/profiling.html

  А что, есть проблемы? В этом документе говорится: <quote>If you are using XSL stylesheets version 1.50 and later with EXSLT enabled XSLT processor (Saxon, xsltproc, Xalan) you can do profiling and transformation to HTML or FO in a single step.</quote> Так что profiling можно делать на этапе преобразования из docbook.

> 
> Уже как-то был разговор о том, что нужно в печатную версию
> включать урезанный вариант документации. Поэтому tuned-документы
> могут отличаться для печатного и html-вывода.
> 
> Кроме урезания документации tuning может быть разным из-за разных
> параметров прореживания одинаковых <ulink/>, удаления
> <revhistory/> и т.п.

  Почему это пришлось поместить в tuning, а не в stylesheet customization, я спрошу потом.

> 
> А поддержку profiling в Makefile до сих пор не сделали, потому
> что она пока никому серьёзно не понадобилась (есть мой древний
> вариант для psi, но он не гибкий).

  Значит, и не надо делать.

> 
> > $ make fo
> > xsltproc --nonet --xinclude --stringparam tag-level1 book 
> > --stringparam tag-level2 part --stringparam tag-level3 chapter
> > -o admin.xml-tuned.1 \...,
> > 
> >   повторное задания этой цели:
> > 
> > $ make -n fo
> > xsltproc --nonet --xinclude --stringparam tag-level1 book 
> > --stringparam tag-level2 part --stringparam tag-level3 chapter
> > -o admin.xml-tuned.1 \...
> > 
> >   приводит к повторной генерации, а не к сообщению о том, что
> >   всё уже собрано.
> > 
> >   По-моему, это неправильно. Я понимаю, что принудительное
> >   кеширование невозможно из-за XInclude (хотя и это можно
> >   побороть с помощью своего make depends), 
> 
> Побороть можно. Я уже пытался сделать подобное в стилях для
> website.
> 
> Для этого нужно:
> 
> 1.
> Указывать дату коммита в самом документе
> <pubdate>$Date$</pubdate>.
> 
> 2.
> При обработке дерева, собранного из XInclude определять, какой
> <pubdate/> относится к какому физическому файлу. Для этого можно
> использовать @xml:base, но будет работать только для документов в
> разных каталогах (у нас так и есть).
> Можно ещё использоваться расширения xslt-процессора для
> определения даты изменения файла, однако cvs $Date$ мне кажется
> более авторитетным :)

  Это уже технические детали, хотя и увлекательные.

> 
> Кстати, обратите внимание на <abbr/> в копирайте на
> docs.altlinux.ru/beta. Вот туда я хотел ещё добавить дату
> модификации исходного документа.

  Это полезная штука. На самом деле, очень правильно в выходной документ (если не финальная версия) вставлять $Id$ всех входящих данных. Снимает кучу вопросов (а вы не забыли обновиться из CVS?)

> 
> >   но предусмотреть что-нибудь типа
> > 
> > $ make CACHETUNED=true <target>
> > 
> >   не помешало бы. Кому-нибудь ещё это надо?
> 
> Если Вы это сделаете, можно закоммитить.

  Сделал. Однако, permission denied, поэтому коммит будет через багзиллу и default owner.

> 
> Однако:
> 
> - Ваша схема может быть сломана при создании схемы profiling.

  Я думаю, что в следующей версии make-файлов будет сломано много чего.

> 
> - в make нет кеширования, он смотрит на даты изменения
>   source и destination файлов.

  А сейчас он ни на что не смотрит.

> Сейчас source/destination
>   (шаблонная) сборка в cvs docs используется только для website.
> 
> - tuned-сборка занимает много времени только на больших
>   документах, которые мало кто собирает, да и то не часто.

  И действительно. Просто после прочтения архива я решил, что все эксперименты надо проводить на "admin.xml".

  В любом случае, меня расстраивает использование make-файлов как урезанных bash-скриптов.

> 
> >   Теперь про basename == dirname. В данный момент имя файла для
> >   генерации должно совпадать с именем папки, в которой он
> >   лежит. Это принципиальное решение или просто так получилось?
> 
> И историческое, и принципиальное. Исторически это было сделано
> для включения не через XInclude, а через SGML entity, а
> принципиально из-за того, что документ может состоять из
> нескольких XML-файлов в одном каталоге (например, docs-howto) и
> нужно как-то определять, кого из них собирать.

  В таком случае можно указать список входных файлов явно.

> 
> >   Если нужно, я могу переписать make-файлы так, что
> > 
> > $ make print/xxx.fo
> > 
> >   будет создавать fo-файл из xxx.xml, а
> 
> Наверное, нужно. Когда-то нужно переходить на шаблонную схему.
> Каюсь, Антон Бояршинов уже делал такое для печатного вывода, а я
> сломал :(

  Ладно, пока работает, обратно ломать не будем.

> 
> > $ make fo
> > 
> >   обработает все xml-файлы в текущей папке.
> 
> Зачем? В cvs каждый документ должен быть в отдельном подкаталоге,
> его одного и нужно собирать.

  Такое ограничение мне кажется неочевидным и достаточно искусственным.

> 
> >   Кстати, мне кажется, что наши make-файлы надо называть не
> >   "Makefile", а "GNUmakefile".
> 
> Если есть веские причины переименовать, давайте переименуем.

  Веских причин нет, просто мне показалось, что make от bsd откажется работать с такими файлами.

> 
> <skipped/>
> 
> -- 
> Regards, Vyt
> mailto:  vyt на vzljot.ru
> JID:     vyt на vzljot.ru

-- 
Олег