| 1 |
Nathan L. Adams wrote: [Thu Nov 03 2005, 07:02:58PM CST] |
| 2 |
> -----BEGIN PGP SIGNED MESSAGE----- |
| 3 |
> Hash: SHA1 |
| 4 |
> |
| 5 |
> Ciaran McCreesh wrote: |
| 6 |
> > Read the list of requirements in the GLEP. The plain text solution |
| 7 |
> > meets all of them. XML fails on several. |
| 8 |
> |
| 9 |
> If readability isn't a requirement, your list is wrong. |
| 10 |
|
| 11 |
I would argue that reading raw xml is a lot less fun than reading minimally |
| 12 |
marked-up plain text (such as an e-mail). |
| 13 |
|
| 14 |
> > | So what are the trade-offs of the 'flat file'? If you store a |
| 15 |
> > | migration guide as a 'flat file', its not going to be very readable. |
| 16 |
> > |
| 17 |
> > Who said anything about storing a migration guide as a flat file? Read |
| 18 |
> > the GLEP. |
| 19 |
> |
| 20 |
> No, *you* need to read my previous response. I was using 'flat file' to |
| 21 |
> mean whatever it is you're calling your less-than-GuideXML scheme. |
| 22 |
|
| 23 |
*Sigh* I think you might be misinterpreting the GLEP. The news items |
| 24 |
are likely to be fairly short, such as the "YourSQL" example that's in |
| 25 |
the GLEP. The news item would then point to a migration guide that |
| 26 |
resides elsewhere, if needed. |
| 27 |
|
| 28 |
The point behind having the news pulled by portage is that the headless |
| 29 |
server, for example, would only report news items that are relevant to |
| 30 |
that machine. The server's admin could then fire up a web browser on a |
| 31 |
desktop machine to read any necessary additional info. |
| 32 |
|
| 33 |
> > | GuideXML is the standard for Gentoo docs for some damn good reasons! |
| 34 |
|
| 35 |
True, but at the same time there's a reason that GLEPs can be written in |
| 36 |
restructured text as well as guidexml. I doubt that it's accidental |
| 37 |
that almost all GLEPs have been submitted in restructured text rather |
| 38 |
than guidexml. (Incidentally, I like our guidexml. I think that it |
| 39 |
renders quite well for what we want. I'm not so fond of writing it, |
| 40 |
however.) |
| 41 |
|
| 42 |
That's really beside the point, though. The real point is that plain |
| 43 |
text news items are going to be the easiest to create and the easiest to |
| 44 |
read on a console screen. |
| 45 |
|
| 46 |
As for having an errata page, it wouldn't be difficult to write a |
| 47 |
program to automatically convert news items to guidexml. I suspect that |
| 48 |
ciaranm could even be talked into writing it, if such a page were to |
| 49 |
become reality. |
| 50 |
|
| 51 |
-g2boojum- |
| 52 |
-- |
| 53 |
Grant Goodyear |
| 54 |
Gentoo Developer |
| 55 |
g2boojum@g.o |
| 56 |
http://www.gentoo.org/~g2boojum |
| 57 |
GPG Fingerprint: D706 9802 1663 DEF5 81B0 9573 A6DC 7152 E0F6 5B76 |
Archives