How to become an author
Search
Write a publication
Pull to refresh
0
Rating
Alawar Entertainment

Собираем удобную документацию для CMake

Reading time9 min
Views12K
«Alawar Entertainment» corporate blogWebsite development*Open source*

Всем привет!

Наверное, каждого, кто хотя бы раз сталкивался с CMake, посещала мысль: почему документация на официальном сайте лежит в виде большущего одностраничного документа, использование которого доставляет больше неудобств, чем должно приносить пользы? Оказывается, нужно выполнить всего несколько шагов, чтобы получить удобную документацию с деревом категорий, списком подразделов и адекватным форматированием всей информации. Подробности сего действа под катом.

Как это работает


В основе всего процесса лежит незаметный и малоизвестный факт: документация для CMake распространяется в нескольких форматах: HTML, txt и DocBook v4.5. Основой для первых двух является документация в формате DocBook – это обычный XML со строгим набором тэгов, который, как вы уже догадались, можно преобразовать с помощью XSLT в совершенно любое представление. Формат этот достаточно популярный и конвертеры в разные форматы help-документов уже написаны, нам же остаётся только применить один из них. Так как CMake создан для кроссплатформенности, документацию для него будем делать также кроссплатформенную. Для этого лучше всего подходит формат Web help. Желающие могут поэкспериментировать со своими форматами в качестве домашней работы.

Ингредиенты



Далее по тексту путь docbook-xsl будет указывать в папку, куда вы извлекли набор DocBook XSLT шаблонов.

DocBook webhelp шаблон


Каждый docbook-конвертер разрабатывается отдельно, в связи с этим, некоторые из них поддерживаются, другие уже давно не обновляются. На наше счастье, webhelp-конвертер достаточно популярен и имеет хорошую документацию по его использованию, которую можно найти в папке docbook-xsl/webhelp/docs.

Подготовительные шаги для решения нашей задачи:

  1. Прописать пути к Saxon и Xerces в файле docbook-xsl/webhelp/build.properties:
    # Modify the following so that they point to your local
# copy of the jars indicated:
# * Saxon 6.5 jar
# * Xerces 2: xercesImpl.jar
# * xml-commons: xml-apis.jar
xslt-processor-classpath=d:/projects/CMake/doc/saxon6-5-5/saxon.jar
xercesImpl.jar=d:/projects/CMake/doc/xerces-2_11_0/xercesImpl.jar
xml-apis.jar=d:/projects/CMake/doc/xerces-2_11_0/xml-apis.jar

  2. Проверить конвертацию docbook-документа модуля webhelp, выполнив следующую команду в папке docbook-xsl/webhelp:
    ant webhelp -Doutput-dir=test-help

    Если вы всё сделали правильно, то результат работы команды должен быть примерно таким:
    Вывод ant webhelp
    d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp>ant webhelp -Doutput-dir=test-help
Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre7\lib\tools.jar
Buildfile: d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\build.xml

validate:

clean:

chunk:
    [mkdir] Created dir: d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help
     [xslt] Processing d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\docsrc\readme.xml to d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help\null1481456544
     [xslt] Loading stylesheet d:\projects\CMake\doc\docbook-xsl-1.78.1\profiling\profile.xsl
     [xslt] Processing d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help\null1481456544 to d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help\null884696268
     [xslt] Loading stylesheet d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\xsl\webhelp.xsl
     [xslt] language: en
     [xslt] Writing test-help/ch01.html for chapter
     [xslt] Writing test-help/ch02s01.html for section
     [xslt] Writing test-help/ch02s02s01.html for section
     [xslt] Writing test-help/ch02s02.html for section
     [xslt] Writing test-help/ch02s03.html for section
     [xslt] Writing test-help/ch02s04.html for section
     [xslt] Writing test-help/ch02s05.html for section
     [xslt] Writing test-help/ch02.html for chapter
     [xslt] Writing test-help/ch03s01.html for section
     [xslt] Writing test-help/ch03s02s01.html for section
     [xslt] Writing test-help/ch03s02.html for section
     [xslt] Writing test-help/ch03.html for chapter
     [xslt] Writing test-help/ch04.html for chapter
     [xslt] Writing test-help/ch05s01.html for section
     [xslt] Writing test-help/ch05s02.html for section
     [xslt] Writing test-help/ch05.html for chapter
     [xslt] Writing test-help/ix01.html for index
     [xslt] Writing test-help/index.html for book
     [xslt] Writing test-help/search/l10n.js
     [copy] Copying 96 files to d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help
     [copy] Copying 1 file to d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help

index:
     [copy] Copying 1 file to d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help\search
     [copy] Copied 1 empty directory to 1 empty directory under d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help\search
     [copy] Copying 4 files to d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\test-help\search
     [echo] Indexing html files in test-help
     [java] Stemming enabled
     [java] The created index files are located in test-help\search
     [java] Indexed the contents in 828 milliseconds

webhelp:

BUILD SUCCESSFUL
Total time: 35 seconds


    В папке docbook-xsl/webhelp/test-help должна появиться сгенерированная документация по модулю webhelp.

CMake документация


Так как DocBook->webhelp конвертер построен на основе Apache Ant, и разработчики конвертера использовали некоторые его полезные возможности, мы можем создать удобное окружение для генерации любой документации из DocBook в формат webhelp.

  1. Создадим рабочую папку и скопируем туда файл cmake.docbook, который обычно находится в установленном CMake в папке: doc/CMake-2.8.
  2. Создадим в рабочей папке файл build.xml следующего содержания:
    <project default="help" name="cmake-doc">
	<property name="input-xml" value="cmake.docbook"/>
	<import file="d:/projects/CMake/doc/docbook-xsl-1.78.1/webhelp/build.xml"/>
</project>

    Путь в атрибуте file скорректируйте в соответствие с вашим окружением.
  3. Запускаем генерацию:
    ant webhelp

    И… Получаем явно не SUCCESSFUL, а ошибку с адским коллстэком.
    Скрытый текст
    d:\projects\CMake\doc\cmake_doc>ant webhelp
Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre7\lib\tools.jar
Buildfile: d:\projects\CMake\doc\cmake_doc\build.xml

validate:

clean:
   [delete] Deleting directory d:\projects\CMake\doc\cmake_doc\docs

chunk:
    [mkdir] Created dir: d:\projects\CMake\doc\cmake_doc\docs
     [xslt] Processing d:\projects\CMake\doc\cmake_doc\cmake.docbook to d:\projects\CMake\doc\cmake_doc\docs\null2096887678
     [xslt] Loading stylesheet d:\projects\CMake\doc\docbook-xsl-1.78.1\profiling\profile.xsl
     [xslt] : Error! No more DTM IDs are available
     [xslt] Failed to process d:\projects\CMake\doc\cmake_doc\cmake.docbook

BUILD FAILED
d:\projects\CMake\doc\docbook-xsl-1.78.1\webhelp\build.xml:36: javax.xml.transform.TransformerException: com.sun.org.apache.xml.internal.dtm.DTMException: No more DTM IDs are available
        at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(Unknown Source)
        at org.apache.tools.ant.taskdefs.optional.TraXLiaison.transform(TraXLiaison.java:195)
        at org.apache.tools.ant.taskdefs.XSLTProcess.process(XSLTProcess.java:850)
        at org.apache.tools.ant.taskdefs.XSLTProcess.execute(XSLTProcess.java:388)
        at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:292)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
        at java.lang.reflect.Method.invoke(Unknown Source)
        at org.apache.tools.ant.dispatch.DispatchUtils.execute(DispatchUtils.java:106)
        at org.apache.tools.ant.Task.perform(Task.java:348)
        at org.apache.tools.ant.Target.execute(Target.java:435)
        at org.apache.tools.ant.Target.performTasks(Target.java:456)
        at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1393)
        at org.apache.tools.ant.Project.executeTarget(Project.java:1364)
        at org.apache.tools.ant.helper.DefaultExecutor.executeTargets(DefaultExecutor.java:41)
        at org.apache.tools.ant.Project.executeTargets(Project.java:1248)
        at org.apache.tools.ant.Main.runBuild(Main.java:851)
        at org.apache.tools.ant.Main.startAnt(Main.java:235)
        at org.apache.tools.ant.launch.Launcher.run(Launcher.java:280)
        at org.apache.tools.ant.launch.Launcher.main(Launcher.java:109)
Caused by: com.sun.org.apache.xml.internal.dtm.DTMException: No more DTM IDs are available
        at com.sun.org.apache.xml.internal.dtm.ref.DTMManagerDefault.addDTM(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.dom.SAXImpl.getResultTreeFrag(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.dom.DOMAdapter.getResultTreeFrag(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.dom.MultiDOM.getResultTreeFrag(Unknown Source)
        at profile.template$dot$1()
        at profile.applyTemplates1()
        at profile.template$dot$1()
        at profile.applyTemplates1()
        at profile.template$dot$1()
        at profile.applyTemplates1()
        at profile.applyTemplates1()
        at profile.template$dot$16()
        at profile.applyTemplates()
        at profile.transform()
        at com.sun.org.apache.xalan.internal.xsltc.runtime.AbstractTranslet.transform(Unknown Source)
        ... 22 more
---------
com.sun.org.apache.xml.internal.dtm.DTMException: No more DTM IDs are available
        at com.sun.org.apache.xml.internal.dtm.ref.DTMManagerDefault.addDTM(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.dom.SAXImpl.getResultTreeFrag(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.dom.DOMAdapter.getResultTreeFrag(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.dom.MultiDOM.getResultTreeFrag(Unknown Source)
        at profile.template$dot$1()
        at profile.applyTemplates1()
        at profile.template$dot$1()
        at profile.applyTemplates1()
        at profile.template$dot$1()
        at profile.applyTemplates1()
        at profile.applyTemplates1()
        at profile.template$dot$16()
        at profile.applyTemplates()
        at profile.transform()
        at com.sun.org.apache.xalan.internal.xsltc.runtime.AbstractTranslet.transform(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(Unknown Source)
        at com.sun.org.apache.xalan.internal.xsltc.trax.TransformerImpl.transform(Unknown Source)
        at org.apache.tools.ant.taskdefs.optional.TraXLiaison.transform(TraXLiaison.java:195)
        at org.apache.tools.ant.taskdefs.XSLTProcess.process(XSLTProcess.java:850)
        at org.apache.tools.ant.taskdefs.XSLTProcess.execute(XSLTProcess.java:388)
        at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:292)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)
        at java.lang.reflect.Method.invoke(Unknown Source)
        at org.apache.tools.ant.dispatch.DispatchUtils.execute(DispatchUtils.java:106)
        at org.apache.tools.ant.Task.perform(Task.java:348)
        at org.apache.tools.ant.Target.execute(Target.java:435)
        at org.apache.tools.ant.Target.performTasks(Target.java:456)
        at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1393)
        at org.apache.tools.ant.Project.executeTarget(Project.java:1364)
        at org.apache.tools.ant.helper.DefaultExecutor.executeTargets(DefaultExecutor.java:41)
        at org.apache.tools.ant.Project.executeTargets(Project.java:1248)
        at org.apache.tools.ant.Main.runBuild(Main.java:851)
        at org.apache.tools.ant.Main.startAnt(Main.java:235)
        at org.apache.tools.ant.launch.Launcher.run(Launcher.java:280)
        at org.apache.tools.ant.launch.Launcher.main(Launcher.java:109)

Total time: 16 seconds



WTF? // FIXME


Возникает мысль, что причиной ошибки является гораздо больший размер docbook-файла из CMake, чем тот, что используется в качестве теста webhelp-конвертера, на что косвенно указывает эта строчка в логе:
     [xslt] : Error! No more DTM IDs are available

После гугления подобной ошибки видим, что она относится к Xalan (XML-парсер, используемый Xerces'ом) и вроде как решена, но по факту проблемы имеются. Проверяем актуальность нужных компонентов – всё ок. Проверив cmake.docbook, никаких вопросов тоже не возникло: вполне себе корректный DocBook v4.5.
Приходим к выводу, что Xalan+Xerces работают некорректно на файлах большого объема, но мы-то понимаем, что XSLT-преобразователей в мире огромная куча, и большинство из них работают с куда большими объемами без проблем. Итак, копаем в сторону подключения другого XSLT-трансформера.

Помедитировав над файлом docbook-xsl/webhelp/build.xml, можно увидеть, что там есть два XSLT шага, но у них есть одно интересное различие – один из них использует Xerces XSLT-преобразователь, а другой — Saxon:

<xslt
	  in="${input-xml}"
	    out="${xincluded-profiled.xml}"
	    style="${ant.file.dir}/../profiling/profile.xsl"
            classpath="${xercesImpl.jar}"> <!-- путь к xercesImpl.jar, который мы задали в build.properties -->
...
</xslt>

<xslt
	  in="${xincluded-profiled.xml}"
	  out="${dummy.html}"
	  style="${stylesheet-path}"
	  scanincludeddirectories="false"
	  classpath="${xslt-processor-classpath}"> <!-- путь к Saxon.jar, который мы задали в build.properties -->
...
</xslt>

Причины такого подхода трудно понять, но возможно это наш шанс на решение проблемы! Прописываем другой XSLT-преобразователь в первый шаг:

<xslt
	  in="${input-xml}"
	    out="${xincluded-profiled.xml}"
	    style="${ant.file.dir}/../profiling/profile.xsl"
            classpath="${xslt-processor-classpath}"> <!-- теперь здесь путь к Saxon.jar -->
...
</xslt>

Запускаем генерацию и… Получаем заветные строчки в конце лога:

ant webhelp
...
BUILD SUCCESSFUL
Total time: 2 minutes 33 seconds

После завершения, в папке docs появится вся документация на CMake в отличном формате. Вам остаётся лишь открыть index.html и начать работу.

Заключение


При желании документацию можно выложить на веб-сервер или общую шару и тянуть оттуда всей командой.

Сравнение оригинального формата и Web help
Оригинал – описание всех команд на одной html странице (обратите внимание на размер скрола).


Web help формат – удобное дерево со списком разделов и подразделов.


Про применение CMake в геймдеве на платформах Win32, Mac OS X, iOS и Android мы расскажем в одной из следующих статей. Там своих интересностей выше крыши.
Tags:
Hubs:
Total votes 22: ↑21 and ↓1+20
Comments7
Alawar Entertainment
Company
24
Karma
0
Rating
Алексей Хорошилов @Dipp

Пользователь

Send message

Articles

Information

Website
company.alawar.ru
Registered
Founded
Employees
201–500 employees
Location
Россия

Your account

Sections

Information

Services

Support
© 2006–2024, Habr