Printed docs
Краткое руководство по сборке макета печатной документации
Сборка печатной документации осуществляется на основе шаблона altlibrary-template с использованием git, издательской системы LaTex и редактора Emacs. Для облегчения процесса сборки печатного макета на основе электронных выпусков предусмотрена автоматизированная система получения и обновления git-репозиториев с исходными модулями. Правила определены в файле Makefile в шаблоне altlibrary-template.
Вкратце процесс выглядит так: создаём новый git-репозиторий, клонируем в него шаблон, получаем репозитории с модулями, конвертируем файлы с текстами в формат TeX, редактируем файл block.tex, компилируем dvi-файл, чистим макет, создаём pdf.
Создание git-репозитория
- Создаём git-репозиторий вида books-productversion.git. Например:
$ mkdir books-desktop4.1/ $ cd books-desktop4.1/ $ git-init
- Клонируем в репозиторий шаблон, заведя для него отдельный бранч:
$ git-clone git.alt:/people/kirill/public/altlibrary-template.git $ git-branch template origin/template
- Создаём рабочую ветку и переходим в неё:
$ git-branch master template $ git-checkout master
- Клонируем в рабочий каталог репозитории с модулями.
- В файле src.list перечисляем git-репозитории с исходными модулями с указанием пути и ветки добавлением записей вида
git://git.altlinux.org/people/someone/packages/repository remote/branch
Например:
git://git.altlinux.org/people/bertis/packages/docs-alterator_vm origin/master
- Выполняем
$ make get-sources
Если за время подготовки макета исходные модули изменились, их необходимо обновить. Для обновления всех модулей:
$ make update-sources
Полученные модули клонируются в подкаталог src/ рабочего каталога репозитория с макетом.
Конвертация в TeX
- Конвертируем расположенные в полученных модулях тексты документации в TeX.
- Файлы для конвертации перечисляются в файле list: repository path/to/file.smth, где
- repository
- название подкаталога в каталоге src/;
- path/to/file.smth
- путь к файлу, как правило doc/file.smth.
Пример:
docs-alterator_vm doc/index.m-k
При конвертации в рабочем каталоге создаются подкаталоги, названия которых совпадают с названиями репозиториев с модулями. В них копируются конвертируемые файлы и кладутся результаты конвертации - tex-файлы. Не забываем коммитить сконвертированные техи!
- Если в модулях содержатся иллюстрации (например. скриншоты в формате .png, как в случае с модулем руководств установки docs-install_smth.git), их также необходимо сконвертировать - в .eps. Для этого нужно вписать в файл list строку вида docs-install_desktop doc/*.png. Сконвертированные иллюстрации ложатся в тот же каталог docs-install_blabla. Полученные EPS-ы перемещаем в каталог images/ и коммитим. (При сборке макета не стоит забывать раскомментировать в block.tex строку
\graphicspath{{images/}}.
- Звёздочка также используется для правильной конвертации файлов в формате XML. Помимо указания основного xml-файла (основной файл лежит в каталоге doc/ репозитория с исходным модулем, а зависимые - в его подкаталогах), нужно перечислить зависимые файлы, указав вместо их названий *. Например:
docs-whatis_linux doc/linux.xml
docs-whatis_linux doc/*
Это будет означать, что данные файлы конвертировать не нужно, но нужно скопировать в подкаталог рабочего каталога, соответствующий данному репозиторию с исходными модулями. Иначе, если файлы не указать, при крнвертации получим parser error, а если указать явно, то получится несколько отдельных файлов, которые впоследствии придётся объединять вручную.
Создание PDF
- Проверяем, что всё, что нужно. сконвертировалось (особенно после make update-sources).
- Заполняем block.tex, расположив в нём в соответствии со структурой создаваемой книги/брошюры ссылки на полученные в результате конвертации tex-файлы (без указания расширения), например:
\input{docs-alterator_vm/index}
- Компилируем dvi: С-с С-с в Emacs (необходимо расширение emacs-mode-auctex).
- Смотрим, ужасаемся, исправляем ошибки конвертации, чистим макет.
- Создаём pdf-макет
$make pdf
- Проверяем и сдаём.