View Issue Details Jump to Notes ] Print ]
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.
Attached Filespatch file icon validate-test.patch [^] (1,957 bytes) 2012-09-02 18:16 [Show Content]
patch file icon docbook-formatter.patch [^] (9,354 bytes) 2012-09-02 18:16 [Show Content]
patch file icon clean-documentation.patch [^] (1,593 bytes) 2012-09-02 18:16 [Show Content]
patch file icon 0001-WIP-Add-CMake.Docbook-test-to-validate-docbook-xml-1.patch [^] (7,471 bytes) 2012-09-03 10:15 [Show Content]
patch file icon 0001-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch [^] (615,409 bytes) 2012-09-06 06:38
patch file icon 0001-Remove-table-of-contents-from-generated-DocBook.patch [^] (1,625 bytes) 2012-09-07 07:23 [Show Content]
patch file icon 0002-Factor-out-code-to-write-valid-DocBook-IDs.patch [^] (5,374 bytes) 2012-09-07 07:24 [Show Content]
patch file icon 0003-Fixed-the-DocBook-output-for-sections.patch [^] (2,522 bytes) 2012-09-07 07:24 [Show Content]
patch file icon 0004-Cleanup-of-DocBook-formatter-and-generated-DocBook.patch [^] (4,052 bytes) 2012-09-07 07:24 [Show Content]
patch file icon 0005-Add-support-for-abstract-at-section-level-1-in-DocBo.patch [^] (2,355 bytes) 2012-09-07 07:24 [Show Content]
patch file icon 0006-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch [^] (498,786 bytes) 2012-09-07 07:24
patch file icon 0007-Fix-offending-part-of-cmDocumentation-that-caused-in.patch [^] (1,108 bytes) 2012-09-07 07:24 [Show Content]
patch file icon 0001-Add-a-test-to-validate-generated-XML-files-DocBook-a.patch [^] (501,042 bytes) 2012-09-07 18:30

 Relationships

  Notes
(0030819)
Daniel Pfeifer (reporter)
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 (manager)
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 (reporter)
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 (manager)
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 (reporter)
2012-09-07 07:29

Hi Brad,

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

cheers,
(0030954)
Brad King (manager)
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 (reporter)
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 (manager)
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 (manager)
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 (manager)
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 (manager)
2013-03-04 08:38

Closing resolved issues that have not been updated in more than 4 months.

 Issue History
Date Modified Username Field Change
2012-09-02 18:16 Daniel Pfeifer New Issue
2012-09-02 18:16 Daniel Pfeifer File Added: validate-test.patch
2012-09-02 18:16 Daniel Pfeifer File Added: docbook-formatter.patch
2012-09-02 18:16 Daniel Pfeifer File Added: clean-documentation.patch
2012-09-02 18:22 Daniel Pfeifer Note Added: 0030819
2012-09-03 10:15 Brad King File Added: 0001-WIP-Add-CMake.Docbook-test-to-validate-docbook-xml-1.patch
2012-09-03 10:20 Brad King Note Added: 0030820
2012-09-06 06:38 Daniel Pfeifer File Added: 0001-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch
2012-09-06 06:49 Daniel Pfeifer Note Added: 0030940
2012-09-06 09:25 Brad King Note Added: 0030941
2012-09-07 07:23 Daniel Pfeifer File Added: 0001-Remove-table-of-contents-from-generated-DocBook.patch
2012-09-07 07:24 Daniel Pfeifer File Added: 0002-Factor-out-code-to-write-valid-DocBook-IDs.patch
2012-09-07 07:24 Daniel Pfeifer File Added: 0003-Fixed-the-DocBook-output-for-sections.patch
2012-09-07 07:24 Daniel Pfeifer File Added: 0004-Cleanup-of-DocBook-formatter-and-generated-DocBook.patch
2012-09-07 07:24 Daniel Pfeifer File Added: 0005-Add-support-for-abstract-at-section-level-1-in-DocBo.patch
2012-09-07 07:24 Daniel Pfeifer File Added: 0006-Add-CMake.DocBook-test-to-validate-docbook-xml-13508.patch
2012-09-07 07:24 Daniel Pfeifer File Added: 0007-Fix-offending-part-of-cmDocumentation-that-caused-in.patch
2012-09-07 07:29 Daniel Pfeifer Note Added: 0030953
2012-09-07 08:34 Brad King Note Added: 0030954
2012-09-07 18:30 Daniel Pfeifer File Added: 0001-Add-a-test-to-validate-generated-XML-files-DocBook-a.patch
2012-09-08 03:33 Daniel Pfeifer Note Added: 0030957
2012-09-08 07:53 Brad King Note Added: 0030958
2012-09-08 07:54 Brad King Assigned To => Brad King
2012-09-08 07:54 Brad King Status new => assigned
2012-09-08 07:55 Brad King Target Version => CMake 2.8.10
2012-09-08 08:02 Brad King Note Added: 0030959
2012-09-11 15:04 Brad King Note Added: 0031001
2012-09-11 15:04 Brad King Status assigned => resolved
2012-09-11 15:04 Brad King Resolution open => fixed
2012-09-11 15:04 Brad King Fixed in Version => CMake 2.8.10
2013-03-04 08:38 Robert Maynard Note Added: 0032445
2013-03-04 08:38 Robert Maynard Status resolved => closed


Copyright © 2000 - 2018 MantisBT Team