https://github.com/courseorchestra/course-doc

Templates for creating asciidoctor documentation
https://github.com/courseorchestra/course-doc

Last synced: 12 months ago
JSON representation

Templates for creating asciidoctor documentation

• Host: GitHub
• URL: https://github.com/courseorchestra/course-doc
• Owner: CourseOrchestra
• Created: 2018-07-31T10:51:59.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2023-03-24T19:22:35.000Z (almost 3 years ago)
• Last Synced: 2025-01-21T21:15:37.113Z (about 1 year ago)
• Language: XSLT
• Size: 2.74 MB
• Stars: 14
• Watchers: 3
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc

Awesome Lists containing this project

README

          
= Шаблоны документации КУРС

[WARNING]

Сведения в документе устарели. Для получения pdf-файла мы разработали проект https://github.com/CourseOrchestra/asciidoctor-open-document .

== Краткое описание

В папке _doc_ приведен шаблон -- расширение для DocBook XSL, -- обеспечивающий конвертацию docbook-файла в _pdf_ через _xsl-fo_. Основан на шаблоне, который поставляется вместе с _AsciidocFX_.

Вариант в меру громоздкий и не очень удобен для кастомизации, но  <>  пока не понятны.

== Использование совместно с AsciidocFX

Для использования функции экспорта в pdf при помощи редактора https://asciidocfx.com/[AsciidocFX] скачайте это приложение и установите его. Далее в папке установки перейдите в _conf\docbook-config_ и замените файлы _fo-pdf.xsl_ и _common.xsl_ на соответствующие файлы, содержащиеся в папке _template/docbook-xsl_ репозитория.

В папке _doc_ репозитория находится файл _db_template_examples.adoc_, содержащий описание всех возможных вариантов использования шаблона c примерами. Сохраните папку _doc_ на диске и экспортируйте его в pdf при помощи _AsciidocFX_.

== Использование для автоматической сборки

Для автоматической сборки используйте проект https://github.com/asciidoctor/asciidoctor-fopub[asciicotor-fopub].

Если нужны скрипты, которые мы используем для сборки документации, поднимите _Issue_, выложим их в отдельную папку.

[[alternatives]]

== Альтернативные варианты

. https://github.com/Mogztter/asciidoctor-web-pdf [Asciidoctor Web PDF]. Лучшая альтернатива, если достаточно фич. Позволяет генерировать pdf через html с использованием спецификаций W3C https://www.w3.org/TR/css-page-3/[Paged Media] и https://www.w3.org/TR/css-gcpm-3/[Generated Content for Paged Media].

. https://github.com/asciidoctor/asciidoctor-pdf[Asciidoctor PDF]. Самый простой вариант, т.к. позволяет осуществлять конвертацию напрямую из asciidoc-формата. Однако на текущий момент обладает рядом ограничений, которые не позволяют пока его использовать для нашей отчетной документации. Эти ограничения потихоньку снимаются и есть надежда, что все-таки это проект будет доведен до требуемого состояния.

. http://dblatex.sourceforge.net/[Dblatex]. Это довольно старый и отработанный проект. Однако он работает на второй версии питона и требует довольно больших усилий для запуска и настройки. 

. https://github.com/asciidoctor/asciidoctor-latex[Asciidoctor LaTeX]. Проект, который не развивается. Не понятно что делает, то ли _TeX_ интегрирует в _Asciidoctor_, то ли _Asciidoctor_ конвертирует в _TeX_. Были какие-то разговоры, что будет отдельный проект по конвертации в _TeX_, но ничего не видно.