MantisBT - CMake
View Issue Details
IDProjectCategoryView StatusDate SubmittedLast Update
0013508CMakeDocumentationpublic2012-09-02 18:162013-03-04 08:38
ReporterDaniel Pfeifer 
Assigned ToBrad King 
PrioritynormalSeveritytweakReproducibilityalways
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version 
Target VersionCMake 2.8.10Fixed in VersionCMake 2.8.10 
Summary0013508: generated DocBook is invalid
DescriptionThe documentation generated by cmake (also cpack, ctest) does not conform to the docbook dtd.
Steps To Reproduce$ cmake --help-full cmake.docbook
$ xmllint --valid --noout cmake.docbook
Additional Informationxmllint is part of libxml2.

validate-test.patch adds validation checks to the CMakeTests directory.
TagsNo tags attached.
Relationships
Attached Filespatch validate-test.patch (1,957) 2012-09-02 18:16
https://public.kitware.com/Bug/file/4445/validate-test.patch
patch docbook-formatter.patch (9,354) 2012-09-02 18:16
https://public.kitware.com/Bug/file/4446/docbook-formatter.patch
patch clean-documentation.patch (1,593) 2012-09-02 18:16
https://public.kitware.com/Bug/file/4447/clean-documentation.patch
patch 0001-WIP-Add-CMake.Docbook-test-to-validate-docbook-xml-1.patch (7,471) 2012-09-03 10:15
https://public.kitware.com/Bug/file/4449/0001-WIP-Add-CMake.Docbook-test-to-validate-docbook-xml-1.patch
patch 0001-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch (615,409) 2012-09-06 06:38
https://public.kitware.com/Bug/file/4457/0001-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch
patch 0001-Remove-table-of-contents-from-generated-DocBook.patch (1,625) 2012-09-07 07:23
https://public.kitware.com/Bug/file/4459/0001-Remove-table-of-contents-from-generated-DocBook.patch
patch 0002-Factor-out-code-to-write-valid-DocBook-IDs.patch (5,374) 2012-09-07 07:24
https://public.kitware.com/Bug/file/4460/0002-Factor-out-code-to-write-valid-DocBook-IDs.patch
patch 0003-Fixed-the-DocBook-output-for-sections.patch (2,522) 2012-09-07 07:24
https://public.kitware.com/Bug/file/4461/0003-Fixed-the-DocBook-output-for-sections.patch
patch 0004-Cleanup-of-DocBook-formatter-and-generated-DocBook.patch (4,052) 2012-09-07 07:24
https://public.kitware.com/Bug/file/4462/0004-Cleanup-of-DocBook-formatter-and-generated-DocBook.patch
patch 0005-Add-support-for-abstract-at-section-level-1-in-DocBo.patch (2,355) 2012-09-07 07:24
https://public.kitware.com/Bug/file/4463/0005-Add-support-for-abstract-at-section-level-1-in-DocBo.patch
patch 0006-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch (498,786) 2012-09-07 07:24
https://public.kitware.com/Bug/file/4464/0006-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch
patch 0007-Fix-offending-part-of-cmDocumentation-that-caused-in.patch (1,108) 2012-09-07 07:24
https://public.kitware.com/Bug/file/4465/0007-Fix-offending-part-of-cmDocumentation-that-caused-in.patch
patch 0001-Add-a-test-to-validate-generated-XML-files-DocBook-a.patch (501,042) 2012-09-07 18:30
https://public.kitware.com/Bug/file/4466/0001-Add-a-test-to-validate-generated-XML-files-DocBook-a.patch
Issue History
Date ModifiedUsernameFieldChange
2012-09-02 18:16Daniel PfeiferNew Issue
2012-09-02 18:16Daniel PfeiferFile Added: validate-test.patch
2012-09-02 18:16Daniel PfeiferFile Added: docbook-formatter.patch
2012-09-02 18:16Daniel PfeiferFile Added: clean-documentation.patch
2012-09-02 18:22Daniel PfeiferNote Added: 0030819
2012-09-03 10:15Brad KingFile Added: 0001-WIP-Add-CMake.Docbook-test-to-validate-docbook-xml-1.patch
2012-09-03 10:20Brad KingNote Added: 0030820
2012-09-06 06:38Daniel PfeiferFile Added: 0001-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch
2012-09-06 06:49Daniel PfeiferNote Added: 0030940
2012-09-06 09:25Brad KingNote Added: 0030941
2012-09-07 07:23Daniel PfeiferFile Added: 0001-Remove-table-of-contents-from-generated-DocBook.patch
2012-09-07 07:24Daniel PfeiferFile Added: 0002-Factor-out-code-to-write-valid-DocBook-IDs.patch
2012-09-07 07:24Daniel PfeiferFile Added: 0003-Fixed-the-DocBook-output-for-sections.patch
2012-09-07 07:24Daniel PfeiferFile Added: 0004-Cleanup-of-DocBook-formatter-and-generated-DocBook.patch
2012-09-07 07:24Daniel PfeiferFile Added: 0005-Add-support-for-abstract-at-section-level-1-in-DocBo.patch
2012-09-07 07:24Daniel PfeiferFile Added: 0006-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch
2012-09-07 07:24Daniel PfeiferFile Added: 0007-Fix-offending-part-of-cmDocumentation-that-caused-in.patch
2012-09-07 07:29Daniel PfeiferNote Added: 0030953
2012-09-07 08:34Brad KingNote Added: 0030954
2012-09-07 18:30Daniel PfeiferFile Added: 0001-Add-a-test-to-validate-generated-XML-files-DocBook-a.patch
2012-09-08 03:33Daniel PfeiferNote Added: 0030957
2012-09-08 07:53Brad KingNote Added: 0030958
2012-09-08 07:54Brad KingAssigned To => Brad King
2012-09-08 07:54Brad KingStatusnew => assigned
2012-09-08 07:55Brad KingTarget Version => CMake 2.8.10
2012-09-08 08:02Brad KingNote Added: 0030959
2012-09-11 15:04Brad KingNote Added: 0031001
2012-09-11 15:04Brad KingStatusassigned => resolved
2012-09-11 15:04Brad KingResolutionopen => fixed
2012-09-11 15:04Brad KingFixed in Version => CMake 2.8.10
2013-03-04 08:38Robert MaynardNote Added: 0032445
2013-03-04 08:38Robert MaynardStatusresolved => closed

Notes
(0030819)
Daniel Pfeifer   
2012-09-02 18:22   
docbook-formatter.patch fixes cmDocumentationFormatterDocbook to generate valid DocBook.

clean-documentation.patch removes some parts of the documentation that cause invalid output. This patch should probably not be applied as-is.

After applying both patches, the validation tests pass.
(0030820)
Brad King   
2012-09-03 10:20   
Thanks for pointing this out and working on the initial patches.

We already run xmllint here:

 http://cmake.org/gitweb?p=cmake.git;a=blob;f=Utilities/CMakeLists.txt;hb=v2.8.9#l134 [^]

to validate the html documentation against the xhtml dtd. See attached 0001-WIP-Add-CMake.Docbook-test-to-validate-docbook-xml-1.patch for the beginning of a change to extend it to test docbook too. Note that we need to include the dtd and its dependencies in the Utilities/xml directory of the source tree. Otherwise the test cannot run fully without network access.

The "fix DocBook documentation formatter" patch is a bit hard to understand because it mixes reformatting of existing code with real changes. Please split it into a series that first does cleanup and then does real changes. Also please explain the errors the changes fix in the commit message.

Finally, the offending documentation should be fixed rather than removed.
(0030940)
Daniel Pfeifer   
2012-09-06 06:49   
Hi Brad,

I uploaded a patch that adds the DocBook DTD to "Utilities/xml/docbook-4.5" and adds the test "CMake.DocBook".

Further,
 * it changes the DTD in cmDocumentationFormatterDocbook.cxx to version 4.5
 * it moves the XHTML1 DTD to "Utilities/xml/xhtml"
 * it %-encodes the spaces in the path of the DTD directory, instead of running the test from the DTD dir and passing "."

The CMake.HTML test still passes (tested with spaces in the path).
The CMake.DocBook test does not pass (obviously).
(0030941)
Brad King   
2012-09-06 09:25   
Thanks. From 0001-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch I extracted the initial refactoring of the CMake.HTML test:

 http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=80e0fc22 [^]

I'd like to avoid adding the CMake.DocBook test until it will pass. Please resubmit your original patch as a series addressing the last two paragraphs of 0013508:0030820.
(0030953)
Daniel Pfeifer   
2012-09-07 07:29   
Hi Brad,

I uploaded a patch series that adds and fixes the docbook validation test.

cheers,
(0030954)
Brad King   
2012-09-07 08:34   
Re 0013508:0030941: I had to add another commit to fix the CMake.HTML test on Windows:

 http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=2ee281c8 [^]
(0030957)
Daniel Pfeifer   
2012-09-08 03:33   
There is no way to misinterpret the colon, so it does not really need to be escaped. Are you sure the "--path" option can be used to help finding DTDs?

I get a lot of "Attempt to load network entity" errors, but they have been there before 80e0fc22 was applied!

To correctly fix these errors, we need to use an entity resolution catalog (see below).


==================================================
The following patches affect the cmDocumentationFormatterDocbook:
* 0001-Remove-table-of-contents-from-generated-DocBook.patch
* 0002-Factor-out-code-to-write-valid-DocBook-IDs.patch
* 0003-Fixed-the-DocBook-output-for-sections.patch
* 0004-Cleanup-of-DocBook-formatter-and-generated-DocBook.patch
* 0005-Add-support-for-abstract-at-section-level-1-in-DocBo.patch

This patch is obsolete (don't apply):
* 0006-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch

This patch fixes a part of cmDocumentation that caused invalid DocBook:
* 0007-Fix-offending-part-of-cmDocumentation-that-caused-in.patch

This patch adds a CMake.ValidateXML test:
* 0001-Add-a-test-to-validate-generated-XML-files-DocBook-a.patch


==================================================
Remove table of contents from generated DocBook

When DocBook is transformed (eg. to PDF, HTML, ...), a TOC is generated from the
document's layout. The TOC-like list that the docbook formatter used to generate
was both redundant and invalid.


==================================================
Factor out code to write valid DocBook IDs

Attributes in XML may contain alphanumeric characters, underscores, colons and
dots. When DocBook is chunked, the dot is often used as a path separator.
To generate a valid ID, we take the title of the section, transform all
non-alphanumeric characters to underscores and then add a prefix separated with
dots. We also add the document name as a prefix, in order to 'xinclude'
eg. cmake.docbook and ctest.docbook in the same document.
IDs are written in multiple places, so the code is factored to a function.


==================================================
Fixed the DocBook output for sections.

The DocBook formatter used to generate something like:

  <para id="section"><sect2><title>Title</title></sect2>Some Text</para>

Which was completely wrong. In DocBook, a section should look like this:

  <sect2 id="section"><title>Title</title><para>Some Text</para></sect2>


==================================================
Cleanup of DocBook formatter and generated DocBook

Comment and whitespace changes, changed docbook version to 4.5, changed
<literallayout> to <programlisting> (the latter implies a fixed-size font).


==================================================
Add support for <abstract> at section level 1 in DocBook formatter.

If a section has subsections (ie. subelemens with a title), all elements before
the first title are written inside an <abstract>.
Also wrap <programlisting> in <para>, to allow preformatted output in abstracts.


==================================================
Fix offending part of cmDocumentation that caused invalid DocBook

If a subsection with a title is added, all subsequent subsections need a title too.


==================================================
Add a test to validate generated XML files (DocBook and XHTML).

Adds an entity resolution catalog with entries for DocBook and XHTML.
All XML files are validated in one test.
(0030958)
Brad King   
2012-09-08 07:53   
"man xmllint" says:

 --path "PATH(S)"
              Use the (space- or colon-separated) list of filesystem paths

so ":" within a path entry must be encoded to avoid being treated as a separator.

I squashed that fix into its parent and then based the rest of the topic on it:

 http://cmake.org/gitweb?p=cmake.git;a=commit;h=53edd90e [^]
(0030959)
Brad King   
2012-09-08 08:02   
I don't get any "Attempt to load network entity" on xmllint 20800. I see them on other versions but they do not cause the test to fail.

If you still think the catalog is needed please base those changes in a new patch on top of the topic I just merged, at commit 9ad85dbb.

Thanks for your work on this!
(0031001)
Brad King   
2012-09-11 15:04   
Topic merged to 'master' here:

 http://cmake.org/gitweb?p=cmake.git;a=commit;h=d07c5f76 [^]

The "CMake.DocBook" test now runs and passes everywhere.

Thanks again for your contribution on this!
(0032445)
Robert Maynard   
2013-03-04 08:38   
Closing resolved issues that have not been updated in more than 4 months.