From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from lists.gentoo.org ([140.105.134.102] helo=robin.gentoo.org) by nuthatch.gentoo.org with esmtp (Exim 4.50) id 1EXuRy-0006PA-Rr for garchives@archives.gentoo.org; Fri, 04 Nov 2005 05:49:19 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.13.5/8.13.5) with SMTP id jA45mc80019150; Fri, 4 Nov 2005 05:48:38 GMT Received: from rwcrmhc12.comcast.net (rwcrmhc13.comcast.net [204.127.198.39]) by robin.gentoo.org (8.13.5/8.13.5) with ESMTP id jA45koSW006658 for ; Fri, 4 Nov 2005 05:46:51 GMT Received: from [67.191.242.121] (c-67-191-242-121.hsd1.ga.comcast.net[67.191.242.121]) by comcast.net (rwcrmhc13) with ESMTP id <2005110405464901500l1sk8e>; Fri, 4 Nov 2005 05:46:49 +0000 Message-ID: <436AF548.8070406@ieee.org> Date: Fri, 04 Nov 2005 00:44:40 -0500 From: "Nathan L. Adams" User-Agent: Mozilla Thunderbird 1.0.6 (X11/20050722) X-Accept-Language: en-us, en Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Reply-to: gentoo-dev@lists.gentoo.org MIME-Version: 1.0 To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] GLEP ??: Critical News Reporting References: <20051101015125.1cc45eb4@snowdrop.home> <200511011722.29840.jkt@gentoo.org> <20051101182506.4dd701f6@snowdrop.home> <436A1576.5070909@ieee.org> <20051103191642.1fbdbd9d@snowdrop.home> <436AAB79.4020700@ieee.org> <20051104004247.0ff50ff0@snowdrop.home> <436AB342.9040606@ieee.org> <20051104020844.GB29252@dst.grantgoodyear.org> In-Reply-To: <20051104020844.GB29252@dst.grantgoodyear.org> X-Enigmail-Version: 0.92.0.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-Archives-Salt: 8d0d0eb4-ca7e-4643-9e67-7ba69da7671d X-Archives-Hash: f1742d123ae984828c9af38640317b40 -----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