I followed the XML Guide as closely as possible, but I can't transform GuideXML documents into HTML correctly. Either something in Gentoo has changed since the guide was written or it failed to mention an important detail. Reproducible: Always Steps to Reproduce: 1.emerge libxslt 2.download "http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz" and untar it 3.cd into the newly created "htdocs" directory 4.issue the command "xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml > /tmp/install.html" Actual Results: The HTML output has many "
I followed the XML Guide as closely as possible, but I can't transform GuideXML documents into HTML correctly. Either something in Gentoo has changed since the guide was written or it failed to mention an important detail. Reproducible: Always Steps to Reproduce: 1.emerge libxslt 2.download "http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz" and untar it 3.cd into the newly created "htdocs" directory 4.issue the command "xsltproc xsl/guide.xsl doc/en/gentoo-x86-install.xml > /tmp/install.html" Actual Results: The HTML output has many "Â" (capital "A" with the circumflex diacritic mark) characters at ends of section title lines, though this character appears nowhere in the source GuideXML file. In addition, xsltproc issues this warning on stderr: ------------------------------------------------------------------------ doc/en/gentoo-x86-install.xml:2: warning: failed to load external entity "/dtd/guide.dtd" <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> ^ ------------------------------------------------------------------------ Expected Results: no warnings about missing DTDs and correct HTML output
the /dtd/guide.dtd is needed because that is the path on the Gentoo webserver ... further in the documentation are a bunch of notes about this ...
What documentation mentions "/dtd/guide.dtd"? I can't find anything about it in the "Gentoo Linux XML Guide" (http://www.gentoo.org/doc/en/xml-guide.xml). The warning is only an annoyance, though I'd like to get rid of it. Where can I learn how to point xsltproc to the DTD? I read the man page and tried specifying catalog files, all to no avail. What about the spurious characters? I've found a couple of bug reports about the same characters in specific guides, but no indication of the root cause. I seem to get them in every guide I transform.
the cheap way i do it w/out any hacking is this: `ln -s /usr/local/gentoo/xml/htdocs/dtd /dtd` that way /dtd/guide.dtd is a valid file ;) gentoo is the cvs module found on the cvs server ...
These are both known issues, but cannot be fixed in the first degree, as it is the difference between a live server (with /dtd/guide.dtd and a combination of four xsl-files) and a locally created "repository". Please check out http://www.gentoo.org/proj/en/gdp/doc/en/docdev.xml; it gives an explanation how to set up a local repository which doesn't have these problems (as it uses an altered guide.xsl version). The xml-guide does need to be updated to reflect this though.
Can't help with those spurious characters. I xsltproc our docs all the time and never have seen this happen here. About the missing DTD warning. 1) You can avoid the warning by not checking the DTD at all. xsltproc DOES check that your xml file IS an xml file. Use the --novalid options. 2) If you do want to validate it without doing spanky's ugly hack, use the --catalogs option (man xsltproc) like this: You can either define the guide dtd in /etc/xml/catalog or use your own copy of this file. I did not want to mess up my "official" /etc/xml/catalog so I created a catalog.gentoo which looks like this: <?xml version="1.0"?> <!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <system systemId="/dtd/guide.dtd" uri="/home/neysx/gentoo.org/gentoo/xml/htdocs/dtd/guide.dtd"/> </catalog> Adapt the uri to your system. Use xsltproc like this SGML_CATALOG_FILES="./catalog.gentoo" xsltproc --catalogs -o vi-guide.html ../../gentoo/xml/htdocs/xsl/guide.xsl vi-guide.xml Or simply export the SGML_CATALOG_FILES env variable. The actual xsltproc command line sits in a script here, I don't type it all every time ;-) Hth
Thanks for all the great suggestions. I was aware that validation wasn't strictly necessary, but I'll try the suggestions to provide a catalog to allow xsltproc to resolve the external entity. The main mystery is the about the generated
Thanks for all the great suggestions. I was aware that validation wasn't strictly necessary, but I'll try the suggestions to provide a catalog to allow xsltproc to resolve the external entity. The main mystery is the about the generated Âs.
AFAIK, the
AFAIK, the Â's come from  's in the guide.xsl template. Those aren't there in the guide.xsl made for local usage (http://emu.gentoo.org/~swift/local/guide.xsl). I'll check when those were added in the official stylesheets and why.
I used http://emu.gentoo.org/~swift/local/guide.xsl and everything looks good now.
Since we have a docdev guide, perhaps it is wise to reference to it from the xml-guide, and remove all the blabla from the current guide. The docdev guide contains all information on testing xml-guides (including tarball usage etc.) I'll put up a patch that does this.
Created attachment 19814 [details, diff] Patch to reference the docdev guide This should do it. If a docdev can review?
One word to the missing guide.xsl during xsltproc: Update the doctype-line in the document so that it reads <!DOCTYPE guide SYSTEM "http://www.gentoo.org/dtd/guide.dtd"> xsltproc will fetch the guide.dtd from the website instead of somewhere in the local filesystem.
patch reviewed
Committed.
