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 

• Проверяем и сдаём.