added asciidoc support

2012-10-31 01:21:23 +04:00 · 2012-10-31 01:21:23 +04:00 · 85217cd11d
commit 85217cd11d
parent 301a13a015
25 changed files with 430 additions and 226 deletions
--- a/Makefile.asciidoc
+++ b/Makefile.asciidoc
@ -0,0 +1,31 @@
+PROJECT = mkimage-profiles
+TOPLEVEL_DOC = mkimage-profiles.asciidoc
+HTMLPAGE = $(TOPLEVEL_DOC:.asciidoc=.html)
+RESOURCE_FILES = /etc/asciidoc/
+
+A2X = a2x
+
+.PHONY: all clean
+
+all: $(HTMLPAGE)
+
+%.html: %.asciidoc
+	$(A2X) -d book -f xhtml -a lang=ru \
+	  --icons -r $(RESOURCE_FILES) -r ./ \
+	  --xsltproc-opts='--stringparam toc.max.depth 3' \
+	  $<
+
+chunked: $(TOPLEVEL_DOC)
+	$(A2X) -d book -f chunked -a lang=ru \
+	  --icons -r /etc/asciidoc/ -r ./ \
+	  --xsltproc-opts='--stringparam toc.max.depth 3' \
+	  $<
+
+pdf: $(TOPLEVEL_DOC)
+	$(A2X) --verbose --fop --fop-opts='-c fop.xconf' -d book -f pdf -a lang=ru \
+	  --xsltproc-opts=' \
+	  --stringparam toc.max.depth 3 \
+	  --stringparam title.font.family "Arial" \
+	  --stringparam body.font.family "Verdana" \
+	  --stringparam monospace.font.family "Arial"' \
+	  $<
--- a/95
+++ b/95
@ -1,69 +1,76 @@
-Welcome to mkimage-profiles!
+[float]
+=== Welcome to mkimage-profiles! ===

-Configurables: ~/.mkimage/profiles.mk;
-see doc/params.txt and conf.d/README
+  Configurables: ~/.mkimage/profiles.mk;
+  see doc/params.txt and conf.d/README

-License: GPLv2+, see COPYING
+  License: GPLv2+, see COPYING

-Most docs are in Russian, welcome to learn it or ask for English.
+  Most docs are in Russian, welcome to learn it or ask for English.

 Задача:
- конфигурирование и создание образов на базе ALT Linux
+
+* конфигурирование и создание образов на базе ALT Linux

 Концепция:
- конфигурация, как и образ -- объект постадийной сборки
- метапрофиль служит репозиторием для построения индивидуального
+
+* конфигурация, как и образ -- объект постадийной сборки
+* метапрофиль служит репозиторием для построения индивидуального
  профиля, по которому создаётся итоговый образ

 Особенности:
- метапрофиль может быть полностью read-only при сборке
- для сборки подыскивается предпочтительно tmpfs
- в профиль копируются только нужные объекты;
+
+* метапрофиль может быть полностью read-only при сборке
+* для сборки подыскивается предпочтительно tmpfs
+* в профиль копируются только нужные объекты;
  он автономен относительно метапрофиля

 Стадии работы:
- инициализация сборочного профиля
- сборка конфигурации образа
- наполнение сборочного профиля
- сборка образа
+
+* инициализация сборочного профиля
+* сборка конфигурации образа
+* наполнение сборочного профиля
+* сборка образа

 Объекты:
- дистрибутивы и виртуальные среды/машины:
-  + описываются в conf.d/*.mk или соответственно lib/{distro,ve,vm}.mk
-  + могут основываться на предшественниках, расширяя их
-  + дистрибутивы также:
-    - включают один или более субпрофилей по надобности
-  + желательно избегать множественного наследования, см. тж. фичи
- субпрофили:
-  + список собирается в $(SUBPROFILES)
-  + базовые комплекты помещены в подкаталогах под sub.in/;
+
+* дистрибутивы и виртуальные среды/машины:
+** описываются в conf.d/*.mk или соответственно lib/{distro,ve,vm}.mk
+** могут основываться на предшественниках, расширяя их
+** дистрибутивы также:
+*** включают один или более субпрофилей по надобности
+** желательно избегать множественного наследования, см. тж. фичи
+* субпрофили:
+** список собирается в $(SUBPROFILES)
+** базовые комплекты помещены в подкаталогах под sub.in/;
    их наборы скриптов могут расширяться фичами
- фичи:
-  + законченные блоки функциональности (или наборы таковых)
-  + описываются в индивидуальных features.in/*/config.mk
-  + могут требовать другие фичи, а также субпрофили
-  + накопительный список собирается в $(FEATURES)
-  + при сборке $(BUILDDIR) содержимое фич добавляется в профиль
- списки пакетов (*_LISTS):
-  + просьба по возможности избегать дублирования (см. bin/pkgdups)
- индивидуальные пакеты (*_PACKAGES): см. тж. conf.d/README
+* фичи:
+** законченные блоки функциональности (или наборы таковых)
+** описываются в индивидуальных features.in/*/config.mk
+** могут требовать другие фичи, а также субпрофили
+** накопительный список собирается в $(FEATURES)
+** при сборке $(BUILDDIR) содержимое фич добавляется в профиль
+* списки пакетов (*_LISTS):
+** просьба по возможности избегать дублирования (см. bin/pkgdups)
+* индивидуальные пакеты (*_PACKAGES): см. тж. conf.d/README

 Результат:
- при успешном завершении сборки образ называется по имени цели
+
+* при успешном завершении сборки образ называется по имени цели
  и укладывается в $(IMAGEDIR):
-  + указанный явно,
-  + либо ~/out/ (если возможно),
-  + или $(BUILDDIR)/out/ иначе
- формируются отчёты, если запрошены (REPORT)
+** указанный явно,
+** либо ~/out/ (если возможно),
+** или $(BUILDDIR)/out/ иначе
+* формируются отчёты, если запрошены (REPORT)

 См. тж.:
- http://altlinux.org/m-p
- doc/:
-  + params.txt: переменные, указываемые при запуске сборки
-  + pkglists.txt: формирование состава образа
-  + features.txt: обзор подключаемых особенностей
+
+* http://altlinux.org/m-p
+* doc/:
+** params.txt: переменные, указываемые при запуске сборки
+** pkglists.txt: формирование состава образа
+** features.txt: обзор подключаемых особенностей

 Удачи; что не так -- пишите.

-- 
 Michael Shigorin <mike@altlinux.org>
--- a/README.asciidoc
+++ b/README.asciidoc
@ -0,0 +1,14 @@
+== Генерация документации == 
+
+Необходимые пакеты:
+apt-get install asciidoc-a2x xmlgraphics* fonts-ttf-ms
+Внимание! Пакеты весьма увесисты (около гигабайта), имейте ввиду.
+
+Для генерации текущей документации посредством ASCIIDOC выполнить:
+для pdf-версии
+  make -f Makefile.asciidoc -d pdf
+для html-версии
+  make -f Makefile.asciidoc -d
+
+Сгенерируются соответственно mkimage-profiles.pdf или mkimage-profiles.html
+Опция -d для детального вывода, необязательна.
--- a/conf.d/README
+++ b/conf.d/README
@ -1,3 +1,4 @@
+== conf.d ==
 Этот каталог содержит включаемые фрагменты конфигурации образов с тем,
 чтобы было удобнее параллельно разрабатывать специфические дистрибутивы
 и VE без излишних merge conflict'ов.
--- a/doc/assumptions.txt
+++ b/doc/assumptions.txt
@ -1,44 +1,46 @@
-предположения фрагментов кода об окружении
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*Предположения фрагментов кода об окружении*
+
 NB: пути приводятся от верхнего уровня; проект в целом предполагает
 ALT Linux 6.0+ и GNU make 3.81 (на которых и разрабатывается),
 но может быть портирован вместе с mkimage.

- lib/report.mk
-  + ожидает, что каждая подлежащая трассированию цель каждого
+* lib/report.mk
+** ожидает, что каждая подлежащая трассированию цель каждого
    makefile при сборке конфигурации образа содержит непустой
    recipe -- хотя бы "; @:" -- т.к. зависит от запуска $(SHELL)
-  + характерный признак пропуска -- разрыв графа (report-targets.png)
+** характерный признак пропуска -- разрыв графа (report-targets.png)

- pkg.in/lists/Makefile
-  + ожидает, что названия пакаджлистов указываются в переменных
+* pkg.in/lists/Makefile
+** ожидает, что названия пакаджлистов указываются в переменных
    вида *_LISTS, и копирует в генерируемый профиль только их
-  + если задать имя файла пакаджлиста непосредственно в Makefile
+** если задать имя файла пакаджлиста непосредственно в Makefile
    субпрофиля, он не будет скопирован
-  + характерное сообщение об ошибке:
+** характерное сообщение об ошибке:
+
    E: Couldn't find package

- features.in/stage2/stage1/scripts.d/02-kdefault
- features.in/stage2/stage1/scripts.d/03-test-kernel
- sub.in/stage1/Makefile
-  + ожидают, что в stage1 попадёт строго одно ядро сообразно
+* features.in/stage2/stage1/scripts.d/02-kdefault
+* features.in/stage2/stage1/scripts.d/03-test-kernel
+* sub.in/stage1/Makefile
+** ожидают, что в stage1 попадёт строго одно ядро сообразно
    явному указанию в STAGE1_KFLAVOUR (либо последнее указанное
    в KFLAVOURS)
-  + если добавить какой-либо kernel-image в STAGE1_PACKAGES*,
+** если добавить какой-либо kernel-image в STAGE1_PACKAGES*,
    результат может быть неожиданным
-  + вероятная ошибка: незагрузка полученного squashfs
+** вероятная ошибка: незагрузка полученного squashfs

- features.in/install2/install2/stage2cfg.mk
- features.in/live/live/stage2cfg.mk
- features.in/rescue/rescue/stage2cfg.mk
- features.in/syslinux/cfg.in/15live.cfg
- features.in/syslinux/cfg.in/20install2.cfg
- features.in/syslinux/cfg.in/80rescue.cfg
- features.in/syslinux/scripts.d/20-propagator-ramdisk
-  + ожидают, что названия squashfs-образов второй стадии инсталятора,
+* features.in/install2/install2/stage2cfg.mk
+* features.in/live/live/stage2cfg.mk
+* features.in/rescue/rescue/stage2cfg.mk
+* features.in/syslinux/cfg.in/15live.cfg
+* features.in/syslinux/cfg.in/20install2.cfg
+* features.in/syslinux/cfg.in/80rescue.cfg
+* features.in/syslinux/scripts.d/20-propagator-ramdisk
+** ожидают, что названия squashfs-образов второй стадии инсталятора,
    livecd и спасательной системы соответственно altinst, live и rescue

- image.in/Makefile
-  + ожидает, что конфигурация будет в distcfg.mk (см. тж. lib/profile.mk),
+* image.in/Makefile
+** ожидает, что конфигурация будет в distcfg.mk (см. тж. lib/profile.mk),
    а лог сборки -- в build.log (см. тж. lib/log.mk); альтернативой было
    бы пробрасывание переменных с полным путём ради единственного места
--- a/doc/debug.txt
+++ b/doc/debug.txt
@ -1,20 +1,20 @@
-ловля плюх
-~~~~~~~~~~
+== Ловля плюх ==
+
 При отладке сборки конфигурации или самого дистрибутива
 могут оказаться полезными следующие средства:

- build/distcfg.mk
-  + формируется автоматически в процессе построения конфигурации;
-  + содержит трассировочную информацию (откуда что взялось);
-  + этот файл применяется как авторитетный конфигурационный
+* build/distcfg.mk
+** формируется автоматически в процессе построения конфигурации;
+** содержит трассировочную информацию (откуда что взялось);
+** этот файл применяется как авторитетный конфигурационный

- build/build.log
-  + подробность зависит от значения переменной DEBUG,
+* build/build.log
+** подробность зависит от значения переменной DEBUG,
    которую можно передать при запуске make (см. params.txt);
-  + содержит коммит, из которого происходит сборка, и признак
+** содержит коммит, из которого происходит сборка, и признак
    "грязности" рабочего каталога при наличии модификаций после
    этого коммита;
-  + содержит список конфигурационных переменных и их конечных значений,
+** содержит список конфигурационных переменных и их конечных значений,
    созданный на основании distcfg.mk (см. тж. build/vars.mk)

 Общая информация по отладке сборки профилей mkimage:
--- a/doc/features.txt
+++ b/doc/features.txt
@ -1,5 +1,5 @@
-фичи
-~~~~
+== Фичи ==
+
 Особенности дистрибутива, не учитываемые в пакетной базе
 или зависящие от переменных времени сборки/установки образа;
 по необходимости влияют на конфигурацию, приносят с собой
--- a/doc/params.txt
+++ b/doc/params.txt
@ -1,116 +1,117 @@
-переменные make
-~~~~~~~~~~~~~~~
+== Переменные make ==
+
 При запуске на сборку принимается ряд переменных
 (см. тж. profiles.mk.sample):

- APTCONF
-  + задаёт путь к требуемому apt.conf
-  + значение: пусто (по умолчанию системный) либо строка
-  + см. ../image.in/Makefile, apt.conf.sample
+* APTCONF
+** задаёт путь к требуемому apt.conf
+** значение: пусто (по умолчанию системный) либо строка
+** см. ../image.in/Makefile, apt.conf.sample

- ARCH
-  + задаёт целевую архитектуру образов
-  + значение: пусто (по умолчанию авто), i586, x86_64, arm, ppc
-  + см. ../lib/build.mk
+* ARCH
+** задаёт целевую архитектуру образов
+** значение: пусто (по умолчанию авто), i586, x86_64, arm, ppc
+** см. ../lib/build.mk

- ARCHES
-  + задаёт набор целевых архитектур при параметрическом задании APTCONF
-  + значение: пусто (по умолчанию авто) либо список через пробел
-  + см. ../Makefile, profiles.mk.sample
+* ARCHES
+** задаёт набор целевых архитектур при параметрическом задании APTCONF
+** значение: пусто (по умолчанию авто) либо список через пробел
+** см. ../Makefile, profiles.mk.sample

- BELL
-  + подаёт сигнал после завершения сборки
-  + значение: пусто (по умолчанию нет) либо любая строка
-  + см. ../lib/build.mk
+* BELL
+** подаёт сигнал после завершения сборки
+** значение: пусто (по умолчанию нет) либо любая строка
+** см. ../lib/build.mk

- BUILDDIR
-  + задаёт каталог генерируемого профиля и сборки
-  + значение: пусто (по умолчанию авто) либо строка
-  + см. ../lib/profile.mk
+* BUILDDIR
+** задаёт каталог генерируемого профиля и сборки
+** значение: пусто (по умолчанию авто) либо строка
+** см. ../lib/profile.mk

- BUILDDIR_PREFIX
-  + задаёт префикс каталога генерируемого профиля и сборки
-  + значение: строка; по умолчанию выбирается алгоритмически
-  + см. ../main.mk
+* BUILDDIR_PREFIX
+** задаёт префикс каталога генерируемого профиля и сборки
+** значение: строка; по умолчанию выбирается алгоритмически
+** см. ../main.mk

- BUILDLOG
-  + задаёт путь к файлу журнала сборки/очистки
-  + значение: по умолчанию $(BUILDDIR)/build.log либо строка
-  + см. ../lib/log.mk
+* BUILDLOG
+** задаёт путь к файлу журнала сборки/очистки
+** значение: по умолчанию $(BUILDDIR)/build.log либо строка
+** см. ../lib/log.mk

- CHECK
-  + включает режим проверки сборки конфигурации (без сборки образа)
-  + значение: пусто (по умолчанию) либо любая строка
-  + см. ../lib/build.mk, ../lib/clean.mk
+* CHECK
+** включает режим проверки сборки конфигурации (без сборки образа)
+** значение: пусто (по умолчанию) либо любая строка
+** см. ../lib/build.mk, ../lib/clean.mk

- CLEAN
-  + экономия RAM+swap при сборке в tmpfs, иначе места на диске
-  + очистка рабочего каталога после успешной сборки очередной стадии
-  + может помешать использовать некоторые варианты отладки
-  + значение: любая строка; по умолчанию пусто при DEBUG, иначе 1
-  + см. ../lib/clean.mk
+* CLEAN
+** экономия RAM+swap при сборке в tmpfs, иначе места на диске
+** очистка рабочего каталога после успешной сборки очередной стадии
+** может помешать использовать некоторые варианты отладки
+** значение: любая строка; по умолчанию пусто при DEBUG, иначе 1
+** см. ../lib/clean.mk

- DEBUG
-  + включает средства отладки, может отключить зачистку после сборки
-  + значение: пусто (по умолчанию), 1 или 2
-  + см. ../lib/log.mk, ../lib/clean.mk
+* DEBUG
+** включает средства отладки, может отключить зачистку после сборки
+** значение: пусто (по умолчанию), 1 или 2
+** см. ../lib/log.mk, ../lib/clean.mk

- HOMEPAGE, HOMENAME, HOMEWAIT
-  + указывают адрес, название и таймаут перехода для домашней страницы
-  + значение: корректный URL, строка, целое неотрицательное число
-  + см. ../features.in/live/generate.mk (тж. по умолчаниям)
+* HOMEPAGE, HOMENAME, HOMEWAIT
+** указывают адрес, название и таймаут перехода для домашней страницы
+** значение: корректный URL, строка, целое неотрицательное число
+** см. ../features.in/live/generate.mk (тж. по умолчаниям)

- ISOHYBRID
-  + включает постобработку ISO-образа isohybrid
-  + значение: пусто (по умолчанию) либо любая строка
-  + см. ../features.in/pack/config.mk
+* ISOHYBRID
+** включает постобработку ISO-образа isohybrid
+** значение: пусто (по умолчанию) либо любая строка
+** см. ../features.in/pack/config.mk

- NICE
-  + понижает нагрузку системы сборочной задачей
-  + значение: пусто (по умолчанию) либо любая строка
-  + см. ../lib/build.mk
+* NICE
+** понижает нагрузку системы сборочной задачей
+** значение: пусто (по умолчанию) либо любая строка
+** см. ../lib/build.mk

- REPORT
-  + запрашивает создание отчётов о собранном образе
-  + значение: пусто (по умолчанию) либо любая строка
-  + NB: в силу специфики обработки передаётся только явно
-  + см. ../Makefile, ../report.mk, ../lib/report.mk
+* REPORT
+** запрашивает создание отчётов о собранном образе
+** значение: пусто (по умолчанию) либо любая строка
+** NB: в силу специфики обработки передаётся только явно
+** см. ../Makefile, ../report.mk, ../lib/report.mk

- ROOTPW
-  + устанавливает пароль root по умолчанию для образов виртуальных машин
-  + значение: пусто (по умолчанию root) либо строка
-  + см. ../features.in/build-vm/image-scripts.d/00root
+* ROOTPW
+** устанавливает пароль root по умолчанию для образов виртуальных машин
+** значение: пусто (по умолчанию root) либо строка
+** см. ../features.in/build-vm/image-scripts.d/00root

- SAVE_PROFILE
-  + сохраняет архив сгенерированного профиля в .disk/
-  + значение: пусто (по умолчанию) либо любая строка
-  + см. ../image.in/Makefile
+* SAVE_PROFILE
+** сохраняет архив сгенерированного профиля в .disk/
+** значение: пусто (по умолчанию) либо любая строка
+** см. ../image.in/Makefile

- SORTDIR
-  + дополнительно структурирует каталог собранных образов
-  + значение: пусто (по умолчанию) либо строка
-    - например, '$(IMAGE_NAME)/$(DATE)'
-  + см. ../image.in/Makefile
+* SORTDIR
+** дополнительно структурирует каталог собранных образов
+** значение: пусто (по умолчанию) либо строка
+*** например, '$(IMAGE_NAME)/$(DATE)'
+** см. ../image.in/Makefile

- SQUASHFS
-  + определяет характер сжатия squashfs для stage2
-  + значение:
-    - пусто (по умолчанию) либо normal: xz
-    - tight: xz с -Xbcj по платформе (лучше, но дольше -- подбор в два прохода)
-    - fast: gzip/lzo (быстрее запаковывается и распаковывается, меньше степень)
-  + см. ../features.in/stage2/stage1/scripts.d/03-test-kernel
+* SQUASHFS
+** определяет характер сжатия squashfs для stage2
+** значение:
+*** пусто (по умолчанию) либо normal: xz
+*** tight: xz с -Xbcj по платформе (лучше, но дольше -- подбор в два прохода)
+*** fast: gzip/lzo (быстрее запаковывается и распаковывается, меньше степень)
+** см. ../features.in/stage2/stage1/scripts.d/03-test-kernel

- STATUS
-  + добавляет в имя образа указанный префикс
-  + значение:
-    - пусто (по умолчанию) либо строка (например, "alpha", "beta")
-  + см. ../image.in/Makefile
+* STATUS
+** добавляет в имя образа указанный префикс
+** значение:
+*** пусто (по умолчанию) либо строка (например, "alpha", "beta")
+** см. ../image.in/Makefile

- VM_SIZE
-  + задаёт размер несжатого образа виртуальной машины в байтах
-  + значение: пусто (по умолчанию двойной размер чрута) или целое
-  + см. ../features.in/build-vm/lib/90-build-vm.mk, ../bin/tar2vm
+* VM_SIZE
+** задаёт размер несжатого образа виртуальной машины в байтах
+** значение: пусто (по умолчанию двойной размер чрута) или целое
+** см. ../features.in/build-vm/lib/90-build-vm.mk, ../bin/tar2vm

-пример
-~~~~~~
-make DEBUG=1 CLEAN=1 distro/syslinux.iso
+[float]
+=== пример ===
+
+  make DEBUG=1 CLEAN=1 distro/syslinux.iso
--- a/doc/pkglists.txt
+++ b/doc/pkglists.txt
@ -1,50 +1,50 @@
-списки пакетов
-~~~~~~~~~~~~~~
+== Списки пакетов ==
+
 Состав пакетной базы субпрофилей определяется значенями
 следующих переменных профиля (см. тж. ../conf.d/README):

- main: пакетная база для установки
-  + sub.in/main/Makefile, features.in/*/main/lib/*.mk
-  + THE_LISTS, BASE_LISTS, MAIN_LISTS
-  + THE_GROUPS, MAIN_GROUPS
-  + THE_PACKAGES, BASE_PACKAGES, MAIN_PACKAGES,
+* main: пакетная база для установки
+** sub.in/main/Makefile, features.in/*/main/lib/*.mk
+** THE_LISTS, BASE_LISTS, MAIN_LISTS
+** THE_GROUPS, MAIN_GROUPS
+** THE_PACKAGES, BASE_PACKAGES, MAIN_PACKAGES,
    SYSTEM_PACKAGES, COMMON_PACKAGES
-  + THE_PACKAGES_REGEXP, BASE_PACKAGES_REGEXP, MAIN_PACKAGES_REGEXP
-  + THE_KMODULES, BASE_KMODULES, MAIN_KMODULES, BASE_KMODULES_REGEXP
-    - KFLAVOURS
+** THE_PACKAGES_REGEXP, BASE_PACKAGES_REGEXP, MAIN_PACKAGES_REGEXP
+** THE_KMODULES, BASE_KMODULES, MAIN_KMODULES, BASE_KMODULES_REGEXP
+*** KFLAVOURS

- stage2: общая часть installer, live, rescue
-  + sub.in/stage2/Makefile, features.in/*/stage2/lib/*.mk
-  + SYSTEM_PACKAGES, STAGE2_PACKAGES
-  + STAGE1_KMODULES, STAGE1_KMODULES_REGEXP,
+* stage2: общая часть installer, live, rescue
+** sub.in/stage2/Makefile, features.in/*/stage2/lib/*.mk
+** SYSTEM_PACKAGES, STAGE2_PACKAGES
+** STAGE1_KMODULES, STAGE1_KMODULES_REGEXP,
    STAGE2_KMODULES, STAGE2_KMODULES_REGEXP
-    - STAGE1_KFLAVOUR или последний из KFLAVOURS
+*** STAGE1_KFLAVOUR или последний из KFLAVOURS

- installer: компактная "живая" система, содержащая только инсталятор
-  + см. stage2
-  + features.in/install2/install2/stage2cfg.mk,
+* installer: компактная "живая" система, содержащая только инсталятор
+** см. stage2
+*** features.in/install2/install2/stage2cfg.mk,
    features.in/*/install2/lib/*.mk
-  + INSTALL2_PACKAGES
+*** INSTALL2_PACKAGES

- live: пользовательский LiveCD (может содержать также инсталятор)
-  + см. stage2
-  + features.in/live/live/stage2cfg.mk,
+* live: пользовательский LiveCD (может содержать также инсталятор)
+** см. stage2
+** features.in/live/live/stage2cfg.mk,
    features.in/*/live/lib/*.mk
-  + THE_LISTS, LIVE_LISTS
-  + THE_GROUPS, LIVE_GROUPS
-  + THE_PACKAGES, LIVE_PACKAGES, COMMON_PACKAGES
-  + THE_PACKAGES_REGEXP, LIVE_PACKAGES_REGEXP
-  + THE_KMODULES, LIVE_KMODULES
+** THE_LISTS, LIVE_LISTS
+** THE_GROUPS, LIVE_GROUPS
+** THE_PACKAGES, LIVE_PACKAGES, COMMON_PACKAGES
+** THE_PACKAGES_REGEXP, LIVE_PACKAGES_REGEXP
+** THE_KMODULES, LIVE_KMODULES

- rescue: спасательный LiveCD
-  + см. stage2
-  + features.in/rescue/rescue/stage2cfg.mk
-  + RESCUE_PACKAGES, COMMON_PACKAGES
-  + RESCUE_LISTS
+* rescue: спасательный LiveCD
+** см. stage2
+** features.in/rescue/rescue/stage2cfg.mk
+** RESCUE_PACKAGES, COMMON_PACKAGES
+** RESCUE_LISTS

- stage1: ядро и загрузчик второй стадии
-  + sub.in/stage1/Makefile, features.in/*/stage1/lib/*.mk
-  + STAGE1_PACKAGES, SYSTEM_PACKAGES
-  + STAGE1_PACKAGES_REGEXP
-  + STAGE1_KMODULES_REGEXP
-    - STAGE1_KFLAVOUR или последний из KFLAVOURS
+* stage1: ядро и загрузчик второй стадии
+** sub.in/stage1/Makefile, features.in/*/stage1/lib/*.mk
+** STAGE1_PACKAGES, SYSTEM_PACKAGES
+** STAGE1_PACKAGES_REGEXP
+** STAGE1_KMODULES_REGEXP
+*** STAGE1_KFLAVOUR или последний из KFLAVOURS
--- a/doc/qemu.txt
+++ b/doc/qemu.txt
@ -1,3 +1,5 @@
+== QEMU ==
+
 Для сборки на "неродной" архитектуре с применением трансляции
 посредством QEMU установите пакет livecd-qemu-arch и выполните
 команду register-qemu-arm от имени root (также предоставляется
--- a/doc/style.txt
+++ b/doc/style.txt
@ -1,5 +1,5 @@
-требования по оформлению кода
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+== Требования по оформлению кода ==
+
 * постарайтесь не вносить без обсуждения разнобой стилей,
  если есть предметные пожелания по коррекции текущего --
  пишите в devel-distro@ или мне (mike@), обсудим;
@ -11,8 +11,9 @@
 * документируйте на русском (README) или английском (README.en) языке
  то, что написали или изменили.

-рекомендации
-~~~~~~~~~~~~
+[float]
+=== рекомендации ===
+
 * трезво относитесь ко входным данным и не пренебрегайте кавычками:
  название дистрибутива с пробелом или получение текста ошибки вместо
  ожидаемого вывода команды могут привести к сложнодиагностируемым
@ -30,7 +31,9 @@

 * постарайтесь не вылазить за 80 колонок.

-ссылки
-~~~~~~
+[float]
+
+=== ссылки ===
+
 * https://lists.altlinux.org/mailman/listinfo/devel-distro
  (подписка по приглашению)
--- a/doc/vm.txt
+++ b/doc/vm.txt
@ -1,6 +1,6 @@
-сборка образов виртуальных машин
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-ВНИМАНИЕ: заключительная операция создания образа жёсткого диска
+== Сборка образов виртуальных машин ==
+
+*ВНИМАНИЕ:* заключительная операция создания образа жёсткого диска
 из архива с содержимым корневой файловой системы требует доступа
 к sudo и разрешения на выполнение скрипта bin/tar2vm в корневом
 каталоге метапрофиля при установке mkimage-profiles из пакета
@ -9,7 +9,7 @@

 Соответствующий фрагмент конфигурации sudo(8) может выглядеть как:

-mike ALL=NOPASSWD: /usr/share/mkimage-profiles/bin/tar2vm
+  mike ALL=NOPASSWD: /usr/share/mkimage-profiles/bin/tar2vm

 При работе с локальной копией mkimage-profiles.git следует иметь
 в виду, что предоставлять недоверенному пользователю право выполнять
@ -24,4 +24,4 @@ mike ALL=NOPASSWD: /usr/share/mkimage-profiles/bin/tar2vm

 Пример сборки и запуска VM:

-$ make ROOTPW=reallysecret1 vm/bare.img && kvm -hda ~/out/bare.img
+  $ make ROOTPW=reallysecret1 vm/bare.img && kvm -hda ~/out/bare.img
--- a/features.in/README
+++ b/features.in/README
@ -1,3 +1,4 @@
+== features.in ==
 Этот каталог содержит т.н. фичи (features, особенности).

 Фича -- отдельно подключаемая сущность, которая содержит
--- a/fop.xconf
+++ b/fop.xconf
@ -0,0 +1,54 @@
+<?xml version="1.0"?>
+<!-- $Id: fop.xconf 901793 2010-01-21 17:37:07Z jeremias $ -->
+ 
+<!-- NOTE: This is the version of the configuration -->
+<fop version="1.0">
+ 
+  <base>.</base>
+  <source-resolution>72</source-resolution>
+  <target-resolution>72</target-resolution>
+  <default-page-settings height="11in" width="8.26in"/>
+  <renderers>
+    <renderer mime="application/pdf">
+      <filterList>
+        <value>flate</value>
+      </filterList>
+ 
+      <fonts>
+          <auto-detect/> 
+      </fonts>
+    </renderer>
+ 
+    <renderer mime="application/x-afp">
+      <images mode="b+w" bits-per-pixel="8"/>
+      <renderer-resolution>240</renderer-resolution>
+      <resource-group-file>resources.afp</resource-group-file>
+    </renderer>
+ 
+    <renderer mime="application/postscript">
+    </renderer>
+ 
+    <renderer mime="application/vnd.hp-PCL">
+    </renderer>
+ 
+    <renderer mime="image/svg+xml">
+      <format type="paginated"/>
+      <link value="true"/>
+      <strokeText value="false"/>
+    </renderer>
+ 
+    <renderer mime="application/awt">
+    </renderer>
+ 
+    <renderer mime="image/png">
+    </renderer>
+ 
+    <renderer mime="image/tiff">
+    </renderer>
+ 
+    <renderer mime="text/xml">
+    </renderer>
+ 
+  </renderers>
+ 
+</fop>
--- a/image.in/README
+++ b/image.in/README
@ -1,3 +1,4 @@
+== image.in ==
 Этот каталог копируется из метапрофиля в профиль "как есть"
 и формирует "заготовку" финальной стадии, собирающей собственно
 образ из результатов работы индивидуальных субпрофилей
--- a/images/icons/note.png
+++ b/images/icons/note.png
--- a/lib/README
+++ b/lib/README
@ -1,3 +1,4 @@
+== lib ==
 Этот каталог содержит вспомогательные makefiles,
 обеспечивающие основную функциональность создания
 конфигурации образа и генерации соответствующего
--- a/mkimage-profiles.asciidoc
+++ b/mkimage-profiles.asciidoc
@ -0,0 +1,74 @@
+= mkimage-profiles =
+Michael Shigorin <mike@altlinux.org>
+:DocVersion: v0.1.0
+:DocDate:  Oct 2012
+
+= Введение =
+
+mkimage-profiles, или m-p — результат осмысления и обобщения опыта создания семейств дистрибутивов.
+
+*Цели*
+
+* пригодность к применению как очень крутыми хакерами, так и новичками
+* относительно низкая трудоёмкость использования
+* поощрение совместной работы
+
+*Средства*
+
+Двухуровневость:
+метапрофиль более объёмен и сложен, но выгоден для долгосрочной разработки
+сгенерированный дистрибутивный профиль более легко обозрим и модифицируем как одноразовый форк
+наследственность на уровне индивидуальных особенностей и образов в целом
+прозрачность и диагностируемость формирования конфигурации
+документированность
+
+*Примеры использования*
+
+Выполняем начальные инструкции по документации
+
+  git clone git://git.altlinux.org/people/mike/packages/mkimage-profiles.git
+  cd mkimage-profiles
+  make distro/icewm.iso
+
+include::README[]
+
+= Основы =
+
+== Предположения об окружении ==
+
+include::doc/assumptions.txt[]
+
+include::doc/debug.txt[]
+
+include::doc/features.txt[]
+
+include::doc/params.txt[]
+
+include::doc/pkglists.txt[]
+
+include::doc/qemu.txt[]
+
+include::doc/style.txt[]
+
+include::doc/vm.txt[]
+
+
+= Каталоги =
+
+include::conf.d/README[]
+
+include::features.in/README[]
+
+include::image.in/README[]
+
+include::lib/README[]
+
+include::pkg.in/README[]
+
+include::sub.in/README[]
+
+include::sub.in/main/README[]
+
+include::sub.in/stage1/README[]
+
+include::sub.in/stage2/README[]
--- a/pkg.in/README
+++ b/pkg.in/README
@ -1,3 +1,4 @@
+== pkg.in ==
 Этот каталог содержит все возможные списки пакетов и описания групп,
 которые по мере необходимости копируются из метапрофиля в формируемый
 профиль.
--- a/pkg.in/groups/README
+++ b/pkg.in/groups/README
@ -1,3 +1,5 @@
+[float]
+=== pkg.in/groups ===
 Этот каталог содержит описания групп, копируемые из метапрофиля
 в создаваемый профиль по необходимости (только фигурирующие в
 списке, которым является значение переменной MAIN_GROUPS).
--- a/pkg.in/lists/tagged/README
+++ b/pkg.in/lists/tagged/README
@ -1,3 +1,4 @@
+=== pkg.in/lists/tagged ===
 Этот каталог содержит тегированные списки; на данный момент
 реализация (../../../bin/tags2lists) требует, чтобы каждый
 из тегов был отдельным словом, состоящим из символов из набора
--- a/sub.in/README
+++ b/sub.in/README
@ -1,3 +1,5 @@
+== sub.in ==
+
 Этот каталог содержит субпрофили; содержимое затребованных
 (названия которых содержатся в значении переменной SUBPROFILES,
 которую заполняют цели sub/* -- см. ../lib/distro.mk) будет
--- a/sub.in/main/README
+++ b/sub.in/main/README
@ -1,12 +1,14 @@
+=== sub.in/main ===
+
 Этот каталог содержит субпрофиль main, собирающий пакетную базу
 для локальной инсталяции дистрибутива из полученного образа,
 включая необязательные пакеты; в distro/live-builder применяется
 как локальный репозиторий для сборки.

 Подбирает:
- SYSTEM_PACKAGES, COMMON_PACKAGES, BASE_PACKAGES, BASE_LISTS:
+* SYSTEM_PACKAGES, COMMON_PACKAGES, BASE_PACKAGES, BASE_LISTS:
  в установку по умолчанию;
- MAIN_PACKAGES, MAIN_LISTS: дополнительные пакеты.
+* MAIN_PACKAGES, MAIN_LISTS: дополнительные пакеты.

 В image-scripts.d/* смысла нет, только scripts.d/* --
 рабочий чрут не содержит исполняемых файлов.
--- a/sub.in/stage1/README
+++ b/sub.in/stage1/README
@ -1,3 +1,4 @@
+=== sub.in/stage1 ===
 Этот каталог содержит субпрофиль первой стадии загрузки;
 здесь место syslinux (загрузчик) и propagator (ориентировка
 на местности, вытягивание второй стадии с CD/FTP/...).
@ -18,6 +19,7 @@ STAGE1_KMODULES_REGEXP -- будет подмножество модулей

 Результат -- каталог syslinux/ для копирования в образ.

-TODO (3.2+): "The network drivers directory (drivers/net)
+
+NOTE: TODO (3.2+): "The network drivers directory (drivers/net)
 has been massively rearranged with most drivers moved into
 media-specific or protocol-specific subdirectories."
--- a/sub.in/stage2/README
+++ b/sub.in/stage2/README
@ -1,3 +1,5 @@
+=== sub.in/stage2 ===
+
 Этот каталог содержит общий базовый субпрофиль "живой" второй стадии,
 используемый для сборки образов install2, live, rescue (возможно,
 нескольких одновременно в составе одного дистрибутива).