Printed docs

Материал из ALT Linux Wiki
Версия от 15:42, 7 октября 2008; 81.222.141.3 (обсуждение) (Новая: {{Stub}} ==Краткое руководство по сборке макета печатной документации== Сборка печатной документации осу...)
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)
Stub.png
Данная страница находится в разработке.
Эта страница ещё не закончена. Информация, представленная здесь, может оказаться неполной или неверной.

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

Сборка печатной документации осуществляется на основе шаблона altlibrary-template с использованием git, издательской системы LaTex и редактора Emacs. Для облегчения процесса сборки печатного макета на основе электронных выпусков предусмотрена автоматизированная система получения и обновления git-репозиториев с исходными модулями. Правила определены в файле Makefile в шаблоне altlibrary-template.

Вкратце процесс выглядит так: создаём новый git-репозиторий, клонируем в него шаблон, получаем репозитории с модулями, конвертируем файлы с текстами в формат TeX, редактируем файл block.tex, компилируем dvi-файл, чистим макет, создаём pdf.

  • Создаём 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.
    • Файлы для ковертации перечисляются в файле 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/devmodel/*.xml
    docs-whatis_linux doc/distributions/*.xml
    docs-whatis_linux doc/freesoft/*.xml
    docs-whatis_linux doc/newbie/*.xml
    docs-whatis_linux doc/security/*.xml

Это будет означать, что данные файлы конвертировать не нужно, но нужно скопировать в подкаталог рабочего каталога, соответствующий данному репозиторию с исходными модулями. Иначе, если файлы не указать, при крныертации будет parser error, а если указать явно, то получится несколько отдельных файлов, которые потом придется объединять вручную.

  • Проверяем, что все, что нужно. сконвертировалось (особенно после make update-sources).
  • Заполняем block.tex, расположив в нем в соответствии со структурой создаваемой книги/брошюры ссылки на полученные в результате конвертации tex-файлы (без указания расширения), например:
 \input{docs-alterator_vm/index}
  • Компилируем dvi: С-с С-с в Emacs (необходимо расширение emacs-mode-auctex).
  • Смотрим, ужасаемся, исправляем ошибки конвертации, чистим макет.
  • Создаём pdf-макет
 $make pdf 
  • Проверяем и сдаём.