Asciidoc — различия между версиями

Материал из ALT Linux Wiki
Перейти к: навигация, поиск
(initial page)
 
 
(не показано 11 промежуточных версий 1 участника)
Строка 1: Строка 1:
 +
'''asciidoc''' - это скрипт на python, преобразующий свою разметку в несколько выходных форматов, в т.ч. html и pdf.
 
==QuickStart==
 
==QuickStart==
 
В качестве примера можно взять документацию docs-simply-linux:
 
В качестве примера можно взять документацию docs-simply-linux:
 
  git clone git://git.altlinux.org/gears/d/docs-simply-linux.git
 
  git clone git://git.altlinux.org/gears/d/docs-simply-linux.git
  
 +
Для подсветки синтаксиса в Vim можно установить плагин:
 +
apt-get install vim-plugin-asciidoc-syntax
 
==PDF==
 
==PDF==
  apt-get install asciidoc-a2x vim-plugin-asciidoc-syntax
+
  apt-get install asciidoc-a2x
 
 
  
 
Чтобы компилировать в pdf (<code>make pdf</code>) нужны дополнительные пакеты xmlgraphics, я сделал так:
 
Чтобы компилировать в pdf (<code>make pdf</code>) нужны дополнительные пакеты xmlgraphics, я сделал так:
Строка 17: Строка 19:
 
  $ make -d pdf 2>&1 | tee makepdf.log
 
  $ make -d pdf 2>&1 | tee makepdf.log
  
 +
===Кириллица===
 +
Известны проблемы fop с кириллицей, когда вместо русских букв в pdf отображается текст вида #### ### ### <br>
 +
Связано это с тем, что встроенные в fop шрифты кириллические символы не поддерживают. Решается встраиванием своих шрифтов.
 +
Вариант решения этой проблемы ниже.
 +
*Установить fonts-ttf-dejavu
 +
*Подготовить свой файл настроек fop.xconf и прописать autodetect
 +
*Прописать в Makefile в опциях a2x <code>--xsltproc-opts=</code> правильное наименование шрифта (например DejaVu Sans)
 +
 +
Посмотреть использованные в сгенерированном pdf фонты в Okular:
 +
Файл - Свойства - Шрифты
 +
Прописывать шрифты из fonts-ttf-dejavu как: DejaVu Sans, DejaVu Serif, DejaVu Sans Mono. <br>
 +
Прописывать шрифты из fonts-ttf-PT как: PT Sans, PT Serif, PT Mono. <br>
 +
Работающие шрифты из fonts-ttf-ms:  Arial, Times New Roman, Tahoma, Verdana, Trebuchet MS, Comic Sans MS, Courier New, Arial Black, Georgia, Andale Mono, Impact. <br>
 +
Работающие шрифты из fonts-ttf-uralic: BookmanUralic, GothicUralic, MonoUralic, PalladioUralic, RomanUralic, SansUralic, SansCondensedUralic, SchoolbookUralic. <br>
 +
Прописывать в Makefile именно так, т.е. не Times, а именно Times New Roman и BookmanUralic.<br>
 +
Ещё [http://xmlsite.sourceforge.net/rusfop/fonts.html <s>Unicode-шрифты, протестированные с FOP для получения кириллических PDF</s>] - список явно устарел.
 +
 +
:'''NB''' В современных версиях fop генерировать свои метрики шрифтов (arial.xml) ''не нужно''.
 +
:'''NB''' В тексте Введения по Симпли вместо "й" отображается квадрат: - видимо это ошибка в самом тексте (через mcedit её видно, через  Vim - нет).
 +
Просмотреть метаданные шрифта (в т.ч. правильное имя)  можно скриптом из пакета python-module-ttfquery
 +
python /usr/lib/python2.6/site-packages/ttfquery/metadata_query.py dejavu
 +
 +
===fop.xconf===
 +
Файл fop.xconf с примерами и комментариями можно взять тут - /usr/share/xmlgraphics-fop/conf<br>
 +
Минимальный файл настроек fop.xconf для генерации кириллических pdf:
 +
<source lang=xml>
 +
<?xml version="1.0"?>
 +
<!-- $Id: fop.xconf 901793 2010-01-21 17:37:07Z jeremias $ -->
 +
 +
<!-- NOTE: This is the version of the configuration -->
 +
<fop version="1.0">
 +
 +
  <base>.</base>
 +
  <source-resolution>72</source-resolution>
 +
  <target-resolution>72</target-resolution>
 +
  <default-page-settings height="11in" width="8.26in"/>
 +
  <renderers>
 +
    <renderer mime="application/pdf">
 +
      <filterList>
 +
        <value>flate</value>
 +
      </filterList>
 +
 +
      <fonts>
 +
          <auto-detect/>
 +
      </fonts>
 +
    </renderer>
 +
 +
    <renderer mime="application/x-afp">
 +
      <images mode="b+w" bits-per-pixel="8"/>
 +
      <renderer-resolution>240</renderer-resolution>
 +
      <resource-group-file>resources.afp</resource-group-file>
 +
    </renderer>
 +
 +
    <renderer mime="application/postscript">
 +
    </renderer>
 +
 +
    <renderer mime="application/vnd.hp-PCL">
 +
    </renderer>
 +
 +
    <renderer mime="image/svg+xml">
 +
      <format type="paginated"/>
 +
      <link value="true"/>
 +
      <strokeText value="false"/>
 +
    </renderer>
 +
 +
    <renderer mime="application/awt">
 +
    </renderer>
 +
 +
    <renderer mime="image/png">
 +
    </renderer>
 +
 +
    <renderer mime="image/tiff">
 +
    </renderer>
 +
 +
    <renderer mime="text/xml">
 +
    </renderer>
 +
 +
  </renderers>
  
 +
</fop>
 +
</source>
  
[[Категория:HOWTO]]
+
{{Category navigation|title=HOWTO|category=HOWTO|sortkey={{SUBPAGENAME}}}}

Текущая версия на 11:39, 19 июля 2015

asciidoc - это скрипт на python, преобразующий свою разметку в несколько выходных форматов, в т.ч. html и pdf.

QuickStart[править]

В качестве примера можно взять документацию docs-simply-linux:

git clone git://git.altlinux.org/gears/d/docs-simply-linux.git

Для подсветки синтаксиса в Vim можно установить плагин:

apt-get install vim-plugin-asciidoc-syntax

PDF[править]

apt-get install asciidoc-a2x

Чтобы компилировать в pdf (make pdf) нужны дополнительные пакеты xmlgraphics, я сделал так:

apt-get install xmlgraphics*

Для большей информативности процесса можно в Makefile docs-simply-linux добавить опцию verbose

$(A2X) --verbose --fop --fop-opts='-c fop.xconf' -d book -f pdf -a lang=ru \

Комментируем секцию install: all (иначе при make pdf пытается установиться)

Компилируем и собираем лог в makepdf.log

$ make -d pdf 2>&1 | tee makepdf.log

Кириллица[править]

Известны проблемы fop с кириллицей, когда вместо русских букв в pdf отображается текст вида #### ### ###
Связано это с тем, что встроенные в fop шрифты кириллические символы не поддерживают. Решается встраиванием своих шрифтов. Вариант решения этой проблемы ниже.

  • Установить fonts-ttf-dejavu
  • Подготовить свой файл настроек fop.xconf и прописать autodetect
  • Прописать в Makefile в опциях a2x --xsltproc-opts= правильное наименование шрифта (например DejaVu Sans)

Посмотреть использованные в сгенерированном pdf фонты в Okular:

Файл - Свойства - Шрифты

Прописывать шрифты из fonts-ttf-dejavu как: DejaVu Sans, DejaVu Serif, DejaVu Sans Mono.
Прописывать шрифты из fonts-ttf-PT как: PT Sans, PT Serif, PT Mono.
Работающие шрифты из fonts-ttf-ms: Arial, Times New Roman, Tahoma, Verdana, Trebuchet MS, Comic Sans MS, Courier New, Arial Black, Georgia, Andale Mono, Impact.
Работающие шрифты из fonts-ttf-uralic: BookmanUralic, GothicUralic, MonoUralic, PalladioUralic, RomanUralic, SansUralic, SansCondensedUralic, SchoolbookUralic.
Прописывать в Makefile именно так, т.е. не Times, а именно Times New Roman и BookmanUralic.
Ещё Unicode-шрифты, протестированные с FOP для получения кириллических PDF - список явно устарел.

NB В современных версиях fop генерировать свои метрики шрифтов (arial.xml) не нужно.
NB В тексте Введения по Симпли вместо "й" отображается квадрат: - видимо это ошибка в самом тексте (через mcedit её видно, через Vim - нет).

Просмотреть метаданные шрифта (в т.ч. правильное имя) можно скриптом из пакета python-module-ttfquery

python /usr/lib/python2.6/site-packages/ttfquery/metadata_query.py dejavu

fop.xconf[править]

Файл fop.xconf с примерами и комментариями можно взять тут - /usr/share/xmlgraphics-fop/conf
Минимальный файл настроек fop.xconf для генерации кириллических pdf:

<?xml version="1.0"?>
<!-- $Id: fop.xconf 901793 2010-01-21 17:37:07Z jeremias $ -->

<!-- NOTE: This is the version of the configuration -->
<fop version="1.0">

  <base>.</base>
  <source-resolution>72</source-resolution>
  <target-resolution>72</target-resolution>
  <default-page-settings height="11in" width="8.26in"/>
  <renderers>
    <renderer mime="application/pdf">
      <filterList>
        <value>flate</value>
      </filterList>

      <fonts>
          <auto-detect/> 
      </fonts>
    </renderer>

    <renderer mime="application/x-afp">
      <images mode="b+w" bits-per-pixel="8"/>
      <renderer-resolution>240</renderer-resolution>
      <resource-group-file>resources.afp</resource-group-file>
    </renderer>

    <renderer mime="application/postscript">
    </renderer>

    <renderer mime="application/vnd.hp-PCL">
    </renderer>

    <renderer mime="image/svg+xml">
      <format type="paginated"/>
      <link value="true"/>
      <strokeText value="false"/>
    </renderer>

    <renderer mime="application/awt">
    </renderer>

    <renderer mime="image/png">
    </renderer>

    <renderer mime="image/tiff">
    </renderer>

    <renderer mime="text/xml">
    </renderer>

  </renderers>

</fop>