Printed docs

Материал из ALT Linux Wiki
Stub.png
Данная страница находится в разработке.
Эта страница ещё не закончена. Информация, представленная здесь, может оказаться неполной или неверной.


Краткое руководство по сборке макета печатной документации

Сборка печатной документации осуществляется на основе шаблона 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 
  • Проверяем и сдаём.