On Friday 04 November 2005 09:32, John Myers wrote:
> [[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

Oh god help. This also points to another reason why this is not such a 
good idea. Writing guideXML is a lot more work than writing an e-mail 
format file (ciaran's proposed format for those who didn't recognize it).

Also having double files containing the same information is broken by 
design. This doesn't mean that all information should be in the news 
file. Let me give an example that would have been relevant some time ago.

Title: Incompatible subversion repository change
Author: Paul de Vrieze <pauldv@gentoo.org>
Content-Type: text/plain
Posted: 2005-11-04
Version: 1
Display-If-Installed: <dev-util/subversion-0.34.0

Subversion has a new repository layout. This new layout is incompatible 
with repositories created with versions before 0.34.0. If you only use 
this machine as client, there are no consequences.

If this machine contains repositories however, these must be dumped before 
installing >=dev-util/subversion-0.34.0. After installation new 
repositories can be created and the dumps can be reloaded.

For more information on dumping and loading see the subversion migration 
guide:
http://subversion.tigris.org/subversion_migration.


<the above url is not correct, everything else would have been>

If I have to write such a file in guidexml it would be a lot more 
complicated. Further this news item would only be relevant to people 
providing older subversion repositories wanting to update. As erata would 
contain all these files, it would be a swamp, hard to wade through.

I also fail to see where such a file as illustrated above is unclear to 
read. I prefer it over a bloated webpage with all kinds of slowness and 
eyecandy.

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net