[docs] Re: Literate programming for Makefiles

[Oleg A. Paraschenko]

  Привет!

On Tue, 4 Nov 2003 17:56:35 +0300
Vitaly Ostanin <vyt на vzljot.ru> wrote:

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

  Во, ещё придумал:

* Я люблю делать завершённые вещи. #-Комментарии внутри make -- завершённые вещи. LP-комментарии -- нет. Их надо "компилировать". А если при этом make-файл ещё невалиден и ничего не собирается?

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

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

  Одна из целей LP и состоит в том, чтобы программист вначале всё-таки сформулировал, а только потом писал.

> 
> <skipped/>
> 
> > > Так вот, javadoc (TeX, LaTeX, html и т.п.) в качестве
> > > исходного формата для разметки документации я обсуждать не
> > > буду.
> > 
> >   А зря. В данном случае наворачивать не стоит.
> 
> Я уже писал - если два дополнительных тега litprog и
> необходимость предварительной сборки Makefile сильно усложняют
> жизнь - пишите просто Makefile и комментарии в plain text, я
> добавлю в litprog.
> 
> Makefile не так уж часто будут меняться. А вот для понимания
> процесса сборки нормальная дока по ним была бы нелишней.

  Для понимания процесса нужна внешняя по отношению к самим make-файлам дока. 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 без подсветки можно утонуть.

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

  Видимо, да.

> 
> <skipped/>
> 
> -- 
> Regards, Vyt
> mailto:  vyt на vzljot.ru
> JID:     vyt на vzljot.ru


-- 
Oleg