[docs] Re: Literate programming for Makefiles

[Vitaly Ostanin]

On Tue, 4 Nov 2003 17:14:34 +0300
"Oleg A. Paraschenko" <olpa на xmlhack.ru> wrote:

<skipped/>

> > >   В данном случае, основной процесс -- это написание
> > >   документации. Написание make-файлов -- поддерживающий
> > >   процесс и должен быть сведён к минимуму. Описательное
> > >   программирование (ОП) будет поддерживающим процессом
> > >   поддерживающего процесса. А учитывая, что ОП тоже надо
> > >   довести до логического завершения, то намечается
> > >   поддерживающий процесс поддерживающего процесса
> > >   поддерживающего процесса. Это не дело.
> > 
> > ОП уже работает и серьёзно меняться не будет. Да, неплохо бы
> > доку по litprog, но её не будет - достаточно статей Уолша (и
> > Кнута, кстати) на эту тему и простых примеров разметки.
> > 
> > Я специально не выкладывал litprog в cvs до получения готовых
> > результатов.
> > 
> > Я понял аргумент про рекурсивный идеализм, но это не тот
> > случай:)
> 
>   Самый что ни на есть. За то время, которое мы уже потратили
>   на Makefiles, можно было написать k док и сделать m
>   скриншотов, а также улучшить passivetex.

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

Кстати, время, потраченное лично мною на создание
Makefiles.litprog съэкономит (кстати, как это слово правильно
пишется?) лично мне время на описание Makefiles в docs-howto.

А кому-то, возможно, сократит время ковыряния в потрохах
Makefiles.

Сравнивать это время с количеством док или скриншотов, по-моему,
неправильно.

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

В документации, кроме красивых 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/> и т.д, а кому-то это захочется сделать.

Кому захочется - вправе задуматься :) Чем это плохо?

Серьёзно, чем litprog плох? Мешает? Сложен? Ну так пишите
простые Makefile - но их описания должны быть в любом случае, и
они будут вставлены в документацию.

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

Я же сказал, что ничего не знаю про vim. Если мне понадобится это
в emacs, я залезу в доку и поищу что-нибудь на предмет смешивания
major modes.

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

Можно и так - дело вкуса. На практике программист не всегда
сразу может сформулировать, что происходит :)

<skipped/>

> > Так вот, javadoc (TeX, LaTeX, html и т.п.) в качестве
> > исходного формата для разметки документации я обсуждать не
> > буду.
> 
>   А зря. В данном случае наворачивать не стоит.

Я уже писал - если два дополнительных тега litprog и
необходимость предварительной сборки Makefile сильно усложняют
жизнь - пишите просто Makefile и комментарии в plain text, я
добавлю в litprog.

Makefile не так уж часто будут меняться. А вот для понимания
процесса сборки нормальная дока по ним была бы нелишней.

> > А вот 1. был бы удобен, но не представляю его на практике.
> > 
> > > ...
> > > # non-doc comment
> > > ## <para>... comment for docs ...</para>
> > 
> > А как отсюда выдирать теги?
> 
> Примерно так (не проверил):
> 
> echo '<makedoc>'
> cat Makefile | grep '^##' | sed '/s/^## /'
> echo '</makedoc>'

Такая схема ещё больше усложнит подсветку синтаксиса одновременно
для DocBook и Makefile.

А как писать параграф, если он содержит 150 символов? В одну
строку? Писать комментарии на русском, придерживаясь
закомментированного объявления XML ? Странно как-то.

<skipped/>

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