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

[Nathan L. Adams]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Grant Goodyear wrote:
> 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).

Oh good grief! Nobody is arguing that the user should have to read raw XML.

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

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.

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

Great; I'm not against that. Now where does that admin point her web
browser? Mailing list archive? GWN archive? The Forums? The stated
feedback is that users what a central place for the errata (whether the
errata be large or small).

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

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?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFDavVI2QTTR4CNEQARAnMnAKCAir22mvnCgoKXc8xPDIYaQMmReACdELKr
aa1l8avqCC7nIvV/VypyJj8=
=LxgP
-----END PGP SIGNATURE-----
-- 
gentoo-dev@g.o mailing list