-----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@gentoo.org mailing list
