[docs] Re: Literate programming for Makefiles

[Vitaly Ostanin]

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 до получения готовых
результатов.

Я понял аргумент про рекурсивный идеализм, но это не тот случай
:)

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

Не понял.

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

Сможет, добавив это что-то в Makefile и прислав в рассылку
уведомление об этом. Если два тега нашего litprog - <alt:doc/> и
<alt:code/> - требуют осознания ;), я добавлю описание в
Makefile.litprog самостоятельно.

Кстати, подразумевается, что автор Makefile для DocBook имеет
представление о DocBook хотя бы в пределах <para/>.

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

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

Кстати, прототипы я делал так: писал 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>

А как отсюда выдирать теги?

PS Прошу остальных участников docs@ тоже высказываться. Мы с
Олегом уже и лично общались :)

<skipped/>

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