[docs] Re: Literate programming for Makefiles

[Oleg A. Paraschenko]

  Привет!

On Tue, 4 Nov 2003 16:36:26 +0300
Vitaly Ostanin <vyt на vzljot.ru> wrote:

> On Tue, 4 Nov 2003 15:59:55 +0300
> "Oleg A. Paraschenko" <olpa на xmlhack.ru> wrote:
> 
> >   Привет!
> > 
> >   Идея, конечно, во всём этом есть, но я бы посоветовал
> >   отказаться от "описательного программирования" для Makefiles.
> > 
> > --
> > 
> >   При разработке ПО, кроме основного процесса, есть
> >   поддерживающие процессы (разработка ПО vs использование CVS,
> >   написание документации vs использование CMS для неё и т.д.). 
> >   Я обычно стараюсь придерживаться следующего подхода. Основная
> >   ветка должна быть вылизана, всё, что мешает -- должно быть
> >   уничтожено, кривости -- переделаны. Но любые попытки доводить
> >   до блеска поддерживающие процессы должны пресекаться.
> >   Работает -- и ладно. Такая своеобразная "бритва Оккама" для
> >   проектов.
> 
> До блеска ещё далеко, и он не самоцель. Цель litprog -
> поддерживаемость кода и док в актуальном состоянии. Это важно для
> любых процессов, в том числе и вспомогательных.
> 
> >   В данном случае, основной процесс -- это написание
> >   документации. Написание make-файлов -- поддерживающий процесс
> >   и должен быть сведён к минимуму. Описательное
> >   программирование (ОП) будет поддерживающим процессом
> >   поддерживающего процесса. А учитывая, что ОП тоже надо
> >   довести до логического завершения, то намечается
> >   поддерживающий процесс поддерживающего процесса
> >   поддерживающего процесса. Это не дело.
> 
> ОП уже работает и серьёзно меняться не будет. Да, неплохо бы
> доку по litprog, но её не будет - достаточно статей Уолша (и
> Кнута, кстати) на эту тему и простых примеров разметки.
> 
> Я специально не выкладывал litprog в cvs до получения готовых
> результатов.
> 
> Я понял аргумент про рекурсивный идеализм, но это не тот случай
> :)

  Самый что ни на есть. За то время, которое мы уже потратили на Makefiles, можно было написать k док и сделать m скриншотов, а также улучшить passivetex.

> 
> > --
> > 
> > Какая документация нужна на make? Думаю, примерно такая:
> > 
> > * для технического писателя (того, кто будет всё это
> > использовать);* для разработчика make-файлов, высокоуровневая
> > -- понять, что к чему;* для разработчика make-файлов,
> > низкоуровневая -- детали.
> > 
> > Вытаскивание Makefile, хотя бы и с комментариями, не является
> > ни одним из этих типов.
> 
> Не понял.

  Что даст наличие в документации красивых make-файлов с комментариями тому, кто задаётся вопросом "а что мне с этим делать?" или "а как работают make-файлы?". Кажется, ничего.

> 
> > --
> > 
> > Предположим, что некто хочет добавить что-то в Makefile, но не
> > хочет разбираться в сущностях (literate programming). Сможет ли
> > он сделать это? Может быть и да, но я бы забил.
> 
> Сможет, добавив это что-то в Makefile и прислав в рассылку
> уведомление об этом. Если два тега нашего litprog - <alt:doc/> и
> <alt:code/> - требуют осознания ;), я добавлю описание в
> Makefile.litprog самостоятельно.
> 
> Кстати, подразумевается, что автор Makefile для DocBook имеет
> представление о DocBook хотя бы в пределах <para/>.

  Вот это как раз хуже всего. Потому что незнакомый с DocBook человек будет писать <para/> и не мучиться, а знакомый -- начнёт задумываться, а есть ли <alt:make-target/>, <alt:make-variable/> и т.д, а кому-то это захочется сделать.

> 
> > --
> > 
> > А как настроить подстветку синтаксиса в моём любимом vim?
> 
> Научить :) Я ничего не знаю про vim - в emacs я переключаю режимы
> редактирования - makefile-mode/nxml-mode.

  Что переключать можно, это понятно. Интересует одновременная подсветка. Как когда php в html -- рассвечивается и то, и другое.

> 
> Кстати, прототипы я делал так: писал Makefile, отлаживал, и
> переносил в Makefile.litprog с описанием.

  Вот-вот. А надо наоборот. Вначале надо написать для человека, что происходит, затем ввести код, скомпилировать, и только тогда начать отлаживать код.

> 
> > --
> > 
> > Тем не менее, идея правильная. Более того, у меня есть
> > комментарии, которые я бы не прочь вставить как в сам
> > make-файл, так и в документацию. Но, может быть, проще? В стиле
> > javadoc?
> 
> Есть разные подходы в litprog (насколько я неправильно понял :)):
> 
> 1.
> Прямое использование источника litprog в качестве кода (javadoc).
> 
> 2.
> Прямое использование источника litprog в качестве док (DocBook
> TDG).
> 
> 3. 
> Предварительная обработка источника litprog и для кода, и для док
> (то, что сейчас в ветке "make2" cvs docs).
> 
> Есть ещё вариант прямого использования litprog сразу и для док, и
> для кода, но он годится только для XML-языков, из которых пока
> есть только XSLT. И этот вариант не позволяет варьировать видом
> документации, например, вставлять код в виде листингов.
> 
> Так вот, javadoc (TeX, LaTeX, html и т.п.) в качестве исходного
> формата для разметки документации я обсуждать не буду.

  А зря. В данном случае наворачивать не стоит.

> 
> А вот 1. был бы удобен, но не представляю его на практике.
> 
> > ...
> > # non-doc comment
> > ## <para>... comment for docs ...</para>
> 
> А как отсюда выдирать теги?

Примерно так (не проверил):

echo '<makedoc>'
cat Makefile | grep '^##' | sed '/s/^## /'
echo '</makedoc>'

> 
> PS Прошу остальных участников docs@ тоже высказываться. Мы с
> Олегом уже и лично общались :)
> 
> <skipped/>
> 
> -- 
> Regards, Vyt
> mailto:  vyt на vzljot.ru
> JID:     vyt на vzljot.ru


-- 
Олег