[docs] current makefiles again (was: Tuning and profiling)

[Oleg A. Paraschenko]

  Привет!

  Уже утро, а письмо до рассылки всё ещё не дошло. Посылаю повторно;

-----

On Tue, 2 Dec 2003 18:10:17 +0300
Vitaly Ostanin <vyt на vzljot.ru> wrote:

...
> > 
> >   Ок, готов. Начать отрывать?
> 
> Тебе виднее, когда начать, но в итоге лучше оторвать :) Спасибо.

  Насколько я понял, ты сейчас тоже работаешь над make-файлами. Чтобы не
возникло конфликтных изменений, я бы хотел дождаться, когда у тебя будет
логический конец, код в cvs и пауза на пару дней.


> > > 
> > > Зависимость вида
> > > %.xinclude: %.xml
> > > накладывает лишние ограничения на имя документа и имя файла
> > > после объединения.
> > 
> >   А именно, что тут лишнее?
> 
> Не будет работать
> make DOCUMENT_NAME=article.docbook

  Будет. "article.docbook.xinclude" будет зависеть от article.docbook.xml.

> 
> Будет сложно переписывать правила везде, где используется
> прибитое гвоздями расширение .xinclude

  С этим согласен. Но надо же в какой-то момент переставать делать
косвенные ссылки и писать явно что от чего зависит. Мне кажется, что
замена ".xinclude" на "$(xinclude)" ничего не даёт.

> 
> Да, Makefiles переписывались для сборки с учётом зависимостей, но
> причём тут тотальная шаблонность? Мы же не проект на С собираем с
> тучей файлов.

  Думаю, что стили написания смешивать нехорошо. Результат будет
объединять недостатки как одного, так и другого подхода.

> 
> > > Почему нельзя воспользоваться зависимостями через переменные
> > > $(XINCLUDED): $(XML)
> > > , как это было сделано в make2 ?
> > 
> >   $(XINCLUDED) и $(XML) зависят от $(DOCUMENT_ROOT).
> >   Соответственно,
> > получается единственное правило.
> > 
> >   %.xinclude: %.xml может раскрываться в несколько правил,
> >   например:
> > 
> > xxx.xinclude: xxx.xml
> > sdfjhk.xinclude:  sdfjhk.xml
> > allother.xinclude:  allother.xml
> > enough.xinclude: enough.xml
> > 
> >   Соответственно, в варианте с % можно говорить:
> > 
> > $ make tmp/xxx.xinclude tmp/sect2.xinclude tmp/sect2.xinclude
> 
> Цель этой команды?

  Собрать с помощью xinclude несколько файлов, находящихся в одном
каталоге.

  Да, в alt docs на каждый текстовый модуль свой каталог. Но зачем делать
это принципиальным ограничением?

> 
> >   или хотя бы
> > 
> > $ make tmp/sect1.xinclude
> > 
> >   совершенно не заботясь об установке DOCUMENT_ROOT.
> 
> Имеется в виду переменная DOCUMENT_NAME ? О её установке и так не
> нужно заботиться.

  В том случае, если имя файла совпадает с именем каталога.

  Хочу заметить, что обратная ситуация вполне возможна. Допустим, в
каталоге"xxx" есть файл "xxx.xml", и я хочу временно внести исправления в
"xxx.xml". Чтобы не править по живому, я создаю копию "tmp.xml".

> 
> > > Зачем в doc-template оставлены неиспользуемые Makefiles ?
> > 
> >   А что именно лишнее? 
> 
> Makefile.html-dir, возможно, и другие - я не разобрался.

  И действительно. Видимо, пропустил при удалении неиспользуемых файлов.
Исправил.

> 
> > Кроме того, проверь, на всякий случай
> >   свой
> > doc-template:
> > 
> > $ pwd
> > .../doc-template
> > $ cvs status
> > 
> >   "Sticky Tag" и "Sticky Date" должны быть "(none)".
> 
> Так и есть.
> 
> > > По поводу недавних дебатов на тему litprog. Я сейчас смотрю
> > > на новые makefiles и думаю, ну вот чем скудные комментарии на
> > > английском лучше, чем litprog ?
> > 
> >   Тем, что комментариев должно быть в меру. Например, в Си,
> > комментарий к коду:
> > 
> > while(*dst++ = *src++);
> > 
> >   должен выглядеть так (если вообще нужен): "copy string", но
> >   не должен
> > описывать, что такое указатели, ++ и '\0'.
> 
> В наших комментариях не стандартизированный синтаксис, так что
> аналогия неуместна.

  Я предположил, что основные трудности со значками "%", "$<", "$*"
и подобными, поэтому привёл именно такую аналогию.

> 
> Возможно, это окажется единственное IMHO, но мне сложно, неудобно
> и долго разбираться в текущих Makefiles.
> 

> Я не вижу смысла писать комментарии на английском для
> русскоязычных коллег,

  Может быть, я слишком пуганая ворона, но мой подход: в программах все
символы (в том числе и комментарии) должны укладываться в ASCII.

> и даже русский текст в koi8 (вероятно) на
> системе в cp1251 нечитаем. См. Makefile.pstricks

  А уж русский язык тем более не должен присутствовать, ибо
koi8 vs cp1251 vs cp866. Кстати, а почему для alt docs выбрана
кодировка windows?

> 
> Да, я знаю про подходы "в программе всё написано",

  Не так. Описание работы программы -- это, несомненно, нормальное
человеческое описание (напоминаю про
http://xmlhack.ru/tmp/alt/makefiles/makefiles-html-dir/).
Но детали реализации -- это "в программе всё написано" и ни в коем случае
не внешнее описание.

> "есть
> перекодировщики" и т.п.
> 
> <skipped/>
> 
> -- 
> Regards, Vyt
> mailto:  vyt на vzljot.ru
> JID:     vyt на vzljot.ru

-- 
Oleg