[docs] Re: on makefiles

[Andriy Dobrovol's'kii]

Vitaly Ostanin wrote:
> 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/>
> 
Исключительно поддерживаю последнюю мысль. :))

-- 
Rgrds,
Andriy
*********************************************************************
email: dobr at iop dot kiev dot ua            Kyiv, Ukraine
Phone: (380-44)   265-7824            Department of Gas Electronics
Fax:   (380-44)   265-2329             Institute of Physics of NASU
*********************************************************************