[docs] Re: Literate programming for Makefiles

[Vitaly Ostanin]

On Tue, 4 Nov 2003 20:24:54 +0300
"Oleg A. Paraschenko" <olpa на xmlhack.ru> wrote:

>   Привет!
> 
> On Tue, 4 Nov 2003 17:56:35 +0300
> Vitaly Ostanin <vyt на vzljot.ru> wrote:
> 
> ...
> > 
> > Время потрачено для приведения Makefiles к схеме сборки по
> > зависимостям. В том, что в процессе приведения встал вопрос
> > документирования, нет ничего удивительного.
> > 
> > Кстати, время, потраченное лично мною на создание
> > Makefiles.litprog съэкономит (кстати, как это слово правильно
> > пишется?) лично мне время на описание Makefiles в docs-howto.
> > 
> > А кому-то, возможно, сократит время ковыряния в потрохах
> > Makefiles.
> 
>   Да, но это относится к любой документации. Пояснения с
>   помощью обычных #-комментариев ничем не хуже.

Хуже - всем тем, чем plain text хуже XML. И соответственно лучше.

Для документирования XML предпочтительнее комментариев.

<skipped/>

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

Пусть начнётся, каждый сходит с ума по своему :) 

> > Серьёзно, чем litprog плох?
> 
> > Мешает?
> 
>   Да.

Конкретнее - только необходимостью предварительной сборки
Makefiles? Это перевешивается качеством документирования и
редкостью их обновления.

> > Сложен?
> 
>   Нет. В данном случае -- многословен.

Это не критично.

> > Ну так пишите
> > простые Makefile - но их описания должны быть в любом случае,
> > и они будут вставлены в документацию.
> 
>   Во, ещё придумал:
> 
> * Я люблю делать завершённые вещи. #-Комментарии внутри make --
> завершённые вещи. LP-комментарии -- нет. 

Хорошо, собери все комментарии в удобоваримом виде и вставь в
описание работы наших Makefiles. На XML это тривиально.

> Их надо
> "компилировать". А если при этом make-файл ещё невалиден и
> ничего не собирается?

Исправить. В компилировании нет ничего нового.

> * успех php, perl и других basic'ов в том, что как написал --
> так сразу и проверил. В варианте с LP надо вначале
> "компилировать".

Для кода. В варианте без LP тоже придётся компилировать - для
док.

Лучше не ударяться в дебри обсуждений "компилируемые языки vs
интерпретируемые" :)

<skipped/>

> > >   Вот-вот. А надо наоборот. Вначале надо написать для
> > >   человека, что происходит, затем ввести код,
> > >   скомпилировать, и только тогда начать отлаживать код.
> > 
> > Можно и так - дело вкуса. На практике программист не всегда
> > сразу может сформулировать, что происходит :)
> 
>   Одна из целей LP и состоит в том, чтобы программист вначале
>   всё-таки сформулировал, а только потом писал.

Не совсем. Программист должен писать на человеческом языке,
описать логику, и рядом эту логику закодировать в программу.

Жёсткий порядок здесь нереален - и письма пишутся,
перечитываются, потом исправляются и отсылаются.

Короче, это не предмет для обсуждения - каждый пишет, как ему
удобнее, лишь бы результат был качественным.

<skipped/>

> > Makefile не так уж часто будут меняться. А вот для понимания
> > процесса сборки нормальная дока по ним была бы нелишней.
> 
>   Для понимания процесса нужна внешняя по отношению к самим
>   make-файлам дока. LP тут ничем не поможет. 

Будет, согласен, и уже про это писал. Насчёт LP у меня другое
мнение.

> > > > А вот 1. был бы удобен, но не представляю его на
> > > > практике.
> > > > 
> > > > > ...
> > > > > # non-doc comment
> > > > > ## <para>... comment for docs ...</para>
> > > > 
> > > > А как отсюда выдирать теги?
> > > 
> > > Примерно так (не проверил):
> > > 
> > > echo '<makedoc>'
> > > cat Makefile | grep '^##' | sed '/s/^## /'
> > > echo '</makedoc>'
> > 
> > Такая схема ещё больше усложнит подсветку синтаксиса
> > одновременно для DocBook и Makefile.
> 
>   Неа. В этом случае можно спокойно оставаться в подсветке для
>   make. Ибо добавить <para/> в комментарии -- не проблема. А
>   вот в супе из тегов в XML LP без подсветки можно утонуть.

Можно, можно и не тонуть. Подстветка синтаксиса здесь вообще
offtopic - повторяю, можно забыть про LP и им не пользоваться,
никто не заставляет. 

Если в конце концов окажется, что он в Makefiles никому не нужен,
то он уже нужен мне для docs-howto и мне не трудно его
поддерживать во всех Makefiles.

<skipped/>

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