[[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
