[docs] Re: on makefiles

Пн Сен 29 15:42:30 MSD 2003

On Mon, 29 Sep 2003 15:21:24 +0400
Oleg A.Paraschenko <olpa на xmlhack.ru> wrote:

>   Привет!
> 
> On Mon, 29 Sep 2003 11:15:33 +0400
> Vitaly Ostanin <vyt на vzljot.ru> wrote:
> 
> ...
> > > 
> > >   Поэтому предлагаю завести что-нибудь простое для
> > >   упорядочивания "коллективного знания", хотя бы, например,
> > >   какой-нибудь WiKi. И это даже не предложение, а
> > >   утверждение, которое вскоре получит default owner
> > >   продукта "4. Docs" багзиллы.
> > 
> > Я не видел ни одного wiki, который бы упорядочивал
> > информацию.
> 
>   Один точно есть. Только он не публичный.

Под "wiki" я подразумеваю средство для массового заполнения типа:
http://docbook.org/wiki/moin.cgi/
именно массовость и отсутствие ограничений на структурирование
приведут к свалке. IMHO.

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

Тогда больше подходит термин "draft".

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

Первое возможно практически и даже известно конкретное место,
куда его положить.

> > В данном конретном случае устарела моя дока.
> > 
> > >   В частности, эта система позволит улучшить комментарии.
> > >   Они достаточно хорошие, но описывают только что и как
> > >   сделано, но не объясняют, зачем. 
> > 
> > Да, это действительно неудобно. Когда читаешь специ w3c, тоже
> > возникает вопрос "а зачем?".
> > 
> > Логику Makefiles можно также описывать в docbook.
> 
>   Увы, я в это не верю.

Просто потому, что пока не сделано на практике :) На самом деле
спасибо Вам огромное за очередной позыв к действию - будут
описания, обязательно. Надеюсь, что скоро.

<skipped/>

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

Нужно, чтобы попинать авторов exsl:node-set() на обновление.

<skipped/>

> > Можно патч сюда прислать, или выложить на 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' не требует обновления.

Спасибо! А можно логику описать? Хотя бы в комментариях. "FORCE:"
- это зарезервированное имя цели, или просто пустая цель?

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

Понравилось :)

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

Ок. См. отдельным тредом про cvs branches.

<skipped/>

>   Да, это верно, экономии времени не будет. Остаётся аргумент
>   из области
> "нравится/не нравится". По-моему, после успешного выполнения
> 
> $ make target,
> 
>   немедленный повторный запуск "make targer" не должен
>   приводить к повторной
> сборке. Иначе как-то это некрасиво.

Согласен. Тогда давайте придерживаться шаблонной схемы Makefiles
вместе с использованием зависимостей. А если нужно что-то
пересобрать, есть make clean.

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

IMHO, это не то соглашение, про которое можно забывать. А для
проверки есть make check.

> > Тех. редактору даже удобно - зашёл в каталог и сразу
> > видно, кто тут главный XML :)
> 
>   Наверное, да.

Кстати, ещё сильно помогает при поиске опечаток во включения
XInclude. Я уж не говорю про удобство модульной разработки:
один документ (картинки, база olink) - один каталог.
один поддокумент (--//--) - один подкаталог.

<skipped/>

> > > > Зачем? В cvs каждый документ должен быть в отдельном
> > > > подкаталоге, его одного и нужно собирать.
> > > 
> > >   Такое ограничение мне кажется неочевидным и достаточно
> > >   искусственным.
> > 
> > Агрументы "за" я приводил. Аргументы "против" ?
> 
>   Только один. Если есть какие-то ограничения, то они должно
>   быть явными и очевидными. Иначе будут проблемы.

Я опишу в документации.

<skipped/>

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