[docs] Re: on makefiles

[Vitaly Ostanin]

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

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

Кроме урезания документации tuning может быть разным из-за разных
параметров прореживания одинаковых <ulink/>, удаления
<revhistory/> и т.п.

А поддержку 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. Вот туда я хотел ещё добавить дату
модификации исходного документа.

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

Если Вы это сделаете, можно закоммитить.

Однако:

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

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

- tuned-сборка занимает много времени только на больших
  документах, которые мало кто собирает, да и то не часто.

>   Теперь про basename == dirname. В данный момент имя файла для
>   генерации должно совпадать с именем папки, в которой он
>   лежит. Это принципиальное решение или просто так получилось?

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

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

Наверное, нужно. Когда-то нужно переходить на шаблонную схему.
Каюсь, Антон Бояршинов уже делал такое для печатного вывода, а я
сломал :(

> $ make fo
> 
>   обработает все xml-файлы в текущей папке.

Зачем? В cvs каждый документ должен быть в отдельном подкаталоге,
его одного и нужно собирать.

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

Если есть веские причины переименовать, давайте переименуем.

<skipped/>

-- 
Regards, Vyt
mailto:  vyt на vzljot.ru
JID:     vyt на vzljot.ru
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : отсутствует
Тип     : application/pgp-signature
Размер  : 189 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20030926/84efd12c/attachment.bin