[docs] Re: on makefiles

[Oleg A.Paraschenko]

  Привет!

On Mon, 29 Sep 2003 11:15:33 +0400
Vitaly Ostanin <vyt на vzljot.ru> wrote:

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

  Один точно есть. Только он не публичный.

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

  Не всякая информация должна идти в документы. WiKi (под этим подразумевается что угодно) служит своеобразным фильтром и черновиком, в то время как финальный документ -- это выжимка и руководство к действию.

  В качестве примера (первое, что попалось) предлагаю рассмотреть ULINK_LEAVE. Оцените время на описание этого параметра (зачем оно, кто что предложил другого, почему отказались) в виде финального документа, а затем оцените время на то, чтобы накидать копии писем без правки орфографии и пунктуации, а также краткие комментарии на страницу 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.

  Во вложении: Makefile.tuned. 

$ make -n docs-howto.xml-tuned.1
xsltproc --nonet --xinclude --stringparam tag-level1 article  --stringparam tag-level2 section -o docs-howto.xml-tuned.1 \
--param ulink.leave.duplicates.after 1 \
--param revhistory.strip 1 \
../../../xsl/common/tuning.xsl docs-howto.xml
$
$ make CACHETUNED=yes -n docs-howto.xml-tuned.1
make: `docs-howto.xml-tuned.1' не требует обновления.

  Если понравится, то могу взять на себя:

<quote>[Про поддержку profiling в Makefile]
В будущем точно понадобится. Точнее, он уже сейчас нужен, но пока
не настолько, чтобы им заняться.
</quote>

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

  Да, это верно, экономии времени не будет. Остаётся аргумент из области
"нравится/не нравится". По-моему, после успешного выполнения

$ make target,

  немедленный повторный запуск "make targer" не должен приводить к повторной
сборке. Иначе как-то это некрасиво.

> 
> > > >   Теперь про 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


  Пока!

--
Олег
----------- следущая часть -----------
Было удалено вложение не в текстовом формате...
Имя     : Makefile.tuned
Тип     : application/octet-stream
Размер  : 710 байтов
Описание: отсутствует
Url     : /pipermail/docs/attachments/20030929/8a065548/Makefile.obj