Re: [gentoo-dev] GLEP ??: Critical News Reporting

[Grant Goodyear <g2boojum@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 2386 bytes --]

Nathan L. Adams wrote: [Thu Nov 03 2005, 07:02:58PM CST]
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Ciaran McCreesh wrote:
> > Read the list of requirements in the GLEP. The plain text solution
> > meets all of them. XML fails on several.
> 
> If readability isn't a requirement, your list is wrong.

I would argue that reading raw xml is a lot less fun than reading minimally
marked-up plain text (such as an e-mail).

> > | So what are the trade-offs of the 'flat file'? If you store a
> > | migration guide as a 'flat file', its not going to be very readable.
> > 
> > Who said anything about storing a migration guide as a flat file? Read
> > the GLEP.
> 
> No, *you* need to read my previous response. I was using 'flat file' to
> mean whatever it is you're calling your less-than-GuideXML scheme.

*Sigh*  I think you might be misinterpreting the GLEP.  The news items
are likely to be fairly short, such as the "YourSQL" example that's in
the GLEP.  The news item would then point to a migration guide that
resides elsewhere, if needed.

The point behind having the news pulled by portage is that the headless
server, for example,  would only report news items that are relevant to
that machine.  The server's admin could then fire up a web browser on a
desktop machine to read any necessary additional info.

> > | GuideXML is the standard for Gentoo docs for some damn good reasons!

True, but at the same time there's a reason that GLEPs can be written in
restructured text as well as guidexml.  I doubt that it's accidental
that almost all GLEPs have been submitted in restructured text rather
than guidexml.  (Incidentally, I like our guidexml.  I think that it
renders quite well for what we want.  I'm not so fond of writing it,
however.)

That's really beside the point, though.  The real point is that plain
text news items are going to be the easiest to create and the easiest to
read on a console screen.

As for having an errata page, it wouldn't be difficult to write a
program to automatically convert news items to guidexml.  I suspect that
ciaranm could even be talked into writing it, if such a page were to
become reality.

-g2boojum-
-- 
Grant Goodyear	
Gentoo Developer
g2boojum@gentoo.org
http://www.gentoo.org/~g2boojum
GPG Fingerprint: D706 9802 1663 DEF5 81B0  9573 A6DC 7152 E0F6 5B76

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]