[docs] Re: on makefiles

Пн Сен 29 11:15:33 MSD 2003

On Fri, 26 Sep 2003 23:06:16 +0400
Oleg A.Paraschenko <olpa на xmlhack.ru> wrote:

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

Я не видел ни одного wiki, который бы упорядочивал информацию.
Лучше задавать такие конкретные вопросы и вешать на них баги,
чтобы не забывали добавлять в документы.

В данном конретном случае устарела моя дока.

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

Да, это действительно неудобно. Когда читаешь специ w3c, тоже
возникает вопрос "а зачем?".

Логику Makefiles можно также описывать в docbook.

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

<skipped/>

> > Однако делать кеширование 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.

xsltproc не поддерживает single pass profiling, т.к. реализует
ровно ту функциональность, которая описана в
http://www.exslt.org/exsl/functions/node-set/index.html

В стилях docbook с какого-то момента для обработки ссылок стали
использовать key() вместо id(). Логика ключей в exsl:node-set()
не определена и в xsltproc не работает.

В рассылке
xsl-list на lists.mulberrytech.com
предлагали дополнить определение exsl:node-set() на эту тему, был
сделан запрос на exsl.org, но результата почему-то нет.

То, что в saxon ключи внутри переменных работают, является
дополнением saxon.

Я добавлю в docs-howto информацию об этом со ссылками на
обсуждения (надо поискать в архивах).

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

Уже сейчас могу сказать, что из-за потребности в прореживании в
разных выводах.

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

В будущем точно понадобится. Точнее, он уже сейчас нужен, но пока
не настолько, чтобы им заняться.

<skipped/>

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

Можно патч сюда прислать, или выложить на web, если размер письма
больше 40Kb.

> > Однако:
> > 
> > - Ваша схема может быть сломана при создании схемы profiling.
> 
>   Я думаю, что в следующей версии make-файлов будет сломано
>   много чего.

Скорее всего :)

> > - в make нет кеширования, он смотрит на даты изменения
> >   source и destination файлов.
> 
>   А сейчас он ни на что не смотрит.
> 
> > Сейчас source/destination
> >   (шаблонная) сборка в cvs docs используется только для
> >   website.
> > 
> > - tuned-сборка занимает много времени только на больших
> >   документах, которые мало кто собирает, да и то не часто.
> 
>   И действительно. Просто после прочтения архива я решил, что
>   все эксперименты надо проводить на "admin.xml".
> 
>   В любом случае, меня расстраивает использование make-файлов
>   как урезанных bash-скриптов.

Чтобы использовать его возможности отслеживания зависимостей
сборки, нужно обрабатывать исходные документы в поиске этих
зависимостей, как Вы и предлагаете.

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

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

Зачем? Чем мешает обязательное совпадение имени документа с
каталогом? Тех. редактору даже удобно - зашёл в каталог и сразу
видно, кто тут главный XML :)

<skipped/>

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

Агрументы "за" я приводил. Аргументы "против" ?

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

Я знаю пример использования наших Makefiles на freebsd, насколько
я знаю - успешный. Правда, gnu make на win32 с такими файлами
отказывается работать, но это проблемы win32 и bsd :)

<skipped/>

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