[docs] Re: on makefiles

Vitaly Ostanin vyt на vzljot.ru
Пн Сен 29 17:33:19 MSD 2003


On Mon, 29 Sep 2003 17:32:05 +0400
Oleg A.Paraschenko <olpa на xmlhack.ru> wrote:

<skipped/>

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

Возможно.

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

Совсем правильный вариант - literate programming
http://nwalsh.com/docs/articles/xml2002/lp/paper.html

Реальный вариант - я пишу draft'ы в каталоге ~/devel,
определившиеся с местом выкладываю в ~/devel/docs :)

> > >   Во вложении: 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).

Я, собственно, не спорю :)

> > Хотя бы в комментариях. "FORCE:"
> > - это зарезервированное имя цели, или просто пустая цель?
> 
>   А ещё я знаю слова ".PHONY", ".PRECIOUS" и вообще хочу
>   когда-нибудь найти время на полное прочтение спецификации на
>   make. Про FORCE:

Ясно.

Итого:

Я против массового wiki и за улучшение актуальности документации
в cvs docs.

<skipped/>

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


Подробная информация о списке рассылки docs