[[ACK! I sent this out from the wrong address before. Hope you don't get it twice!]] On Thursday 03 November 2005 21:44, Nathan L. Adams wrote: > No, I happen to understand the that point. Emerge outputting a short > summary is great. But the GLEP should cover the "hey mr. end user, the > central repository for errata/full fledged migration guides is here: > [insert url]" as well. [snip] > I happen to think that the assumption that the errata are going to be > small is a bad one. I think if errata is neccessary in the first place > then its going to be something larger than a screen's worth of console > output and worth the supposed trouble of GuideXML. So why not approach > it from the GuideXML end first, and extract the summary from that? Here's an idea for a compromise solution. Sorry it's so messy:
The errata entries would consist of two files per language: - An emerge news file, identical to the format ciaranm proposed. This file would give a very general notice of the issue, such as that given as an example in the GLEP, as well as containing the machine-readable commands for portage to control display. This file's name would end in .news.<LC>.txt - A GuideXML-formatted errata document. This would be the actual migration guide, such as the contents of the http://www.gentoo.org/doc/en/yoursql-upgrading.xml referenced by the example. This file's name would end in .guide.<LC>.xml - The leading part of the filename would be as in ciaranm's GLEP Once it is time for the errata item to be published (after review, etc.), the files would be placed in a standard location, where an automated process would pick them up. The news files would be transferred to the Portage tree for emerge to pick up, and simultaneously published to a central errata website, e.g. http://errata.gentoo.org/. On the errata website, *all* errata notices would be published to its front page, unless specified differently by each individual user (perhaps a feature storing filters in a cookie). Each entry in the list would contain at least the publication date, the title of the news item as a link to a news item page, and the title of the guideXML document as a link to the document. Errata items would be accessible in a uniform namespace with names derived from their source filenames. For example: 2005-11/2005-11-01-mysql-4.0-4.1-upgrade.news.en.txt 2005-11/2005-11-01-mysql-4.0-4.1-upgrade.guide.en.xml might become: http://errata.gentoo.org/2005-11-01-mysql-4.0-4.1-upgrade/en/ http://errata.gentoo.org/2005-11-01-mysql-4.0-4.1-upgrade/en/guide.xml For user convenience, URLs with language codes the text is not yet translated to, as well as URLs without a language code, should be redirected to the English version. Errata items may be published in other areas for wider exposure, but should always contain a link back to the main source. The news item page would contain a copy of the news text typeset in a fixed-width font, and with links made clickable, as well as a prominent link to the GuideXML document. The title of the page should be the title of the news item, and the title of the link to the GuideXML page should be the title of the GuideXML document. Questions? Comments?
pgpHAcs3R8c1G.pgp
Description: PGP signature