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 [EMAIL PROTECTED] http://www.gentoo.org/~g2boojum GPG Fingerprint: D706 9802 1663 DEF5 81B0 9573 A6DC 7152 E0F6 5B76
pgppllN4FWKVp.pgp
Description: PGP signature
