Gentoo Archives: gentoo-doc

From: Xavier Neys <neysx@g.o>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] Project-specific documentation and dynamic documentation index
Date: Fri, 26 Nov 2004 18:16:48
In Reply to: [gentoo-doc] Project-specific documentation and dynamic documentation index by Sven Vermeulen
Sven Vermeulen wrote:
> Hi all > > Xavier kindly pointed me to a problem I'm now facing with the documentation > metadata that allows us to dynamically generate a documentation index. > > Now on to the issue: the XSLT code we use sources the linked documents to > get their version, summary, title, etc. As long as all documents exist, this > isn't a problem. However, when a document is removed from CVS, sourcing the > inexisting document yields a "Internal Server 500" error which just doesn't > look nice. > > However, when dealing with project-specific documentation (such as the > Hardened Docs), the responsibility of the document itself is in hands of the > project documentation developer, not ours. This also means that "they" will > undoubtedly (re)move their documents without prior notice to the > documentation team. Each such action will lead to a "Internal Server 500" > error.
AxKit does. I have no idea whether that behaviour can be changed or not. Gorg makes an error 500 on all errors and warnings. *We* can easily change that. More about that later.
> Their are a few solutions to this: > > We can implement any QA-tool on client-side ("repodoc") and keep asking all > developers to use repodoc to operate on xml files. Since they're usually > used to working with repoman, I don't think too much objections will be > stated. > > We can implement a QA-tool on server-side (extend the current XML-Checker) > that verifies if the removal of a file can happen (see if the file is listed > in the English metadoc.xml) and, if not, issue an error. > > We can request the used xml parsers on our webnodes to return an empty > node-set instead of generating an error and update our XSLT to verify if the > returned node-set is empty. If it is, ignore the document. We can then > create a new chapter in the overview-dyn.xml document that lists all > non-existing documents. > > This latter solution is possible with Xavier's gorg application but has the > drawback that any other issues with missing xml files (for instance, > checking a handbook that lacks some files) will need to be covered in the > XSLT as well. The advantage is however that a nicer error can be shown to > the user that has a bit more information.
I would say all three to have several lines of defence. 1) The server-side script must block on critical errors like a non-valid file. We could add a check on the link attribute. It could check other things but not get in the way of other devs, e.g. it should not block when a hardened doc is (re)moved just because it would break our metadoc but it could mail docs-team@.g.o (or a new docs-warning@g.o) about metadoc.xml needing some TLC whenever a listed document is being removed. Overhead would be minimal as files are not (re)moved very often. 2) A client-side QA tool would be in our hands and could do miracles like: . checking/copying <version> & <date> elements in translations; . check/add the lang attribute; . check/fix the link attribute. Just keep throwing ideas of what it would need to do. 3) About the "failed to load external entity {file.xml}" warning: We could make gorg return an empty xml file e.g. "<empty/>" to libxslt. That would make the warning completely disappear. IMHO, there is no need to go that far. The only reason gorg makes it an error 500 is that AxKit does. I had originally made gorg ignore all warnings and use whatever comes back from the xslt processor. Gorg's cache can already handle missing dependencies and it makes a new html when a missing file is added. It would be rather trivial to add a parameter to gorg's config to make it ignore a list of given warnings and we would start with IgnoreWarnings=1549 Missing document()'ed files can be tested in xsl if needed: <xsl:variable name="M" select="document('month.xml')"/> <xsl:choose> <xsl:when test="$M"> <date><xsl:copy-of select="$M/datedata/months[@lang='fr']/month[6]"/></date> </xsl:when> <xsl:otherwise> <date>NONE!</date> </xsl:otherwise> </xsl:choose> 1) and 3) can be implemented quickly. 2) needs more specs With kind regards, -- / Xavier Neys \_ Gentoo Documentation Project / French & Internationalisation Lead \ /\


File name MIME type
signature.asc application/pgp-signature