We collect the convenient documentation for CMake

Hello!

Probably everyone who has come across CMake at least once has thought: why is the documentation on the official website lying in the form of a huge one-page document , the use of which causes more inconvenience than it should be useful? It turns out that you need to perform just a few steps to get convenient documentation with the category tree, a list of subsections and adequate formatting of all the information. Details of this action under the cut.

How it works

The whole process is based on an imperceptible and obscure fact: the documentation for CMake is distributed in several formats: HTML, txt and DocBook v4.5. The basis for the first two is the documentation in the DocBook format - this is plain XML with a strict set of tags, which, you guessed it, can be converted using XSLT to completely any representation. This format is quite popular and the converters into different formats of help-documents have already been written, we just need to apply one of them. Since CMake is created for cross-platform, we will also do cross-platform documentation for it. For this, the best format is Web help . Those interested can experiment with their formats as homework.

Ingredients

• Apache ant
• DocBook XSLT Templates Set
• Java
• Saxon - XSLT Java Converter
• Xerces - XML ​​Java Parser

Further on, the docbook-xsl path will point to the folder where you extracted the DocBook XSLT template set.
')

DocBook webhelp template

Each docbook-converter is developed separately, in this connection, some of them are supported, others are not updated for a long time. Fortunately, the webhelp-converter is quite popular and has good documentation on its use, which can be found in the docbook-xsl / webhelp / docs folder.

Preparatory steps for solving our problem:

1. Add the paths to Saxon and Xerces in the docbook-xsl / webhelp / build.properties file :
   

   # 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. Check the conversion of the docbook-document of the webhelp module by running the following command in the docbook-xsl / webhelp folder :
   

    ant webhelp -Doutput-dir=test-help 

   
   If you did everything correctly, the result of the team’s work should be something like this:
   
   Ant webhelp output

    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
   

   
   
   
   Generated documentation for the webhelp module should appear in the docbook-xsl / webhelp / test-help folder.
   

CMake documentation

Since DocBook-> webhelp converter is based on Apache Ant , and the converter’s developers used some of its useful features, we can create a convenient environment for generating any documentation from DocBook to webhelp format.

1. Create a working folder and copy the file cmake.docbook , which is usually located in the installed CMake in the folder: doc / CMake-2.8 .
2. Create the following build.xml file in the working folder:
   

    <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> 

   
   Adjust the path in the file attribute to suit your environment.
   
3. Run the generation:
   

    ant webhelp 

   
   And ... We get clearly not a SUCCESSFUL, but an error with the hell callstack.
   
   Hidden text

    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.7388)
            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 Tre48)
            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.7388)
            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 Tre48)
            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

The thought arises that the cause of the error is a much larger size of the docbook file from CMake than the one used as a test of the webhelp converter, which this line in the log indirectly indicates:

  [xslt] : Error! No more DTM IDs are available 

After googling such an error, we see that it refers to Xalan (the XML parser used by Xerces) and seems to be solved, but there are problems in fact. We check the relevance of the necessary components - everything is ok. Having checked the cmake.docbook , no questions either arose: the very correct DocBook v4.5.
We conclude that Xalan + Xerces work incorrectly on large files, but we understand that the XSLT converters in the world are a huge heap, and most of them work with much larger volumes without problems. So, dig in the direction of connecting another XSLT-transformer.

By meditating on the docbook-xsl / webhelp / build.xml file, you can see that there are two XSLT steps, but they have one interesting difference - one of them uses the Xerces XSLT converter, and the other is 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> 

The reasons for this approach are difficult to understand, but perhaps this is our chance to solve the problem! We register another XSLT converter in the first step:

 <xslt in="${input-xml}" out="${xincluded-profiled.xml}" style="${ant.file.dir}/../profiling/profile.xsl" classpath="${xslt-processor-classpath}"> <!--     Saxon.jar --> ... </xslt> 

We start the generation and ... We get the cherished lines at the end of the log:

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

Upon completion, all documentation on CMake will appear in a great format in the docs folder. All you have to do is open index.html and get started.

Conclusion

If you wish, you can put the documentation on a web server or a shared ball and pull the whole team from there.


We will tell you about the use of CMake in game development on Win32, Mac OS X, iOS and Android platforms in one of the following articles. There its interesting features are above the roof.