Re: [gentoo-doc] Project-specific documentation and dynamic documentation index

[Xavier Neys]

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
\  http://www.gentoo.org/doc/en
/\