GNOME Bugzilla – Bug 142098
Documentation incomplete
Last modified: 2006-04-02 16:41:50 UTC
doc/{en,pl}/dia.xml includes many other xml and sgml files, but those are not present. Former versions of dia shipped the documentation in compiled form (html). But since this seems to be dropped in 0.93, documentation is just missing.
Looking at the contents of CVS, it seems that the Makefile.am's just don't include the respective XML files into the distribution.
Yep. They're now in there. Kinda had expected them to be magically include, but it's just ain't that easy.
Now that the files are included, there are problems with the XML contents for the pl version: ================================================================================= ernie@atari:~/debian/dia-0.94-pre1$ xmlto -o doc/pl/manual html doc/pl/dia.xml xmlto: input does not validate (status 1) /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:4: parser error : Input is not proper UTF-8, indicate encoding ! <title>Co mo�na zrobi�?</title> ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:4: error: Bytes: 0xBF 0x6E 0x61 0x20 <title>Co mo�na zrobi�?</title> ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:21: parser error : Opening and ending tag mismatch: graphic line 20 and screenshot </screenshot> ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:22: parser error : Opening and ending tag mismatch: screenshot line 16 and figure </figure> ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:23: parser error : Opening and ending tag mismatch: figure line 14 and para </para> ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:24: parser error : Opening and ending tag mismatch: para line 5 and sect1 </sect1> ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:155: parser error : Opening and ending tag mismatch: sect1 line 3 and chapter </chapter> ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:156: parser error : Premature end of data in tag chapter line 1 ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml:156: parser error : chunk is not well balanced ^ /home/ernie/debian/dia-0.94-pre1/doc/pl/dia.xml:58: parser error : chunk is not well balanced &QUICKSTART; ^ ernie@atari:~/debian/dia-0.94-pre1$ ================================================================================= This works for the en version.
Note that this only works when the referenced sgml files are present. I guess the currently referenced sgml files are meant to be the actually present xml files. With the original 0.94-pre1 version, I get: ================================================================================ ernie@atari:~/debian/dia-0.94-pre1$ xmlto -o doc/pl/manual html doc/pl/dia.xml xmlto: input does not validate (status 3) I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-quickstart.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-canvas.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-objects.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-objects-special.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-objects-selecting.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-loadsave.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-customization.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/usage-layers.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/authors.sgml" I/O warning : failed to load external entity "/home/ernie/debian/dia-0.94-pre1/doc/pl/license.sgml" /home/ernie/debian/dia-0.94-pre1/doc/pl/dia.xml:20: element book: validity error : root and DTD name do not match 'book' and 'Book' Document /home/ernie/debian/dia-0.94-pre1/doc/pl/dia.xml does not validate ernie@atari:~/debian/dia-0.94-pre1$ ================================================================================
The SGML files are not meant to be used any more, any references to them should be replaced with references to the XML files. Why it complains about the &#XXXX; entries I don't get. Let's concentrate on getting the SGML out -- the XML files seem to be all clean in the CVS, do you still get errors when trying to compile?
I needed to change some things (you don't regularly check the docbook files for correct syntax, do you? :). Then, it worked fine. See patch.
Created attachment 38009 [details] [review] documentation docbook syntax fixes This makes the en|pl documentation compile with e.g. xmlto -o doc/en/manual html doc/en/dia.xml
Fixed itself? :-)
It's nearly fixed. Please change the DOCTYPE Book in doc/pl/dia.xml from uppercase to lowercase (-> "DOCTYPE book") as in doc/en/dia.xml.
Thanks, commited. 2006-04-02 Hans Breuer <hans@breuer.org> * doc/pl/dia.xml : "DOCTYPE book" closes bug #142098, Roland Stigge