[docs] Literate programming for Makefiles

[Oleg A. Paraschenko]

  Привет!

  Идея, конечно, во всём этом есть, но я бы посоветовал отказаться от "описательного программирования" для Makefiles.

--

  При разработке ПО, кроме основного процесса, есть поддерживающие процессы (разработка ПО vs использование CVS, написание документации vs использование CMS для неё и т.д.).  Я обычно стараюсь придерживаться следующего подхода. Основная ветка должна быть вылизана, всё, что мешает -- должно быть уничтожено, кривости -- переделаны. Но любые попытки доводить до блеска поддерживающие процессы должны пресекаться. Работает -- и ладно. Такая своеобразная "бритва Оккама" для проектов.

  В данном случае, основной процесс -- это написание документации. Написание make-файлов -- поддерживающий процесс и должен быть сведён к минимуму. Описательное программирование (ОП) будет поддерживающим процессом поддерживающего процесса. А учитывая, что ОП тоже надо довести до логического завершения, то намечается поддерживающий процесс поддерживающего процесса поддерживающего процесса. Это не дело.

--

Какая документация нужна на make? Думаю, примерно такая:

* для технического писателя (того, кто будет всё это использовать);
* для разработчика make-файлов, высокоуровневая -- понять, что к чему;
* для разработчика make-файлов, низкоуровневая -- детали.

Вытаскивание Makefile, хотя бы и с комментариями, не является ни одним из этих типов.

--

Предположим, что некто хочет добавить что-то в Makefile, но не хочет разбираться в сущностях (literate programming). Сможет ли он сделать это? Может быть и да, но я бы забил.

--

А как настроить подстветку синтаксиса в моём любимом vim?

--

Тем не менее, идея правильная. Более того, у меня есть комментарии, которые я бы не прочь вставить как в сам make-файл, так и в документацию. Но, может быть, проще? В стиле javadoc?

...
# non-doc comment
## <para>... comment for docs ...</para>
...

-->

<makedoc>
...
<para>... comment for docs ...</para>
...
</makedoc>
 
--
Олег

On Tue, 4 Nov 2003 12:20:30 +0300
Vitaly Ostanin <vyt на vzljot.ru> wrote:

> Hello, All!
> 
> Вместе с переделкой Makefiles в cvs docs (для использования
> сборки по зависимостям) я сделал прототипы "описательного
> программирования" для Makefiles.
> 
> Суть "описательного программирования" (literate programming, в
> дальнейшем - litprog) описана в статьях
> http://nwalsh.com/docs/articles/dbdesign/#litprog
> http://nwalsh.com/docs/articles/xml2002/lp/paper.html
> 
> Вкратце - это написание документации рядом с кодом, для
> последующей генерации (или прямого использования) документации и
> кода из одного источника.
> 
> Прототипы лежат в ветке "make2", $CVSROOT/docs/doc-template,
> и в аттаче (второго нет, он неинтересный) :)
> 
> Пока в litprog переписаны только
> Makefile.default-variables.litprog и Makefile.xinclude.litprog
> 
> Стиль для генерации документации из них лежит в
> $CVSROOT/xsl/common/litprog.xsl
> 
> Для генерации кода Makefiles сделан дополнительный
> makefile.makefile
> 
> Пересобрать Makefiles можно запуском
> make -f makefile.makefile all
> 
> Пример включения сгенерированной документации можно посмотреть на
> http://people.altlinux.ru/~vyt/temp/docs-howto-html-dir/ar01s04.html
> 
> Это только пример, там нет общего описания схемы Makefiles для
> сборки по зависимостям, но это только начало :) Нам нужно такое
> начало?
> 
> Есть предложение использовать такие litprog makefiles в HEAD
> проекта.
> 
> -- 
> Regards, Vyt
> mailto:  vyt на vzljot.ru
> JID:     vyt на vzljot.ru


-- 
Oleg Paraschenko  olpa@ http://xmlhack.ru/  XML news in Russian