documentation: use paths relative to toplevel dir

This change is done to reduce ambiguity in some cases;
the previous intention has been to ease navigation when
staying in a particular directory, now it's been changed
in favour of convenient toplevel `git grep' in fact.

Both variants have their pros and cons, I just find myself
leaning to this one by now hence the commit.  Feel free to
provide constructive criticism :)

Some path-related bitrot has also been fixed while at that.

README

@@ -71,6 +71,9 @@
 ** pkglists.txt: формирование состава образа
 ** features.txt: обзор подключаемых особенностей
 
+Примечание: пути в документации задаются от каталога верхнего уровня,
+если не указаны как относительные в явном виде (./) или по смыслу.
+
 Удачи; что не так -- пишите.
 
 Michael Shigorin <mike@altlinux.org>

conf.d/README

@@ -12,7 +12,7 @@
 
 Попросту говоря, copy-paste -- тревожный признак.
 
-По переменным (см. тж. ../doc/pkglists.txt):
+По переменным (см. тж. doc/pkglists.txt):
 
 * для пользовательского окружения (live, main) предназначены
   THE_PACKAGES, THE_LISTS, THE_GROUPS, THE_PACKAGES_REGEXP

conf.d/p7.mk

@@ -5,7 +5,7 @@ mixin/p7:
 
 ifeq (distro,$(IMAGE_CLASS))
 
-### kludge compatibility: introspection stub for ../main.mk :-/
+### kludge compatibility: introspection stub for main.mk :-/
 distro/altlinux-p7-cinnamon: distro/regular-cinnamon mixin/p7; @:
 distro/altlinux-p7-e17: distro/regular-e17 mixin/p7; @:
 distro/altlinux-p7-icewm: distro/regular-icewm mixin/p7; @:

doc/params.txt

@@ -6,91 +6,91 @@
 * APTCONF
 ** задаёт путь к требуемому apt.conf
 ** значение: пусто (по умолчанию системный) либо строка
-** см. ../image.in/Makefile, apt.conf.sample
+** см. image.in/Makefile, doc/apt.conf.sample
 
 * ARCH
 ** задаёт целевую архитектуру образов
 ** значение: пусто (по умолчанию авто), i586, x86_64, arm, ppc
-** см. ../lib/build.mk
+** см. lib/build.mk
 
 * ARCHES
 ** задаёт набор целевых архитектур при параметрическом задании APTCONF
 ** значение: пусто (по умолчанию авто) либо список через пробел
-** см. ../Makefile, profiles.mk.sample
+** см. Makefile, doc/profiles.mk.sample
 
 * BELL
 ** подаёт сигнал после завершения сборки
 ** значение: пусто (по умолчанию нет) либо любая строка
-** см. ../lib/build.mk
+** см. lib/build.mk
 
 * BUILDDIR
 ** задаёт каталог генерируемого профиля и сборки
 ** значение: пусто (по умолчанию авто) либо строка
-** см. ../lib/profile.mk
+** см. lib/profile.mk
 
 * BUILDDIR_PREFIX
 ** задаёт префикс каталога генерируемого профиля и сборки
 ** значение: строка; по умолчанию выбирается алгоритмически
-** см. ../main.mk
+** см. main.mk
 
 * BUILDLOG
 ** задаёт путь к файлу журнала сборки/очистки
-** значение: по умолчанию $(BUILDDIR)/build.log либо строка
+** значение: $(BUILDDIR)/build.log (по умолчанию) либо строка
-** см. ../lib/log.mk
+** см. lib/log.mk
 
 * CHECK
 ** включает режим проверки сборки конфигурации (без сборки образа)
 ** значение: пусто (по умолчанию) либо любая строка
-** см. ../lib/build.mk, ../lib/clean.mk
+** см. lib/build.mk, lib/clean.mk
 
 * CLEAN
 ** экономия RAM+swap при сборке в tmpfs, иначе места на диске
 ** очистка рабочего каталога после успешной сборки очередной стадии
 ** может помешать использовать некоторые варианты отладки
 ** значение: пусто, 0, 1, 2; по умолчанию пусто при DEBUG, иначе 1
-** см. ../lib/clean.mk
+** см. lib/clean.mk
 
 * DEBUG
 ** включает средства отладки, может отключить зачистку после сборки
 ** значение: пусто (по умолчанию), 1 или 2
-** см. ../lib/log.mk, ../lib/clean.mk
+** см. lib/log.mk, lib/clean.mk
 
 * HOMEPAGE, HOMENAME, HOMEWAIT
 ** указывают адрес, название и таймаут перехода для домашней страницы
 ** значение: корректный URL, строка, целое неотрицательное число
-** см. ../features.in/live/generate.mk (тж. по умолчаниям)
+** см. features.in/live/generate.mk (тж. по умолчаниям)
 
 * ISOHYBRID
 ** включает создание гибриднго ISO-образа
 ** значение: пусто (по умолчанию) либо любая строка
-** см. ../features.in/pack/config.mk
+** см. features.in/pack/config.mk, features.in/isohybrid/config.mk
 
 * NICE
 ** понижает нагрузку системы сборочной задачей
 ** значение: пусто (по умолчанию) либо любая строка
-** см. ../lib/build.mk
+** см. lib/build.mk
 
 * REPORT
 ** запрашивает создание отчётов о собранном образе
 ** значение: пусто (по умолчанию) либо любая строка
 ** NB: в силу специфики обработки передаётся только явно
-** см. ../Makefile, ../report.mk, ../lib/report.mk
+** см. Makefile, report.mk, lib/report.mk
 
 * ROOTPW
 ** устанавливает пароль root по умолчанию для образов виртуальных машин
 ** значение: пусто (по умолчанию root) либо строка
-** см. ../features.in/build-vm/image-scripts.d/00root
+** см. features.in/deflogin/rootfs/image-scripts.d/50-root
 
 * SAVE_PROFILE
 ** сохраняет архив сгенерированного профиля в .disk/
 ** значение: пусто (по умолчанию) либо любая строка
-** см. ../image.in/Makefile
+** см. image.in/Makefile
 
 * SORTDIR
 ** дополнительно структурирует каталог собранных образов
 ** значение: пусто (по умолчанию) либо строка
 *** например, '$(IMAGE_NAME)/$(DATE)'
-** см. ../image.in/Makefile
+** см. image.in/Makefile
 
 * SQUASHFS
 ** определяет характер сжатия squashfs для stage2
@@ -98,18 +98,18 @@
 *** пусто (по умолчанию) либо normal: xz
 *** tight: xz с -Xbcj по платформе (лучше, но дольше -- подбор в два прохода)
 *** fast: gzip/lzo (быстрее запаковывается и распаковывается, меньше степень)
-** см. ../features.in/stage2/stage1/scripts.d/03-test-kernel
+** см. features.in/stage2/stage1/scripts.d/03-test-kernel
 
 * STATUS
 ** добавляет в имя образа указанный префикс
 ** значение:
 *** пусто (по умолчанию) либо строка (например, "alpha", "beta")
-** см. ../image.in/Makefile
+** см. image.in/Makefile
 
 * VM_SIZE
 ** задаёт размер несжатого образа виртуальной машины в байтах
 ** значение: пусто (по умолчанию двойной размер чрута) или целое
-** см. ../features.in/build-vm/lib/90-build-vm.mk, ../bin/tar2fs
+** см. features.in/build-vm/lib/90-build-vm.mk, bin/tar2vm
 
 [float]
 === пример ===

doc/pkglists.txt

@@ -1,7 +1,7 @@
 == Списки пакетов ==
 
-Состав пакетной базы субпрофилей определяется значенями
+Состав пакетной базы субпрофилей определяется значениями
-следующих переменных профиля (см. тж. ../conf.d/README;
+следующих переменных профиля (см. тж. conf.d/README;
 некоторые "*" ниже заэкранированы ради парсера asciidoc):
 
 * main: пакетная база для установки

features.in/00example/README

@@ -21,12 +21,12 @@
 цели в UI конфигурирования образа.
 
 Остальное содержимое является дополнительным и используется
-в таком порядке (см. ../Makefile):
+в таком порядке (см. features.in/Makefile):
 
 * сперва в $(BUILDDIR)/image/ копируются все подкаталоги,
   соответствующие итоговым именам субпрофилей, запрошенных
   для профиля образа; при этом они сливаются с деревом,
-  которое уже сформировано субпрофилями (../sub.in/*) и уже
+  которое уже сформировано субпрофилями (sub.in/*) и уже
   скопированными фичами; если какие-либо файлы перекрылись
   по именам, rsync должен оставить резервные копии (*~),
   которые должны просигнализировать о беспорядке;

features.in/README

@@ -8,14 +8,14 @@
 других фич либо субпрофилей.
 
 Каждая фича должна содержать файл config.mk, включаемый
-в ../main.mk при построении конфигурации будущего профиля;
+в main.mk при построении конфигурации будущего профиля;
 он может описывать одну или более целей вида use/*,
 дополняющих конфигурацию, и обязан добавить имя фичи
 в $(FEATURES), для чего создана функция add_feature.
 
 На этапе генерации сборочного профиля фичи рассматриваются
-после инициализации профиля (см. ../image.in/) и копирования
+после инициализации профиля (см. image.in/) и копирования
-субпрофилей (см. ../sub.in/).  Для каждой фичи, указанной
+субпрофилей (см. sub.in/).  Для каждой фичи, указанной
 в $(FEATURES), копируются подкаталоги сообразно включенным
 субпрофилям, а также lib/ и {image-,}scripts.d/; затем
 выполняются generate.sh и generate.mk при их наличии.

features.in/build-distro/config.mk

@@ -1,3 +1,3 @@
-# hooked from ../../lib/sugar.mk
+# hooked from lib/sugar.mk
 use/build-distro:
 	@$(call add_feature)

features.in/build-ve/config.mk

@@ -1,3 +1,3 @@
-# hooked from ../../lib/sugar.mk
+# hooked from lib/sugar.mk
 use/build-ve: sub/rootfs@/
 	@$(call add_feature)

features.in/build-vm/README

@@ -1,3 +1,3 @@
 Эта фича конфигурирует создание образа виртуальной машины (VM).
 Дополняет финальную стадию сборки (lib/, image-scripts.d/).
-Требует для работы sudo(8) -- см. тж. ../../doc/vm.txt .
+Требует для работы sudo(8) -- см. тж. doc/vm.txt

features.in/build-vm/config.mk

@@ -1,3 +1,3 @@
-# hooked from ../../lib/sugar.mk
+# hooked from lib/sugar.mk
 use/build-vm: sub/rootfs@/ use/kernel use/deflogin
 	@$(call add_feature)

features.in/build-vm/image-scripts.d/07-kernel

@@ -1,6 +1,6 @@
 #!/bin/sh
 # predictable file locations make bootloader configuration simple;
-# this script relates to .../features.in/stage2/stage1/scripts.d/80-make-initfs
+# this script relates to features.in/stage2/stage1/scripts.d/80-make-initfs
 
 kver="$(rpm -qa 'kernel-image*' \
             --qf '%{installtime} %{version}-%{name}-%{release}\n' \

features.in/efi/README

@@ -2,7 +2,7 @@
 
 Конфигурируется заданием загрузчика (EFI_BOOTLOADER)
 и файла сертификата (EFI_CERT) при помощи целей;
-пример использования доступен в ../../conf.d/regular.mk
+пример использования доступен в conf.d/regular.mk
 
 См. тж.:
 * http://www.altlinux.org/UEFI

features.in/isohybrid/README

@@ -5,7 +5,7 @@
 Можно указать в цепочке зависимостей дистрибутива явно с тем,
 чтобы гарантировать гибридный вид образа, либо запросить включение
 этой фичи при сборке конфигурации произвольного дистрибутива
-(ISOHYBRID=1, см. ../pack/config.mk).
+(ISOHYBRID=1, см. features.in/pack/config.mk).
 
 Обратите внимание: в propagator до 20101130-alt15 поддержка
 автоматической загрузки с флэш-носителя, содержащего ISO-образ,

features.in/metadata/lib/50-metadata.mk

@@ -3,7 +3,7 @@
 # package lists are needed for installer and live-install images
 METADIR := files/Metadata
 
-# preparation targets of ../../build-distro/lib/build-distro.mk
+# preparation targets of features.in/build-distro/lib/build-distro.mk
 WHATEVER += metadata
 
 # handle these too

features.in/syslinux/stage1/scripts.d/01-syslinux

@@ -1,6 +1,6 @@
 #!/bin/sh
 # gather syslinux configuration from snippets;
-# copy modules; see also ../../generate.mk
+# copy modules; see also this feature's generate.mk
 
 MODDIR="/usr/lib/syslinux"
 CFG="$GLOBAL_BOOTLOADER.cfg"
@@ -48,4 +48,4 @@ fi
 if [ "$DEBUG" != 2 ]; then rm -r .in/; fi
 
 # NB: there will be final macro expansion based on actual image sizes
-#     (done by ../../scripts.d/10-propagator-ramdisk)
+#     done by features.in/syslinux/scripts.d/20-propagator-ramdisk

features.in/systemd/README

@@ -1,2 +1,4 @@
 Эта фича заменяла в базовой системе sysvinit на systemd;
-в настоящее время является устаревшей, см. ../init/
+в настоящее время является устаревшей, см. features.in/init
+
+# TODO: DROP

image.in/README

@@ -5,17 +5,17 @@
 образ из результатов работы индивидуальных субпрофилей
 (для distro) либо непосредственно "на месте" (для ve, vm).
 
-Содержимое files/ копируется в корень образа.
+Содержимое image.in/files/ копируется в корень образа.
 
 Соответственно для сборки также потребуется одна из фич
-../features.in/build-*.
+features.in/build-*.
 
 Пакетная база рабочего чрута минимальна (может чуть расширяться
-фичами -- см. ../features.in/repo/lib/50-genbasedir.mk
+фичами -- см. features.in/repo/lib/50-genbasedir.mk
 в качестве примера).
 
 Если требуется какая-либо иная обработка чрута, следует
-предпочитать scripts.d/ -- для универсальной обработки
+предпочитать scripts.d -- для универсальной обработки
 скрипт можно добавить здесь, для специфичной -- в фичу.
 
 Результат -- готовый образ в $(IMAGEDIR)/.

lib/README

@@ -3,7 +3,7 @@
 Этот каталог содержит вспомогательные makefiles,
 обеспечивающие основную функциональность создания
 конфигурации образа и генерации соответствующего
-профиля для сборки; см. тж. ../conf.d/.
+профиля для сборки; см. тж. conf.d/.
 
-Следует помнить, что будучи включаемыми в ../main.mk,
+Следует помнить, что будучи включаемыми в main.mk,
 они работают в каталоге верхнего уровня.

pkg.in/groups/README

@@ -6,4 +6,4 @@
 списке, которым является значение переменной MAIN_GROUPS).
 
 В данный момент перенесено почти 1:1 из mkimage-profiles-desktop,
-требует увязки с ../lists/tagged/.
+требует увязки с pkg.in/lists/tagged/

pkg.in/lists/README

@@ -2,14 +2,14 @@
 
 Этот каталог содержит списки пакетов, копируемые из метапрофиля
 в создаваемый профиль по необходимости (определяется по наличию
-имён списков в переменных *_LISTS, см. реализацию в Makefile).
+имён списков в переменных *_LISTS, см. реализацию в ./Makefile).
 
 Список .base является особенным (формирует базовую систему,
 см. http://www.altlinux.org/Alterator-pkg); он создаётся из
-содержимого ряда переменных (см. Makefile).
+содержимого ряда переменных (см. реализацию).
 
-Подкаталог tagged/ содержит тегированные списки, имена которых
+Подкаталог tagged содержит тегированные списки, имена которых
-удобно получать функцией tags() (см. ../../lib/functions.mk).
+удобно получать функцией tags() (см. lib/functions.mk).
 
 Для выявления дубликатов в составе списков служит `make pkgdups';
 пытаться избежать дублей на 100% скорее бесполезно, но бродячие

pkg.in/lists/tagged/README

@@ -1,8 +1,8 @@
 === pkg.in/lists/tagged ===
 
 Этот каталог содержит тегированные списки; на данный момент
-реализация (../../../bin/tags2lists) требует, чтобы каждый
+реализация (bin/tags2lists) требует, чтобы каждый из тегов
-из тегов был отдельным словом, состоящим из символов из набора
+был отдельным словом, состоящим из символов из набора
 [a-zA-Z0-9_] (внимание: не используйте в слове "-");
 рекомендуется разделять слова "+".
 
@@ -11,4 +11,4 @@
 списка тегов.
 
 Реализация является экспериментальной и требует утряски
-с ../groups/; комментарии и помощь всячески приветствуются.
+с pkg.in/groups/; комментарии и помощь всячески приветствуются.

sub.in/README

@@ -2,12 +2,12 @@
 
 Этот каталог содержит субпрофили; содержимое затребованных
 (названия которых содержатся в значении переменной SUBPROFILES,
-которую заполняют цели sub/* -- см. ../lib/sugar.mk) будет
+которую заполняют цели sub/* -- см. lib/sugar.mk) будет
 скопировано в корневой каталог формируемого профиля.
 
 Просьба ответственно относиться к изменению существующих субпрофилей
 и вдумчиво -- к созданию новых; возможно, достаточно всего лишь
-оформить нужное новой фичей (см. ../features.in/).
+оформить нужное новой фичей (см. features.in/).
 
 Обратите внимание: поскольку сборка частей дистрибутивного образа
 и происходит в каталогах субпрофилей, то повторное использование
@@ -35,4 +35,4 @@
 
 * main: пакетная база, укладываемая на образ (NB: поскольку рабочий
   чрут в этом случае не содержит ничего, кроме пакетов, добавлять
-  image-scripts.d/* смысла нет, только scripts.d/*)
+  что-либо в image-scripts.d смысла нет, только в scripts.d)

sub.in/stage1/Makefile

@@ -44,7 +44,7 @@ GLOBAL_SQUASHFS := $(SQUASHFS)
 -include $(sort $(wildcard lib/*.mk))
 
 # scripts prepare bootloader configuration, too
-# NB: we pass tested squashfs options for ../stage2/Makefile to include
+# NB: we pass tested squashfs options for sub.in/stage2/Makefile to include
 all: | debug prepare-workdir copy-tree run-scripts $(BUILD_PROPAGATOR) \
 	copy-$(BOOTLOADER) $(COPY_SQUASHCFG) pack-image $(GLOBAL_CLEAN_WORKDIR)
 	@if [ -s $(OUTDIR)/squashcfg.mk ]; then \

sub.in/stage2/Makefile

@@ -13,7 +13,8 @@ include $(GLOBAL_BUILDDIR)/distcfg.mk
 include $(GLOBAL_BUILDDIR)/functions.mk
 include $(MKIMAGE_PREFIX)/config.mk
 
-# this might have been prepared by ../stage1/scripts.d/03-test-kernel
+# this might have been prepared
+# by features.in/stage2/stage1/scripts.d/03-test-kernel
 -include $(GLOBAL_BUILDDIR)/squashcfg.mk
 
 # this should be brought in by corresponding specific stage2 feature
@@ -39,7 +40,7 @@ IMAGE_PACKAGES_REGEXP += $(call kpackages, \
 
 -include $(sort $(wildcard lib/*.mk))
 
-# see also scripts.d/99-elf-stats
+# see also ./scripts.d/99-elf-stats
 ifdef GLOBAL_SQUASHFS_SORT
 ifeq (tight,$(SQUASHFS))
 CHROOT_PACKAGES += file