From davep at dpawson.co.uk Sun Aug 1 12:24:44 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 01 Aug 2004 13:24:44 +0100 Subject: Using elvis? In-Reply-To: <20040731225151.GA20834@www.pagan.org.uk> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <200407301132.58369.hoyt@cavtel.net> <1091225022.10960.19.camel@bettie.internal.frields.org> <1091258576.2049.38.camel@homer> <1091282516.16376.21.camel@bettie.internal.frields.org> <20040731225151.GA20834@www.pagan.org.uk> Message-ID: <1091363084.2022.18.camel@homer> On Sat, 2004-07-31 at 23:51, Telsa Gwynne wrote: > I am really going to regret saying this. But... > My Docbook learning experience is a little while ago now, and I > expect a new one shortly. But the "which part" is easy: > > Emacs. > > I realise this is a holy war, > I am sorry. I do not think this is the answer you wanted to > hear! But for me, the problem was an editor that didn't seem > to fit me, for which every manual was written. Perfectly good answer. I am told that vim has an xml mode too, but I don't use vim, so I can't point you to it. I think the *use emacs* mandate is too strong, but your point about needing Unicode is well taken. Any text editor that supports Unicode, or an understanding of Numerical code points is necessary. > > As for installing, I am the wrong person to comment, because > from my point of view it has become a lot easier. (But it was > hell before.) I just ensure that DocBook and stylesheets are > selected in the install. And hope that they'll pull the rest > in. Hoorah for dependencies. Having done it before, and suffered, I'm now able to do a full docbook install without problems. The docbook community update so frequently that you need to be able to re-install without pain :-) Google on vim xml gets some results. Tobias seems to have documented it; I'm sure there is plenty around, if you want it? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sun Aug 1 12:34:01 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 01 Aug 2004 13:34:01 +0100 Subject: [Fwd: USB Key and Fedora Core 2/Gnome2.6 How-To] In-Reply-To: <1091297233.24634.27.camel@hermione.aeon.com.my> References: <1091297233.24634.27.camel@hermione.aeon.com.my> Message-ID: <1091363640.2022.29.camel@homer> On Sat, 2004-07-31 at 19:07, Colin Charles wrote: > Don't know if we can make this of use in the Docs Project, but it might > be handy > > The author, and Tim has been CC'ed as well > > This adds to Tim Waugh's guide http://cyberelk.net/tim/usb-storage.html, > and I think will make a good HOWTO/Guide for the docs project > In thanks, I wrote a simple and to the point How-To for using autofs to > mount a USB memory key on a Fedora Core 2 system. The How-To is > available here: > > http://www.systemsaligned.com/learn/howto/hwtusbkey I needed this last week :-) I think that's an excellent addition to the docs project. I wasn't aware of the hardware probe via the menu system, so did it via a terminal! I also mounted it using /etc/fstab rather than the more useful option mentioned! What next? reference it from Fedora-docs, or move it to docbook for addition, if the author is OK for that? btw, this also raises the fc1 fc2 issue. the method works with fc1, so it would be a good testbed for marking up, entity extensions etc. ** action required from project lead** :-) regards DaveP -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Sun Aug 1 14:30:11 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 01 Aug 2004 10:30:11 -0400 Subject: [Fwd: USB Key and Fedora Core 2/Gnome2.6 How-To] In-Reply-To: <1091297233.24634.27.camel@hermione.aeon.com.my> References: <1091297233.24634.27.camel@hermione.aeon.com.my> Message-ID: <1091370611.23345.23.camel@bettie.internal.frields.org> On Sat, 2004-07-31 at 14:07, Colin Charles wrote: > Don't know if we can make this of use in the Docs Project, but it might > be handy [...snip...] > In thanks, I wrote a simple and to the point How-To for using autofs to > mount a USB memory key on a Fedora Core 2 system. The How-To is > available here: > > http://www.systemsaligned.com/learn/howto/hwtusbkey > > I have noticed other How-To's out there about this very same subject, or > close to it. They are helpful too, but I wanted to write a How-To as > well with my own little slant to it. I know from experience that the > more there is written about an open source tool, the easier it has been > for me to get new things working. You can never have enough > documentation, tips and tricks, eh? I got about halfway there in my updfstab-tutorial for FDP (at http://docs.frields.org if anyone cares), but there's two things I need to add: 1. from Tim's document, the section on checking USB device ID's in the distmap 2. Add the fact that if you run updfstab [-t] as root, there's no need to do any logging in, etc. The only problem that I've seen in Fedora Core (both 1 and 2) is that the usb-storage module doesn't go away fast enough to accommodate removal and reinsertion of the device after only a minute or two. I haven't spent much time looking at that problem, but if someone wants to offer a solution (off-list please!) feel free. The author using autofs is actually taking kind of the long way around, I think. After I update my updfstab-tutorial I will e-mail a link to him. -- Paul W. Frields, RHCE From rodolfo at heartsome.net Sun Aug 1 14:57:47 2004 From: rodolfo at heartsome.net (Rodolfo M. Raya) Date: Sun, 01 Aug 2004 11:57:47 -0300 Subject: Using elvis? In-Reply-To: <1091363084.2022.18.camel@homer> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <200407301132.58369.hoyt@cavtel.net> <1091225022.10960.19.camel@bettie.internal.frields.org> <1091258576.2049.38.camel@homer> <1091282516.16376.21.camel@bettie.internal.frields.org> <20040731225151.GA20834@www.pagan.org.uk> <1091363084.2022.18.camel@homer> Message-ID: <1091372267.31790.115.camel@elrond.maxprograms.com> On Sun, 2004-08-01 at 09:24, Dave Pawson wrote: > I think the *use emacs* mandate is too strong, but your point > about needing Unicode is well taken. > Any text editor that supports Unicode, or an understanding of > Numerical code points is necessary. Hi, There are several free XML editors that can be used to edit DocBook documents. Being a vi user that does not need/want to learn emacs, I prefer a good Java based XML editor to do my XML editing. I think that http://fedora.redhat.com/projects/docs/ should be changed, giving potential contributors some alternatives besides recommending Emacs with PSGML mode. My 0.02, Rodolfo -- Rodolfo M. Raya Heartsome Holdings Pte. Ltd. From rodolfo at heartsome.net Sun Aug 1 15:22:05 2004 From: rodolfo at heartsome.net (Rodolfo M. Raya) Date: Sun, 01 Aug 2004 12:22:05 -0300 Subject: Using elvis? In-Reply-To: <1091372267.31790.115.camel@elrond.maxprograms.com> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <200407301132.58369.hoyt@cavtel.net> <1091225022.10960.19.camel@bettie.internal.frields.org> <1091258576.2049.38.camel@homer> <1091282516.16376.21.camel@bettie.internal.frields.org> <20040731225151.GA20834@www.pagan.org.uk> <1091363084.2022.18.camel@homer> <1091372267.31790.115.camel@elrond.maxprograms.com> Message-ID: <1091373725.31790.118.camel@elrond.maxprograms.com> On Sun, 2004-08-01 at 11:57, Rodolfo M. Raya wrote: > I think that http://fedora.redhat.com/projects/docs/ should be changed, > giving potential contributors some alternatives besides recommending > Emacs with PSGML mode. This page, from TLDP, provides interesting information: http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html Regards, Rodolfo -- Rodolfo M. Raya Heartsome Holdings Pte. Ltd. From Tommy.Reynolds at MegaCoder.com Sun Aug 1 17:15:53 2004 From: Tommy.Reynolds at MegaCoder.com (Tommy Reynolds) Date: Sun, 1 Aug 2004 12:15:53 -0500 Subject: Using elvis? In-Reply-To: <1091373725.31790.118.camel@elrond.maxprograms.com> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <200407301132.58369.hoyt@cavtel.net> <1091225022.10960.19.camel@bettie.internal.frields.org> <1091258576.2049.38.camel@homer> <1091282516.16376.21.camel@bettie.internal.frields.org> <20040731225151.GA20834@www.pagan.org.uk> <1091363084.2022.18.camel@homer> <1091372267.31790.115.camel@elrond.maxprograms.com> <1091373725.31790.118.camel@elrond.maxprograms.com> Message-ID: <20040801121553.5f89a8a6.Tommy.Reynolds@MegaCoder.com> Uttered "Rodolfo M. Raya" , spake thus: > This page, from TLDP, provides interesting information: > http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html We all have preferences about this, but I suggest http://www.jedit.org for a java-based not-crippleware alternative. It will validate against a custom DTD, unlike some of the tldp.org tools. After being a vi-guy for a few decades, jedit is now my XML editor of choice. It's also easily usable for a newbie. Cheers! From kwade at redhat.com Sun Aug 1 17:31:34 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 01 Aug 2004 10:31:34 -0700 Subject: Using elvis? In-Reply-To: <1091362203.2022.10.camel@homer> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <1091203967.2020.20.camel@homer> <1091223825.11946.13466.camel@erato.phig.org> <1091258329.2049.33.camel@homer> <1091297927.11946.14760.camel@erato.phig.org> <1091362203.2022.10.camel@homer> Message-ID: <1091381494.11946.16186.camel@erato.phig.org> Did you mean to take this off-list? I accidentally sent this message directly to you yesterday before bouncing a copy to the list ... since you are addressing issues that others have brought up, I'm going to save myself the breath and push this back to fedora-docs-list. On Sun, 2004-08-01 at 05:10, Dave Pawson wrote: > On Sat, 2004-07-31 at 19:18, Karsten Wade wrote: > > > I mean something a little more than that. If we had CVS access > > immediately, we would have zero documents to post and zero changes to > > make to the website. We have a very few bugs files against just the > > Documentation Guide. > > I've handed two documents over to Tammy. They aren't available. > At least if they were in CVS they'd be there for someone else to pick > up? True. > > > > We, meaning all of us contributing to the docs project, are not in > > control of CVS access. We are in control of the rest of this. We can > > write patches to the Doc Guide and pass them around the (archived) > > mailing list. > > And if they are not seen to arrive as Fedora documentation, we'd soon > get pissed off? I can't help it if someone gets pissed off; to be honest, I'm not in much of a better situation -- I just write stuff for this project, and I currently can't write to the Fedora CVS. Still, I'd rather have a number of items in the queue for when CVS shows up, than have a bunch of whining in the queue. This is my style, so you can use it or abuse it: I'd rather do everything within my power _first_ instead of waiting for Mom to fix it all for me. I see there being many things we, as a group, can do while waiting for CVS. > > So, some suggestions: > > > > * If you have a suggestion for something to fix on any of the > > fedora.redhat.com pages, file a bug, and please reply back to us here > > with the details and the bugzilla number. > > Never having used bugzilla: > Where does (our project) recommend this process. > What documents need scrutiny? > Where's the bugzilla page | instructions whatever? > More hurdles Karsten? In the middle of the page at http://fedora.redhat.com/projects/docs/ it has always said the following; it can't be much clearer than this: "Bug Reporting, Testing, and Quality Assurance Before you file a bug, please read through the list of current and previous bugs for fedora-docs to determine if your bug has already been filed. If your bug does not exists, enter a bug report using the Bugzilla bug entry page. If your bug exists and has not been fixed, add additional information to the existing bug. If your bug exists and has been fixed, upgrade to the version in the bug report to determine if the bug was properly fixed. If it was not, reopen the bug. Some other interesting Bugzilla queries: * All open bugs for fedora-docs * The requests for enhancements (RFEs) for fedora-docs" Bugzilla is the tool for reporting problems and requesting features with any aspect of Fedora. This is no more a hurdle for Fedora docs project than it is for Fedora Core. Ultimately, it's a better-than-nothing project management tool for maintainers. Much easier to do a bugzilla search for all open bugs than comb through this mailing list looking for someone's suggested fix. > > When CVS opens for us, we will have a lot of work to do, but it will be > > good work, instead of starting from scratch. > No note of this as an interim on the docs project page? > Its dead meat as far as a project page goes. > Gathering dust. I don't have access to update that page. If I were to suddenly have that access tomorrow, I still don't know exactly what needs to be updated on that page. If every message on this list reporting what needs to be changed was a bugzilla report, we'd be much further ahead than we are now. > > > > > > 4. What should be on the fedora.redhat.com/docs pages _right_now_? > > > > > > http://fedora.redhat.com/docs/ > > > Is that a documentation page for fedora? > > > There's a link to rh9 doco. > > > No document list... > > > What is that page for please? > > > > As I understand it, this should be a list all of the documentation that > > this project produces. It is up to this project and it's leader to > > decide what should be on that page, which is directly related to all > > these questions I'm asking. > > I don't see a Fedora docs project/leader? > I see a few people willing to write, others wanting to, > and nix back from Fedora|Redhat. I take my philosophy from this page: http://fedora.redhat.com/about/leadership.html "Leadership Leadership in the Fedora Project will be post-facto recognition of acting leaders, not appointment of people to start acting as leaders after appointment. The leaders that we will recognize will be those who lead by example, whose goals as expressed in their words and actions are aligned with our goals (as stated in the Project Objectives and which we expect to refine over time), and who are willing to be officially recognized as leaders. Note that this necessarily means that there will be people acting as leaders who are not officially recognized on this web page. This is not meant to denigrate them, or to imply that their opinions are not worthwhile, or to say that their points are not considered. If the only leaders we have are the ones that are officially recognized, then we'll be a dying community. ..." Right now what this means to me is that if I just say, "I can't do anything about this stuff except complain, that's the leader's job to fix," then I'm part of the problem and not the solution. > > Anywhere on fedora.redhat.com, the left side of the window has a blue > > stack of links to pages, that open up to reveal somewhat of a tree. If > > you click on Docs in that link (as I think many visitors might do), it > > expands to show two documents, the Release Notes and the Jargon Buster, > > the only successful scratch-to-webpage document from the Fedora docs > > project. > > So its pure future then for documentation. I don't understand this idiom. Do you mean that the future is wide-open for creating new documentation? If so, then I agree. > > That nav bar needs to have more documents, or feeds into versions or > > areas of documents. We should recommend how that information flows, and > > of course we need to be filling in the blanks with content. :) > > The challenge is to get a user view of documentation. I think its real > hard to find your way to 'the hole where documentation will be'. > > As I see it, the links should be there, the end point being a document > that says docs wanted on subject X, Subjects Y,Z A are being worked on > ..... So ... there's this thread I started with the subject "what is ready for fedora.redhat.com." I think we should use that thread to gain consensus about what changes we think should take place on the two docs pages, then file a bugzilla report detailing the changes. Would you like to contribute your ideas to that thread, maybe even try out the bug reporting? - Karsten -- Karsten Wade, RHCE, Tech Writer this .signature subject to random changes http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Sun Aug 1 18:09:33 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 01 Aug 2004 19:09:33 +0100 Subject: Using elvis? In-Reply-To: <1091381494.11946.16186.camel@erato.phig.org> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <1091203967.2020.20.camel@homer> <1091223825.11946.13466.camel@erato.phig.org> <1091258329.2049.33.camel@homer> <1091297927.11946.14760.camel@erato.phig.org> <1091362203.2022.10.camel@homer> <1091381494.11946.16186.camel@erato.phig.org> Message-ID: <1091383773.2022.45.camel@homer> On Sun, 2004-08-01 at 18:31, Karsten Wade wrote: > Did you mean to take this off-list? No, sorry, I just hit return. > I can't help it if someone gets pissed off; to be honest, I'm not in > much of a better situation -- I just write stuff for this project, and I > currently can't write to the Fedora CVS. Still, I'd rather have a > number of items in the queue for when CVS shows up, than have a bunch of > whining in the queue. > > This is my style, so you can use it or abuse it: I'd rather do > everything within my power _first_ instead of waiting for Mom to fix it > all for me. I'm trying to point out ways for improvement Karsten. I dont' see it as waiting for mom to fix anything. Though if you *are* the only RH input, and you don't have site access, why are we here? Waiting for Tammy's child to leave home? > > Where's the bugzilla page | instructions whatever? > > More hurdles Karsten? > > In the middle of the page at http://fedora.redhat.com/projects/docs/ it > has always said the following; it can't be much clearer than this: My bad. I'd not read it|taken it in| seen bugfixes on the horizon... Though how the heck can we fix 'em if we can't commit? More catch 22? / Join the queue? > > Bugzilla is the tool for reporting problems and requesting features with > any aspect of Fedora. This is no more a hurdle for Fedora docs project > than it is for Fedora Core. Two wheels is a hurdle if you've never ridden a bike. You may be familiar, I'm not. > Ultimately, it's a better-than-nothing > project management tool for maintainers. Much easier to do a bugzilla > search for all open bugs than comb through this mailing list looking for > someone's suggested fix. > > > > When CVS opens for us, we will have a lot of work to do, but it will be > > > good work, instead of starting from scratch. > > No note of this as an interim on the docs project page? > > Its dead meat as far as a project page goes. > > Gathering dust. > > I don't have access to update that page. If I were to suddenly have > that access tomorrow, I still don't know exactly what needs to be > updated on that page. If every message on this list reporting what > needs to be changed was a bugzilla report, we'd be much further ahead > than we are now. OK. Bugs and bare/unchanging web pages are two different things IMHO. > http://fedora.redhat.com/about/leadership.html > > "Leadership > > Leadership in the Fedora Project will be post-facto recognition of > acting leaders, not appointment of people to start acting as leaders > after appointment. The leaders that we will recognize Who's 'we' if not RH? => some manner of project lead to make that decision? Or is this just another rh catch 22? > So ... there's this thread I started with the subject "what is ready for > fedora.redhat.com." I think we should use that thread to gain consensus > about what changes we think should take place on the two docs pages, > then file a bugzilla report detailing the changes. Would you like to > contribute your ideas to that thread, maybe even try out the bug > reporting? If that's the definition of a bug, I'll try it; but I'm losing hope. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sun Aug 1 18:31:29 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 01 Aug 2004 19:31:29 +0100 Subject: Using elvis? In-Reply-To: <1091383773.2022.45.camel@homer> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <1091203967.2020.20.camel@homer> <1091223825.11946.13466.camel@erato.phig.org> <1091258329.2049.33.camel@homer> <1091297927.11946.14760.camel@erato.phig.org> <1091362203.2022.10.camel@homer> <1091381494.11946.16186.camel@erato.phig.org> <1091383773.2022.45.camel@homer> Message-ID: <1091385089.2022.51.camel@homer> I've been informed off list that my comments may be taken as being insulting to Tammy. Please be assured that was not my intent. If interpreted that way, my sincere apologies Tammy. regrets DaveP From paul at frields.com Sun Aug 1 23:49:54 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 01 Aug 2004 19:49:54 -0400 Subject: Some BZ entries Message-ID: <1091404194.25999.3.camel@bettie.internal.frields.org> #123267 - Fix filename tag in docs-guide #128903 - Additional content for example-tutorial #128951 - Add FC2 entry to jargon-buster #128952 - Tutorial submission: updfstab-tutorial-en I guess this could be considered an RFC of sorts. For anyone out there who doesn't know much about bugzilla, just visit http://bugzilla.redhat.com and use the "Goto bug#" field at the top right of the front page to visit these bugs. You can see the patches, enter comments, and so forth. Most of these are small and simple. -- Paul W. Frields, RHCE From paul at frields.com Sun Aug 1 23:51:52 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 01 Aug 2004 19:51:52 -0400 Subject: [Fwd: Creating a Fedora instllation boot floppy] In-Reply-To: <1091300551.24634.42.camel@hermione.aeon.com.my> References: <1091300551.24634.42.camel@hermione.aeon.com.my> Message-ID: <1091404312.25999.6.camel@bettie.internal.frields.org> On Sat, 2004-07-31 at 15:02, Colin Charles wrote: > David, > > Consider dropping this to the fedora-docs-list at redhat.com as this is > possibly a guide [...snip...] If no one else is jumping in, I'll mark it up and try and make it guide-like. This actually dovetails nicely with a presentation I was preparing for a symposium in September, so it may be a good fit. Any objections? -- Paul W. Frields, RHCE From gleblanc at linuxweasel.com Mon Aug 2 16:04:47 2004 From: gleblanc at linuxweasel.com (Gregory Leblanc) Date: Mon, 02 Aug 2004 09:04:47 -0700 Subject: Some BZ entries In-Reply-To: <1091404194.25999.3.camel@bettie.internal.frields.org> References: <1091404194.25999.3.camel@bettie.internal.frields.org> Message-ID: <1091462687.2588.6.camel@gregslaptop> Hi Paul! Took a quick glance at these this morning. I'd like to see minor changes in at least the first three before they land in CVS. I haven't read over all of the last one, but I'll try to get to it this evening. Hopefully I'll have time to jot down comments on the other three this morning. Later, Greg On Sun, 2004-08-01 at 19:49 -0400, Paul W. Frields wrote: > #123267 - Fix filename tag in docs-guide > #128903 - Additional content for example-tutorial > #128951 - Add FC2 entry to jargon-buster > #128952 - Tutorial submission: updfstab-tutorial-en > -- Gregory Leblanc From kwade at redhat.com Mon Aug 2 23:09:03 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 02 Aug 2004 16:09:03 -0700 Subject: fedora-entities - a proposal in the flesh In-Reply-To: <1091241903.12901.4.camel@bettie.internal.frields.org> References: <1091222713.11946.13425.camel@erato.phig.org> <1091241903.12901.4.camel@bettie.internal.frields.org> Message-ID: <1091488142.3378.1758.camel@erato.phig.org> On Fri, 2004-07-30 at 19:45, Paul W. Frields wrote: > Would it be OK to request a couple extra entities? > > url='http://fedora.redhat.com/'>http://fedora.redhat.com/"> > url='http://fedora.redhat.com/projects/docs/'>http://fedora.redhat.com/projects/docs/"> Good idea. I added and expanded as below. If there are no further suggestions, I'm going to open a bugzilla to request this for inclusion, hereby putting it into the queue. http://fedora.redhat.com/"> http://fedora.redhat.com/projects/docs/"> http://fedora.redhat.com/docs/"> Updated at: http://people.redhat.com/kwade/fedora-docs/common/fedora-entities-en.xml - Karsten -- Karsten Wade, RHCE, Tech Writer this .signature subject to random changes http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From redwire at therockmere.com Tue Aug 3 11:46:30 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Tue, 3 Aug 2004 07:46:30 -0400 (EDT) Subject: CVS Mirror Message-ID: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> The question was asked about 2 weeks ago about hosting the CVS. I got some specs, but I wanted to follow up. I am migrating to a static IP 1.5/286 with Speakeasy in the next month. While I don't want to drag my connex down, I'd be interested in hosting a CVS mirror. In real terms, how much drag will I see if I host a CVS or mirror CVS? I guess I don't quite understand why the CVS is LOCKED and why the Fedora Main Page hasn't been updated to release\hyperlink to at least some documentation. FC1 and FC2 have been in production since APRIL, it seems important to ME at least that there be some sort of documentation made avail. Also, I think that releasing some documentation would help alleviate some of the errant posting of questions to the fedora-docs mailing list. The other alt. is to consider a FC docs based website, on my server, and ask for any interested doc mailing list participants to send their docs to me and I'll post them. Thoughts and clarification of usage appreicated Brad From hugofmesquita at yahoo.com Tue Aug 3 12:42:46 2004 From: hugofmesquita at yahoo.com (Fernando) Date: Tue, 03 Aug 2004 07:42:46 -0500 Subject: Can't unsubscribe from list, PLEASE HELP! Message-ID: <1091536966.3028.5.camel@Chief.site> Hi, I tried several times to unsubscribe from this list with no success.I click on the link at the end section of the email messages and then log in to my account. Then I select the option to unsubscribe. After that I receive an email confirmation, but I still getting the posts from you guys. What am I missing? Thanks in advance! Fernando, From paul at frields.com Tue Aug 3 12:53:10 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 03 Aug 2004 08:53:10 -0400 Subject: CVS Mirror In-Reply-To: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> Message-ID: <1091537589.2701.17.camel@berlin.east.gov> On Tue, 2004-08-03 at 07:46, redwire at therockmere.com wrote: > The question was asked about 2 weeks ago about hosting the CVS. I got some > specs, but I wanted to follow up. > > I am migrating to a static IP 1.5/286 with Speakeasy in the next month. > While I don't want to drag my connex down, I'd be interested in hosting a > CVS mirror. In real terms, how much drag will I see if I host a CVS or > mirror CVS? > > I guess I don't quite understand why the CVS is LOCKED and why the Fedora > Main Page hasn't been updated to release\hyperlink to at least some > documentation. > > FC1 and FC2 have been in production since APRIL, it seems important to ME > at least that there be some sort of documentation made avail. Also, I > think that releasing some documentation would help alleviate some of the > errant posting of questions to the fedora-docs mailing list. > > The other alt. is to consider a FC docs based website, on my server, and > ask for any interested doc mailing list participants to send their docs to > me and I'll post them. > > Thoughts and clarification of usage appreicated My $0.02: CVS is still locked because we don't yet have a workable protocol for prioritizing, assigning, accepting, editing, QA/QC'ing, and automatically Web-fielding documents. I think (hope?) Red Hat people are working on the infrastructure part of that. We are here to talk about those protocols, and not to just grow a plethora of third-party repositories for docs. There's no reason why anyone on their own (or in a group) can't make a Web site full of helpful Fedora documents. I would hope that the best of those would make it into the official repository, just like software. However, there are plenty of these already, not least among them FedoraNews.org, just for one example. Multiplying these document repositories doesn't fix the problem. What would really help would be using this list to nail down the process. Having a reliable process makes the product better. There's a big difference in quality between, say, the official Red Hat Linux documentation of yore and the average "article" on any of a number of Fedora doc sites. Bad grammar and spelling, colloquial language or jargon that's difficult for foreign readers, failure to cover other than limited usage cases... the list goes on. Personally, I want the official site to represent exceptional achievement in documentation and not just an "anything-goes" inclusivity. Just as Linux was built on a technocracy, the Docs Project should probably be built on a, erm... "literocracy?" (Sorry, I have to rush to a meeting, so I don't have time to come up with the right term here. I guess I just ceded my place at the table.) :-) If you REALLY want to help the project as a whole, give us your thoughts on how we can accomplish my very first sentence in this reply. That's how we'll make progress. The idea is not to do it fast and then fix it through eighty-five revisions... we should do it right the first time through careful planning and analysis of alternatives, even if it's frustrating to figure out that right way. Having said that, and although I am no one other than JAFE (just another flippin' editor), I for one recognize your generosity and say thanks. -- Paul W. Frields, RHCE From paul at frields.com Tue Aug 3 15:47:36 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 03 Aug 2004 11:47:36 -0400 Subject: CVS Mirror In-Reply-To: <1091537589.2701.17.camel@berlin.east.gov> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> <1091537589.2701.17.camel@berlin.east.gov> Message-ID: <1091548056.4176.4.camel@berlin.east.gov> On Tue, 2004-08-03 at 08:53, Paul W. Frields wrote: > My $0.02: CVS is still locked because we don't yet have a workable > protocol for prioritizing, assigning, accepting, editing, QA/QC'ing, and > automatically Web-fielding documents. I think (hope?) Red Hat people are > working on the infrastructure part of that. We are here to talk about > those protocols, and not to just grow a plethora of third-party > repositories for docs. One correction: it's not because we don't have a protocol that there's no writable CVS access. Not having a protocol just makes a writable CVS next to useless even if we had it. Sorry. -- Paul W. Frields, RHCE From kwade at redhat.com Tue Aug 3 17:18:31 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 03 Aug 2004 10:18:31 -0700 Subject: Can't unsubscribe from list, PLEASE HELP! In-Reply-To: <1091536966.3028.5.camel@Chief.site> References: <1091536966.3028.5.camel@Chief.site> Message-ID: <1091553510.3378.4019.camel@erato.phig.org> On Tue, 2004-08-03 at 05:42, Fernando wrote: > Hi, > I tried several times to unsubscribe from this list with no success.I > click on the link at the end section of the email messages and then log > in to my account. Then I select the option to unsubscribe. After that I > receive an email confirmation, but I still getting the posts from you > guys. > What am I missing? I hear this enough it makes me wonder if there is something broken at www.redhat.com/mailman? The list admin address for this list is Cc:'d for attention. Fernando, if this doesn't work, please try contacting Warren (wtogami at redhat.com) directly. -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 3 17:35:19 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 03 Aug 2004 10:35:19 -0700 Subject: docs process (was CVS Mirror) In-Reply-To: <1091548056.4176.4.camel@berlin.east.gov> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> <1091537589.2701.17.camel@berlin.east.gov> <1091548056.4176.4.camel@berlin.east.gov> Message-ID: <1091554519.3378.4085.camel@erato.phig.org> On Tue, 2004-08-03 at 08:47, Paul W. Frields wrote: > On Tue, 2004-08-03 at 08:53, Paul W. Frields wrote: > > My $0.02: CVS is still locked because we don't yet have a workable > > protocol for prioritizing, assigning, accepting, editing, QA/QC'ing, and > > automatically Web-fielding documents. I think (hope?) Red Hat people are > > working on the infrastructure part of that. We are here to talk about > > those protocols, and not to just grow a plethora of third-party > > repositories for docs. > > One correction: it's not because we don't have a protocol that there's > no writable CVS access. Not having a protocol just makes a writable CVS > next to useless even if we had it. Sorry. This is just speaking for myself, not Red Hat, but I don't think there is any specific work being done outside this project (read: this mailing list) on a process as you describe - taking a document from idea through to publication. What you see in the Documentation Guide, on &FDP-URL[1];, and on this mailing list is it, afaik. This is not to say that we are without anything. There is some process inherent in the Documentation Guide. It looks as if we need to start work on some new chapters to the Doc Guide, such as "Chapter 11 Getting a Document From Idea to Publication", which details how we want to manage accepting submissions, editing, QA/QC, etc. Perhaps Chapter 12 Document Lifecycle, which details ongoing maintenance, upgrading, and support of a document once it's published. - Karsten [1] Just getting used to the new entities, for those who forgot that expands to http://fedora.redhat.com/projects/docs . -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 3 17:37:57 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 03 Aug 2004 10:37:57 -0700 Subject: CVS Mirror In-Reply-To: <1091537589.2701.17.camel@berlin.east.gov> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> <1091537589.2701.17.camel@berlin.east.gov> Message-ID: <1091554677.3378.4099.camel@erato.phig.org> On Tue, 2004-08-03 at 05:53, Paul W. Frields wrote: > Having said that, and although I am no one other than JAFE (just another > flippin' editor), I for one recognize your generosity and say thanks. Yeah, have to agree with Paul fully - this is very generous of you, and thanks very much for the offer. I also agree with his reasons for saying that it's a mis-focus of energy and resources. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From redwire at therockmere.com Tue Aug 3 17:01:43 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Tue, 3 Aug 2004 13:01:43 -0400 (EDT) Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <20040803160012.C19EA73D96@hormel.redhat.com> References: <20040803160012.C19EA73D96@hormel.redhat.com> Message-ID: <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> > My $0.02: CVS is still locked because we don't yet have a workable > protocol for prioritizing, assigning, accepting, editing, QA/QC'ing, and > automatically Web-fielding documents. I think (hope?) Red Hat people are > working on the infrastructure part of that. We are here to talk about > those protocols, and not to just grow a plethora of third-party > repositories for docs. > Paul; I understand that we maybe waiting on RH, but waiting on something that 'may' happen when 'someone' gets to it is like being the bridesmaid and never the bride. [also, Sounds like Redmond, WA] I'm not trying to be rude or insulting, but IF a working documentation structure isn't able to be Resolved\Approved by those people that are spending their own free time on it, then 'Houston, we have a problem'. There is a difference between a releasing documents, especially those that can be change so easily like XML, and making revisions and what seems to be occurring; saying 'well, unless it is 100.01% perfect nobody gets to see it'. The advantage of OPEN SOURCE is the FREE EXCHANGE of information. This is most importantly includes documentation. Red Hat gave the Fedora project to the OS community because their focus shifted to Enterprise level sales and service to make a profit. By extension that means that WE are able to set standards. [aside: until recently monster.com had a job posting for a DocBook person at RH. It is since been removed] If FC is to progress to FC3, and gain traction, then it requires, and demands, a large, free and accessible Document set. While there are a number of 'document' sites. I will say that most of them are a hodge-podge of minor tutorials and\or a document here or there on FC. Not a dedicated single source for FC in an easy to read, DocBook format. Lastly, I understand that I am new to the group. I understand that I don't post alot and am still trying to master DocBook syntax and d'l the examples, but I will mention that I have 10+ yrs of computer programming & training experience. I know from experience that if you don't provide a basis for knowledge for others to build on then the product, no matter how good, is destine to fall by the wayside. Brad From davep at dpawson.co.uk Tue Aug 3 17:53:08 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 03 Aug 2004 18:53:08 +0100 Subject: CVS Mirror In-Reply-To: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> Message-ID: <1091555588.2056.18.camel@homer> On Tue, 2004-08-03 at 12:46, redwire at therockmere.com wrote: > FC1 and FC2 have been in production since APRIL, it seems important to ME > at least that there be some sort of documentation made avail. Also, I > think that releasing some documentation would help alleviate some of the > errant posting of questions to the fedora-docs mailing list. > > The other alt. is to consider a FC docs based website, on my server, and > ask for any interested doc mailing list participants to send their docs to > me and I'll post them. I was thinking, kind offer etc, until I read Karstens mail, which I believe to be from within Redhat. Simple proposal, +1 to redwire's offer. If we need an editing process, I'll defer to Pauls experience, I can do no better than iso 9000. Proposal. Paul as edit loop: comments back to this forum. Corrected docs move from rh CVS to redwire's site, CVS in docbook format, posted in HTML (bandwidth permitting). If RH are saying they don't care about documentation, lets put the work in somewhere else? At least until RH realise its important. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Tue Aug 3 18:00:52 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 03 Aug 2004 19:00:52 +0100 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> Message-ID: <1091556051.2056.27.camel@homer> On Tue, 2004-08-03 at 18:01, redwire at therockmere.com wrote: > I understand that we maybe waiting on RH, but waiting on something that > 'may' happen when 'someone' gets to it is like being the bridesmaid and > never the bride. [also, Sounds like Redmond, WA] Hey Brad, stop trying to frighten us :-) +1 to most of your comments though; which seem to echo Karstens? If you don't like it, don't moan, do something about it. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Tue Aug 3 19:27:10 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 03 Aug 2004 12:27:10 -0700 Subject: CVS Mirror In-Reply-To: <1091555588.2056.18.camel@homer> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> <1091555588.2056.18.camel@homer> Message-ID: <1091561230.3378.4501.camel@erato.phig.org> On Tue, 2004-08-03 at 10:53, Dave Pawson wrote: > On Tue, 2004-08-03 at 12:46, redwire at therockmere.com wrote: > > FC1 and FC2 have been in production since APRIL, it seems important to ME > > at least that there be some sort of documentation made avail. Also, I > > think that releasing some documentation would help alleviate some of the > > errant posting of questions to the fedora-docs mailing list. > > > > The other alt. is to consider a FC docs based website, on my server, and > > ask for any interested doc mailing list participants to send their docs to > > me and I'll post them. > > I was thinking, kind offer etc, until I read Karstens mail, which I > believe to be from within Redhat. Sorry, can you elaborate? I'm positive I stated my own opinions clearly, and not that of Red Hat or anyone else involved in Fedora. I don't understand what you mean here. > If RH are saying they don't care about documentation, lets put the work > in somewhere else? At least until RH realise its important. Did someone say this? Where and when specifically, please? I'm happy to help apply cluestick. thx - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 3 19:32:12 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 03 Aug 2004 12:32:12 -0700 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> Message-ID: <1091561532.3378.4523.camel@erato.phig.org> On Tue, 2004-08-03 at 10:01, redwire at therockmere.com wrote: > > My $0.02: CVS is still locked because we don't yet have a workable > > protocol for prioritizing, assigning, accepting, editing, QA/QC'ing, and > > automatically Web-fielding documents. I think (hope?) Red Hat people are > > working on the infrastructure part of that. We are here to talk about > > those protocols, and not to just grow a plethora of third-party > > repositories for docs. > > > > Paul; > > I understand that we maybe waiting on RH, but waiting on something that > 'may' happen when 'someone' gets to it is like being the bridesmaid and > never the bride. [also, Sounds like Redmond, WA] I think you are correct, and are welcome to start up a docs repository of Fedora documentation. You can even have every single thing that is in the Fedora docs project, thanks to the FDL. You may come here looking for contributors, help, and ideas, although you may be told it's no longer on topic. But what you describe is starting to sound like a fork to me, and as such is outside of the scope of the Fedora docs project. If instead what you want to do is help the Fedora docs project succeed at delivering high quality documentation, then I really think you should reconsider your offer and ideas in terms of what it will take to get this group to that goal. In other words, your intention is clear and good, but I don't think setting up an ad-hoc CVS is going to help us, at least until we are clear what even needs to be put in it. That said, if we want a short-term CVS holding tank to build a new fedora-docs tree for submission back into the permanent Fedora CVS, and you want to setup and administer that, I don't think it can hurt. As long as it's understood that it's temporary. This example illustrates my point. When FC2test1 was coming out, I was helping Ed Bailey with the release notes, and many of us realized we desperately needed an FAQ for the test release. With the timing of the test release, there wasn't time for me to write the FAQ and go through the process to publish on fedora.redhat.com/docs. We also needed to be able to add and fix questions/answers in the FAQ on very short notice, like immediately. With no good solution in site, I decided to host it on my people.redhat.com page. Now I have a small logistics problem. That URL is the well known and propagated URL. It should be on fedora.redhat.com/docs/selinux-faq (or something like that), and when I do move it over there, I will have to figure out how to move visitors from people.redhat.com to fedora.redhat.com, or face keeping multiple sites live indefinitely. > I'm not trying to be rude or insulting, but IF a working documentation > structure isn't able to be Resolved\Approved by those people that are > spending their own free time on it, then 'Houston, we have a problem'. To a large degree, we-the-group _haven't_ been spending our time on it. We've been writing some stuff, not quite enough, and saying that we can't do anything until we have every piece of the structure in place. For example, up until the separation of Fedora CVS from internal Red Hat CVS sometime over the last few months, there were several of us here who could have been making commits for the project. The project pages even specify that the project leader can do this. None of us, myself included, thought to ask if we could ease Tammy's burden some and move the project along at the same time. I'm asking for that now. And looking around, I see that we are not where we should be for the eventual arrival of Fedora CVS. > There is a difference between a releasing documents, especially those that > can be change so easily like XML, and making revisions and what seems to > be occurring; saying 'well, unless it is 100.01% perfect nobody gets to > see it'. Yes. At the same time, we want to have a high quality, well processed document, so that calls for a bit more process than "just write it, post it, and fix problems when people report them." There is a balance here. It makes sense for us to be more diligent in testing and editing each other's documents. Paul speaks about this in his first reply to this thread. Still, as you say, we don't want to get stagnate ... > The advantage of OPEN SOURCE is the FREE EXCHANGE of information. This is > most importantly includes documentation. Red Hat gave the Fedora project > to the OS community because their focus shifted to Enterprise level sales > and service to make a profit. By extension that means that WE are able to > set standards. Agreed. Let's discuss what those should be and how to deliver them. > If FC is to progress to FC3, and gain traction, then it requires, and > demands, a large, free and accessible Document set. > > While there are a number of 'document' sites. I will say that most of them > are a hodge-podge of minor tutorials and\or a document here or there on > FC. Not a dedicated single source for FC in an easy to read, DocBook > format. Yeah, I'm frustrated too at the lack of document set for Fedora after all this time. Still, no one can do it by themselves. Let's get the content written, work up a process from ad-hoc through to repeatable (at least), and just be so fscking ready when CVS opens up that we can roll straight forward into FC3 with a lot of momentum. > Lastly, I understand that I am new to the group. I understand that I don't > post alot and am still trying to master DocBook syntax and d'l the > examples, but I will mention that I have 10+ yrs of computer programming & > training experience. > I know from experience that if you don't provide a basis for knowledge for > others to build on then the product, no matter how good, is destine to > fall by the wayside. Word. > [aside: until recently monster.com had a job posting for a > DocBook person at RH. It is since been removed] Since you opened the can, I don't mind a shameless plug as a reward for reading this far ... :) ... There is at least one position for a tech writer at Red Hat. http://redhat.hrdpt.com/cgi-bin/a/highlightjob.cgi?jobid=7 This is the position that authors the System Administration Guide, so requires a fair amount of Linux and writing expertise. If you are a perfect fit for this position, feel free to contact me, I'll see your resume gets to the right person. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Tue Aug 3 19:35:37 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 03 Aug 2004 15:35:37 -0400 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> Message-ID: <1091561737.5282.101.camel@berlin.east.gov> On Tue, 2004-08-03 at 13:01, redwire at therockmere.com wrote: > > My $0.02: CVS is still locked because we don't yet have a workable > > protocol for prioritizing, assigning, accepting, editing, QA/QC'ing, and > > automatically Web-fielding documents. I think (hope?) Red Hat people are > > working on the infrastructure part of that. We are here to talk about > > those protocols, and not to just grow a plethora of third-party > > repositories for docs. > > > > I understand that we maybe waiting on RH, but waiting on something that > 'may' happen when 'someone' gets to it is like being the bridesmaid and > never the bride. [also, Sounds like Redmond, WA] See my erratum for more. I misstated at first, but Karsten subsequently said it better anyway. > I'm not trying to be rude or insulting, but IF a working documentation > structure isn't able to be Resolved\Approved by those people that are > spending their own free time on it, then 'Houston, we have a problem'. I think we're actually in agreement here. I'm just trying to state the case that until we have a process, having CVS write access anywhere is pointless. We should set the course before we press on the gas pedal. [...snip...] > Lastly, I understand that I am new to the group. I understand that I don't > post alot and am still trying to master DocBook syntax and d'l the > examples, but I will mention that I have 10+ yrs of computer programming & > training experience. > I know from experience that if you don't provide a basis for knowledge for > others to build on then the product, no matter how good, is destine to > fall by the wayside. No argument here. As an aside, I've been a teacher for almost that long in a number of technical fields, although I'm not a programmer by trade, which is why I agree that we do need to provide the knowledge, but we need to make sure we're not taking a shotgun approach. Let's devote this time to figuring out the protocol, then. Thread to start shortly, and thanks for your consideration. -- Paul W. Frields, RHCE From moises at digicon.com.br Tue Aug 3 20:53:20 2004 From: moises at digicon.com.br (Moises Beck) Date: Tue, 03 Aug 2004 17:53:20 -0300 Subject: fedora and ramdisk Message-ID: <1091566399.2694.25.camel@localhost.localdomain> Hello, I' trying to make a ramdisk image using the follow script: dd if=/dev/zero of=/dev/ram bs=1k count=8192 mke2fs -vm0 /dev/ram 8192 mount -t ext2 /dev/ram /mnt/ramdisk cp -dpRf /root/projetos/ramdisk/ramdisk_ponto_fixo/* /mnt/ramdisk umount /mnt/ramdisk dd if=/dev/ram bs=1k count=8192 | gzip -v9 > ramdisk.image.gz mkimage -A ppc -O linux -T ramdisk -C gzip -a 0 -e 0 -n "Ramdisk Image Digicon S/A" -d ramdisk.image.gz pRamdisk_ponto_fixo When I was using Red Hat 9.0, the script ran very well. But when I installed Fedora core 2 and ran the script, the file ramdisk.image.gz created was too small (around 40kB), when it must be around 1.6Mb. I uncompressed the file ramdisk.image.gz and mounted it, and the mount point showed that the only directory that appears (in /mnt/ramdisk) is "lost+found". This is very strange, becouse the problem appears only when I installed Fedora. Does anyone have some clue ? Thanks, Moises Beck From paul at frields.com Tue Aug 3 21:33:45 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 03 Aug 2004 17:33:45 -0400 Subject: fedora and ramdisk In-Reply-To: <1091566399.2694.25.camel@localhost.localdomain> References: <1091566399.2694.25.camel@localhost.localdomain> Message-ID: <1091568825.2580.3.camel@bettie.internal.frields.org> On Tue, 2004-08-03 at 16:53, Moises Beck wrote: > I' trying to make a ramdisk image using the follow script: [...snip...] Moises, You've posted this to fedora-docs-list, which is a list for discussion of Fedora documentation. If you want help with a technical issue, you probably want to look to the fedora-list instead. Here's the address: http://www.redhat.com/mailman/listinfo/fedora-list/ If you don't mind taking a minute or two, can you tell us what brought you to fedora-docs-list? We are interested because we're trying to improve the way that people find technical help for Fedora. Thanks and good luck. -- Paul W. Frields, RHCE From paul at frields.com Tue Aug 3 21:57:49 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 03 Aug 2004 17:57:49 -0400 Subject: Process suggestions vol. 1 Message-ID: <1091570269.2580.27.camel@bettie.internal.frields.org> The following is a core dump, because I have to get to a HOA meeting and want to strike while the iron is hot. (Why yes, that *does* mean I have a thick head, thanks for noticing.) Ideas for improvied Docs Guide organization: "Part 0." Which part you should start reading. If you skip any parts (e.g. you already have a tutorial written), what do you need to know to proceed? Part 1. From idea to assignment. Guidelines for scope, "pitch" (sorry if it's too Hollywood -- I mean defining the syllabus or synopsis), and how to get the FDP's attention (where to find us, come with a project in mind if possible, etc.). Why this is a good idea rather than just throwing documents at us pell-mell. Querying BZ for ideas. Part 2. From assignment to production. A slightly gentler how-to on getting the tools working, especially for the Emacs/PSGML faint-of-heart. Pointers to other tool sets, and maybe even instructions as well. Guidelines for the system you're documenting, such as making sure that you're eliminating variables on your system to which the "average" Fedora user isn't privy, trying to stick to best methods for doing things (up2date vs. cli apt/yum, RPM vs tarballs, etc.). Remember that we are not here to "fix" the system, we are here to document how to use it as is. (See GNOME Docs Guide for similar sentiments.) We might want to include a style guide here. Part 3. From production to posting. How to submit the finished sources (BZ, eventual CVS, fedora-docs-list...). What happens to your document after you submit it. What the editor's responsibility is to you. What your responsibility is to the editor. Approval process. Part 4. From posting to...? (the grave?) FDP/editors'/authors' responsibilities for keeping docs updated, and how to change hands. Using BZ to report or query problems. Resolving problems. Branching documents for different releases of FC. Just some thoughts, more to come I fear.... :-) -- Paul W. Frields, RHCE From mjohnson at redhat.com Wed Aug 4 02:05:39 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Tue, 03 Aug 2004 22:05:39 -0400 Subject: Process suggestions vol. 1 In-Reply-To: <1091570269.2580.27.camel@bettie.internal.frields.org> References: <1091570269.2580.27.camel@bettie.internal.frields.org> Message-ID: <41104473.3060004@redhat.com> Hi Paul, Your brain dump is chock full of useful suggestions, esp regarding the content of a "Getting Started writng Docs for Fedora", or whatever the document name turns out to be. I hope you don't mind if I "appropriate" some of your ideas into the fedora-docs tutorial:-) Thanks, Mark Paul W. Frields wrote: > The following is a core dump, because I have to get to a HOA meeting and > want to strike while the iron is hot. (Why yes, that *does* mean I have > a thick head, thanks for noticing.) > > Ideas for improvied Docs Guide organization: > > "Part 0." > Which part you should start reading. If you skip any parts (e.g. you > already have a tutorial written), what do you need to know to proceed? > > Part 1. From idea to assignment. > Guidelines for scope, "pitch" (sorry if it's too Hollywood -- I mean > defining the syllabus or synopsis), and how to get the FDP's attention > (where to find us, come with a project in mind if possible, etc.). Why > this is a good idea rather than just throwing documents at us pell-mell. > Querying BZ for ideas. > > Part 2. From assignment to production. > A slightly gentler how-to on getting the tools working, especially for > the Emacs/PSGML faint-of-heart. Pointers to other tool sets, and maybe > even instructions as well. Guidelines for the system you're documenting, > such as making sure that you're eliminating variables on your system to > which the "average" Fedora user isn't privy, trying to stick to best > methods for doing things (up2date vs. cli apt/yum, RPM vs tarballs, > etc.). Remember that we are not here to "fix" the system, we are here to > document how to use it as is. (See GNOME Docs Guide for similar > sentiments.) > We might want to include a style guide here. > > Part 3. From production to posting. > How to submit the finished sources (BZ, eventual CVS, > fedora-docs-list...). What happens to your document after you submit it. > What the editor's responsibility is to you. What your responsibility is > to the editor. Approval process. > > Part 4. From posting to...? (the grave?) > FDP/editors'/authors' responsibilities for keeping docs updated, and > how to change hands. Using BZ to report or query problems. Resolving > problems. Branching documents for different releases of FC. > > Just some thoughts, more to come I fear.... :-) > -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From byte at aeon.com.my Wed Aug 4 11:58:12 2004 From: byte at aeon.com.my (Colin Charles) Date: Wed, 04 Aug 2004 21:58:12 +1000 Subject: Using elvis? In-Reply-To: <1091169289.11946.11661.camel@erato.phig.org> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> Message-ID: <1091530137.3271.21.camel@hermione.aeon.com.my> On Fri, 2004-07-30 at 16:34, Karsten Wade wrote: > > We've been talking about public CVS for far too long, and I think the > > longer we wait, the longer Fedora Docs becomes less & less relevant > > Sorry if I'm being dense, but I don't understand how having public CVS > resolves the problems of Fedora docs? I see a lack of content, some > broken processes, and barriers to entry, but I don't see how public CVS > resolves that. People can commit to a place - it will be in one central location - there will be drive and interest to write it Where do people who write Fedora docs now commit things to? Or host it? FedoraNEWS.ORG seems like a welcome host (but its not Fedora Docs!). Random websites on the Net look like welcome hosts (but i ts not Fedora Docs!) We need docs in one place, not scattered all over the Net - we have to grow as a project, and we don't have docs to start with (sending people to RHL9 documentation is *embarassing*) Lack of content is because there are broken processes and barriers to entry. Stop telling people that there's Emacs, and only Emacs to use. Let people write in HTML, and we might even find folk whom want to DocBookify them - remember, together we stand and colloboration is the way to get work done. Let's work like how FreeBSD/Gentoo get documentation done (which is excellent, in comparison to ours) > > Keeping in mind that the barrier of entry is already relatively high > > (you need to know DocBook, you need to use Emacs, etc...), this makes > > folk move closer to creating docs on 3rd party sites > > Agreed about the difficulties. To address this, Mark Johnson mentioned > the idea of doing a Fedora Docs Quick Start Guide. He would make it a > focused tutorial, using his psgmlx mode for Emacs, which gives a > friendly and useful XML editing environment. Would that be helpful? I'm guessing. I can use Emacs, so this doesn't apply. Maybe we want to ask fedora-list folk? > Still, Emacs is not required, and there have been plenty of offers to > convert and actual conversions from just about any source document into > a Fedora doc. The contribution of content is what is lacking. Yes. Notice I've been picking out bits and pieces from fedora-list and sending it to fedora-docs-list? I'll continue doing this... But I'm willing to bet the lack of contribution is because the momentum/wheel hasn't started rolling > Going back to the CVS, I don't see how giving write access to people who > are having difficulties learning the tools is helpful? Give it to those that know how to use it. If say, 10 of us here have CVS write access, we can get quite a lot of work done, I'm sure. Once there are some actual Fedora Docs sitting online, at our documentation site (not 3rd party sites, scattered, everywhere), we can definitely encourage more to contribute > OTOH, giving write access to some of the people who a) know the tools, > and b) have demonstrated their ability to submit good code, that would > be a great thing. Not code, just documentation. If I see errors, it's easily fixable (and I'm sure others who have write access will do it too) > > Why can't we use elvis.redhat.com ? Anaconda, translations and so on > > happen at elvis, so why not fedora docs? This will mean external > > contributors *can* commit to cvs as well > > This is an interesting end-run idea. Speaking for myself, my > inclination is not to create a parallel system to what is being worked > on and waited for. We are actually using elvis.redhat.com (my bad!). elvis==rhlinux. Its just that we don't have commit access Parallel system is more targetted towards source - I've not actually heard much mention about supporting the docs project. I'm sure its part of it, but its mighty silent The longer we wait, the longer 3rd party sites will get stronger, making this project more and more irrelevant > My email about what content is actually ready for CVS and posting on > fedora.redhat.com/docs is very relevant to your question. Once we know > exactly what there is to post and put in CVS, then we have something to > agitate about. Deliver the content, and we'll find a way to get it > posted. I think there's content, and you've identified some. There's plenty scattered on the Net (anaconda, davep has some, etc...), now the hard task is getting it all in one place. Oh wait, we don't have this one place :) Don't get me wrong, I'm playing the Devil's Advocate here, but someone has to do it. FC3 is going to be out within a couple of months, and we have absolutely zero usable documentation. We should aim for a handbook styled documentation, not point people to dated RHL9 docs -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From listbox at nedron.net Wed Aug 4 14:40:38 2004 From: listbox at nedron.net (David Nedrow) Date: Wed, 04 Aug 2004 10:40:38 -0400 Subject: Fedora install boot floppy doc Message-ID: <4110F566.8020904@nedron.net> I've begun a document that details how to create a boot floppy for Fedora installs on systems that don't have CD-ROM drives, etc. Several people suggested I participate in the docs list to see about adding it into the doc stream. It's already in Docbook XML format, since that's what we do all of our documentation in at work. Several people have already contributed additions, including a script to pretty much handle the gruntwork automatically. I'm including a text transform of the first draft. I haven't lloked at the Fedora doc guidelines yet, but if I remember correctly they're pretty straightforward, so it should be relatively easy for me to jimmy things around if necessary. -David -------------- next part -------------- Fedora Boot Floppy David Nedrow _________________________________________________________ Table of Contents I. Motivation and Overview Motivation Overview II. Detailed Boot Floppy Instructions Build the kernel Set up the work files Create modules.cgz Create new initrd Create the boot floppy Appendix A. Sample kernel config file I. Motivation and Overview Table of Contents Motivation Overview _________________________________________________________ Motivation Fedora does not currently provide boot floppies for installation. The reason for this can be attributed to the fact that virtually no computer ships these days without either a CD-ROM drive or a DVD-ROM drive. Additionally, many computers now do not even ship with a floppy drive. This can present a problem for systems that may have a floppy, but no CD-ROM drive A good example of the problem presented by the lack of a boot install floppy comes when users are dealing with remote installations on systems for which the user does not have physical access. In the case of the original Compaq Remote Insight Lights Out (RILO) boards, the user can only remote install the system using a boot floppy. There is no support for virtuallized CD-ROM access on the original RILO cards. _________________________________________________________ Overview Creating a boot floppy for Fedora is actually quite simple, though it does require several manual steps. Basically, you will use the diskboot.img file that is provided Fedora. This image is normally used to create bootable devices using USB memory pens, etc. This image provides all of the installation bits to which you will add a custom kernel and modules. II. Detailed Boot Floppy Instructions Table of Contents Build the kernel Set up the work files Create modules.cgz Create new initrd Create the boot floppy _________________________________________________________ Build the kernel You will need to build a new kernel using the kernel source files provided with the Fedora installation you are attempting. For this document, I will be using Fedora Core 2 (FC2) as the base system. FC2 uses a kernel tree identified as linux-2.6.5-1.358. If you do not have this source tree, simply download and install kernel-source-2.6.5-1.358.i386.rpm. The key to making a boot floppy for the Fedora installation is creating a kernel and set of modules that include the absolute minimum number of features you need to boot and install. This means excluding items like parallel port support, ACPI and APM, non-essential filesystem support, etc. You should also exclude serial support, framebuffer support, etc. Basically, anything that you don't need for the installation process should not be included in the kernel or as modules. E.g., don't add CD-ROM drivers if you're installing from the network. It's important to remember that the installation itself will install a fully functional kernel on the target system. Included in Appendix A is a sample kernel configuration file. _________________________________________________________ Set up the work files You will need the diskboot.img file provided with the Fedora installation under the images directory. Warning You will need mount/umount access on the local filesystem for the following steps. Create a working directory (for this document, I'll be using ~/bootwork), and move diskboot.img to that directory. Within the working directory, also create the following sub-directories: * initrd-old * initrd-new * bootdisk-old * floppy You can use the following command to create all of the required directories and files you will need: cd ~ mkdir -p ~/bootwork/initrd-old; mkdir ~/bootwork/initrd-new mkdir ~/bootwork/diskboot-old; mkdir ~/bootwork/floppy mkdir ~/bootwork/linux-2.6.5-1.358 dd if=/dev/zero of=~/bootwork/initrd bs=512 count=2880 /sbin/mke2fs -F -m0 ~/bootwork/initrd dd if=/dev/zero of=~/bootwork/floppy.img bs=512 count=2880 /sbin/mkfs.vfat ~/bootwork/floppy.img syslinux ~/bootwork/floppy.img Now, you need to mount diskboot.img so that we can get to the files we need. Assuming that diskboot.img is in your home directory: cd ~/bootwork mount -o loop ~/diskboot.img diskboot-old mount -o loop floppy.img floppy cp diskboot-old/*.msg floppy/ cp diskboot-old/splash.lss floppy/ cp diskboot-old/syslinux.cfg floppy/ cp /usr/src/linux-2.6.5-1.358/arch/i386/boot/bzImage floppy/vmlinuz gunzip -dc diskboot-old/initrd.img > initrd.old mount -o loop initrd.old initrd-old mount -o loop initrd initrd-new _________________________________________________________ Create modules.cgz The modules.cgz contains the modules (if any) that you built with your custom kernel. Use the following commands to create a new modules.cgz: cd ~/bootwork mkdir 2.6.5-1.358 find /usr/src/linux-2.6.5-1.358/drivers -name *.ko | xargs -n 1 -I {} c p {} 2.6.5-1.358 find 2.6.5-1.358 | cpio -o -H crc | gzip -c9 > modules.cgz _________________________________________________________ Create new initrd Most of the new initrd image will be copied from the original initrd that was extracted from the diskboot image. cd ~/bootwork cp -a initrd-old/bin initrd-new cp -a initrd-old/dev initrd-new cp -a initrd-old/etc initrd-new cp -a initrd-old/linuxrc initrd-new cp -a initrd-old/proc initrd-new cp -a initrd-old/sbin initrd-new cp -a initrd-old/selinux initrd-new cp -a initrd-old/sys initrd-new cp -a initrd-old/tmp initrd-new cp -a initrd-old/var initrd-new mkdir initrd-new/modules cp -a initrd-old/modules/module-info initrd-new/modules cp -a initrd-old/modules/modules.dep initrd-new/modules cp -a initrd-old/modules/modules.pcimap initrd-new/modules cp -a initrd-old/modules/pcitable initrd-new/modules cp ~/anaconda-ks.cfg initrd-new/ks.cfg cp -a modules.cgz initrd-new/modules umount initrd-new gzip -c9 initrd > initrd.img cp initrd.img floppy _________________________________________________________ Create the boot floppy Now, all that has to be done is to unmount the new floppy image and dump it to a floppy. cd ~/bootwork umount floppy umount diskboot-old umount initrd-old dd if=floppy.img of=/dev/fd0 _________________________________________________________ Sample kernel config file # # Automatically generated make config: don't edit # CONFIG_X86=y CONFIG_MMU=y CONFIG_UID16=y CONFIG_GENERIC_ISA_DMA=y # # Code maturity level options # CONFIG_EXPERIMENTAL=y CONFIG_CLEAN_COMPILE=y CONFIG_STANDALONE=y CONFIG_BROKEN_ON_SMP=y # # General setup # CONFIG_SWAP=y CONFIG_SYSVIPC=y CONFIG_POSIX_MQUEUE=y CONFIG_BSD_PROCESS_ACCT=y CONFIG_SYSCTL=y # CONFIG_AUDIT is not set CONFIG_LOG_BUF_SHIFT=14 # CONFIG_HOTPLUG is not set # CONFIG_IKCONFIG is not set # CONFIG_EMBEDDED is not set CONFIG_KALLSYMS=y CONFIG_FUTEX=y CONFIG_EPOLL=y CONFIG_IOSCHED_NOOP=y CONFIG_IOSCHED_AS=y CONFIG_IOSCHED_DEADLINE=y CONFIG_IOSCHED_CFQ=y CONFIG_CC_OPTIMIZE_FOR_SIZE=y # # Loadable module support # CONFIG_MODULES=y CONFIG_MODULE_UNLOAD=y # CONFIG_MODULE_FORCE_UNLOAD is not set CONFIG_OBSOLETE_MODPARM=y # CONFIG_MODVERSIONS is not set CONFIG_KMOD=y # # Processor type and features # CONFIG_X86_PC=y # CONFIG_X86_ELAN is not set # CONFIG_X86_VOYAGER is not set # CONFIG_X86_NUMAQ is not set # CONFIG_X86_SUMMIT is not set # CONFIG_X86_BIGSMP is not set # CONFIG_X86_VISWS is not set # CONFIG_X86_GENERICARCH is not set # CONFIG_X86_ES7000 is not set # CONFIG_M386 is not set # CONFIG_M486 is not set CONFIG_M586=y # CONFIG_M586TSC is not set # CONFIG_M586MMX is not set # CONFIG_M686 is not set # CONFIG_MPENTIUMII is not set # CONFIG_MPENTIUMIII is not set # CONFIG_MPENTIUMM is not set # CONFIG_MPENTIUM4 is not set # CONFIG_MK6 is not set # CONFIG_MK7 is not set # CONFIG_MK8 is not set # CONFIG_MCRUSOE is not set # CONFIG_MWINCHIPC6 is not set # CONFIG_MWINCHIP2 is not set # CONFIG_MWINCHIP3D is not set # CONFIG_MCYRIXIII is not set # CONFIG_MVIAC3_2 is not set # CONFIG_X86_GENERIC is not set CONFIG_X86_CMPXCHG=y CONFIG_X86_XADD=y CONFIG_X86_L1_CACHE_SHIFT=5 CONFIG_RWSEM_XCHGADD_ALGORITHM=y CONFIG_X86_PPRO_FENCE=y CONFIG_X86_F00F_BUG=y CONFIG_X86_WP_WORKS_OK=y CONFIG_X86_INVLPG=y CONFIG_X86_BSWAP=y CONFIG_X86_POPAD_OK=y CONFIG_X86_ALIGNMENT_16=y # CONFIG_X86_4G is not set # CONFIG_X86_SWITCH_PAGETABLES is not set # CONFIG_X86_4G_VM_LAYOUT is not set # CONFIG_X86_UACCESS_INDIRECT is not set # CONFIG_X86_HIGH_ENTRY is not set # CONFIG_HPET_TIMER is not set # CONFIG_HPET_EMULATE_RTC is not set # CONFIG_SMP is not set # CONFIG_PREEMPT is not set # CONFIG_X86_UP_APIC is not set # CONFIG_X86_MCE is not set # CONFIG_TOSHIBA is not set # CONFIG_I8K is not set # CONFIG_MICROCODE is not set # CONFIG_X86_MSR is not set # CONFIG_X86_CPUID is not set # # Firmware Drivers # # CONFIG_EDD is not set CONFIG_NOHIGHMEM=y # CONFIG_HIGHMEM4G is not set # CONFIG_HIGHMEM64G is not set # CONFIG_MATH_EMULATION is not set # CONFIG_MTRR is not set # CONFIG_REGPARM is not set # # Power management options (ACPI, APM) # # CONFIG_PM is not set # # ACPI (Advanced Configuration and Power Interface) Support # # CONFIG_ACPI is not set CONFIG_ACPI_BOOT=y # # CPU Frequency scaling # # CONFIG_CPU_FREQ is not set # # Bus options (PCI, PCMCIA, EISA, MCA, ISA) # CONFIG_PCI=y # CONFIG_PCI_GOBIOS is not set # CONFIG_PCI_GOMMCONFIG is not set # CONFIG_PCI_GODIRECT is not set CONFIG_PCI_GOANY=y CONFIG_PCI_BIOS=y CONFIG_PCI_DIRECT=y CONFIG_PCI_MMCONFIG=y CONFIG_PCI_LEGACY_PROC=y # CONFIG_PCI_NAMES is not set # CONFIG_ISA is not set # CONFIG_MCA is not set # CONFIG_SCx200 is not set # # Executable file formats # CONFIG_BINFMT_ELF=y # CONFIG_BINFMT_AOUT is not set # CONFIG_BINFMT_MISC is not set # # Device Drivers # # # Generic Driver Options # # # Memory Technology Devices (MTD) # # CONFIG_MTD is not set # # Parallel port support # # CONFIG_PARPORT is not set # # Plug and Play support # # # Block devices # CONFIG_BLK_DEV_FD=y CONFIG_BLK_CPQ_DA=y CONFIG_BLK_CPQ_CISS_DA=y # CONFIG_BLK_DEV_DAC960 is not set # CONFIG_BLK_DEV_UMEM is not set CONFIG_BLK_DEV_LOOP=y # CONFIG_BLK_DEV_CRYPTOLOOP is not set # CONFIG_BLK_DEV_NBD is not set # CONFIG_BLK_DEV_CARMEL is not set CONFIG_BLK_DEV_RAM=y CONFIG_BLK_DEV_RAM_SIZE=16384 CONFIG_BLK_DEV_INITRD=y # CONFIG_LBD is not set # # ATA/ATAPI/MFM/RLL support # CONFIG_IDE=y CONFIG_BLK_DEV_IDE=y # # Please see Documentation/ide.txt for help/info on IDE drives # # CONFIG_BLK_DEV_HD_IDE is not set # CONFIG_BLK_DEV_IDEDISK is not set # CONFIG_BLK_DEV_IDECD is not set # CONFIG_BLK_DEV_IDETAPE is not set # CONFIG_BLK_DEV_IDEFLOPPY is not set # CONFIG_IDE_TASK_IOCTL is not set # CONFIG_IDE_TASKFILE_IO is not set # # IDE chipset support/bugfixes # CONFIG_IDE_GENERIC=y # CONFIG_BLK_DEV_CMD640 is not set CONFIG_BLK_DEV_IDEPCI=y CONFIG_IDEPCI_SHARE_IRQ=y # CONFIG_BLK_DEV_OFFBOARD is not set CONFIG_BLK_DEV_GENERIC=y # CONFIG_BLK_DEV_OPTI621 is not set # CONFIG_BLK_DEV_RZ1000 is not set CONFIG_BLK_DEV_IDEDMA_PCI=y # CONFIG_BLK_DEV_IDEDMA_FORCED is not set CONFIG_IDEDMA_PCI_AUTO=y CONFIG_IDEDMA_ONLYDISK=y CONFIG_BLK_DEV_ADMA=y # CONFIG_BLK_DEV_AEC62XX is not set # CONFIG_BLK_DEV_ALI15X3 is not set # CONFIG_BLK_DEV_AMD74XX is not set # CONFIG_BLK_DEV_ATIIXP is not set # CONFIG_BLK_DEV_CMD64X is not set # CONFIG_BLK_DEV_TRIFLEX is not set # CONFIG_BLK_DEV_CY82C693 is not set # CONFIG_BLK_DEV_CS5520 is not set # CONFIG_BLK_DEV_CS5530 is not set # CONFIG_BLK_DEV_HPT34X is not set # CONFIG_BLK_DEV_HPT366 is not set # CONFIG_BLK_DEV_SC1200 is not set # CONFIG_BLK_DEV_PIIX is not set # CONFIG_BLK_DEV_NS87415 is not set # CONFIG_BLK_DEV_PDC202XX_OLD is not set # CONFIG_BLK_DEV_PDC202XX_NEW is not set CONFIG_BLK_DEV_SVWKS=y # CONFIG_BLK_DEV_SIIMAGE is not set # CONFIG_BLK_DEV_SIS5513 is not set # CONFIG_BLK_DEV_SLC90E66 is not set # CONFIG_BLK_DEV_TRM290 is not set # CONFIG_BLK_DEV_VIA82CXXX is not set CONFIG_BLK_DEV_IDEDMA=y # CONFIG_IDEDMA_IVB is not set CONFIG_IDEDMA_AUTO=y # CONFIG_BLK_DEV_HD is not set # # SCSI device support # # CONFIG_SCSI is not set # # Multi-device support (RAID and LVM) # # CONFIG_MD is not set # # Fusion MPT device support # # CONFIG_FUSION is not set # # IEEE 1394 (FireWire) support # # CONFIG_IEEE1394 is not set # # I2O device support # # CONFIG_I2O is not set # # Networking support # CONFIG_NET=y # # Networking options # CONFIG_PACKET=y CONFIG_PACKET_MMAP=y # CONFIG_NETLINK_DEV is not set CONFIG_UNIX=y # CONFIG_NET_KEY is not set CONFIG_INET=y # CONFIG_IP_MULTICAST is not set # CONFIG_IP_ADVANCED_ROUTER is not set # CONFIG_IP_PNP is not set # CONFIG_NET_IPIP is not set # CONFIG_NET_IPGRE is not set # CONFIG_ARPD is not set # CONFIG_SYN_COOKIES is not set # CONFIG_INET_AH is not set # CONFIG_INET_ESP is not set # CONFIG_INET_IPCOMP is not set # CONFIG_IPV6 is not set # CONFIG_NETFILTER is not set # # SCTP Configuration (EXPERIMENTAL) # # CONFIG_IP_SCTP is not set # CONFIG_ATM is not set # CONFIG_BRIDGE is not set # CONFIG_VLAN_8021Q is not set # CONFIG_DECNET is not set # CONFIG_LLC2 is not set # CONFIG_IPX is not set # CONFIG_ATALK is not set # CONFIG_X25 is not set # CONFIG_LAPB is not set # CONFIG_NET_DIVERT is not set # CONFIG_ECONET is not set # CONFIG_WAN_ROUTER is not set # CONFIG_NET_FASTROUTE is not set # CONFIG_NET_HW_FLOWCONTROL is not set # # QoS and/or fair queueing # # CONFIG_NET_SCHED is not set # # Network testing # # CONFIG_NET_PKTGEN is not set # CONFIG_NETPOLL is not set # CONFIG_NET_POLL_CONTROLLER is not set # CONFIG_HAMRADIO is not set # CONFIG_IRDA is not set # CONFIG_BT is not set # CONFIG_TUX is not set CONFIG_NETDEVICES=y # CONFIG_DUMMY is not set # CONFIG_BONDING is not set # CONFIG_EQUALIZER is not set # CONFIG_TUN is not set # # ARCnet devices # # CONFIG_ARCNET is not set # # Ethernet (10 or 100Mbit) # CONFIG_NET_ETHERNET=y CONFIG_MII=y # CONFIG_HAPPYMEAL is not set # CONFIG_SUNGEM is not set # CONFIG_NET_VENDOR_3COM is not set # # Tulip family network device support # # CONFIG_NET_TULIP is not set # CONFIG_HP100 is not set CONFIG_NET_PCI=y # CONFIG_PCNET32 is not set # CONFIG_AMD8111_ETH is not set # CONFIG_ADAPTEC_STARFIRE is not set # CONFIG_B44 is not set # CONFIG_FORCEDETH is not set # CONFIG_DGRS is not set CONFIG_EEPRO100=m # CONFIG_EEPRO100_PIO is not set CONFIG_E100=m # CONFIG_E100_NAPI is not set # CONFIG_FEALNX is not set # CONFIG_NATSEMI is not set # CONFIG_NE2K_PCI is not set # CONFIG_8139CP is not set # CONFIG_8139TOO is not set # CONFIG_SIS900 is not set # CONFIG_EPIC100 is not set # CONFIG_SUNDANCE is not set # CONFIG_TLAN is not set # CONFIG_VIA_RHINE is not set # # Ethernet (1000 Mbit) # # CONFIG_ACENIC is not set # CONFIG_DL2K is not set # CONFIG_E1000 is not set # CONFIG_NS83820 is not set # CONFIG_HAMACHI is not set # CONFIG_YELLOWFIN is not set # CONFIG_R8169 is not set # CONFIG_SK98LIN is not set # CONFIG_TIGON3 is not set # # Ethernet (10000 Mbit) # # CONFIG_IXGB is not set # CONFIG_S2IO is not set # # Token Ring devices # # CONFIG_TR is not set # # Wireless LAN (non-hamradio) # # CONFIG_NET_RADIO is not set # # Wan interfaces # # CONFIG_WAN is not set # CONFIG_FDDI is not set # CONFIG_HIPPI is not set # CONFIG_PPP is not set # CONFIG_SLIP is not set # CONFIG_RCPCI is not set # CONFIG_SHAPER is not set # CONFIG_NETCONSOLE is not set # # ISDN subsystem # # CONFIG_ISDN is not set # # Telephony Support # # CONFIG_PHONE is not set # # Input device support # CONFIG_INPUT=y # # Userland interfaces # CONFIG_INPUT_MOUSEDEV=y # CONFIG_INPUT_MOUSEDEV_PSAUX is not set CONFIG_INPUT_MOUSEDEV_SCREEN_X=1024 CONFIG_INPUT_MOUSEDEV_SCREEN_Y=768 # CONFIG_INPUT_JOYDEV is not set # CONFIG_INPUT_TSDEV is not set # CONFIG_INPUT_EVDEV is not set # CONFIG_INPUT_EVBUG is not set # # Input I/O drivers # # CONFIG_GAMEPORT is not set CONFIG_SOUND_GAMEPORT=y CONFIG_SERIO=y CONFIG_SERIO_I8042=y # CONFIG_SERIO_SERPORT is not set # CONFIG_SERIO_CT82C710 is not set # CONFIG_SERIO_PCIPS2 is not set # # Input Device Drivers # CONFIG_INPUT_KEYBOARD=y CONFIG_KEYBOARD_ATKBD=y # CONFIG_KEYBOARD_SUNKBD is not set # CONFIG_KEYBOARD_LKKBD is not set # CONFIG_KEYBOARD_XTKBD is not set # CONFIG_KEYBOARD_NEWTON is not set CONFIG_INPUT_MOUSE=y CONFIG_MOUSE_PS2=y # CONFIG_MOUSE_SERIAL is not set # CONFIG_MOUSE_VSXXXAA is not set # CONFIG_INPUT_JOYSTICK is not set # CONFIG_INPUT_TOUCHSCREEN is not set # CONFIG_INPUT_MISC is not set # # Character devices # CONFIG_VT=y CONFIG_VT_CONSOLE=y CONFIG_HW_CONSOLE=y # CONFIG_SERIAL_NONSTANDARD is not set # # Serial drivers # # CONFIG_SERIAL_8250 is not set # # Non-8250 serial port support # CONFIG_UNIX98_PTYS=y # CONFIG_LEGACY_PTYS is not set # CONFIG_CRASH is not set # CONFIG_QIC02_TAPE is not set # # IPMI # # CONFIG_IPMI_HANDLER is not set # # Watchdog Cards # # CONFIG_WATCHDOG is not set # CONFIG_HW_RANDOM is not set # CONFIG_NVRAM is not set # CONFIG_RTC is not set # CONFIG_GEN_RTC is not set # CONFIG_DTLK is not set # CONFIG_R3964 is not set # CONFIG_APPLICOM is not set # CONFIG_SONYPI is not set # # Ftape, the floppy tape device driver # # CONFIG_FTAPE is not set # CONFIG_AGP is not set # CONFIG_DRM is not set # CONFIG_MWAVE is not set # CONFIG_RAW_DRIVER is not set # CONFIG_HANGCHECK_TIMER is not set # # I2C support # # CONFIG_I2C is not set # # Misc devices # # CONFIG_IBM_ASM is not set # # Multimedia devices # # CONFIG_VIDEO_DEV is not set # # Digital Video Broadcasting Devices # # CONFIG_DVB is not set # # Graphics support # # CONFIG_FB is not set # CONFIG_VIDEO_SELECT is not set # # Console display driver support # CONFIG_VGA_CONSOLE=y # CONFIG_MDA_CONSOLE is not set CONFIG_DUMMY_CONSOLE=y # # Sound # # CONFIG_SOUND is not set # # USB support # # CONFIG_USB is not set # # USB Gadget Support # # CONFIG_USB_GADGET is not set # # File systems # CONFIG_EXT2_FS=y CONFIG_EXT2_FS_XATTR=y CONFIG_EXT2_FS_POSIX_ACL=y CONFIG_EXT2_FS_SECURITY=y CONFIG_EXT3_FS=y CONFIG_EXT3_FS_XATTR=y CONFIG_EXT3_FS_POSIX_ACL=y CONFIG_EXT3_FS_SECURITY=y CONFIG_JBD=y # CONFIG_JBD_DEBUG is not set CONFIG_FS_MBCACHE=y # CONFIG_REISERFS_FS is not set # CONFIG_JFS_FS is not set CONFIG_FS_POSIX_ACL=y # CONFIG_XFS_FS is not set # CONFIG_MINIX_FS is not set CONFIG_ROMFS_FS=y # CONFIG_QUOTA is not set CONFIG_AUTOFS_FS=y # CONFIG_AUTOFS4_FS is not set # # CD-ROM/DVD Filesystems # # CONFIG_ISO9660_FS is not set # CONFIG_UDF_FS is not set # # DOS/FAT/NT Filesystems # CONFIG_FAT_FS=y CONFIG_MSDOS_FS=y CONFIG_VFAT_FS=y # CONFIG_NTFS_FS is not set # # Pseudo filesystems # CONFIG_PROC_FS=y CONFIG_PROC_KCORE=y CONFIG_SYSFS=y # CONFIG_DEVFS_FS is not set # CONFIG_DEVPTS_FS_XATTR is not set CONFIG_TMPFS=y # CONFIG_HUGETLBFS is not set # CONFIG_HUGETLB_PAGE is not set CONFIG_RAMFS=y # # Miscellaneous filesystems # # CONFIG_ADFS_FS is not set # CONFIG_AFFS_FS is not set # CONFIG_HFS_FS is not set # CONFIG_HFSPLUS_FS is not set # CONFIG_BEFS_FS is not set # CONFIG_BFS_FS is not set # CONFIG_EFS_FS is not set CONFIG_CRAMFS=y # CONFIG_VXFS_FS is not set # CONFIG_HPFS_FS is not set # CONFIG_QNX4FS_FS is not set # CONFIG_SYSV_FS is not set # CONFIG_UFS_FS is not set # # Network File Systems # # CONFIG_NFS_FS is not set # CONFIG_NFSD is not set # CONFIG_EXPORTFS is not set # CONFIG_SMB_FS is not set # CONFIG_CIFS is not set # CONFIG_NCP_FS is not set # CONFIG_CODA_FS is not set # CONFIG_INTERMEZZO_FS is not set # CONFIG_AFS_FS is not set # # Partition Types # CONFIG_PARTITION_ADVANCED=y # CONFIG_ACORN_PARTITION is not set # CONFIG_OSF_PARTITION is not set # CONFIG_AMIGA_PARTITION is not set # CONFIG_ATARI_PARTITION is not set # CONFIG_MAC_PARTITION is not set CONFIG_MSDOS_PARTITION=y # CONFIG_BSD_DISKLABEL is not set # CONFIG_MINIX_SUBPARTITION is not set # CONFIG_SOLARIS_X86_PARTITION is not set # CONFIG_UNIXWARE_DISKLABEL is not set # CONFIG_LDM_PARTITION is not set # CONFIG_NEC98_PARTITION is not set # CONFIG_SGI_PARTITION is not set # CONFIG_ULTRIX_PARTITION is not set # CONFIG_SUN_PARTITION is not set # CONFIG_EFI_PARTITION is not set # # Native Language Support # CONFIG_NLS=y CONFIG_NLS_DEFAULT="utf8" # CONFIG_NLS_CODEPAGE_437 is not set # CONFIG_NLS_CODEPAGE_737 is not set # CONFIG_NLS_CODEPAGE_775 is not set # CONFIG_NLS_CODEPAGE_850 is not set # CONFIG_NLS_CODEPAGE_852 is not set # CONFIG_NLS_CODEPAGE_855 is not set # CONFIG_NLS_CODEPAGE_857 is not set # CONFIG_NLS_CODEPAGE_860 is not set # CONFIG_NLS_CODEPAGE_861 is not set # CONFIG_NLS_CODEPAGE_862 is not set # CONFIG_NLS_CODEPAGE_863 is not set # CONFIG_NLS_CODEPAGE_864 is not set # CONFIG_NLS_CODEPAGE_865 is not set # CONFIG_NLS_CODEPAGE_866 is not set # CONFIG_NLS_CODEPAGE_869 is not set # CONFIG_NLS_CODEPAGE_936 is not set # CONFIG_NLS_CODEPAGE_950 is not set # CONFIG_NLS_CODEPAGE_932 is not set # CONFIG_NLS_CODEPAGE_949 is not set # CONFIG_NLS_CODEPAGE_874 is not set # CONFIG_NLS_ISO8859_8 is not set # CONFIG_NLS_CODEPAGE_1250 is not set # CONFIG_NLS_CODEPAGE_1251 is not set # CONFIG_NLS_ISO8859_1 is not set # CONFIG_NLS_ISO8859_2 is not set # CONFIG_NLS_ISO8859_3 is not set # CONFIG_NLS_ISO8859_4 is not set # CONFIG_NLS_ISO8859_5 is not set # CONFIG_NLS_ISO8859_6 is not set # CONFIG_NLS_ISO8859_7 is not set # CONFIG_NLS_ISO8859_9 is not set # CONFIG_NLS_ISO8859_13 is not set # CONFIG_NLS_ISO8859_14 is not set # CONFIG_NLS_ISO8859_15 is not set # CONFIG_NLS_KOI8_R is not set # CONFIG_NLS_KOI8_U is not set CONFIG_NLS_UTF8=y # # Profiling support # # CONFIG_PROFILING is not set # # Kernel hacking # # CONFIG_DEBUG_KERNEL is not set CONFIG_EARLY_PRINTK=y # CONFIG_DEBUG_SPINLOCK_SLEEP is not set # CONFIG_FRAME_POINTER is not set # # Security options # # CONFIG_SECURITY is not set # # Cryptographic options # # CONFIG_CRYPTO is not set # # Library routines # # CONFIG_CRC32 is not set # CONFIG_LIBCRC32C is not set CONFIG_ZLIB_INFLATE=y CONFIG_X86_BIOS_REBOOT=y CONFIG_X86_STD_RESOURCES=y CONFIG_PC=y From davep at dpawson.co.uk Wed Aug 4 17:54:29 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 04 Aug 2004 18:54:29 +0100 Subject: CVS Mirror In-Reply-To: <1091561230.3378.4501.camel@erato.phig.org> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> <1091555588.2056.18.camel@homer> <1091561230.3378.4501.camel@erato.phig.org> Message-ID: <1091642069.2020.35.camel@homer> On Tue, 2004-08-03 at 20:27, Karsten Wade wrote: > On Tue, 2004-08-03 at 10:53, Dave Pawson wrote: > > On Tue, 2004-08-03 at 12:46, redwire at therockmere.com wrote: > > > FC1 and FC2 have been in production since APRIL, it seems important to ME > > > at least that there be some sort of documentation made avail. Also, I > > > think that releasing some documentation would help alleviate some of the > > > errant posting of questions to the fedora-docs mailing list. > > > > > > The other alt. is to consider a FC docs based website, on my server, and > > > ask for any interested doc mailing list participants to send their docs to > > > me and I'll post them. > > > > I was thinking, kind offer etc, until I read Karstens mail, which I > > believe to be from within Redhat. > > Sorry, can you elaborate? I'm positive I stated my own opinions > clearly, and not that of Red Hat or anyone else involved in Fedora. I > don't understand what you mean here. > > > If RH are saying they don't care about documentation, lets put the work > > in somewhere else? At least until RH realise its important. > > Did someone say this? Where and when specifically, please? I'm happy > to help apply cluestick. Tue, 03 Aug 2004 10:35:19 -0700, your good self This is just speaking for myself, not Red Hat, but I don't think there is any specific work being done outside this project (read: this mailing list) on a process as you describe - taking a document from idea through to publication. What you see in the Documentation Guide, on &FDP-URL[1];, and on this mailing list is it, afaik. To me that implies, as you said, if we don't do it, it won't get done? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Wed Aug 4 18:01:52 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 04 Aug 2004 19:01:52 +0100 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <1091561532.3378.4523.camel@erato.phig.org> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> <1091561532.3378.4523.camel@erato.phig.org> Message-ID: <1091642512.2020.43.camel@homer> On Tue, 2004-08-03 at 20:32, Karsten Wade wrote: > > I think you are correct, and are welcome to start up a docs repository > of Fedora documentation. You can even have every single thing that is > in the Fedora docs project, thanks to the FDL. You may come here > looking for contributors, help, and ideas, although you may be told it's > no longer on topic. But what you describe is starting to sound like a > fork to me, and as such is outside of the scope of the Fedora docs > project. Not how I read it Karsten. > That said, if we want a short-term CVS holding tank to build a new > fedora-docs tree for submission back into the permanent Fedora CVS, and > you want to setup and administer that, I don't think it can hurt. As > long as it's understood that it's temporary. That's how I heard it. > > This example illustrates my point. When FC2test1 was coming out, I was > helping Ed Bailey with the release notes, and many of us realized we > desperately needed an FAQ for the test release. With the timing of the > test release, there wasn't time for me to write the FAQ and go through > the process to publish on fedora.redhat.com/docs. We also needed to be > able to add and fix questions/answers in the FAQ on very short notice, > like immediately. With no good solution in site, I decided to host it > on my people.redhat.com page. What makes you think things will change over time? Shouldn't the publishing cycle react to keep up with the things its describing? Do you expect RH to provide more people on the docs front? I don't. > > Now I have a small logistics problem. That URL is the well known and > propagated URL. It should be on fedora.redhat.com/docs/selinux-faq (or > something like that), and when I do move it over there, I will have to > figure out how to move visitors from people.redhat.com to > fedora.redhat.com, or face keeping multiple sites live indefinitely. Or run a redirect? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Wed Aug 4 21:18:51 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 04 Aug 2004 17:18:51 -0400 Subject: Fedora install boot floppy doc In-Reply-To: <4110F566.8020904@nedron.net> References: <4110F566.8020904@nedron.net> Message-ID: <1091654331.2682.31.camel@bettie.internal.frields.org> On Wed, 2004-08-04 at 10:40, David Nedrow wrote: > I've begun a document that details how to create a boot floppy for > Fedora installs on systems that don't have CD-ROM drives, etc. > Several people suggested I participate in the docs list to see about > adding it into the doc stream. > It's already in Docbook XML format, since that's what we do all of our > documentation in at work. > Several people have already contributed additions, including a script to > pretty much handle the gruntwork automatically. > I'm including a text transform of the first draft. > I haven't lloked at the Fedora doc guidelines yet, but if I remember > correctly they're pretty straightforward, so it should be relatively > easy for me to jimmy things around if necessary. [...snip...] I only see a few style problems such as voice, etc. Perhaps the document could also include a bit noting that you can simply take .ko modules from an existing installation if you have one running that kernel version. I used to do this a few years ago when presented with the same problem; I don't know of any relevant 2.6-related issue with that procedure. If I can make one small suggestion for the "Create new initrd" section... all those command lines seem a bit wearying. Why not: cd ~/bootwork/initrd-old find -type f | cpio -pamd ../initrd-new # aahhh... cd .. cp anaconda-ks.cfg initrd-new/ks.cfg cp -a modules.cgz initrd-new/modules umount initrd-new gzip -c9 initrd > initrd.img cp initrd.img floppy Just a thought, there. To me, this is a good idea for a doc, since I've taught it manually to a bunch of people myself, a couple of them pretty recently, in fact. If you need someone to edit, feel free to send me the source when you feel you've tinkered with it sufficiently. -- Paul W. Frields, RHCE From paul at frields.com Wed Aug 4 21:21:00 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 04 Aug 2004 17:21:00 -0400 Subject: Process suggestions vol. 1 In-Reply-To: <41104473.3060004@redhat.com> References: <1091570269.2580.27.camel@bettie.internal.frields.org> <41104473.3060004@redhat.com> Message-ID: <1091654460.2682.35.camel@bettie.internal.frields.org> On Tue, 2004-08-03 at 22:05, Mark Johnson wrote: > Your brain dump is chock full of useful suggestions, esp regarding the > content of a "Getting Started writng Docs for Fedora", or whatever the > document name turns out to be. > > I hope you don't mind if I "appropriate" some of your ideas into the > fedora-docs tutorial:-) [...snip...] You're welcome to... I'm heartened that anything I said was of any value. Could be that my ego is taking a beating at my day job. ;-) Are you willing to discuss what you liked, and whether I can help you with any of the writing? I don't want to just launch off on my own and duplicate efforts, of course. Still working on a vol. 2 -- forewarned is four-armed! Erm, there goes my editorial position. -- Paul W. Frields, RHCE From redwire at therockmere.com Thu Aug 5 12:17:29 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Thu, 5 Aug 2004 08:17:29 -0400 (EDT) Subject: Clarification In-Reply-To: <20040804144120.540F9740D3@hormel.redhat.com> References: <20040804144120.540F9740D3@hormel.redhat.com> Message-ID: <60083.199.224.21.254.1091708249.squirrel@TheRockmere.com> I guess I kicked the hornets nest...so, Let me clarify a couple of points that I raised in my last post I am not suggesting that we Fork the doc project. I used the offer of setting a CVS on my server only as repository for completed documentation, to be made avail on a website. I'm not openning my server to become a public FTP. Not going to happen. But, I may have been a little OT with my terminology. In order to offer my server for this I need it to be 90-95% automated. Like most of you, I work, have kids and blah, blah, blah [ insert your busy sched. here ;-) ]. I am looking for controlled thruput. That is why I didn't suggest a WiKi. I believe that the document integrity needs to be maintained. The DocBook s/b published to a site with versioning. I propose to give CVS or U'L access to ONLY the active members of this list group for upload of Completed project(s). Then they are propagate to the website. Docs are then avail for dissemination. OK, here is what I have to ask\state; 1) Is this acceptable to the group? 2) Can CVS port to a live site? if so, where is the tutorial. Is there a better tool for this idea? ( I can have a Nuke site up ASAP, but I dis-like some of the display features for docs,but, can the RSS feeds pull the data?) 3) If RH opens their CVS ~ or starts posting docs ~ then they become prime 4) Proposed \ avail names? 5) I'm not asking you, singularly or as a group, to duplicate your published work to 2 CVS's if there is a way to scrap the RH CVS. if so, how? Lastly, Karsten ~ TY for the shameless plug. I love tech writing and trning, but I'd never get that job ~ I write like I talk ~ rambling on-and-on-and... you get the idea! > Since you opened the can, I don't mind a shameless plug as a reward for > reading this far ... :) ... There is at least one position for a tech > writer at Red Hat. > > http://redhat.hrdpt.com/cgi-bin/a/highlightjob.cgi?jobid=7 > > This is the position that authors the System Administration Guide, so > requires a fair amount of Linux and writing expertise. > > If you are a perfect fit for this position, feel free to contact me, > I'll see your resume gets to the right person. > Thanks, Brad From help at codefit.com Fri Aug 6 19:15:48 2004 From: help at codefit.com (codefit) Date: Fri, 6 Aug 2004 15:15:48 -0400 Subject: Documentation for VSFTPD RPM and setup - install info? Message-ID: Hi there, Can anyone point me to a url for VSFTPD RPM info for RH 8? Thanks very much. From paul at frields.com Fri Aug 6 20:36:58 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 06 Aug 2004 16:36:58 -0400 Subject: Documentation for VSFTPD RPM and setup - install info? In-Reply-To: References: Message-ID: <1091824618.3280.1.camel@bettie.internal.frields.org> On Fri, 2004-08-06 at 15:15, codefit wrote: > Can anyone point me to a url for VSFTPD RPM info for RH 8? Hmm. We deal with Fedora documentation here, but have you tried: http://vsftpd.beasts.org http://redhat.com/docs ? -- Paul W. Frields, RHCE From help at codefit.com Fri Aug 6 21:31:42 2004 From: help at codefit.com (codefit) Date: Fri, 6 Aug 2004 17:31:42 -0400 Subject: Documentation for VSFTPD RPM and setup - install info? In-Reply-To: <1091824618.3280.1.camel@bettie.internal.frields.org> Message-ID: Yes thanks Paul, I did check out vsftpd.beasts.org this am, very informative. I was also hoping to find such info on the RH 8 URL you listed below, checked it today and did not find anything on the VSFTPD. I'd rather get the source and info from RH if I could. Is there a good RH 8 forum or list you know of? Isn't the RH 8 list on the red hat site closed now? -----Original Message----- From: fedora-docs-list-bounces at redhat.com [mailto:fedora-docs-list-bounces at redhat.com]On Behalf Of Paul W. Frields Sent: Friday, August 06, 2004 4:37 PM To: For participants of the docs project Subject: Re: Documentation for VSFTPD RPM and setup - install info? On Fri, 2004-08-06 at 15:15, codefit wrote: > Can anyone point me to a url for VSFTPD RPM info for RH 8? Hmm. We deal with Fedora documentation here, but have you tried: http://vsftpd.beasts.org http://redhat.com/docs ? -- Paul W. Frields, RHCE -- fedora-docs-list mailing list fedora-docs-list at redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list From hugofmesquita at yahoo.com Fri Aug 6 22:34:14 2004 From: hugofmesquita at yahoo.com (Fernando) Date: Fri, 6 Aug 2004 17:34:14 -0500 Subject: Documentation for VSFTPD RPM and setup - install info? References: <1091824618.3280.1.camel@bettie.internal.frields.org> Message-ID: <001501c47c05$80fe80e0$033c9645@delldesk1> I've tried so many times to unsubscribe from this list that now I give up. I guess since it didn't work I'll have to go ahead and setup a rule in my inbox to delete messages automatically. Sincerely, Fernando. ----- Original Message ----- From: "Paul W. Frields" To: "For participants of the docs project" Sent: Friday, August 06, 2004 3:36 PM Subject: Re: Documentation for VSFTPD RPM and setup - install info? > On Fri, 2004-08-06 at 15:15, codefit wrote: > > Can anyone point me to a url for VSFTPD RPM info for RH 8? > > Hmm. We deal with Fedora documentation here, but have you tried: > > http://vsftpd.beasts.org > http://redhat.com/docs > ? > -- > Paul W. Frields, RHCE > > > -- > fedora-docs-list mailing list > fedora-docs-list at redhat.com > To unsubscribe: > http://www.redhat.com/mailman/listinfo/fedora-docs-list From paul at frields.com Fri Aug 6 22:39:43 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 06 Aug 2004 18:39:43 -0400 Subject: Documentation for VSFTPD RPM and setup - install info? In-Reply-To: References: Message-ID: <1091831983.4879.1.camel@bettie.internal.frields.org> On Fri, 2004-08-06 at 17:31, codefit wrote: > Yes thanks Paul, I did check out vsftpd.beasts.org this am, very > informative. > I was also hoping to find such info on the RH 8 URL you listed below, > checked it today and did not find anything on the VSFTPD. I'd rather get > the source and > info from RH if I could. > > Is there a good RH 8 forum or list you know of? Isn't the RH 8 list on the > red hat site closed now? Not at all... visit the list page at: http://www.redhat.com/mailman/listinfo/redhat-list/ The list looks like it's plenty active to me. Sorry I didn't mention it sooner! I'm sure you can find assistance there for whatever details are giving you trouble. Good luck and best wishes. -- Paul W. Frields, RHCE From kwade at redhat.com Mon Aug 9 09:57:03 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 09 Aug 2004 02:57:03 -0700 Subject: Clarification In-Reply-To: <60083.199.224.21.254.1091708249.squirrel@TheRockmere.com> References: <20040804144120.540F9740D3@hormel.redhat.com> <60083.199.224.21.254.1091708249.squirrel@TheRockmere.com> Message-ID: <1092045423.4488.28029.camel@erato.phig.org> On Thu, 2004-08-05 at 05:17, redwire at therockmere.com wrote: > I guess I kicked the hornets nest... Aww, you only tried to solve a problem that plagues us all. > so, Let me clarify a couple of points > that I raised in my last post > I am not suggesting that we Fork the doc project. Okay, I understand that, and maybe fork was too harsh of a word, but given this: > I used the offer of setting a CVS on my server only as repository for > completed documentation, to be made avail on a website. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ I'm not really concerned about the CVS, or even a Wiki for that matter ... as repositories of source content that can come over to the One True CVS in a few, simple steps. Dave Pawson, for example, has demonstrated a working method for taking Anaconda docs written in Wiki and converting them to vanilla DocBook. It's the "made avail(able) on a website" that is a concern. I think it would be very useful to advance the current XML codebase in a CVS somewhere while we wait for the One True CVS, but we really need to hold off on disseminating a URL for the documents, i.e., in announcements, on mailing lists, etc. Documents are a little different from software; when they are in a broken, unusable state, they can _look_ working and lead users astray. Broken code will usually just segfault and be done with it. A broken document can be disastrous. It's really OK if we develop documents without "releasing early, releasing often." > I propose to give CVS or U'L access to ONLY the active members of this > list group for upload of Completed project(s). Then they are propagate to > the website. Docs are then avail for dissemination. I like this except for the propagation to random URLs as even temporary locations. We can have everything lined up for going onto fedora.redhat.com/docs when we can make those changes, which might even be at anytime. > OK, here is what I have to ask\state; Speaking for myself ... > 1) Is this acceptable to the group? With my caveats, yes. Ye gods know I don't have time to set up a CVS server right now. :) > 2) Can CVS port to a live site? if so, where is the tutorial. Is there a > better tool for this idea? > ( I can have a Nuke site up ASAP, but I dis-like some of the display > features for docs,but, can the RSS feeds pull the data?) I recommend we stick to CVS for now. I'm sold on the value of that idea. > 3) If RH opens their CVS ~ or starts posting docs ~ then they become prime We are the Fedora docs project, regardless of who holds the gate keys. Let's act like we are FDP, and when we rattle the gate, we'll have baskets and baskets of documents ready to post > 4) Proposed \ avail names? > 5) I'm not asking you, singularly or as a group, to duplicate your > published work to 2 CVS's if there is a way to scrap the RH CVS. if so, > how? I think your CVS can become the latest tree, and get merged back into Fedora CVS, then you can maintain a mirror if it suits you. > Lastly, Karsten ~ TY for the shameless plug. I love tech writing and > trning, but I'd never get that job ~ I write like I talk ~ rambling > on-and-on-and... you get the idea! You betcha. cheers - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 9 10:05:58 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 09 Aug 2004 03:05:58 -0700 Subject: Using elvis? In-Reply-To: <1091530137.3271.21.camel@hermione.aeon.com.my> References: <1091155694.18914.26.camel@hermione.aeon.com.my> <1091169289.11946.11661.camel@erato.phig.org> <1091530137.3271.21.camel@hermione.aeon.com.my> Message-ID: <1092045958.4488.28066.camel@erato.phig.org> On Wed, 2004-08-04 at 04:58, Colin Charles wrote: > On Fri, 2004-07-30 at 16:34, Karsten Wade wrote: > > > > We've been talking about public CVS for far too long, and I think the > > > longer we wait, the longer Fedora Docs becomes less & less relevant > > > > Sorry if I'm being dense, but I don't understand how having public CVS > > resolves the problems of Fedora docs? I see a lack of content, some > > broken processes, and barriers to entry, but I don't see how public CVS > > resolves that. > > People can commit to a place - it will be in one central location - > there will be drive and interest to write it I think we are in agreement, at least on the major points: 1. A temporary CVS is useful, and Brad is generous to offer to setup and maintain such. 2. Hosting Fedora docs not at fedora.redhat.com/docs is fractious and confusing. > Where do people who write Fedora docs now commit things to? Or host it? > FedoraNEWS.ORG seems like a welcome host (but its not Fedora Docs!). > Random websites on the Net look like welcome hosts (but i ts not Fedora > Docs!) > > We need docs in one place, not scattered all over the Net - we have to > grow as a project, and we don't have docs to start with (sending people > to RHL9 documentation is *embarassing*) > > Lack of content is because there are broken processes and barriers to > entry. Stop telling people that there's Emacs, and only Emacs to use. > Let people write in HTML, and we might even find folk whom want to > DocBookify them - remember, together we stand and colloboration is the > way to get work done. Let's work like how FreeBSD/Gentoo get > documentation done (which is excellent, in comparison to ours) That would make a wonderful bugzilla/RFE, to change our Doc Guide to say that other formats are welcome _if_ the author gets on the list and finds at least one person willing to help with the conversion. I think that 50% of the HTML-based authors will get excited about maintaining their own doc in DocBook. Perhaps part of the process of maintaining a doc over the long term is to actually learn the toolchain. But the toolchain need not be a barrier. And, as you say, if we have a CVS to commit to, work will get done just because now there is somewhere to put it. I'm sold on that idea. > > > Keeping in mind that the barrier of entry is already relatively high > > > (you need to know DocBook, you need to use Emacs, etc...), this makes > > > folk move closer to creating docs on 3rd party sites > > > > Agreed about the difficulties. To address this, Mark Johnson mentioned > > the idea of doing a Fedora Docs Quick Start Guide. He would make it a > > focused tutorial, using his psgmlx mode for Emacs, which gives a > > friendly and useful XML editing environment. Would that be helpful? > > I'm guessing. I can use Emacs, so this doesn't apply. Maybe we want to > ask fedora-list folk? Some kind of Quick Start guide would be good, and it can have a short chapter that tells you how to use other editors and toolchains, if they will work. Mainly, I think we should try to spend our energy on tools that work under Fedora Core. > > Still, Emacs is not required, and there have been plenty of offers to > > convert and actual conversions from just about any source document into > > a Fedora doc. The contribution of content is what is lacking. > > Yes. Notice I've been picking out bits and pieces from fedora-list and > sending it to fedora-docs-list? I'll continue doing this... > > But I'm willing to bet the lack of contribution is because the > momentum/wheel hasn't started rolling Right. Out of these threads, I'm hoping we'll have the following: * A bunch of bug reports on existing documents and websites * Several specific lists of content that is ready to post on /docs * Specific changes to make to /projects/docs I'm in agreement with the rest of your points. - Karsten > > Going back to the CVS, I don't see how giving write access to people who > > are having difficulties learning the tools is helpful? > > Give it to those that know how to use it. If say, 10 of us here have CVS > write access, we can get quite a lot of work done, I'm sure. Once there > are some actual Fedora Docs sitting online, at our documentation site > (not 3rd party sites, scattered, everywhere), we can definitely > encourage more to contribute > > > OTOH, giving write access to some of the people who a) know the tools, > > and b) have demonstrated their ability to submit good code, that would > > be a great thing. > > Not code, just documentation. If I see errors, it's easily fixable (and > I'm sure others who have write access will do it too) > > > > Why can't we use elvis.redhat.com ? Anaconda, translations and so on > > > happen at elvis, so why not fedora docs? This will mean external > > > contributors *can* commit to cvs as well > > > > This is an interesting end-run idea. Speaking for myself, my > > inclination is not to create a parallel system to what is being worked > > on and waited for. > > We are actually using elvis.redhat.com (my bad!). elvis==rhlinux. Its > just that we don't have commit access > > Parallel system is more targetted towards source - I've not actually > heard much mention about supporting the docs project. I'm sure its part > of it, but its mighty silent > > The longer we wait, the longer 3rd party sites will get stronger, making > this project more and more irrelevant > > > My email about what content is actually ready for CVS and posting on > > fedora.redhat.com/docs is very relevant to your question. Once we know > > exactly what there is to post and put in CVS, then we have something to > > agitate about. Deliver the content, and we'll find a way to get it > > posted. > > I think there's content, and you've identified some. There's plenty > scattered on the Net (anaconda, davep has some, etc...), now the hard > task is getting it all in one place. Oh wait, we don't have this one > place :) > > Don't get me wrong, I'm playing the Devil's Advocate here, but someone > has to do it. FC3 is going to be out within a couple of months, and we > have absolutely zero usable documentation. We should aim for a handbook > styled documentation, not point people to dated RHL9 docs > -- > Colin Charles, byte at aeon.com.my > http://www.bytebot.net/ > "First they ignore you, then they laugh at you, then they fight you, > then you win." -- Mohandas Gandhi -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 9 10:18:52 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 09 Aug 2004 03:18:52 -0700 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <1091642512.2020.43.camel@homer> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> <1091561532.3378.4523.camel@erato.phig.org> <1091642512.2020.43.camel@homer> Message-ID: <1092046731.4488.28120.camel@erato.phig.org> On Wed, 2004-08-04 at 11:01, Dave Pawson wrote: > On Tue, 2004-08-03 at 20:32, Karsten Wade wrote: > > > > > I think you are correct, and are welcome to start up a docs repository > > of Fedora documentation. You can even have every single thing that is > > in the Fedora docs project, thanks to the FDL. You may come here > > looking for contributors, help, and ideas, although you may be told it's > > no longer on topic. But what you describe is starting to sound like a > > fork to me, and as such is outside of the scope of the Fedora docs > > project. > > Not how I read it Karsten. > > > That said, if we want a short-term CVS holding tank to build a new > > fedora-docs tree for submission back into the permanent Fedora CVS, and > > you want to setup and administer that, I don't think it can hurt. As > > long as it's understood that it's temporary. > > That's how I heard it. Okay, I'm sold on the value of the second. I still don't think it's a good idea to worry about hosting separate "unofficial Fedora docs" repositories. The One True CVS will open up before the end of time, I'm sure, and in the meantime we can probably find a way to get changes posted to fedora.redhat.com. > > This example illustrates my point. When FC2test1 was coming out, I was > > helping Ed Bailey with the release notes, and many of us realized we > > desperately needed an FAQ for the test release. With the timing of the > > test release, there wasn't time for me to write the FAQ and go through > > the process to publish on fedora.redhat.com/docs. We also needed to be > > able to add and fix questions/answers in the FAQ on very short notice, > > like immediately. With no good solution in site, I decided to host it > > on my people.redhat.com page. > > What makes you think things will change over time? > Shouldn't the publishing cycle react to keep up with the things its > describing? > Do you expect RH to provide more people on the docs front? > I don't. Heck, RH isn't really "providing" any people on the docs front right now. :) Really, I'm sure there are others like me whose "real work" inside Red Hat only marginally touches upon Fedora. I write books for Enterprise Linux, and the toolchain, processes, and content for that work is only related to Fedora docs by the sharing of the word "DocBook". When I say that I'm here speaking for myself, I mean that. ;-) That's not to say the outlook is bleak! Actually, it appears to me that our stodgy corporate documentation process has some problems fitting with the real Fedora docs project. It's good that everyone is shooting holes into it, especially if those get filed as bug reports so they get taken care of. :) > > Now I have a small logistics problem. That URL is the well known and > > propagated URL. It should be on fedora.redhat.com/docs/selinux-faq (or > > something like that), and when I do move it over there, I will have to > > figure out how to move visitors from people.redhat.com to > > fedora.redhat.com, or face keeping multiple sites live indefinitely. > > Or run a redirect? It's not that there isn't a solution to my problem, it's that it requires some intervention and maintenance, and I don't want to wish that on everybody else's docs. Kinda messy. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 9 10:22:16 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 09 Aug 2004 03:22:16 -0700 Subject: CVS Mirror In-Reply-To: <1091642069.2020.35.camel@homer> References: <62321.199.224.21.254.1091533590.squirrel@TheRockmere.com> <1091555588.2056.18.camel@homer> <1091561230.3378.4501.camel@erato.phig.org> <1091642069.2020.35.camel@homer> Message-ID: <1092046935.4488.28134.camel@erato.phig.org> On Wed, 2004-08-04 at 10:54, Dave Pawson wrote: > > On Tue, 2004-08-03 at 20:27, Karsten Wade wrote: > > Tue, 03 Aug 2004 10:35:19 -0700, your good self > > This is just speaking for myself, not Red Hat, but I don't think there > > is any specific work being done outside this project (read: this mailing > > list) on a process as you describe - taking a document from idea through > > to publication. > > > What you see in the Documentation Guide, on &FDP-URL[1];, and on this > > mailing list is it, afaik. > > > To me that implies, as you said, if we don't do it, it won't get done? Yes. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Mon Aug 9 10:34:34 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 09 Aug 2004 11:34:34 +0100 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <1092046731.4488.28120.camel@erato.phig.org> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> <1091561532.3378.4523.camel@erato.phig.org> <1091642512.2020.43.camel@homer> <1092046731.4488.28120.camel@erato.phig.org> Message-ID: <1092047674.2020.21.camel@homer> Just addressing the issue of hosting html versions of documentation, as well as using the cvs. If the site is clearly labelled 'holding pen', with a clean link to some rh url where it should be (if RH get their fingers out) then I can't see an issue. I do see a real benefit from people seeing new documentation appearing. It shows this project is live. We've had to offers of documentation this last week or so. Have both gone into the bit bucket? Good test for an 'interim'/Brads CVS? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Mon Aug 9 10:38:17 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 09 Aug 2004 03:38:17 -0700 Subject: Fedora install boot floppy doc In-Reply-To: <4110F566.8020904@nedron.net> References: <4110F566.8020904@nedron.net> Message-ID: <1092047897.4488.28195.camel@erato.phig.org> On Wed, 2004-08-04 at 07:40, David Nedrow wrote: > I've begun a document that details how to create a boot floppy for > Fedora installs on systems that don't have CD-ROM drives, etc. > > Several people suggested I participate in the docs list to see about > adding it into the doc stream. > > It's already in Docbook XML format, since that's what we do all of our > documentation in at work. This looks great so far. I'll be happy to offer an edit of the XML; I like to give patches in a useful format. :) > Several people have already contributed additions, including a script to > pretty much handle the gruntwork automatically. > > I'm including a text transform of the first draft. > > I haven't lloked at the Fedora doc guidelines yet, but if I remember > correctly they're pretty straightforward, so it should be relatively > easy for me to jimmy things around if necessary. It's pretty straightforward. You should be able to grab the example from CVS, read the bug report, and jimmy your document into the structure. Here are some more useful details: http://fedora.redhat.com/participate/documentation-guide/ch-tutorial.html -- current best description of how to layout a tutorial. It is a little dated, and there are several bugs in it (e.g. the DocBook version at the top should be 4.2) ... To view all the open Fedora docs bugs, and thereby understand what to do differently, I'll post the huge URL below[1]. You can also find it as a link on http://fedora.redhat.com/projects/docs/ midway down the page called "All open bugs for fedora-docs". Also on the Fedora docs project webpage are instructions for grabbing modules from CVS. You'll want fedora-docs/example-tutorial and fedora-docs/common. This bug has some useful fixes to the example-tutorial. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=128903 . I recently proposed some common entities to be found in fedora-docs/common/fedora-entities-en.xml ... you'll need to apply this convention yourself, it's not part of the proper CVS yet. I presume that it's going to be used, but I'm only speaking for myself on this one. This is the start of that thread on the list: http://redhat.com/archives/fedora-docs-list/2004-July/msg00046.html hth - Karsten [1] http://bugzilla.redhat.com/bugzilla/buglist.cgi?short_desc_type=allwordssubstr&component=fedora-docs&bug_status=ASSIGNED&bug_status=MODIFIED&bug_status=NEEDINFO&bug_status=NEW&bug_status=REOPENED&bug_status=VERIFIED&bug_severity=high&bug_severity=low&bug_severity=normal&bug_severity=security&bug_severity=translation&long_desc_type=allwordssubstr&bug_file_loc_type=allwordssubstr&status_whiteboard_type=allwordssubstr&fixed_in_type=allwordssubstr&devel_whiteboard_type=allwordssubstr&keywords_type=allwords&cust_facing=YES&emailassigned_to1=1&emailtype1=exact&emailreporter2=1&emailtype2=exact&bugidtype=include&chfieldto=Now&cmdtype=doit&remaction=run&namedcmd=blank&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 9 10:41:18 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 09 Aug 2004 03:41:18 -0700 Subject: Fedora install boot floppy doc In-Reply-To: <1092047897.4488.28195.camel@erato.phig.org> References: <4110F566.8020904@nedron.net> <1092047897.4488.28195.camel@erato.phig.org> Message-ID: <1092048078.4488.28206.camel@erato.phig.org> On Mon, 2004-08-09 at 03:38, Karsten Wade wrote: [snip verbosity] Almost forgot, #fedora-docs on irc.freenode.net. If you have questions or problems while setting up your
, see if anyone is home to help. I try to be. :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From byte at aeon.com.my Tue Aug 10 08:07:59 2004 From: byte at aeon.com.my (Colin Charles) Date: Tue, 10 Aug 2004 18:07:59 +1000 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <1092047674.2020.21.camel@homer> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> <1091561532.3378.4523.camel@erato.phig.org> <1091642512.2020.43.camel@homer> <1092046731.4488.28120.camel@erato.phig.org> <1092047674.2020.21.camel@homer> Message-ID: <1092125278.25749.6.camel@hermione.aeon.com.my> On Mon, 2004-08-09 at 20:34, Dave Pawson wrote: > If the site is clearly labelled 'holding pen', with a clean > link to some rh url where it should be (if RH get their fingers out) > then I can't see an issue. > I do see a real benefit from people seeing new documentation > appearing. It shows this project is live. No, I think I'll agree with Karsten on this - let's not set something up externally, if we know the projects' one is almost there Two reasons for this: 1. Familiarity with the external CVS will mean that people know one resource now, and they'll have to re-learn another resource soon. Bad marketing move 2. Less pressure on the Fedora Steering Committee to release CVS ASAP Its double-edged to push for the official Fedora CVS, but also to not set one up externally. So while the offer is kind, it might mean that if Brad's CVS is set up one way, with perms and everyone getting commit access, while the Fedora one will be more restricted, it just causes lots of issues later on > We've had to offers of documentation this last week or so. > Have both gone into the bit bucket? Bugzilla them, file it under fedora-docs, and we'll keep track of them -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From davep at dpawson.co.uk Tue Aug 10 08:50:54 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 10 Aug 2004 09:50:54 +0100 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <1092125278.25749.6.camel@hermione.aeon.com.my> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> <1091561532.3378.4523.camel@erato.phig.org> <1091642512.2020.43.camel@homer> <1092046731.4488.28120.camel@erato.phig.org> <1092047674.2020.21.camel@homer> <1092125278.25749.6.camel@hermione.aeon.com.my> Message-ID: <1092127854.2018.14.camel@homer> On Tue, 2004-08-10 at 09:07, Colin Charles wrote: > On Mon, 2004-08-09 at 20:34, Dave Pawson wrote: > > > If the site is clearly labelled 'holding pen', with a clean > > link to some rh url where it should be (if RH get their fingers out) > > then I can't see an issue. > > I do see a real benefit from people seeing new documentation > > appearing. It shows this project is live. > > No, I think I'll agree with Karsten on this - let's not set something up > externally, if we know the projects' one is almost there But its not, as Karsten pointed out? No support from RH is putting it bluntly, but accurately AFAIK. > 2. Less pressure on the Fedora Steering Committee to release CVS ASAP Fair comment, but what will it take to make them move at all? They've shown the inertia of the Titanic so far. > > We've had to offers of documentation this last week or so. > > Have both gone into the bit bucket? > > Bugzilla them, file it under fedora-docs, and we'll keep track of them Not been done. No author perms AFAIK? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Tue Aug 10 12:37:35 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 10 Aug 2004 08:37:35 -0400 Subject: fedora-docs-list Digest, Vol 6, Issue 3 In-Reply-To: <1092127854.2018.14.camel@homer> References: <20040803160012.C19EA73D96@hormel.redhat.com> <20296.199.224.21.254.1091552503.squirrel@TheRockmere.com> <1091561532.3378.4523.camel@erato.phig.org> <1091642512.2020.43.camel@homer> <1092046731.4488.28120.camel@erato.phig.org> <1092047674.2020.21.camel@homer> <1092125278.25749.6.camel@hermione.aeon.com.my> <1092127854.2018.14.camel@homer> Message-ID: <1092141455.6309.5.camel@berlin.east.gov> On Tue, 2004-08-10 at 04:50, Dave Pawson wrote: > > > We've had to offers of documentation this last week or so. > > > Have both gone into the bit bucket? > > > > Bugzilla them, file it under fedora-docs, and we'll keep track of them > > Not been done. > No author perms AFAIK? David Nedrow, Just in case you haven't been following the discussion of late, could you please either: (1) Go to Bugzilla and enter a bug against fedora-docs, attaching your XML source for the boot floppy document you brought to the list; or, if that's not convenient for you, (2) Send the XML source to me and I'll be happy to do it for you. This will allow us to show your item as a pending addition for the Docs Project, and make sure it gets into the editorial and distribution processes. Thanks, and cheers! -- Paul W. Frields, RHCE From kwade at redhat.com Wed Aug 11 02:52:55 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 10 Aug 2004 19:52:55 -0700 Subject: Process suggestions vol. 1 In-Reply-To: <1091570269.2580.27.camel@bettie.internal.frields.org> References: <1091570269.2580.27.camel@bettie.internal.frields.org> Message-ID: <1092192775.4488.30857.camel@erato.phig.org> On Tue, 2004-08-03 at 14:57, Paul W. Frields wrote: > The following is a core dump, because I have to get to a HOA meeting and > want to strike while the iron is hot. (Why yes, that *does* mean I have > a thick head, thanks for noticing.) [snipped] - the original can be found at: http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00028.html Okay, that was great to work with. Sparked a lot of ideas for me. I liked the format/flow, thinking of this as a lifecycle. I submit the following as a next step. Please, Please read this thoroughly. It's just a bunch of ideas put together coherently by me, because that's what I do. It needs the deep thought of everyone who is serious about this project's success. http://people.redhat.com/kwade/fedora-docs/process-docs/writing_lifecycle.txt This document presumes the existence of the process it describes, just as a stylistic decision; many pieces of the process will need to be created. I tried to identify all the roles needed and parts of the process that are unwritten or otherwise don't exist. As the intro to the process itself states, the idea is to get a process we want to start with, then we divide up the parts to work on, such as writing additional chapters for the Doc Guide, defining how an editorial team works together, etc. We enact each part as it moves into a usable beta stage, trying to get the process working as early as possible for real world testing. How does that sound? - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Wed Aug 11 07:18:35 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 11 Aug 2004 08:18:35 +0100 Subject: Process suggestions vol. 1 In-Reply-To: <1092192775.4488.30857.camel@erato.phig.org> References: <1091570269.2580.27.camel@bettie.internal.frields.org> <1092192775.4488.30857.camel@erato.phig.org> Message-ID: <1092208715.2570.9.camel@homer> On Wed, 2004-08-11 at 03:52, Karsten Wade wrote: > > http://people.redhat.com/kwade/fedora-docs/process-docs/writing_lifecycle.txt Comment. I'm nervous about the number of 'titles' around? (Roles) Agree the jobs need doing; Some 'titles' aren't mentioned again? (package maintainer) Specifics: Invalid use for emacs. If you want your xml tidying up say so. XSLT can indent nicely with no content change. (identity transform, output set to indent=yes. Generally agree though. Want it marking up? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Wed Aug 11 08:27:07 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 11 Aug 2004 01:27:07 -0700 Subject: Process suggestions vol. 1 In-Reply-To: <1092208715.2570.9.camel@homer> References: <1091570269.2580.27.camel@bettie.internal.frields.org> <1092192775.4488.30857.camel@erato.phig.org> <1092208715.2570.9.camel@homer> Message-ID: <1092212827.4488.31196.camel@erato.phig.org> On Wed, 2004-08-11 at 00:18, Dave Pawson wrote: > On Wed, 2004-08-11 at 03:52, Karsten Wade wrote: > > > > http://people.redhat.com/kwade/fedora-docs/process-docs/writing_lifecycle.txt > > Comment. I'm nervous about the number of 'titles' around? (Roles) These aren't empty titles, they are roles to be fulfilled in a process. Not intended to add bureaucracy, just layers to get stuff done and make sure it is of a consistent quality. > Agree the jobs need doing; > Some 'titles' aren't mentioned again? (package maintainer) Somewhere toward the end I mention that we may want to have a fedora-docs RPM that goes in Core, Extras, etc., which contains a snapshot of documentation for the related version of FC. That package would need a maintainer, in addition to having a process to decide what goes into the package. > Specifics: > Invalid use for emacs. > If you want your xml tidying up say so. > XSLT can indent nicely with no content change. (identity transform, > output set to indent=yes. I'll disagree about that being a valid use of Emacs, but whatever. ;-) You can't blindly indent the document and walk away. If you anything in a or block that requires specific formatting (white space, etc.) -- such as code from a program, example from a config file, or a series of command line examples -- doing a DTD based indent will likely mess up those sections. If that is not true, I'd be very happy to see a demonstration. Otherwise, I will continue to manually C-c C-q my XML in Emacs. > Generally agree though. > > Want it marking up? Not a problem to do it myself, just wanted to get it more set in sandstone before going over from plain text. :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Wed Aug 11 08:57:26 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 11 Aug 2004 09:57:26 +0100 Subject: Process suggestions vol. 1 In-Reply-To: <1092212827.4488.31196.camel@erato.phig.org> References: <1091570269.2580.27.camel@bettie.internal.frields.org> <1092192775.4488.30857.camel@erato.phig.org> <1092208715.2570.9.camel@homer> <1092212827.4488.31196.camel@erato.phig.org> Message-ID: <1092214646.9043.5.camel@homer> On Wed, 2004-08-11 at 09:27, Karsten Wade wrote: > > > > Comment. I'm nervous about the number of 'titles' around? (Roles) > > These aren't empty titles, they are roles to be fulfilled in a process. > Not intended to add bureaucracy, just layers to get stuff done and make > sure it is of a consistent quality. In which case its rephrasing then? 'The following tasks need doing' or 'terminology'? > > > Agree the jobs need doing; > > Some 'titles' aren't mentioned again? (package maintainer) > > Somewhere toward the end I mention that we may want to have a > fedora-docs RPM that goes in Core, Extras, etc., which contains a > snapshot of documentation for the related version of FC. That package > would need a maintainer, in addition to having a process to decide what > goes into the package. OK, I misunderstood... or it wasn't clear. You decide. > > > Specifics: > > Invalid use for emacs. > > If you want your xml tidying up say so. > > XSLT can indent nicely with no content change. (identity transform, > > output set to indent=yes. > > I'll disagree about that being a valid use of Emacs, but whatever. ;-) > > You can't blindly indent the document and walk away. If you anything in > a or block that requires specific formatting > (white space, etc.) -- such as code from a program, example from a > config file, or a series of command line examples -- doing a DTD based > indent will likely mess up those sections. If that is not true, I'd be > very happy to see a demonstration. Otherwise, I will continue to > manually C-c C-q my XML in Emacs. Yes. For docbook just list the element names requiring whitespace retaining. The rest get 'tidied' up. > > Not a problem to do it myself, just wanted to get it more set in > sandstone before going over from plain text. :) OK Save you 5 mins. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl -------------- next part -------------- A non-text attachment was scrubbed... Name: process.xml Type: text/xml Size: 16478 bytes Desc: not available URL: From davep at dpawson.co.uk Wed Aug 11 10:18:59 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 11 Aug 2004 11:18:59 +0100 Subject: Process suggestions vol. 1 In-Reply-To: <1092212827.4488.31196.camel@erato.phig.org> References: <1091570269.2580.27.camel@bettie.internal.frields.org> <1092192775.4488.30857.camel@erato.phig.org> <1092208715.2570.9.camel@homer> <1092212827.4488.31196.camel@erato.phig.org> Message-ID: <1092219539.9043.11.camel@homer> On Wed, 2004-08-11 at 09:27, Karsten Wade wrote: > You can't blindly indent the document and walk away. If you anything in > a or block that requires specific formatting > (white space, etc.) -- such as code from a program, example from a > config file, or a series of command line examples -- doing a DTD based > indent will likely mess up those sections. If that is not true, I'd be > very happy to see a demonstration. Attached, clean.xsl Works with any docbook file. Note: indent is an implementation option. Saxon does it. I know msxsl doesn't, 'cos it doesn't play fair with ws :-) YMMV -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl -------------- next part -------------- A non-text attachment was scrubbed... Name: clean.xsl Type: text/x-xslt Size: 497 bytes Desc: not available URL: From byte at aeon.com.my Thu Aug 12 05:07:39 2004 From: byte at aeon.com.my (Colin Charles) Date: Thu, 12 Aug 2004 15:07:39 +1000 Subject: New tracker Message-ID: <1092287259.2973.20.camel@albus.aeon.com.my> Since no one else started it, the tracker now is: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129722 I've added various docs that should be on the site, so to speak. Comments, etc.. welcome (on the bug) Paul, I notice several docs at docs.frields.org, if they're ready, or awaiting QA/editors, you should submit them to bugzilla Regards -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From byte at aeon.com.my Thu Aug 12 09:34:38 2004 From: byte at aeon.com.my (Colin Charles) Date: Thu, 12 Aug 2004 19:34:38 +1000 Subject: [Fwd: Re: Creating Customized Single CD distro] Message-ID: <1092303278.2973.36.camel@albus.aeon.com.my> Can we use this, along with the anaconda docs? Looks like it requires some DocBook-ifying, but yeah, it might be useful -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi -------------- next part -------------- An embedded message was scrubbed... From: "Manilal K M" Subject: Re: Creating Customized Single CD distro Date: Thu, 12 Aug 2004 10:48:10 +0600 Size: 3917 URL: From davep at dpawson.co.uk Thu Aug 12 09:45:22 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 12 Aug 2004 10:45:22 +0100 Subject: usb-keys Message-ID: <1092303921.2516.14.camel@homer> Since we've heard no more from this guy; here's the attributed docbook version, -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl -------------- next part -------------- A non-text attachment was scrubbed... Name: usbkeys.xml Type: text/xml Size: 9761 bytes Desc: not available URL: From paul at frields.com Thu Aug 12 13:35:14 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 12 Aug 2004 09:35:14 -0400 Subject: [Fwd: Re: Creating Customized Single CD distro] In-Reply-To: <1092303278.2973.36.camel@albus.aeon.com.my> References: <1092303278.2973.36.camel@albus.aeon.com.my> Message-ID: <1092317713.18844.113.camel@berlin.east.gov> On Thu, 2004-08-12 at 05:34, Colin Charles wrote: > Can we use this, along with the anaconda docs? http://www.coolgoose.com/sites/lal_tvm/anaconda.html > Looks like it requires some DocBook-ifying, but yeah, it might be > useful Sure. Questions you need to answer first: 1. Does it work, as is? If not, correct the technical material. 2. Does it contain any glaring grammatical errors, or is the language unclear in any portion? If so, try and fix them. (Remember that this document might/must be translated by others, so make the sentences concise and clear.) 3. Can you mark up the XML? If not, feel free to ask for help. 4. Make a bugzilla entry either linking to a URL for your corrected copy, or attach the XML code. Make sure you take a look at Karsten's lifecycle suggestions from earlier this week: http://people.redhat.com/kwade/fedora-docs/process-docs/writing_lifecycle.txt Good suggestion for a document. Now to take it to the next level.... -- Paul W. Frields, RHCE From paul at frields.com Thu Aug 12 13:41:15 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 12 Aug 2004 09:41:15 -0400 Subject: usb-keys In-Reply-To: <1092303921.2516.14.camel@homer> References: <1092303921.2516.14.camel@homer> Message-ID: <1092318074.18844.126.camel@berlin.east.gov> On Thu, 2004-08-12 at 05:45, Dave Pawson wrote: > Since we've heard no more from this guy; here's the attributed docbook > version, Hi Dave, Have you already looked at my updfstab-tutorial? I think it presents a better technical solution that works with the existing subsystems (hotplug, kudzu) rather than creating a need for another one (autofs in this case). I like autofs too, but I normally use it only for things like NFS or SMB mounts, since it doesn't have great support in the spatial browser. Mounts supported by updfstab will appear in the "Computer" browser, which makes the user experience a little more seamless. Please check out the current version at my site, http://docs.frields.org ... there's a HTML-browseable copy for convenience. I've been working on intergrating Tim Waugh's guidelines for troubleshooting hotplug problems such as missing USB vendor/product information. -- Paul W. Frields, RHCE From byte at aeon.com.my Thu Aug 12 13:51:36 2004 From: byte at aeon.com.my (Colin Charles) Date: Thu, 12 Aug 2004 23:51:36 +1000 Subject: [Fwd: Re: Creating Customized Single CD distro] In-Reply-To: <1092317713.18844.113.camel@berlin.east.gov> References: <1092303278.2973.36.camel@albus.aeon.com.my> <1092317713.18844.113.camel@berlin.east.gov> Message-ID: <1092318696.2973.53.camel@albus.aeon.com.my> On Thu, 2004-08-12 at 23:35, Paul W. Frields wrote: > > Can we use this, along with the anaconda docs? > http://www.coolgoose.com/sites/lal_tvm/anaconda.html > > Looks like it requires some DocBook-ifying, but yeah, it might be > > useful > > Sure. Questions you need to answer first: These are questions down to the original author, thanks. I just forward interesting bits that could be possible docs (if you've been noticing lately) - since I read all the lists, I might as well assign bits and pieces that seem useful to different parts of the project > Good suggestion for a document. Now to take it to the next level.... Yes -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From paul at frields.com Thu Aug 12 13:53:43 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 12 Aug 2004 09:53:43 -0400 Subject: fedora-docs bugs Message-ID: <1092318823.18844.155.camel@berlin.east.gov> At Colin's behest I added a few more bugs for docs on which I am working (and would love some help). I also changed some of my existing bugs to reflect "enhancement" rather than "normal" severity. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129738 http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129739 Colin also helpfully entered a bug regarding ESR's Fedora Multimedia HOWTO. However, I think that this particular request may not be one that the Fedora Documentation Project should handle. You can read the bug and my comments here, after which my reasons might be clearer: http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129721 As an aside, remember that documentation that is published under the GNU FDL is suitable fodder for inclusion in the FDP. The FDL is an obvious signal of the author's intent to share this content with others. It's always courteous, though, and probably a good SOP, to let the author know your intentions; if nothing else, it gives them a "warm fuzzy" that their work might go on to help a broader audience. The particular case in point may not be the best example of material the FDP should include, but it's definitely a good example of how to put the FDL to good use. -- Paul W. Frields, RHCE From paul at frields.com Thu Aug 12 13:56:11 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 12 Aug 2004 09:56:11 -0400 Subject: New tracker In-Reply-To: <1092287259.2973.20.camel@albus.aeon.com.my> References: <1092287259.2973.20.camel@albus.aeon.com.my> Message-ID: <1092318971.18844.159.camel@berlin.east.gov> On Thu, 2004-08-12 at 01:07, Colin Charles wrote: > Since no one else started it, the tracker now is: > > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129722 > > I've added various docs that should be on the site, so to speak. > Comments, etc.. welcome (on the bug) > > Paul, I notice several docs at docs.frields.org, if they're ready, or > awaiting QA/editors, you should submit them to bugzilla Only one is close to "ready" status, the updfstab-tutorial. I am incorporating some info from Tim Waugh's site, but it should be noted that FC3 will likely obsolete most or all of this document, as noted in the Bugzilla entry by Bill Nottingham. See: http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=128952 Several of the other documents were submitted by subscribers to this list. Gavin Henry sent me a link to the samba-ldap tutorial; someone else (I apologize for forgetting the name, but I'm sure it's in the archives) sent the ClamAV tutorial. I'll Bugzilla both of them. (*Note: done now.) These two tutorials still contain some atrocious style and syntax and desperately need some rewriting. Also, I am not familiar with all the subject matter, and would prefer that a more knowledgeable person test the content to make sure it's valid. In the absence of a Style Guide, I can't really demand that anyone take up the banner for these pieces (even the original submitters), but if anyone's willing to have a go at them, it would be appreciated. Karsten, I was going to suggest that folks send me their patches directly (rather than putting them in Bugzilla), so that I can prevent conflicts in the patches, as well as retain some editorial role and participate in the cleanup. Do you see any problems with using that method, if only temporarily? -- Paul W. Frields, RHCE From davep at dpawson.co.uk Thu Aug 12 15:14:12 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 12 Aug 2004 16:14:12 +0100 Subject: usb-keys In-Reply-To: <1092318074.18844.126.camel@berlin.east.gov> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> Message-ID: <1092323652.2541.4.camel@homer> On Thu, 2004-08-12 at 14:41, Paul W. Frields wrote: > On Thu, 2004-08-12 at 05:45, Dave Pawson wrote: > > Since we've heard no more from this guy; here's the attributed docbook > > version, > > Hi Dave, > > Have you already looked at my updfstab-tutorial? I think it presents a > better technical solution that works with the existing subsystems > (hotplug, kudzu) rather than creating a need for another one (autofs in > this case). I like autofs too, but I normally use it only for things > like NFS or SMB mounts, since it doesn't have great support in the > spatial browser. Mounts supported by updfstab will appear in the > "Computer" browser, which makes the user experience a little more > seamless. > > Please check out the current version at my site, http://docs.frields.org > ... there's a HTML-browseable copy for convenience. I've been working on > intergrating Tim Waugh's guidelines for troubleshooting hotplug problems > such as missing USB vendor/product information. 1. I'm in no position to judge either as being better / worse. 2. Any reason to have more than one alternative? Are you (is anyone) in a position to say this is better/easier if ..... 3. I do actually need / want such doco myself, since I use a flash card in a reader :-) (And I did it a.n.otherway :-) Anyway Paul, I was first to get it to the list :-) So there Dunno where to go from here. Tammy? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Thu Aug 12 15:20:04 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 12 Aug 2004 16:20:04 +0100 Subject: New tracker In-Reply-To: <1092318971.18844.159.camel@berlin.east.gov> References: <1092287259.2973.20.camel@albus.aeon.com.my> <1092318971.18844.159.camel@berlin.east.gov> Message-ID: <1092324003.2541.9.camel@homer> On Thu, 2004-08-12 at 14:56, Paul W. Frields wrote: > > These two tutorials still contain some atrocious style and syntax and > desperately need some rewriting. Also, I am not familiar with all the > subject matter, and would prefer that a more knowledgeable person test > the content to make sure it's valid. In the absence of a Style Guide, I > can't really demand that anyone take up the banner for these pieces > (even the original submitters), but if anyone's willing to have a go at > them, it would be appreciated. I'll have a go at improving them Paul, if its style. Karsten, did you have a 'techie' review in your process document? Somebody such as me has written a piece. I think its great. I don't realise that my xyz is way out different from the majority. Needed. A geek to read a piece with a wider view, to pick up oddities. E.g. This morning I realised that the author had 'assumed' that root had a different prompt from 'userX'. This may|may not be typical. I 'judged' it a weak assumption. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Thu Aug 12 16:24:42 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 12 Aug 2004 12:24:42 -0400 Subject: usb-keys In-Reply-To: <1092323652.2541.4.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> Message-ID: <1092327882.18844.186.camel@berlin.east.gov> On Thu, 2004-08-12 at 11:14, Dave Pawson wrote: > > Have you already looked at my updfstab-tutorial? I think it presents a > > better technical solution that works with the existing subsystems > > (hotplug, kudzu) rather than creating a need for another one (autofs in > > this case). I like autofs too, but I normally use it only for things > > like NFS or SMB mounts, since it doesn't have great support in the > > spatial browser. Mounts supported by updfstab will appear in the > > "Computer" browser, which makes the user experience a little more > > seamless. > > > > Please check out the current version at my site, http://docs.frields.org > > ... there's a HTML-browseable copy for convenience. I've been working on > > intergrating Tim Waugh's guidelines for troubleshooting hotplug problems > > such as missing USB vendor/product information. > > 1. I'm in no position to judge either as being better / worse. > 2. Any reason to have more than one alternative? > Are you (is anyone) in a position to say this is better/easier if > ..... > 3. I do actually need / want such doco myself, since I use a flash card > in a reader :-) (And I did it a.n.otherway :-) > Anyway Paul, I was first to get it to the list :-) So there For 1 & 2, I guess I meant "better" in the sense that the hotplug/updfstab method (1) is a way that both makes a more consistent user interface (see comments above), (2) does not depend on the hardware configuration remaining constant between insertions (i.e. what happens if next time you have one or more other USB storage devices plugged in already?), and (3) allows the user to contribute back to the community by entering a bug against either hotplug or kudzu for their particular USB device, so others can benefit. As for your flash card, I'm genuinely curious: Does your card reader not allow the card to report its identity using "lsusb -v" or dmesg? If it does, the process in updfstab-tutorial will work. If not, I'd love it if you would try out the process in the updfstab-tutorial and let me know where it breaks so I can fix it. :-) Q.v. my BZ entry from 8/1: http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=128952 Having said all that, there's always more than one way to skin a cat! Perhaps we could combine these in such a way as to make the whole thing palatable to a broader audience? It seems to me a single document that gives multiple methods is better than finding several partly or wholly inconsistent documents, each professing to be the One True Method(TM). -- Paul W. Frields, RHCE From kwade at redhat.com Thu Aug 12 17:40:55 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 12 Aug 2004 10:40:55 -0700 Subject: [Fwd: Re: Creating Customized Single CD distro] In-Reply-To: <1092318696.2973.53.camel@albus.aeon.com.my> References: <1092303278.2973.36.camel@albus.aeon.com.my> <1092317713.18844.113.camel@berlin.east.gov> <1092318696.2973.53.camel@albus.aeon.com.my> Message-ID: <1092332454.4488.33292.camel@erato.phig.org> On Thu, 2004-08-12 at 06:51, Colin Charles wrote: > On Thu, 2004-08-12 at 23:35, Paul W. Frields wrote: > > > > Can we use this, along with the anaconda docs? > > http://www.coolgoose.com/sites/lal_tvm/anaconda.html > > > Looks like it requires some DocBook-ifying, but yeah, it might be > > > useful > > > > Sure. Questions you need to answer first: > > > > These are questions down to the original author, thanks. I just forward > interesting bits that could be possible docs (if you've been noticing > lately) - since I read all the lists, I might as well assign bits and > pieces that seem useful to different parts of the project Yes, this is a good example of an idea or existing document without an author. I'm thinking that perhaps the process should be, when an idea has enough weight to make a bugzilla report, make it one, and have it block the master tracker. In many ways, bugzilla has a manual workflow, comment tracking, and other features to make it a usable CMS (content management system). So, I filed 129782 for this Anaconda customization doc. It's OK if we file 100 and drop 70 of them into the bit-bucket, it's a better tracking and dropping mechanism than the mailing list. :) I set it to block 129722 for now, although that bug is nominally for finished, ready to post docs. I'm wondering, should we have a separate tracker bug that is just for "docs moving from idea to ready-to-publish"? Oh, wait, I decided to do that. So, 129784 is now a bucket for catching docs with authors but not ready for CVS and ideas without authors or needing conversion. 129782 is now only tracked by 129784. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Thu Aug 12 17:43:29 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 12 Aug 2004 10:43:29 -0700 Subject: New tracker In-Reply-To: <1092324003.2541.9.camel@homer> References: <1092287259.2973.20.camel@albus.aeon.com.my> <1092318971.18844.159.camel@berlin.east.gov> <1092324003.2541.9.camel@homer> Message-ID: <1092332609.4488.33300.camel@erato.phig.org> On Thu, 2004-08-12 at 08:20, Dave Pawson wrote: > On Thu, 2004-08-12 at 14:56, Paul W. Frields wrote: > > > > > These two tutorials still contain some atrocious style and syntax and > > desperately need some rewriting. Also, I am not familiar with all the > > subject matter, and would prefer that a more knowledgeable person test > > the content to make sure it's valid. In the absence of a Style Guide, I > > can't really demand that anyone take up the banner for these pieces > > (even the original submitters), but if anyone's willing to have a go at > > them, it would be appreciated. > > I'll have a go at improving them Paul, if its style. > > Karsten, did you have a 'techie' review in your process document? In my mind, I thought of this as part of the editor role. However, that might be asking too many skills of an editor - grammar/writing and technical review. There is some value in having it be a separate role. Since one person can fill many roles, we may find that our writing/style editors at the start are also technical editors, and that new editors choose to do one or the other role or both. The key in that process which might not have been obvious is -- it's all about writers and editors. Everything from acceptance as in-progress for Fedora docs to publication on fedora.redhat.com needs to be an agreement between the author(s) and the editor(s). Which reminds me, I need to find someone to edit the FC2 SELinux FAQ before it can go live ... - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Thu Aug 12 17:56:53 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 12 Aug 2004 10:56:53 -0700 Subject: editors Message-ID: <1092333413.4488.33328.camel@erato.phig.org> Here are some further ideas about the role of an editor: * Helps writing adhere throughout the creation process to the (unwritten) Style Guide(lines). * The relationship between authors and editors will take many forms. Some people will create a pairing, two or more people who work together regularly on a set of docs. * Two people can edit each other's document. This is often a good way to get a technical edit. * Before going live, a document needs two editorial sign-offs -- writing style (grammar, spelling, etc.) and technical content. * Should there be an editorial board? Such a board would oversee the Fedora docs, make sure we are adhering to our standards, filling in holes, following or advancing our process, etc. * Separate mailing list for editors? Or just accept that fedora-docs-list gets busier with traffic between editors and authors. The more I think about it, the more I think we should keep all traffic on the one mailing list until there is a solid reason split. For example, the editorial board needs to do its deliberations and decisions in the open, and it's unfair to make people go to a separate mailing list just to see that. We'll get better community input if we do editorial stuff on the main list. * Also, much of the editing traffic can be in bugzilla, as each document will have it's own bug throughout it's lifecycle. * The board can be in charge of deciding between competing or conflicting documents. Still, we can agree that more choice is better, so having documents that cover multiple methods of solving the same problems just means we get to bundle them together as a set. :) * The board needs to have an odd number of people so that if consensus can't be reached, a majority vote without a tie is possible. * The board members don't necessarily have to edit anything actively. * Editorial board could just form like Voltron right now from available interested parties (myself included there, please), and proceed with some process defining. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Thu Aug 12 18:01:01 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 12 Aug 2004 11:01:01 -0700 Subject: usb-keys In-Reply-To: <1092327882.18844.186.camel@berlin.east.gov> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> Message-ID: <1092333660.4488.33339.camel@erato.phig.org> On Thu, 2004-08-12 at 09:24, Paul W. Frields wrote: > Having said all that, there's always more than one way to skin a cat! > Perhaps we could combine these in such a way as to make the whole thing > palatable to a broader audience? It seems to me a single document that > gives multiple methods is better than finding several partly or wholly > inconsistent documents, each professing to be the One True Method(TM). For maintainability sake, it might be easier to keep things separate. Either way, we could have a document set that covers multiple methods. Fedora Doc Set: Hot Plugging or something. I was thinking that doc sets are a way for us to get something that more closely resembles one of the classic Red Hat Linux guides, without the associated maintenance hassle. Believe me, it is a true full-time job writing and maintaining just one of those guides. Besides, modularizing projects to get a greater sum from the parts is the open source way! - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From tlarge at thelug.org Thu Aug 12 18:36:40 2004 From: tlarge at thelug.org (Tom Large) Date: Thu, 12 Aug 2004 13:36:40 -0500 Subject: Self-Introduction: Tom Large In-Reply-To: <1092192775.4488.30857.camel@erato.phig.org> References: <1091570269.2580.27.camel@bettie.internal.frields.org> <1092192775.4488.30857.camel@erato.phig.org> Message-ID: <411BB8B8.1040203@thelug.org> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 ~ Full Name: Thomas (Tom) Large ~ Country, City: USA -- Dallas, Texas ~ Profession: Open Systems Architect ~ Company: Clear Technologies, Inc ~ Goals In Fedora Project: Assist With Document Creation and eventually become an editor. Historical Qualifications: Founder and contributor of THELUG. See sig. ~ Have written technical documents for ~ various businesses from a consulting ~ perspective over the years. ~ Have played with Linux since '94, and ~ worked with professionally since '97. ~ Speak PERL, PHP, BASH, KSH, SQL, HTML, ~ and XML scripting/formatting languages. ~ Specialize in nothing, but spend most ~ time with security and network related ~ tasks. GPG KEYID and fingerprint: pub 1024D/CCFEBEB7 2004-05-26 Tom Large (No Comment) tlarge at thelug.org> ~ Key fingerprint = 5D10 45E0 4E3E 216C AEE1 FE64 52B5 75D0 CCFE EB7 sub 1024g/37154B3F 2004-05-26 Aside from all that, I'm mainly just interested in working with an Open Source project that I use regularly and can get some satisfaction out of helping. Thanks, /tlarge - -- ~ - T H E L U G ~ - The Hectic Eclectic Linux User Group ~ - Linux without attitude, or directions, or goals... ~ - http://www.thelug.org -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.4 (GNU/Linux) iD8DBQFBG7i4UrV10Mz+vrcRAlcbAJ9Rn4jdmRIz3bWt9fvsoWnpKaey3QCgjnTe 7ZZwBUQmF7VbSTAH7Ot5EeQ= =zq6i -----END PGP SIGNATURE----- From kwade at redhat.com Thu Aug 12 19:38:41 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 12 Aug 2004 12:38:41 -0700 Subject: Self-Introduction: Tom Large Message-ID: <1092339521.4488.33458.camel@erato.phig.org> Welcome, Tom! On Thu, 2004-08-12 at 11:36, Tom Large wrote: > Aside from all that, I'm mainly just interested in working with an Open > Source project that I use regularly and can get some satisfaction out of > helping. We're just starting to gather ideas in a bucket in https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129784. Do you come with any specific ideas of where Fedora needs documenting? > ~ - T H E L U G > ~ - The Hectic Eclectic Linux User Group > ~ - Linux without attitude, or directions, or goals... > ~ - http://www.thelug.org Ha! Careful, or someone might want to franchise that idea. :) - Karsten ps - sorry, had to break the message-id ;-) -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From tlarge at thelug.org Thu Aug 12 19:53:32 2004 From: tlarge at thelug.org (Tom Large) Date: Thu, 12 Aug 2004 14:53:32 -0500 Subject: Self-Introduction: Tom Large In-Reply-To: <1092339521.4488.33458.camel@erato.phig.org> References: <1092339521.4488.33458.camel@erato.phig.org> Message-ID: <411BCABC.7020402@thelug.org> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Karsten Wade wrote: | Welcome, Tom! Thanks! | We're just starting to gather ideas in a bucket in | https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129784. Do you | come with any specific ideas of where Fedora needs documenting? I was originally thinking about some troubleshooting tutorials--how to resolve problems like a corrupted /bin/bash file and the like, but after doing some research (reading some archives and the tutorial on how to write a tutorial) they seemed inappropriate. At this point, I was thinking about helping with some of the "(unwritten)" documents you referenced in the manifesto you linked earlier today or yesterday--though I don't know that I'm familiar enough with existing processes and procedures to create that kind of document. At this point, I'm not really picky--I think once I've done a tut on something I find boring, I'll maybe get more finicky. |>~ - T H E L U G |>~ - The Hectic Eclectic Linux User Group |>~ - Linux without attitude, or directions, or goals... |>~ - http://www.thelug.org | | | Ha! Careful, or someone might want to franchise that idea. :) Heh, that was actually one of the originating thoughts. The goal was to stay a small user group, so when we top 50 or so members, we're going to split it up. Have groups like dallas.thelug.org and ftworth.thelug.org. ~ Oh well... sorry for continuing the off topic discussion here. | ps - sorry, had to break the message-id ;-) I understand. /tlarge - -- ~ - T H E L U G ~ - The Hectic Eclectic Linux User Group ~ - Linux without attitude, or directions, or goals... ~ - http://www.thelug.org -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.4 (GNU/Linux) iD8DBQFBG8q8UrV10Mz+vrcRApBOAKCBZTWvmmhs8ITh7OIsriddDj2U5ACeKDtT SgqNKUyS15NVDwgwCvlUDJA= =dBt3 -----END PGP SIGNATURE----- From paul at frields.com Thu Aug 12 19:54:39 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 12 Aug 2004 15:54:39 -0400 Subject: editors In-Reply-To: <1092333413.4488.33328.camel@erato.phig.org> References: <1092333413.4488.33328.camel@erato.phig.org> Message-ID: <1092340479.18844.244.camel@berlin.east.gov> On Thu, 2004-08-12 at 13:56, Karsten Wade wrote: > Here are some further ideas about the role of an editor: > > * Helps writing adhere throughout the creation process to the > (unwritten) Style Guide(lines). Speaking of which, the eos-guide is "done" in the sense that it is now a complete (and, I believe, correct to the best of my abilities) recreation of the original S&W 1918. However, it obviously needs to be revisited for "Fedora-izing." That's my next project, I promise. :-) I haven't put it in Bugzilla because in order to Fedora-ize it, my plan is to simply create an FDP patch that will be applied to the original XML. > * The relationship between authors and editors will take many forms. > Some people will create a pairing, two or more people who work together > regularly on a set of docs. > > * Two people can edit each other's document. This is often a good way > to get a technical edit. > > * Before going live, a document needs two editorial sign-offs -- writing > style (grammar, spelling, etc.) and technical content. Good points, these. For example, the Samba/LDAP tutorial needs someone who works in a more mixed environment. I don't have any systems at work that are running Windows with which to test this stuff. > * Should there be an editorial board? Such a board would oversee the > Fedora docs, make sure we are adhering to our standards, filling in > holes, following or advancing our process, etc. [...snip...] I'd like to volunteer for the board; it's what I had in mind when I volunteered in the first place. Of course, I've found out since how much work there is to do, and I'm glad that there are so many ways to get involved. I for one would not choose to have a separate editors list. I would also say the board should have some guidelines to help make decisions on a less ad-hoc basis. Having said that, I don't want to create so much advance detail work that it's impossible to actually get to the real work. But at least a statement of principles would be enough to get started. That would also give authors/editors proper guidance for when things are ready to go to the board. > * Also, much of the editing traffic can be in bugzilla, as each document > will have it's own bug throughout it's lifecycle. Perhaps, then, XML patches for docs in Bugzilla should be uploaded to Bugzilla for review by the authors/editors. Does that put too much of a strain on Bugzilla's storage? -- Paul W. Frields, RHCE From paul at frields.com Thu Aug 12 20:57:58 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 12 Aug 2004 16:57:58 -0400 Subject: [Fwd: Re: Creating Customized Single CD distro] In-Reply-To: <1092318696.2973.53.camel@albus.aeon.com.my> References: <1092303278.2973.36.camel@albus.aeon.com.my> <1092317713.18844.113.camel@berlin.east.gov> <1092318696.2973.53.camel@albus.aeon.com.my> Message-ID: <1092344278.4708.0.camel@bettie.internal.frields.org> On Thu, 2004-08-12 at 09:51, Colin Charles wrote: > On Thu, 2004-08-12 at 23:35, Paul W. Frields wrote: > > > > Can we use this, along with the anaconda docs? > > http://www.coolgoose.com/sites/lal_tvm/anaconda.html > > > Looks like it requires some DocBook-ifying, but yeah, it might be > > > useful > > > > Sure. Questions you need to answer first: > > These are questions down to the original author, thanks. I just forward > interesting bits that could be possible docs (if you've been noticing > lately) - since I read all the lists, I might as well assign bits and > pieces that seem useful to different parts of the project I stand corrected! s/need/might want/ -- Paul W. Frields, RHCE From kwade at redhat.com Thu Aug 12 21:55:25 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 12 Aug 2004 14:55:25 -0700 Subject: editors In-Reply-To: <1092340479.18844.244.camel@berlin.east.gov> References: <1092333413.4488.33328.camel@erato.phig.org> <1092340479.18844.244.camel@berlin.east.gov> Message-ID: <1092347725.4488.33720.camel@erato.phig.org> On Thu, 2004-08-12 at 12:54, Paul W. Frields wrote: > On Thu, 2004-08-12 at 13:56, Karsten Wade wrote: > > * Should there be an editorial board? Such a board would oversee the > > Fedora docs, make sure we are adhering to our standards, filling in > > holes, following or advancing our process, etc. > > [...snip...] > > I'd like to volunteer for the board; it's what I had in mind when I > volunteered in the first place. Of course, I've found out since how much > work there is to do, and I'm glad that there are so many ways to get > involved. Yes, 100% agreed, I volunteer for the board, as well; I'm certainly good for the next twelve months (random term limit?), if we can stand me that long. > I for one would not choose to have a separate editors list. I would also > say the board should have some guidelines to help make decisions on a > less ad-hoc basis. Having said that, I don't want to create so much > advance detail work that it's impossible to actually get to the real > work. But at least a statement of principles would be enough to get > started. That would also give authors/editors proper guidance for when > things are ready to go to the board. That sounds exactly right. The statement of principles will guide in making up necessary process as we go along. > > * Also, much of the editing traffic can be in bugzilla, as each document > > will have it's own bug throughout it's lifecycle. > > Perhaps, then, XML patches for docs in Bugzilla should be uploaded to > Bugzilla for review by the authors/editors. Does that put too much of a > strain on Bugzilla's storage? I doubt it, but IANABSA (bugzilla sysadmin). Still, DocBook XML is pretty lightweight compared to software source; it's density is in the ideas within the words, and the tag:content ratio is skewed in that direction[1]. Bit-for-bit, I'd say our documents would be a very efficient usage of bugzilla space. :) - Karsten [1] Incidentally, as a writer this is one of the big attractions for me in DocBook. WYSIWYG editors typically burden a file with a lot of extra junk, making the junk:content ratio poorly balanced, and requires enormous amounts of content to even out or tip the balance toward the content side. DocBook junk:content starts out with a great balance, and keeps that balance as it scales. This is why I usually write in plain text first, it has the best junk:content ratio of all. :) -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Thu Aug 12 23:07:36 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 12 Aug 2004 16:07:36 -0700 Subject: New tracker In-Reply-To: <1092287259.2973.20.camel@albus.aeon.com.my> References: <1092287259.2973.20.camel@albus.aeon.com.my> Message-ID: <1092352056.4488.33859.camel@erato.phig.org> On Wed, 2004-08-11 at 22:07, Colin Charles wrote: > Since no one else started it, the tracker now is: > > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129722 > > I've added various docs that should be on the site, so to speak. > Comments, etc.. welcome (on the bug) Saw Tammy this afternoon, she cleared through a few bugs (if you filed them, you saw the resolution, changes coming to the website) and moved some stuff along. We discussed the doc tracking process, and she expanded the doc tracker bugs, so there is now: 1. http://bugzilla.redhat.com/129784 Docs ideas without owners - a general bucket for ideas for new documents or conversions that come _first_ through the list 2. http://bugzilla.redhat.com/129807 Docs in progress - for tracking documents actively being written/developed/edited 3. http://bugzilla.redhat.com/129722 Docs ready for going to fedora.redhat.com - when it is done with 129807, it comes here while it undergoes final editing to go to the website. This means the process of idea -> publication is: 1. File a bug report for your document, or carry the on the one with the idea in it. 2. Move the bug through the tracker in this order idea -> develop <-> publish 129784 129807 129722 Note: there is a double-arrow between develop <-> publish because a document should stay alive after it is published. Once you have published a version and have moved to writing for the next version of Fedora Core, your document's bug moves back to 129807. I'll add this into the process document, which Dave converted to XML and I am editing for reposting back here for more comments. cheers - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From tfox at redhat.com Fri Aug 13 00:35:16 2004 From: tfox at redhat.com (Tammy Fox) Date: Thu, 12 Aug 2004 20:35:16 -0400 Subject: status Message-ID: <1092357316.11376.231.camel@localhost.localdomain> Hi everyone, My maternity leave ends this month, so I am going through the Fedora docs bugs to start getting back in the swing of things. After that, I'll go through the mailing list to read about what I have missed. So far, here is a summary of the bug reports: Bug #129784 has been created to track docs ideas without owners Bug #129807 has been created to track docs in progress with a writer assigned to it A new bug report must be submitted for any new docs or docs changes so we can keep track of them (these should also be listed as blockers for bug #129807) I have fixed the following bugs: 122665, 123258, 123267, 125751, 125754, 129005 A new version of the Documentation Guide will appear on the website shortly. It is just a maintenance release after fixing the previously mentioned bugs. Cheers, Tammy From tfox at redhat.com Fri Aug 13 00:44:09 2004 From: tfox at redhat.com (Tammy Fox) Date: Thu, 12 Aug 2004 20:44:09 -0400 Subject: fedora-docs bugs In-Reply-To: <1092318823.18844.155.camel@berlin.east.gov> References: <1092318823.18844.155.camel@berlin.east.gov> Message-ID: <1092357849.11376.235.camel@localhost.localdomain> On Thu, 2004-08-12 at 09:53, Paul W. Frields wrote: > At Colin's behest I added a few more bugs for docs on which I am working > (and would love some help). I also changed some of my existing bugs to > reflect "enhancement" rather than "normal" severity. > > http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129738 > http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129739 > Great! Glad to know work on the docs project has started up again. > Colin also helpfully entered a bug regarding ESR's Fedora Multimedia > HOWTO. However, I think that this particular request may not be one that > the Fedora Documentation Project should handle. You can read the bug and > my comments here, after which my reasons might be clearer: > > http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129721 > I agree. I don't think the Fedora Docs Project is the place for information on adding non-open source software to Fedora, especially if that software is not legal. Tammy > As an aside, remember that documentation that is published under the GNU > FDL is suitable fodder for inclusion in the FDP. The FDL is an obvious > signal of the author's intent to share this content with others. It's > always courteous, though, and probably a good SOP, to let the author > know your intentions; if nothing else, it gives them a "warm fuzzy" that > their work might go on to help a broader audience. The particular case > in point may not be the best example of material the FDP should include, > but it's definitely a good example of how to put the FDL to good use. > > -- > Paul W. Frields, RHCE From tfox at redhat.com Fri Aug 13 01:07:21 2004 From: tfox at redhat.com (Tammy Fox) Date: Thu, 12 Aug 2004 21:07:21 -0400 Subject: status In-Reply-To: <1092357316.11376.231.camel@localhost.localdomain> References: <1092357316.11376.231.camel@localhost.localdomain> Message-ID: <1092359241.11376.253.camel@localhost.localdomain> On Thu, 2004-08-12 at 20:35, Tammy Fox wrote: > Hi everyone, > > My maternity leave ends this month, so I am going through the Fedora > docs bugs to start getting back in the swing of things. After that, I'll > go through the mailing list to read about what I have missed. So far, > here is a summary of the bug reports: > > Bug #129784 has been created to track docs ideas without owners > > Bug #129807 has been created to track docs in progress with a writer > assigned to it > > A new bug report must be submitted for any new docs or docs changes so > we can keep track of them (these should also be listed as blockers for > bug #129807) > > I have fixed the following bugs: > 122665, 123258, 123267, 125751, 125754, 129005 > > A new version of the Documentation Guide will appear on the website > shortly. It is just a maintenance release after fixing the previously > mentioned bugs. > Version 0.2.2 is now on the website. I have also updated the main docs project page to include links to the tracker bugs. This change should appear within the hour. Tammy From byte at aeon.com.my Fri Aug 13 02:25:10 2004 From: byte at aeon.com.my (Colin Charles) Date: Fri, 13 Aug 2004 12:25:10 +1000 Subject: editors In-Reply-To: <1092340479.18844.244.camel@berlin.east.gov> References: <1092333413.4488.33328.camel@erato.phig.org> <1092340479.18844.244.camel@berlin.east.gov> Message-ID: <1092363909.2973.68.camel@albus.aeon.com.my> On Fri, 2004-08-13 at 05:54, Paul W. Frields wrote: > > * Should there be an editorial board? Such a board would oversee the > > Fedora docs, make sure we are adhering to our standards, filling in > > holes, following or advancing our process, etc. > > [...snip...] > > I'd like to volunteer for the board; it's what I had in mind when I > volunteered in the first place. Of course, I've found out since how much > work there is to do, and I'm glad that there are so many ways to get > involved. We actually did have an editor list, if someone can pull out the CVS version of http://fedora.redhat.com/projects/docs/ I suggest e-mailing each person, asking if they're still interested in being an editor. Judging by initial interest, you'd have then formed "an editorial board" -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From dataking at cox.net Fri Aug 13 03:47:26 2004 From: dataking at cox.net (D@7@k|N&) Date: Thu, 12 Aug 2004 20:47:26 -0700 Subject: status In-Reply-To: <1092357316.11376.231.camel@localhost.localdomain> Message-ID: -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Hi all, I'm new to the Docs, but I would like to help. Running FC2 here, so I should have access to all of the software that I need to create any docs. How can I view the list of docs that need owners? - -- - -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 - -----Original Message----- From: fedora-docs-list-bounces at redhat.com [mailto:fedora-docs-list-bounces at redhat.com] On Behalf Of Tammy Fox Sent: Thursday, August 12, 2004 5:35 PM To: fedora-docs-list at redhat.com Subject: status Hi everyone, My maternity leave ends this month, so I am going through the Fedora docs bugs to start getting back in the swing of things. After that, I'll go through the mailing list to read about what I have missed. So far, here is a summary of the bug reports: Bug #129784 has been created to track docs ideas without owners Bug #129807 has been created to track docs in progress with a writer assigned to it A new bug report must be submitted for any new docs or docs changes so we can keep track of them (these should also be listed as blockers for bug #129807) I have fixed the following bugs: 122665, 123258, 123267, 125751, 125754, 129005 A new version of the Documentation Guide will appear on the website shortly. It is just a maintenance release after fixing the previously mentioned bugs. Cheers, Tammy - -- fedora-docs-list mailing list fedora-docs-list at redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list -----BEGIN PGP SIGNATURE----- Version: PGP 8.0 iQA/AwUBQRw5zqbnQHwVWKJjEQI0agCeIGsBXLONQYWaSQAcTxMH4KjEIKUAn0D7 KcXwjuTct5raXvUYxvumayJJ =aHxP -----END PGP SIGNATURE----- From davep at dpawson.co.uk Fri Aug 13 08:04:05 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 09:04:05 +0100 Subject: New tracker In-Reply-To: <1092332609.4488.33300.camel@erato.phig.org> References: <1092287259.2973.20.camel@albus.aeon.com.my> <1092318971.18844.159.camel@berlin.east.gov> <1092324003.2541.9.camel@homer> <1092332609.4488.33300.camel@erato.phig.org> Message-ID: <1092384245.2519.32.camel@homer> On Thu, 2004-08-12 at 18:43, Karsten Wade wrote: > > Karsten, did you have a 'techie' review in your process document? > > In my mind, I thought of this as part of the editor role. However, that > might be asking too many skills of an editor - grammar/writing and > technical review. There is some value in having it be a separate role. In an ideal world, give (the html version) to the author of the tool? Believe me, I've written about stuff I really don't understand; so I agree its expecting a bit much :-) Some people can, others can't. ~Be nice to recognise that? > > Since one person can fill many roles, +1, but the task needs doing (my earlier point), hence recognising that is good. > > The key in that process which might not have been obvious is -- it's all > about writers and editors. Everything from acceptance as in-progress > for Fedora docs to publication on fedora.redhat.com needs to be an > agreement between the author(s) and the editor(s). And if needed, the techies who understand what this particular XYZ does? > > Which reminds me, I need to find someone to edit the FC2 SELinux FAQ > before it can go live ... Not me! I've enough faq work :-) -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Aug 13 08:09:17 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 09:09:17 +0100 Subject: editors In-Reply-To: <1092333413.4488.33328.camel@erato.phig.org> References: <1092333413.4488.33328.camel@erato.phig.org> Message-ID: <1092384557.2519.38.camel@homer> On Thu, 2004-08-12 at 18:56, Karsten Wade wrote: > Here are some further ideas about the role of an editor: > * Should there be an editorial board? Such a board would oversee the > Fedora docs, make sure we are adhering to our standards, filling in > holes, following or advancing our process, etc. Were there enough of us here I might agree. Beginning to sniff bureaucracy? > > * Also, much of the editing traffic can be in bugzilla, as each document > will have it's own bug throughout it's lifecycle. It took me nearly ten minutes to enter a 'bug'. I'm reluctant to use that Karsten? A DMS surely isn't needed as yet? The only additional tool I'd like at the moment is a 'notice board' | wiki to keep track of what's going on, a todo list for the group etc? Use that as a DMS? Certainly could be used to track docs. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Aug 13 08:10:57 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 09:10:57 +0100 Subject: usb-keys In-Reply-To: <1092333660.4488.33339.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> Message-ID: <1092384657.2519.41.camel@homer> On Thu, 2004-08-12 at 19:01, Karsten Wade wrote: > For maintainability sake, it might be easier to keep things separate. > Either way, we could have a document set that covers multiple methods. > Fedora Doc Set: Hot Plugging or something. Due care when authoring Paul? E.g. if the different ways are at level, its no problem to merge or separate them? 'nother benefit of XML? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Aug 13 08:12:44 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 09:12:44 +0100 Subject: Self-Introduction: Tom Large In-Reply-To: <411BB8B8.1040203@thelug.org> References: <1091570269.2580.27.camel@bettie.internal.frields.org> <1092192775.4488.30857.camel@erato.phig.org> <411BB8B8.1040203@thelug.org> Message-ID: <1092384764.2519.44.camel@homer> On Thu, 2004-08-12 at 19:36, Tom Large wrote: > > Aside from all that, I'm mainly just interested in working with an Open > Source project that I use regularly and can get some satisfaction out of > helping. Hi Tom. Unsure if this list has the bandwidth for signatures like that :-) Welcome aboard. Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Aug 13 08:15:25 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 09:15:25 +0100 Subject: Self-Introduction: Tom Large In-Reply-To: <411BCABC.7020402@thelug.org> References: <1092339521.4488.33458.camel@erato.phig.org> <411BCABC.7020402@thelug.org> Message-ID: <1092384924.2519.47.camel@homer> On Thu, 2004-08-12 at 20:53, Tom Large wrote: > |>~ - T H E L U G > |>~ - The Hectic Eclectic Linux User Group > |>~ - Linux without attitude, or directions, or goals... > |>~ - http://www.thelug.org > | > | > | Ha! Careful, or someone might want to franchise that idea. :) > > Heh, that was actually one of the originating thoughts. The goal was to > stay a small user group, so when we top 50 or so members, we're going to > split it up. Have groups like dallas.thelug.org and ftworth.thelug.org. > ~ Oh well... sorry for continuing the off topic discussion here. Now that has been done :-) Isn't that how HP works... or at least used to work. Once a division grows it splits out to its own base? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Aug 13 08:18:12 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 09:18:12 +0100 Subject: editors In-Reply-To: <1092340479.18844.244.camel@berlin.east.gov> References: <1092333413.4488.33328.camel@erato.phig.org> <1092340479.18844.244.camel@berlin.east.gov> Message-ID: <1092385091.2519.50.camel@homer> On Thu, 2004-08-12 at 20:54, Paul W. Frields wrote: > > Good points, these. For example, the Samba/LDAP tutorial needs someone > who works in a more mixed environment. I don't have any systems at work > that are running Windows with which to test this stuff. I'm running both, two side by side machines? FC2 and win2k. I've got samba running, but not set up right I guess, since its not an easy flow of files between the two. What's needed Paul? regards DaveP -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From byte at aeon.com.my Fri Aug 13 08:06:46 2004 From: byte at aeon.com.my (Colin Charles) Date: Fri, 13 Aug 2004 18:06:46 +1000 Subject: fedora-docs bugs In-Reply-To: <1092357849.11376.235.camel@localhost.localdomain> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> Message-ID: <1092384405.2973.429.camel@albus.aeon.com.my> On Fri, 2004-08-13 at 10:44, Tammy Fox wrote: > > Colin also helpfully entered a bug regarding ESR's Fedora Multimedia > > HOWTO. However, I think that this particular request may not be one that > > the Fedora Documentation Project should handle. You can read the bug and > > my comments here, after which my reasons might be clearer: > > > > http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129721 > > > > I agree. I don't think the Fedora Docs Project is the place for > information on adding non-open source software to Fedora, especially if > that software is not legal. Yeah, I sort of figured it out after doing my usual Google trawl (and mailing list) I bring to mind, an FAQ now (not relevant to bug report)... Many users of FC find usefulness in the Unofficial FAQ. Can we brainstorm here to find out how we can make this more "official", since Fedora Core itself is "retarded" without lots of additional multimedia support Thanks -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From byte at aeon.com.my Fri Aug 13 09:07:52 2004 From: byte at aeon.com.my (Colin Charles) Date: Fri, 13 Aug 2004 19:07:52 +1000 Subject: editors In-Reply-To: <1092384557.2519.38.camel@homer> References: <1092333413.4488.33328.camel@erato.phig.org> <1092384557.2519.38.camel@homer> Message-ID: <1092388072.2973.434.camel@albus.aeon.com.my> On Fri, 2004-08-13 at 18:09, Dave Pawson wrote: > > * Also, much of the editing traffic can be in bugzilla, as each document > > will have it's own bug throughout it's lifecycle. > > It took me nearly ten minutes to enter a 'bug'. > I'm reluctant to use that Karsten? > A DMS surely isn't needed as yet? You'll eventually get the hang of it; I think Bugzilla is important for tracking. This also means that hosting things offline is unnecessary, and everything will be at bugzilla.redhat.com It shows we're moving forward, and working around the lack of CVS problem -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From hoyt at cavtel.net Fri Aug 13 09:47:35 2004 From: hoyt at cavtel.net (Hoyt) Date: Fri, 13 Aug 2004 05:47:35 -0400 Subject: fedora-docs bugs In-Reply-To: <1092384405.2973.429.camel@albus.aeon.com.my> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> Message-ID: <200408130547.35778.hoyt@cavtel.net> On Friday 13 August 2004 04:06 am, Colin Charles wrote: > I bring to mind, an FAQ now (not relevant to bug report)... Many users > of FC find usefulness in the Unofficial FAQ. Can we brainstorm here to > find out how we can make this more "official", since Fedora Core itself > is "retarded" without lots of additional multimedia support The FedoraNews site might be an appropriate venue for the "enhancement" of Fredora Core. That stuff won't ever be officially sanctioned, but without it, the enthusiast users are likely to migrate away from FC. I'm seeing some of that in my LUG. -- Hoyt From byte at aeon.com.my Fri Aug 13 09:52:15 2004 From: byte at aeon.com.my (Colin Charles) Date: Fri, 13 Aug 2004 19:52:15 +1000 Subject: fedora-docs bugs In-Reply-To: <200408130547.35778.hoyt@cavtel.net> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> Message-ID: <1092390735.2973.447.camel@albus.aeon.com.my> On Fri, 2004-08-13 at 19:47, Hoyt wrote: > > I bring to mind, an FAQ now (not relevant to bug report)... Many users > > of FC find usefulness in the Unofficial FAQ. Can we brainstorm here to > > find out how we can make this more "official", since Fedora Core itself > > is "retarded" without lots of additional multimedia support > > The FedoraNews site might be an appropriate venue for the "enhancement" of > Fredora Core. That stuff won't ever be officially sanctioned, but without it, > the enthusiast users are likely to migrate away from FC. I'm seeing some of > that in my LUG. People whom do installs for the first time, either: 1. Migrating Windows users 2. Proficient Linux users from other distros Don't know about the wonderful Fedora resources available out there... they know fedora.redhat.com, but that's about it They find fedorafaq.org or fedoranews.org too late, usually Our aim is to fix that, with the documentation subproject; so how do we go about that? -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From hoyt at cavtel.net Fri Aug 13 10:09:59 2004 From: hoyt at cavtel.net (Hoyt) Date: Fri, 13 Aug 2004 06:09:59 -0400 Subject: fedora-docs bugs In-Reply-To: <1092390735.2973.447.camel@albus.aeon.com.my> References: <1092318823.18844.155.camel@berlin.east.gov> <200408130547.35778.hoyt@cavtel.net> <1092390735.2973.447.camel@albus.aeon.com.my> Message-ID: <200408130609.59010.hoyt@cavtel.net> On Friday 13 August 2004 05:52 am, Colin Charles wrote: > Don't know about the wonderful Fedora resources available out there... > they know fedora.redhat.com, but that's about it > > They find fedorafaq.org or fedoranews.org too late, usually > > Our aim is to fix that, with the documentation subproject; so how do we > go about that? Provide a mention of them in the REAMDE in the root CD directory with a disclaimer that "These sites are not maintained by RH/Fedora, you should always examine software licenses, etc." A similar approach taken by Mandrake at my suggestion seems to have helped them. In other words, you try to tell the new user as soon as possible that there is a community with something useful to offer. Those sites could also provide cut-and-paste examples of the alternative sites for yum.conf, perhaps wrapped in a script that inserts them in the yum.conf file and runs "yum check-update" to grab the data files as well as display a "Here's what you do with this stuff" html page and a desktop link to that page. Ambitious, yes, but appropriate to the audience. -- Hoyt From rahulsundaram at yahoo.co.in Fri Aug 13 10:21:05 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Fri, 13 Aug 2004 03:21:05 -0700 (PDT) Subject: fedora-docs bugs In-Reply-To: <1092384405.2973.429.camel@albus.aeon.com.my> Message-ID: <20040813102105.11455.qmail@web8303.mail.in.yahoo.com> Hi > I bring to mind, an FAQ now (not relevant to bug > report)... Many users > of FC find usefulness in the Unofficial FAQ. Can we > brainstorm here to > find out how we can make this more "official", since > Fedora Core itself > is "retarded" without lots of additional multimedia > support > > I heard that Fedora site cannot link to these multimedia stuff directly because its a violation of DMCA or something like that. If that isnt true I wonder why the redhat docs never didnt mention how to add mp3 support to the distro by downloading a simple plugin rpm regards Rahul Sundaram __________________________________ Do you Yahoo!? New and Improved Yahoo! Mail - Send 10MB messages! http://promotions.yahoo.com/new_mail From paul at frields.com Fri Aug 13 12:03:03 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 08:03:03 -0400 Subject: editors In-Reply-To: <1092385091.2519.50.camel@homer> References: <1092333413.4488.33328.camel@erato.phig.org> <1092340479.18844.244.camel@berlin.east.gov> <1092385091.2519.50.camel@homer> Message-ID: <1092398583.24302.21.camel@berlin.east.gov> On Fri, 2004-08-13 at 04:18, Dave Pawson wrote: > > Good points, these. For example, the Samba/LDAP tutorial needs someone > > who works in a more mixed environment. I don't have any systems at work > > that are running Windows with which to test this stuff. > > I'm running both, two side by side machines? FC2 and win2k. > I've got samba running, but not set up right I guess, since its not > an easy flow of files between the two. > What's needed Paul? Hi Dave, What's required is (1) a check of the technical accuracy of the document, and (2) rewriting to eliminate problems of style. As I mentioned, I don't have any Windows boxes with which to check some of the technical fine points, nor am I that familiar with LDAP (soon, but not right now). I can do the style rewriting, but you had mentioned you were interested in doing so yourself, and I would like to spend the time working on the Style Guide. I know that sounds a little backward, but if you know good technical documentation, you probably can see the problems in the doc and how to fix them without a formal Style Guide. (For example, "OK, let's get started!" and "We'll do XYZ..." are clearly out of place, even if they have a nice, friendly ring.) The fine points could always be tweaked later. If you (or anyone on the list) is interested in doing the technical evaluation, I would suggest the following guidelines (I'll be general so that this might be useful to someone for another doc): Once you've completed whatever portion you're willing to massage, just drop a patch to the XML in Bugzilla under the doc's entry there (#129739). 1. Goals - The document might lay out a number of scenarios, with each one requiring an alteration in the steps, but in which the goals are related. Test the document using each major scenario presented. Does it work as written? Are there sections that are unclear, misleading, or out of date? 2. Common Failures - Does the document address possible causes of failure? In other words, if things didn't work right and you followed all the steps correctly, would it be within the doc's scope to tell you what might be wrong? Every document shouldn't turn into a full-fledged troubleshooting class, but if there is a common point of failure, a short note is probably required. 3. Other Omissions - Is there something the document didn't address, about which you have questions when you're running it, and which you think other people are likely to have? If anyone sees problems with these guidelines, or I've missed or skipped something obvious, please chime in. I am also cc'ing this to the original author, on the off chance that he might be interested in participating. -- Paul W. Frields, RHCE From paul at frields.com Fri Aug 13 12:15:55 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 08:15:55 -0400 Subject: usb-keys In-Reply-To: <1092384657.2519.41.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> Message-ID: <1092399355.24302.25.camel@berlin.east.gov> On Fri, 2004-08-13 at 04:10, Dave Pawson wrote: > On Thu, 2004-08-12 at 19:01, Karsten Wade wrote: > > > For maintainability sake, it might be easier to keep things separate. > > Either way, we could have a document set that covers multiple methods. > > Fedora Doc Set: Hot Plugging or something. > > Due care when authoring Paul? > E.g. if the different ways are at level, > its no problem to merge or separate them? > 'nother benefit of XML? We could always just use to incorporate them for that matter. In any case, point taken, that DocBook XML rules. :-) (Side geekness update: I find myself hitting C-C < and C-C / in other environments now without thinking. A good sign?) -- Paul W. Frields, RHCE From paul at frields.com Fri Aug 13 12:26:58 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 08:26:58 -0400 Subject: usb-keys In-Reply-To: <1092383645.2519.22.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092383645.2519.22.camel@homer> Message-ID: <1092400017.24302.36.camel@berlin.east.gov> On Fri, 2004-08-13 at 03:54, Dave Pawson wrote: > > For 1 & 2, I guess I meant "better" in the sense that the > > hotplug/updfstab method (1) is a way that both makes a more consistent > > user interface (see comments above), (2) does not depend on the hardware > > configuration remaining constant between insertions (i.e. what happens > > if next time you have one or more other USB storage devices plugged in > > already?), and (3) allows the user to contribute back to the community > > by entering a bug against either hotplug or kudzu for their particular > > USB device, so others can benefit. > > OK, I'm convinced! > (And I'll expect those comments in the write-up Paul :-) Hmm, that's a good point. I don't mention the "up side" in the document. If someone's reviewing a bunch of different how-to docs, they would probably be interested in knowing why I think my way is a good one. If we can score points like that in official Fedora docs, then it keeps 'em coming back. ;-) > My notes were (sorry if too cryptic) > > mount /dev/sda1 /mnt/usbflash > > http://www.fedoraforum.org/forum/showthread.php?t=1291&highlight=mounted+usb [...snip...] Right. That's the way I used to do it before updfstab, too. And there's no doubt that the venerable way works, it just doesn't give you all the crunchy goodness of having your browser and permissions all fall into line too, for whoever owns the console. [...snip...] > > Q.v. my BZ entry from 8/1: > > http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=128952 > > I note you broke off into Martian half way through that Paul. > A conversation with ??? Nasrat went the same way on IRC this week. > I'm beginning to suspect that using Linux for a while does things > to the vocal chords. > I'll also try and keep up with g-v-m and HAL so the > document can be polished for FC3 > What happended to English? :-) Sorry, I was short on time and abbreviating gnome-volume-manager, which Bill N. noted in his comment directly before. HAL is a non-Linux-specific acronym, standing for "Hardware Abstraction Layer." I suppose they talk about this a lot on the Linux kernel mailing list; I don't have time to keep up with all of that traffic and actually *see* my family! Hope that doesn't make me too much of a loser. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Fri Aug 13 13:44:30 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 14:44:30 +0100 Subject: editors In-Reply-To: <1092388072.2973.434.camel@albus.aeon.com.my> References: <1092333413.4488.33328.camel@erato.phig.org> <1092384557.2519.38.camel@homer> <1092388072.2973.434.camel@albus.aeon.com.my> Message-ID: <1092404669.2519.348.camel@homer> On Fri, 2004-08-13 at 10:07, Colin Charles wrote: > On Fri, 2004-08-13 at 18:09, Dave Pawson wrote: > > > > * Also, much of the editing traffic can be in bugzilla, as each document > > > will have it's own bug throughout it's lifecycle. > > > > It took me nearly ten minutes to enter a 'bug'. > > I'm reluctant to use that Karsten? > > A DMS surely isn't needed as yet? > > You'll eventually get the hang of it; I think Bugzilla is important for > tracking. For tracking bugs, yes. We aren't talking bugs? > This also means that hosting things offline is unnecessary, > and everything will be at bugzilla.redhat.com But without an updated home page (no can do) we've no reference to these stupid numbers? At least a wiki would be accessible? OK, we'll get used to using bugzilla. I don't see it as an appropriate tool for what we need to do. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Aug 13 13:45:43 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 14:45:43 +0100 Subject: fedora-docs bugs In-Reply-To: <200408130547.35778.hoyt@cavtel.net> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> Message-ID: <1092404743.2519.350.camel@homer> On Fri, 2004-08-13 at 10:47, Hoyt wrote: > On Friday 13 August 2004 04:06 am, Colin Charles wrote: > > I bring to mind, an FAQ now (not relevant to bug report)... Many users > > of FC find usefulness in the Unofficial FAQ. Can we brainstorm here to > > find out how we can make this more "official", since Fedora Core itself > > is "retarded" without lots of additional multimedia support > > The FedoraNews site might be an appropriate venue for the "enhancement" of > Fredora Core. That stuff won't ever be officially sanctioned, but without it, > the enthusiast users are likely to migrate away from FC. I'm seeing some of > that in my LUG. I wonder why RH can't see that? ... no -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Aug 13 13:49:30 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 14:49:30 +0100 Subject: fedora-docs bugs In-Reply-To: <1092390735.2973.447.camel@albus.aeon.com.my> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092390735.2973.447.camel@albus.aeon.com.my> Message-ID: <1092404970.2519.355.camel@homer> On Fri, 2004-08-13 at 10:52, Colin Charles wrote: > People whom do installs for the first time, either: > 1. Migrating Windows users > 2. Proficient Linux users from other distros > > Don't know about the wonderful Fedora resources available out there... > they know fedora.redhat.com, but that's about it Exactly. > > They find fedorafaq.org or fedoranews.org too late, usually > > Our aim is to fix that, with the documentation subproject; so how do we > go about that? I added a comment to one of the bug pages. I'd like to collate a list of FC links. Even make it wider than RH if necessary. Request, to be longstanding. If you have a link you find relevant to FCx feed me the link and a few lines saying what you find it good for. I'll mark it up and add to it. Hopefully be of a useful size by the time Tammy is back on stream? Please include anything that's useful. I'd like it to be such that any new user can find what they want eventually. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From rahulsundaram at yahoo.co.in Fri Aug 13 13:48:41 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Fri, 13 Aug 2004 06:48:41 -0700 (PDT) Subject: editors In-Reply-To: <1092404669.2519.348.camel@homer> Message-ID: <20040813134841.74237.qmail@web8310.mail.in.yahoo.com> Hi > At least a wiki would be accessible? > > OK, we'll get used to using bugzilla. I don't see it > as an appropriate > tool for what we need to do. ya fedora is eventually planning to get things like a wiki and cvs access. till then bugzilla is useful for keeping track of things. consider it a work around. pretty good one neverthless regards Rahul Sundaram _______________________________ Do you Yahoo!? Express yourself with Y! Messenger! Free. Download now. http://messenger.yahoo.com From rahulsundaram at yahoo.co.in Fri Aug 13 13:48:41 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Fri, 13 Aug 2004 06:48:41 -0700 (PDT) Subject: editors In-Reply-To: <1092404669.2519.348.camel@homer> Message-ID: <20040813134841.74237.qmail@web8310.mail.in.yahoo.com> Hi > At least a wiki would be accessible? > > OK, we'll get used to using bugzilla. I don't see it > as an appropriate > tool for what we need to do. ya fedora is eventually planning to get things like a wiki and cvs access. till then bugzilla is useful for keeping track of things. consider it a work around. pretty good one neverthless regards Rahul Sundaram _______________________________ Do you Yahoo!? Express yourself with Y! Messenger! Free. Download now. http://messenger.yahoo.com From mjohnson at redhat.com Fri Aug 13 14:48:53 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Fri, 13 Aug 2004 10:48:53 -0400 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092384657.2519.41.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> Message-ID: <411CD4D5.4090605@redhat.com> Dave Pawson wrote: > On Thu, 2004-08-12 at 19:01, Karsten Wade wrote: > > >>For maintainability sake, it might be easier to keep things separate. >>Either way, we could have a document set that covers multiple methods. >>Fedora Doc Set: Hot Plugging or something. > > > Due care when authoring Paul? > E.g. if the different ways are at level, > its no problem to merge or separate them? > 'nother benefit of XML? Is there any possibility of revisiting the policy of using , ..., instead of
? The latter allows one to move sections around (& in to other docs) much more easily. Also, there's a slight possibility that , etc., might disappear when DocBook 5 comes out. The fedora docs policy on this is spelled out here: http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-sections.html IMO, use of
makes a document much more modular, in the sense that it may later be incorporated into another document. I can't recall where, but some 'best practices' presentation/doc I've seen recommends moving to
. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From davep at dpawson.co.uk Fri Aug 13 15:14:30 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 16:14:30 +0100 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <411CD4D5.4090605@redhat.com> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> Message-ID: <1092410070.2519.365.camel@homer> On Fri, 2004-08-13 at 15:48, Mark Johnson wrote: > Is there any possibility of revisiting the policy of using > , ..., instead of
? > > The latter allows one to move sections around (& in to other docs) > much more easily. Also, there's a slight possibility that , > etc., might disappear when DocBook 5 comes out. Is there? I don't think that likely. Even 5 needs some backwards compatibility. > > The fedora docs policy on this is spelled out here: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-sections.html > > IMO, use of
makes a document much more modular, in the > sense that it may later be incorporated into another document. I > can't recall where, but some 'best practices' presentation/doc I've > seen recommends moving to
. Modifying sect1 to section isn't too hard, and the content models are near as damn it identical Mark? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From tfox at redhat.com Fri Aug 13 15:27:02 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 11:27:02 -0400 Subject: status In-Reply-To: References: Message-ID: <1092410822.11376.267.camel@localhost.localdomain> Go to http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129784 I attached a list of topics and volunteers from several months ago. Most of the tutorials weren't written by the person who volunteered for it, so you can email the list back to request one of these topics. Then, we will open up a Bugzilla report to show you are working on it. Cheers, Tammy On Thu, 2004-08-12 at 23:47, D at 7@k|N& wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > Hi all, > > I'm new to the Docs, but I would like to help. Running FC2 here, so I should have access to all of the software that I need to create any docs. How can I view the list of docs that need owners? > > - -- > - -=D at 7@k|N&=- > > <== dataking's pgp ==> > 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 > > > - -----Original Message----- > From: fedora-docs-list-bounces at redhat.com [mailto:fedora-docs-list-bounces at redhat.com] On Behalf Of Tammy Fox > Sent: Thursday, August 12, 2004 5:35 PM > To: fedora-docs-list at redhat.com > Subject: status > > Hi everyone, > > My maternity leave ends this month, so I am going through the Fedora > docs bugs to start getting back in the swing of things. After that, I'll > go through the mailing list to read about what I have missed. So far, > here is a summary of the bug reports: > > Bug #129784 has been created to track docs ideas without owners > > Bug #129807 has been created to track docs in progress with a writer > assigned to it > > A new bug report must be submitted for any new docs or docs changes so > we can keep track of them (these should also be listed as blockers for > bug #129807) > > I have fixed the following bugs: > 122665, 123258, 123267, 125751, 125754, 129005 > > A new version of the Documentation Guide will appear on the website > shortly. It is just a maintenance release after fixing the previously > mentioned bugs. > > Cheers, > Tammy > > > - -- > fedora-docs-list mailing list > fedora-docs-list at redhat.com > To unsubscribe: > http://www.redhat.com/mailman/listinfo/fedora-docs-list > > -----BEGIN PGP SIGNATURE----- > Version: PGP 8.0 > > iQA/AwUBQRw5zqbnQHwVWKJjEQI0agCeIGsBXLONQYWaSQAcTxMH4KjEIKUAn0D7 > KcXwjuTct5raXvUYxvumayJJ > =aHxP > -----END PGP SIGNATURE----- From paul at frields.com Fri Aug 13 15:46:26 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 11:46:26 -0400 Subject: fedora-docs bugs In-Reply-To: <1092404743.2519.350.camel@homer> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092404743.2519.350.camel@homer> Message-ID: <1092411986.2449.4.camel@berlin.east.gov> On Fri, 2004-08-13 at 09:45, Dave Pawson wrote: > On Fri, 2004-08-13 at 10:47, Hoyt wrote: > > On Friday 13 August 2004 04:06 am, Colin Charles wrote: > > > I bring to mind, an FAQ now (not relevant to bug report)... Many users > > > of FC find usefulness in the Unofficial FAQ. Can we brainstorm here to > > > find out how we can make this more "official", since Fedora Core itself > > > is "retarded" without lots of additional multimedia support > > > > The FedoraNews site might be an appropriate venue for the "enhancement" of > > Fredora Core. That stuff won't ever be officially sanctioned, but without it, > > the enthusiast users are likely to migrate away from FC. I'm seeing some of > > that in my LUG. > > I wonder why RH can't see that? > ... no I'm pretty sure they can. However, directing people to places where they can (essentially) violate IP rights may be roughly as actionable as violating them yourself. Yes, that's a bit over-dramatic, but if you learn to see this situation the way that Red Hat's legal department likely does, you'll quickly understand why this is a very tangled problem. I think, frankly, directing people to Google is always best, that way they generally end up with the information they want, and it's up to them to provide the search parameters. I'm not saying that's the way to handle official documentation, I'm only saying it's an alternative that's free of legal entanglements. -- Paul W. Frields, RHCE From paul at frields.com Fri Aug 13 16:07:40 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 12:07:40 -0400 Subject: editors In-Reply-To: <1092404669.2519.348.camel@homer> References: <1092333413.4488.33328.camel@erato.phig.org> <1092384557.2519.38.camel@homer> <1092388072.2973.434.camel@albus.aeon.com.my> <1092404669.2519.348.camel@homer> Message-ID: <1092413259.2449.27.camel@berlin.east.gov> On Fri, 2004-08-13 at 09:44, Dave Pawson wrote: > > You'll eventually get the hang of it; I think Bugzilla is important for > > tracking. > For tracking bugs, yes. > We aren't talking bugs? Bugzilla is a decent tool for tracking TODO's and doing very simple project management. We are thinking of using it in-house for some development tasks as well. > > This also means that hosting things offline is unnecessary, > > and everything will be at bugzilla.redhat.com > > But without an updated home page (no can do) we've no reference > to these stupid numbers? > At least a wiki would be accessible? You only have to do a query on Bugzilla for all bugs for fedora-docs. Here's a link you can put in your bookmarks which will do an up-to-date listing (formatting alert for your MUA?): http://bugzilla.redhat.com/bugzilla/buglist.cgi?query_format=&product=Fedora+Core&component=fedora-docs&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED > OK, we'll get used to using bugzilla. I don't see it as an appropriate > tool for what we need to do. It will grow on you! :-) It's like having an idea repository. You can drop ideas there as well as to the mailing list and everyone will have the opportunity to see them without having to use the search facility on the mailing list pages. (I've found that engine doesn't work at all... anyone else have any luck?) -- Paul W. Frields, RHCE From tfox at redhat.com Fri Aug 13 16:58:00 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 12:58:00 -0400 Subject: status In-Reply-To: <1092359241.11376.253.camel@localhost.localdomain> References: <1092357316.11376.231.camel@localhost.localdomain> <1092359241.11376.253.camel@localhost.localdomain> Message-ID: <1092416280.11376.350.camel@localhost.localdomain> On Thu, 2004-08-12 at 21:07, Tammy Fox wrote: > On Thu, 2004-08-12 at 20:35, Tammy Fox wrote: > > Hi everyone, > > > > My maternity leave ends this month, so I am going through the Fedora > > docs bugs to start getting back in the swing of things. After that, I'll > > go through the mailing list to read about what I have missed. So far, > > here is a summary of the bug reports: > > > > Bug #129784 has been created to track docs ideas without owners > > > > Bug #129807 has been created to track docs in progress with a writer > > assigned to it > > > > A new bug report must be submitted for any new docs or docs changes so > > we can keep track of them (these should also be listed as blockers for > > bug #129807) > > > > I have fixed the following bugs: > > 122665, 123258, 123267, 125751, 125754, 129005 > > > > A new version of the Documentation Guide will appear on the website > > shortly. It is just a maintenance release after fixing the previously > > mentioned bugs. > > > > Version 0.2.2 is now on the website. > > I have also updated the main docs project page to include links to the > tracker bugs. This change should appear within the hour. > > Tammy Bugs 125759, 126101, and 129553, 129709 are also fixed. I put some in NEEDINFO state. Version 0.2.3 of the Docs Guide as well as the FC 2 SELinux FAQ are now on the website. I have company through Wednesday, so I probably won't find time to do any more work until after that. The only bugs left (that are mine) are in NEEDINFO or are new tutorial submissions. Hopefully I'll get to the new tutorial submissions next week. Have a great weekend! Tammy From tfox at redhat.com Fri Aug 13 17:02:39 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 13:02:39 -0400 Subject: more defined process Message-ID: <1092416559.11376.356.camel@localhost.localdomain> I still haven't finished reading the mailing list since I started my maternity leave, so forgive me if this has already been discussed. I am putting together a Quick Guide for this interested in learning how to participate since I get emails daily asking. It also helps define the life cycle of a tutorial. Please share your thoughts about it. Thanks! Tammy --page begins-- Fedora Documentation Project Quick Start Guide Since reading the Documentation Guide can be a bit overwhelming at first, read this page first to understand how to start participating and the process used to add a tutorial to the project. The first step is to choose whether you want to be a writer or an editor. Refer to the project page for each role's definition (which is still being developed). Editors must first be approved by the project leader and must have experience with DocBook XML and the proper use of tags since all editors must follow the same guidelines when reviewing tutorials. If you are chosen as an editor, your name is added to the project page, and your job is to wait until writers are finished writing the tutorials and need editing. If you choose to be a writer, the follow process must be used: * Refer to bug 129807 to see the list of tutorials already in progress to make sure you do not select a duplicate. * If you have an idea that is not in the list of docs in progress, open a Bugzilla report with your idea and be sure to make bug 129807 depend on it. Also, email the mailing list to let everyone know you are working on it. If you can't think of an idea, refer to 129784 for a list of ideas without owners. * If you are not familiar with DocBook XML, read the Documentation Guide to learn how to use this format. Tutorials must be submitted in this format. Even if you are familiar with it, read the guide to learn how tags are used for the project and to learn how to setup your file to make it compatible with the CVS structure and the common entities file. Once your file is ready, attach it to the bug report you created so that an editor can be assigned to it. * The editor will review your tutorial according to the editing guidelines (which are in progress) and work with you to get them corrected. * Once the writer and editor feel it is ready to be published to the website, make bug 129722 depend on this bug so the project maintainer can review it and post it to the website. Once it is posted to the website, you are still responsible for maintaining your tutorial. Until write access is available for CVS, submit updates to your tutorial in the form of patches via Bugzilla so that they can be applied. --page ends-- From mfedyk at matchmail.com Fri Aug 13 17:23:09 2004 From: mfedyk at matchmail.com (Mike Fedyk) Date: Fri, 13 Aug 2004 10:23:09 -0700 Subject: fedora-docs bugs In-Reply-To: <20040813102105.11455.qmail@web8303.mail.in.yahoo.com> References: <20040813102105.11455.qmail@web8303.mail.in.yahoo.com> Message-ID: <411CF8FD.8090501@matchmail.com> Rahul Sundaram wrote: >I heard that Fedora site cannot link to these >multimedia stuff directly because its a violation of >DMCA or something like that. If that isnt true I >wonder why the redhat docs never didnt mention how to >add mp3 support to the distro by downloading a simple >plugin rpm > Then how does debian do it with their non-free repositories. It's not "Official" debian, but it's there as an optoinal repository. Is debian endangering itself by doing this? From davep at dpawson.co.uk Fri Aug 13 17:30:04 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 18:30:04 +0100 Subject: fedora-docs bugs In-Reply-To: <1092411986.2449.4.camel@berlin.east.gov> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092404743.2519.350.camel@homer> <1092411986.2449.4.camel@berlin.east.gov> Message-ID: <1092418203.2519.428.camel@homer> On Fri, 2004-08-13 at 16:46, Paul W. Frields wrote: > > I wonder why RH can't see that? > > ... no > > I'm pretty sure they can. However, directing people to places where they > can (essentially) violate IP rights may be roughly as actionable as > violating them yourself. I don't understand. > I think, frankly, directing people to Google is always best, that way > they generally end up with the information they want, and it's up to > them to provide the search parameters. I'm not saying that's the way to > handle official documentation, I'm only saying it's an alternative > that's free of legal entanglements. And if it leads to yours or my website, then 'customers' will be happy? +1 Who gives a monkeys if its on RH website? Just because that's where customers expect it. When using Python, I find it quicker to use google to find documentation than using the actual documentation index. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From rahulsundaram at yahoo.co.in Fri Aug 13 17:35:43 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Fri, 13 Aug 2004 10:35:43 -0700 (PDT) Subject: fedora-docs bugs In-Reply-To: <411CF8FD.8090501@matchmail.com> Message-ID: <20040813173543.46423.qmail@web8309.mail.in.yahoo.com> Hi > Then how does debian do it with their non-free > repositories. > > It's not "Official" debian, but it's there as an > optoinal repository. > Is debian endangering itself by doing this? > assuming it does suing debian is harder than redhat regards Rahul Sundaram __________________________________ Do you Yahoo!? Yahoo! Mail Address AutoComplete - You start. We finish. http://promotions.yahoo.com/new_mail From davep at dpawson.co.uk Fri Aug 13 17:38:01 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 13 Aug 2004 18:38:01 +0100 Subject: more defined process In-Reply-To: <1092416559.11376.356.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> Message-ID: <1092418680.2519.435.camel@homer> On Fri, 2004-08-13 at 18:02, Tammy Fox wrote: > If you are chosen as an editor, your name is added to the project page, > and your job is to wait until writers are finished writing the tutorials > and need editing. ? How do I get chosen as an editor? What's an editor do? (Paul/Karsten) How often do 'writers finish a piece' Bit of a drop off there? Fill in please, but yes. good basic intro. (needs the 'sales pitch' too. WE REALLY REALLY NEED MORE DOCUMENTATION.) -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From rahulsundaram at yahoo.co.in Fri Aug 13 17:38:08 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Fri, 13 Aug 2004 10:38:08 -0700 (PDT) Subject: fedora-docs bugs In-Reply-To: <1092411986.2449.4.camel@berlin.east.gov> Message-ID: <20040813173808.27296.qmail@web8312.mail.in.yahoo.com> Hi > > I wonder why RH can't see that? > > ... no > > I'm pretty sure they can. However, directing people > to places where they > can (essentially) violate IP rights may be roughly > as actionable as > violating them yourself. the violation of IP rights if any is not universal. we dont have software patents in India. its perfectly legal for me to use an mp3 player in fedora regards Rahul Sundaram __________________________________ Do you Yahoo!? Yahoo! Mail Address AutoComplete - You start. We finish. http://promotions.yahoo.com/new_mail From paul at frields.com Fri Aug 13 18:03:26 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 14:03:26 -0400 Subject: fedora-docs bugs In-Reply-To: <1092418203.2519.428.camel@homer> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092404743.2519.350.camel@homer> <1092411986.2449.4.camel@berlin.east.gov> <1092418203.2519.428.camel@homer> Message-ID: <1092420206.2449.38.camel@berlin.east.gov> On Fri, 2004-08-13 at 13:30, Dave Pawson wrote: > > > I wonder why RH can't see that? > > > ... no > > > > I'm pretty sure they can. However, directing people to places where they > > can (essentially) violate IP rights may be roughly as actionable as > > violating them yourself. > I don't understand. Actionable = someone could start a legal action against Red Hat. If I am a corporate entity that directs you to resources that allow you to knowingly violate Karsten's IP rights, then Karsten may have a legal claim against me. Since I'm not an attorney, I don't know on what exactly that claim would be predicated, but I do know that I would like to avoid that risk where possible. > > I think, frankly, directing people to Google is always best, that way > > they generally end up with the information they want, and it's up to > > them to provide the search parameters. I'm not saying that's the way to > > handle official documentation, I'm only saying it's an alternative > > that's free of legal entanglements. > > And if it leads to yours or my website, > then 'customers' will be happy? > +1 > Who gives a monkeys if its on RH website? > Just because that's where customers expect it. I can't tell from your verbiage whether you're agreeing or not. :-) Customers' expectations for a free, community-supported product should be reasonable. Just because a doc's not on Red Hat's site doesn't invalidate it. The Fedora Docs Project is not going to be one-stop shopping for everything Fedora-related. There will always be other sites that have a particular focus or specialty. > When using Python, > I find it quicker to use google to find > documentation than using the actual documentation index. Does this mean we agree? I'm sorry, now I'm confused! :-) -- Paul W. Frields, RHCE From paul at frields.com Fri Aug 13 18:12:08 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 14:12:08 -0400 Subject: fedora-docs bugs In-Reply-To: <20040813173808.27296.qmail@web8312.mail.in.yahoo.com> References: <20040813173808.27296.qmail@web8312.mail.in.yahoo.com> Message-ID: <1092420728.2449.48.camel@berlin.east.gov> On Fri, 2004-08-13 at 13:38, Rahul Sundaram wrote: > Hi > > > I wonder why RH can't see that? > > > ... no > > > > I'm pretty sure they can. However, directing people > > to places where they > > can (essentially) violate IP rights may be roughly > > as actionable as > > violating them yourself. > > the violation of IP rights if any is not universal. we > dont have software patents in India. its perfectly > legal for me to use an mp3 player in fedora Absolutely. But Red Hat is a US-based company and thus has to abide by US restrictions. The Fedora Project servers are (I believe) located in the US and thus similarly bound, I would guess. This is probably a FAQ topic on a Linux legal list somewhere. I would doubt that the policy will change from how Red Hat handles docs for their RHEL product, or previous incarnations of Red Hat Linux. Will that satisfy all Fedora users? Probably not, but we have to live with it until people give up on patent-encumbered software or Red Hat relocates all its operations to a nation that doesn't have these legal entanglements. I'm not holding my breath for either. International users will be able to make use of a multitude of non-Red Hat hosted sites for HOWTOs and documentation. Once again, Google conquers all. :-) No one's putting a lid on all that information, I'm just saying that I doubt the FDP will address it. Doing so conflicts with the mission of the whole Project (q.v. Bugzilla #129721). -- Paul W. Frields, RHCE From kwade at redhat.com Fri Aug 13 18:13:52 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 13 Aug 2004 11:13:52 -0700 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <411CD4D5.4090605@redhat.com> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> Message-ID: <1092420832.4488.35395.camel@erato.phig.org> On Fri, 2004-08-13 at 07:48, Mark Johnson wrote: > IMO, use of
makes a document much more modular, in the > sense that it may later be incorporated into another document. I > can't recall where, but some 'best practices' presentation/doc I've > seen recommends moving to
. Yes, I agree. The value that you can get from an explicit section number and associated ID tag are far less than the value of true modularity and the ability to interleave documents. Since this is all FDL covered materials, we do our own licensing choice a service by making it easier to use our works in a truly free manner. I'd recommend a standard of:
Like The Title: The Details The ID has meaning to the content. When moving chunks if
s around, you can know what something is easily. Want an idea what sections you have in what order? 'grep " vs , ... [was: Re: usb-keys] In-Reply-To: <1092420832.4488.35395.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> Message-ID: <1092421685.2449.62.camel@berlin.east.gov> > I'd recommend a standard of: > >
> Like The Title: The Details > > The ID has meaning to the content. When moving chunks if
s > around, you can know what something is easily. Want an idea what > sections you have in what order? 'grep " something meaningful that directly corresponds to your table of > contents. > > Any other thoughts on this? I'll hold off for a bit on filling out the > bug report. :) Up until now we've been using Documentation Guide instructions that recommend attributes such as id="s1-top-section" or id="s2-subsection". Will we likewise be abandoning those as well? They don't actually cut down on portability but definitely interfere with the logic of the document when one starts copying and pasting sections around. Perhaps using id="sn-*" would work better, and allow us to keep most of the guidelines as they are. I supposed sed really is our friend! :-D -- Paul W. Frields, RHCE From kwade at redhat.com Fri Aug 13 18:31:21 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 13 Aug 2004 11:31:21 -0700 Subject: fedora-docs bugs In-Reply-To: <1092411986.2449.4.camel@berlin.east.gov> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092404743.2519.350.camel@homer> <1092411986.2449.4.camel@berlin.east.gov> Message-ID: <1092421880.4488.35482.camel@erato.phig.org> On Fri, 2004-08-13 at 08:46, Paul W. Frields wrote: > I think, frankly, directing people to Google is always best, that way > they generally end up with the information they want, and it's up to > them to provide the search parameters. I'm not saying that's the way to > handle official documentation, I'm only saying it's an alternative > that's free of legal entanglements. I wonder if we could direct people to google with suggestions on search terminology and usage? For example: "One of the powers of Fedora Core is the enormous community behind it. You will find that community is your best resource for using Fedora Core. To find popular and useful websites with information, use your favorite Web search engine, such as http://www.google.com. Try search terms such as: using fedora to fedora multimedia software fedora packages" The search results that return for those search are not controlled by us in any way. There are often more than 10,000 results. We can in no way be held responsible for what is on those pages. Of course, IANAL, TINLA. Just an idea I personally am having. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Fri Aug 13 18:37:18 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 14:37:18 -0400 Subject: more defined process In-Reply-To: <1092416559.11376.356.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> Message-ID: <1092422237.2449.73.camel@berlin.east.gov> On Fri, 2004-08-13 at 13:02, Tammy Fox wrote: > I still haven't finished reading the mailing list since I started my > maternity leave, so forgive me if this has already been discussed. > > I am putting together a Quick Guide for this interested in learning how > to participate since I get emails daily asking. It also helps define the > life cycle of a tutorial. > > Please share your thoughts about it. Hi Tammy, in case you haven't made it there yet, Karsten also had some thoughts about this: http://people.redhat.com/kwade/fedora-docs/process-docs/writing_lifecycle.txt He posted this link to the list in a message a few days ago: http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00052.html I'd like to think that maybe I started this ball rolling with a rather bizarre, punch-drunk, and poorly thought out core dump here: http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00028.html (Thank goodness there's more agile minds around to make sense of this drivel.) :-D -- Paul W. Frields, RHCE From kwade at redhat.com Fri Aug 13 18:42:42 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 13 Aug 2004 11:42:42 -0700 Subject: editors In-Reply-To: <1092413259.2449.27.camel@berlin.east.gov> References: <1092333413.4488.33328.camel@erato.phig.org> <1092384557.2519.38.camel@homer> <1092388072.2973.434.camel@albus.aeon.com.my> <1092404669.2519.348.camel@homer> <1092413259.2449.27.camel@berlin.east.gov> Message-ID: <1092422562.4488.35538.camel@erato.phig.org> On Fri, 2004-08-13 at 09:07, Paul W. Frields wrote: > On Fri, 2004-08-13 at 09:44, Dave Pawson wrote: > > > You'll eventually get the hang of it; I think Bugzilla is important for > > > tracking. > > For tracking bugs, yes. > > We aren't talking bugs? > > Bugzilla is a decent tool for tracking TODO's and doing very simple > project management. We are thinking of using it in-house for some > development tasks as well. It has a couple of useful project management features that a Wiki doesn't have: * Dependency tracking -- when working on a project, you have items which depend on the completion of previous items. For example, to build a floor for you house, first you need to make a foundation. In bugzilla, the report for the floor would have several blocking bugs ("Bug XXXXXX depends on" and then a list of bug numbers in the Additional Feature Information section of a bugzilla report). Those blocking bugs would be things such as "dig foundation", "pour concrete", "lay under the floor plumbing", "under the floor wiring", etc. All of those would have to be marked CLOSED for the bug report for the floor to be marked CLOSED. Of course, the floor is just itself a dependency for the walls it supports. And they are dependencies for the roof. All of those dependencies all have individual dependencies similar to the floor. A proper project management tool has lots of nice ways to do this with some poor person in charge of manually updating it. Bugzilla has grown from a simple bug reporting tool to a little bit more than that; it collects community project information, and lets people create interdependencies to track open source software projects. It works well for that, which is why we recommend adopting it for the FDP. * Automated features -- email to involved parties, which can even include a mailing list setup as an account (kind of useful, kind of annoying). Cross dependency checking. * Database backed -- a bug report can capture a huge amount of useful information, making your one bug report part of a massive information resource. You can track time estimates and hours worked, keep track of your tasks in one location, search and slice those tasks, etc. On top of that, it's easier to do URLs now (http://bugzilla.redhat.com/123456 will work), and it's searchable via google (try: site:bugzilla.redhat.com some search terms). - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Fri Aug 13 18:44:55 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 14:44:55 -0400 Subject: fedora-docs bugs In-Reply-To: <1092421880.4488.35482.camel@erato.phig.org> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092404743.2519.350.camel@homer> <1092411986.2449.4.camel@berlin.east.gov> <1092421880.4488.35482.camel@erato.phig.org> Message-ID: <1092422694.2449.82.camel@berlin.east.gov> > > I think, frankly, directing people to Google is always best, that way > > they generally end up with the information they want, and it's up to > > them to provide the search parameters. I'm not saying that's the way to > > handle official documentation, I'm only saying it's an alternative > > that's free of legal entanglements. > > I wonder if we could direct people to google with suggestions on search > terminology and usage? For example: > > "One of the powers of Fedora Core is the enormous community behind it. > You will find that community is your best resource for using Fedora > Core. To find popular and useful websites with information, use your > favorite Web search engine, such as http://www.google.com. Try search > terms such as: > > using fedora to > fedora multimedia software > fedora packages" > > The search results that return for those search are not controlled by us > in any way. There are often more than 10,000 results. We can in no way > be held responsible for what is on those pages. > > Of course, IANAL, TINLA. Just an idea I personally am having. That's kind of similar to what I was thinking. I would suspect anything of this nature should make its way over the desk of a person whose business card includes "IAAL." I would guess that happens routinely with any remotely questionable Web material sponsored or hosted at Red Hat. Hopefully I'm not coming off as too stodgy or finicky about this issue, since I don't have any true appreciation for the very fine points of the law pertaining hereto. But having worked for some highly skilled attorneys for a significant portion of my career, I try not to run afoul of any of them. Besides which, I have a great admiration for the stance Red Hat took on this issue, especially in light of its unpopularity. -- Paul W. Frields, RHCE From tfox at redhat.com Fri Aug 13 19:18:47 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 15:18:47 -0400 Subject: more defined process In-Reply-To: <1092418680.2519.435.camel@homer> References: <1092416559.11376.356.camel@localhost.localdomain> <1092418680.2519.435.camel@homer> Message-ID: <1092424727.11376.384.camel@localhost.localdomain> On Fri, 2004-08-13 at 13:38, Dave Pawson wrote: > On Fri, 2004-08-13 at 18:02, Tammy Fox wrote: > > > > If you are chosen as an editor, your name is added to the project page, > > and your job is to wait until writers are finished writing the tutorials > > and need editing. > > ? How do I get chosen as an editor? > What's an editor do? (Paul/Karsten) > How often do 'writers finish a piece' > > Bit of a drop off there? > > Fill in please, > but yes. good basic intro. > That's why earlier it says that the role definitions are still being defined. I'm trying to develop the process and the roles at the same time to speed things up. My thoughts on how to get chosen as an editor: you submit a description of your experience as a writer, editor, and user of DocBook to the project lead along with a brief description of your technical skills. I can put together a form that allows people to submit the same information. I'll share some guidelines I developed when I was tech lead of the RH docs: *Before* the writer hands a document over to the editor, he/she must verify the following: 1. Spell check all files 2. Verify that all URLs are still valid 3. Verify that the technical content is correct -- which means follow your own documentation step by step to confirm 4. Verify that the names of the files include the language such as example-tutorial-en.xml 5. Verify that all sections have an id so all HTML files generated have static filenames 6. Verify that all ids following the naming convention in the Docs Guide 7. Checkout the fedora-docs CVS module if you haven't already, and verify that if you drop in your directory that it builds within the CVS environment, including using a Makefile based on the existing ones 8. Verify the HTML Output: a. Click all links to make sure they are valid b. View each page to make sure there aren't any missing images. c. Make sure all the images match their description in the text. d. Click the Legal Notice link on the title page to make sure it works and contains the FDL, that the version number has been bumped if a previous version existed, and that the last modified date has been updated. Then, the editor is responsible for: 1. Making sure the writer followed the docs conventions including using standard id names, verifying that the parent file follows the example tutorial so that it builds in CVS, and proper use of XML tags. 2. Checking the grammar and word usage 3. Verifying that it is written for the intended target audience 4. Looking for any possible missing steps (While reading, if it feels like a step was omitted, ask the writer to make sure. Many times writers who are familiar with a procedure will leave out a step that is obvious to them but not to the reader. 5. Verifying that it builds in the CVS structure 6. Determine if the topic needs a second technical review. If it does, work with the writer to email the mailing lists to find someone to follow the document step by step to make sure it works on their system as well. > (needs the 'sales pitch' too. WE REALLY REALLY NEED MORE DOCUMENTATION.) Anyone have anything to add? Thoughts? Tammy From tfox at redhat.com Fri Aug 13 19:27:34 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 15:27:34 -0400 Subject: more defined process In-Reply-To: <1092422237.2449.73.camel@berlin.east.gov> References: <1092416559.11376.356.camel@localhost.localdomain> <1092422237.2449.73.camel@berlin.east.gov> Message-ID: <1092425254.11376.387.camel@localhost.localdomain> On Fri, 2004-08-13 at 14:37, Paul W. Frields wrote: > On Fri, 2004-08-13 at 13:02, Tammy Fox wrote: > > I still haven't finished reading the mailing list since I started my > > maternity leave, so forgive me if this has already been discussed. > > > > I am putting together a Quick Guide for this interested in learning how > > to participate since I get emails daily asking. It also helps define the > > life cycle of a tutorial. > > > > Please share your thoughts about it. > > Hi Tammy, in case you haven't made it there yet, Karsten also had some > thoughts about this: > > http://people.redhat.com/kwade/fedora-docs/process-docs/writing_lifecycle.txt > > He posted this link to the list in a message a few days ago: > > http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00052.html > > I'd like to think that maybe I started this ball rolling with a rather > bizarre, punch-drunk, and poorly thought out core dump here: > > http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00028.html > > (Thank goodness there's more agile minds around to make sense of this > drivel.) :-D > > -- > Paul W. Frields, RHCE Paul, Thanks for pointing me to the right thread. I'll incorporate some of Karsten's thoughts into mine and come up with a new and improved Quick Start Guide. I'll probably post something soon to the website while we work on it just so the thoughts don't get lost and so it can start answering some people's questions. Best, Tammy From mjohnson at redhat.com Fri Aug 13 20:05:47 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Fri, 13 Aug 2004 16:05:47 -0400 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092421685.2449.62.camel@berlin.east.gov> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> Message-ID: <411D1F1B.4080306@redhat.com> Paul W. Frields wrote: >>I'd recommend a standard of: >> >>
>> Like The Title: The Details >> >>The ID has meaning to the content. When moving chunks if
s >>around, you can know what something is easily. Want an idea what >>sections you have in what order? 'grep ">something meaningful that directly corresponds to your table of >>contents. >> >>Any other thoughts on this? I'll hold off for a bit on filling out the >>bug report. :) > > > Up until now we've been using Documentation Guide instructions that > recommend attributes such as id="s1-top-section" or id="s2-subsection". To me (& I would guess Karsten), assigning IDs based on the document structure seems not to take advantage of ID="meaning-of-content". If one wants to give IDs such as id="s1-top-section", one can get the same effect by having the stylesheet *not* use IDs as filenames for html output. The output filenames then serve the purpose of identifying the structural location of the output file within the document. I have to admit that I found it bizarre when I first discovered that one would assign IDs as id="s2-subsection", etc. This method seems to throw out the possibility to add some content-related info to the tags themselves. Don't forget that we're trying to convey meaning here. The more semantic meaning we can give to the structural markup the better, IMO. FWIW, I've always used meaning-derived IDs, such as id="xml-catalogs", as that's what the section is about. And to me, I *want* the output filename to be "xml-catalogs.html" because it carries more meaning than does the sort of structure identifier recommended in the Documentation Guide. Perhaps in some abstract way, having output filenames like "s2-subsection.html" adds a more 'professional' touch to the docs, but I'm not even sure what I mean by that:) My $0.02, Mark > Will we likewise be abandoning those as well? They don't actually cut > down on portability but definitely interfere with the logic of the > document when one starts copying and pasting sections around. > > Perhaps using id="sn-*" would work better, and allow us to keep most of > the guidelines as they are. I supposed sed really is our friend! :-D > -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From hoyt at cavtel.net Fri Aug 13 20:07:06 2004 From: hoyt at cavtel.net (Hoyt) Date: Fri, 13 Aug 2004 16:07:06 -0400 Subject: FedoraCommunity.org (was:Re: fedora-docs bugs) In-Reply-To: <1092421880.4488.35482.camel@erato.phig.org> References: <1092318823.18844.155.camel@berlin.east.gov> <1092411986.2449.4.camel@berlin.east.gov> <1092421880.4488.35482.camel@erato.phig.org> Message-ID: <200408131607.06416.hoyt@cavtel.net> On Friday 13 August 2004 02:31 pm, Karsten Wade wrote: > The search results that return for those search are not controlled by us > in any way. ?There are often more than 10,000 results. ?We can in no way > be held responsible for what is on those pages. It's just a game. If someone hosted a static page with a URL of fedoracommunity.org gateway-style that provided a list of non-RH community-based resources, including Google search hints and un-commented links to Fedora-related sites, that should easily pass muster for mention in the README. No enticement to break laws and violate rights, just the facts. Consider it done; that someone will be me. I just registered the domain name and will be hosting the site by next week on a Fedora server, no less. Hoyt From kwade at redhat.com Fri Aug 13 20:12:53 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 13 Aug 2004 13:12:53 -0700 Subject: more defined process In-Reply-To: <1092416559.11376.356.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> Message-ID: <1092427973.4488.35981.camel@erato.phig.org> On Fri, 2004-08-13 at 10:02, Tammy Fox wrote: > I still haven't finished reading the mailing list since I started my > maternity leave, so forgive me if this has already been discussed. Most of the good stuff has been in the last month or so. :) > I am putting together a Quick Guide for this interested in learning how > to participate since I get emails daily asking. It also helps define the > life cycle of a tutorial. This is a good idea, a gap that needs filling. Mark Johnson is also starting work on something with a name like Quick Start Guide, but it has a different scope. The purpose is to get people who know the tools involved a way to get quickly started, a sort of distillation of the Doc Guide. Just bringing that up because the titles are similar, but the purposes are not, and there is room for both. Just not with the same title. :) I'll leave the rest of this intact so as to make my inline comments make more sense: > Fedora Documentation Project Quick Start Guide > > Since reading the Documentation Guide can be a bit overwhelming at > first, read this page first to understand how to start participating and > the process used to add a tutorial to the project. > > The first step is to choose whether you want to be a writer or an > editor. Refer to the project page for each role's definition (which is > still being developed). Editors must first be approved by the project > leader and must have experience with DocBook XML and the proper use of > tags since all editors must follow the same guidelines when reviewing > tutorials. I think a person can fill both roles, depending on what he or she is doing. Unless there is a compelling reason not to, I'd suggest mentioning that you can fill both roles, but it's easier to fill just one to start. > If you are chosen as an editor, your name is added to the project page, > and your job is to wait until writers are finished writing the tutorials > and need editing. Just a note, the 'process for choosing an editor' remains unwritten. The criteria are pretty obvious. This could be a job for the editorial board, to recommend and/or approve editors? > If you choose to be a writer, the follow process must be used: > > * Refer to bug 129807 to see the list of tutorials already in progress > to make sure you do not select a duplicate. A direct link to the dependency tree might make it easy for people to see what is there: https://bugzilla.redhat.com/bugzilla/showdependencytree.cgi?id=129807 > * If you have an idea that is not in the list of docs in progress, open > a Bugzilla report with your idea and be sure to make bug 129807 depend > on it. Also, email the mailing list to let everyone know you are working > on it. If you can't think of an idea, refer to 129784 for a list of > ideas without owners. > > * If you are not familiar with DocBook XML, read the Documentation Guide > to learn how to use this format. Tutorials must be submitted in this > format. Even if you are familiar with it, read the guide to learn how > tags are used for the project and to learn how to setup your file to > make it compatible with the CVS structure and the common entities file. > Once your file is ready, attach it to the bug report you created so that > an editor can be assigned to it. One thing that has been discussed a number of times over the last few months is the barrier to entry that DocBook XML provides for some people. Without rehashing the arguments, I think the consensus boils down to this: * For now, we will take initial submissions in other formats and volunteers will do the conversion to DocBook. This is on a case-by-case basis. * If the document is going to be maintained, and you are the maintainer, you must be willing to learn enough DocBook to maintain your document. * Alternately, you can have a team of authors, where at least one is responsible for the DocBook. If you have an idea, bring it to the list and ask for a co-author who can help you get through the changes. My suspicion is that 50% of the non-DocBook people who go down this path end up learning the new format. These are an unknown number who wouldn't have come over here in the first place, if they had to learn DocBook just to get their document into the project. > * The editor will review your tutorial according to the editing > guidelines (which are in progress) and work with you to get them > corrected. > > * Once the writer and editor feel it is ready to be published to the > website, make bug 129722 depend on this bug so the project maintainer > can review it and post it to the website. > Once it is posted to the website, you are still responsible for > maintaining your tutorial. Until write access is available for CVS, > submit updates to your tutorial in the form of patches via Bugzilla so > that they can be applied. Looks good, very complete and brief. Only thing we might want is to point people at a how-to use bugzilla, or do a quick one ourselves that defines just how to use it for the FDP. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Fri Aug 13 20:18:16 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 13 Aug 2004 16:18:16 -0400 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <411D1F1B.4080306@redhat.com> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> Message-ID: <1092428296.4241.2.camel@berlin.east.gov> On Fri, 2004-08-13 at 16:05, Mark Johnson wrote: > > Up until now we've been using Documentation Guide instructions that > > recommend attributes such as id="s1-top-section" or id="s2-subsection". > > To me (& I would guess Karsten), assigning IDs based on the document > structure seems not to take advantage of ID="meaning-of-content". If > one wants to give IDs such as id="s1-top-section", one can get the > same effect by having the stylesheet *not* use IDs as filenames for > html output. The output filenames then serve the purpose of > identifying the structural location of the output file within the > document. > > I have to admit that I found it bizarre when I first discovered that > one would assign IDs as id="s2-subsection", etc. This method seems > to throw out the possibility to add some content-related info to the > tags themselves. Don't forget that we're trying to convey meaning > here. The more semantic meaning we can give to the structural markup > the better, IMO. [...snip...] Sorry, I over-genericized the labels. :-) What I would *actually* use in one of my documents would be something like or . In fact, you'll see that kind of usage throughout all the documents I've marked up or written myself. Sorry to give the wrong impression. -- Paul W. Frields, RHCE From kwade at redhat.com Fri Aug 13 20:18:48 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 13 Aug 2004 13:18:48 -0700 Subject: installation guide Message-ID: <1092428328.4488.36007.camel@erato.phig.org> Today had to tell someone on #fedora-docs that we don't have an Installation Guide, and just like many others, had to refer to RHL 9 IG and other resources. Are a couple of people interested in taking on this task? It has some tedium to it, but it's not that bad. Once completed, it will need regular updating, so it's a good, valuable, and stable long-term project. Anaconda has support for taking screenshots, iirc. A format can be borrowed from existing guides, as a starting place. However ... this is a full guide, which requires more effort than a shorter tutorial. Is it even worth it to throw this idea into the bucket at this stage? If so, I'll file the bug and etc. This should be an early one to be tackled, when we are ready. And, yes, I know it's been discussed before. So, I bring it up again. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Fri Aug 13 20:25:06 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 13 Aug 2004 13:25:06 -0700 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092428296.4241.2.camel@berlin.east.gov> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> Message-ID: <1092428706.4488.36031.camel@erato.phig.org> On Fri, 2004-08-13 at 13:18, Paul W. Frields wrote: > What I would *actually* use in > one of my documents would be something like > or . In fact, you'll see that kind of > usage throughout all the documents I've marked up or written myself. > Sorry to give the wrong impression. It is probably and properly lost in the annals of Red Hat documentation history as to exactly why this format decision came about ... and as for sed being your friend, I can tell you it gets harder when you have a really big doc that has lots of tags throughout with hard-coded LINKEND to IDs full of s1-, s2-, s3- and so forth. We should really run from this convention while there is still time, before it is not possible to fix thing with sed then make, fix, make, fix, make, fix ... make, build! - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From mjohnson at redhat.com Fri Aug 13 21:22:22 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Fri, 13 Aug 2004 17:22:22 -0400 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092428706.4488.36031.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> Message-ID: <411D310E.4080209@redhat.com> Couldn't have sed it better myself! Thanks Karsten - yes, we should indeed run from this convention before we get locked in! Cheers, Mark Karsten Wade wrote: > On Fri, 2004-08-13 at 13:18, Paul W. Frields wrote: > >>What I would *actually* use in >>one of my documents would be something like >>or . In fact, you'll see that kind of >>usage throughout all the documents I've marked up or written myself. >>Sorry to give the wrong impression. > > > It is probably and properly lost in the annals of Red Hat documentation > history as to exactly why this format decision came about ... and as for > sed being your friend, I can tell you it gets harder when you have a > really big doc that has lots of tags throughout with hard-coded > LINKEND to IDs full of s1-, s2-, s3- and so forth. > > We should really run from this convention while there is still time, > before it is not possible to fix thing with sed then make, fix, make, > fix, make, fix ... make, build! > > - Karsten -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From tfox at redhat.com Fri Aug 13 23:54:41 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 19:54:41 -0400 Subject: more defined process In-Reply-To: <1092425254.11376.387.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> <1092422237.2449.73.camel@berlin.east.gov> <1092425254.11376.387.camel@localhost.localdomain> Message-ID: <1092441281.11376.637.camel@localhost.localdomain> On Fri, 2004-08-13 at 15:27, Tammy Fox wrote: > On Fri, 2004-08-13 at 14:37, Paul W. Frields wrote: > > On Fri, 2004-08-13 at 13:02, Tammy Fox wrote: > > > I still haven't finished reading the mailing list since I started my > > > maternity leave, so forgive me if this has already been discussed. > > > > > > I am putting together a Quick Guide for this interested in learning how > > > to participate since I get emails daily asking. It also helps define the > > > life cycle of a tutorial. > > > > > > Please share your thoughts about it. > > > > Hi Tammy, in case you haven't made it there yet, Karsten also had some > > thoughts about this: > > > > http://people.redhat.com/kwade/fedora-docs/process-docs/writing_lifecycle.txt > > > > He posted this link to the list in a message a few days ago: > > > > http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00052.html > > > > I'd like to think that maybe I started this ball rolling with a rather > > bizarre, punch-drunk, and poorly thought out core dump here: > > > > http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00028.html > > > > (Thank goodness there's more agile minds around to make sense of this > > drivel.) :-D > > > > -- > > Paul W. Frields, RHCE > > Paul, > > Thanks for pointing me to the right thread. I'll incorporate some of > Karsten's thoughts into mine and come up with a new and improved Quick > Start Guide. I'll probably post something soon to the website while we > work on it just so the thoughts don't get lost and so it can start > answering some people's questions. > > Best, > Tammy I posted a rough draft so far at: http://fedora.redhat.com//participate/documentation-quick-start/ It needs before formatting, but I'll get to that once we agree on the overall process. At least we have the ball rolling again. ;-) Tammy From tfox at redhat.com Sat Aug 14 00:00:03 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 20:00:03 -0400 Subject: more defined process In-Reply-To: <1092427973.4488.35981.camel@erato.phig.org> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> Message-ID: <1092441603.11376.642.camel@localhost.localdomain> On Fri, 2004-08-13 at 16:12, Karsten Wade wrote: > On Fri, 2004-08-13 at 10:02, Tammy Fox wrote: > > I still haven't finished reading the mailing list since I started my > > maternity leave, so forgive me if this has already been discussed. > > Most of the good stuff has been in the last month or so. :) > > > I am putting together a Quick Guide for this interested in learning how > > to participate since I get emails daily asking. It also helps define the > > life cycle of a tutorial. > > This is a good idea, a gap that needs filling. Mark Johnson is also > starting work on something with a name like Quick Start Guide, but it > has a different scope. The purpose is to get people who know the tools > involved a way to get quickly started, a sort of distillation of the Doc > Guide. > > Just bringing that up because the titles are similar, but the purposes > are not, and there is room for both. Just not with the same title. :) > Mark, if you are on this list, can you add a Bugzilla entry for it and link it to the tracker for docs in progress? That way, no one else will start working on the same thing. > I'll leave the rest of this intact so as to make my inline comments make > more sense: > > > Fedora Documentation Project Quick Start Guide > > > > Since reading the Documentation Guide can be a bit overwhelming at > > first, read this page first to understand how to start participating and > > the process used to add a tutorial to the project. > > > > The first step is to choose whether you want to be a writer or an > > editor. Refer to the project page for each role's definition (which is > > still being developed). Editors must first be approved by the project > > leader and must have experience with DocBook XML and the proper use of > > tags since all editors must follow the same guidelines when reviewing > > tutorials. > > I think a person can fill both roles, depending on what he or she is > doing. Unless there is a compelling reason not to, I'd suggest > mentioning that you can fill both roles, but it's easier to fill just > one to start. > True. A person just can't be both the writer and the editor on the same document. > > If you are chosen as an editor, your name is added to the project page, > > and your job is to wait until writers are finished writing the tutorials > > and need editing. > > Just a note, the 'process for choosing an editor' remains unwritten. > The criteria are pretty obvious. This could be a job for the editorial > board, to recommend and/or approve editors? > > > If you choose to be a writer, the follow process must be used: > > > > * Refer to bug 129807 to see the list of tutorials already in progress > > to make sure you do not select a duplicate. > > A direct link to the dependency tree might make it easy for people to > see what is there: > > https://bugzilla.redhat.com/bugzilla/showdependencytree.cgi?id=129807 > > > * If you have an idea that is not in the list of docs in progress, open > > a Bugzilla report with your idea and be sure to make bug 129807 depend > > on it. Also, email the mailing list to let everyone know you are working > > on it. If you can't think of an idea, refer to 129784 for a list of > > ideas without owners. > > > > * If you are not familiar with DocBook XML, read the Documentation Guide > > to learn how to use this format. Tutorials must be submitted in this > > format. Even if you are familiar with it, read the guide to learn how > > tags are used for the project and to learn how to setup your file to > > make it compatible with the CVS structure and the common entities file. > > Once your file is ready, attach it to the bug report you created so that > > an editor can be assigned to it. > > One thing that has been discussed a number of times over the last few > months is the barrier to entry that DocBook XML provides for some > people. > > Without rehashing the arguments, I think the consensus boils down to > this: > > * For now, we will take initial submissions in other formats and > volunteers will do the conversion to DocBook. This is on a case-by-case > basis. > > * If the document is going to be maintained, and you are the maintainer, > you must be willing to learn enough DocBook to maintain your document. > I have found that once someone sees their own document in DocBook it helps them learn it themselves. > * Alternately, you can have a team of authors, where at least one is > responsible for the DocBook. If you have an idea, bring it to the list > and ask for a co-author who can help you get through the changes. > > My suspicion is that 50% of the non-DocBook people who go down this path > end up learning the new format. These are an unknown number who > wouldn't have come over here in the first place, if they had to learn > DocBook just to get their document into the project. > > > * The editor will review your tutorial according to the editing > > guidelines (which are in progress) and work with you to get them > > corrected. > > > > * Once the writer and editor feel it is ready to be published to the > > website, make bug 129722 depend on this bug so the project maintainer > > can review it and post it to the website. > > Once it is posted to the website, you are still responsible for > > maintaining your tutorial. Until write access is available for CVS, > > submit updates to your tutorial in the form of patches via Bugzilla so > > that they can be applied. > > Looks good, very complete and brief. Only thing we might want is to > point people at a how-to use bugzilla, or do a quick one ourselves that > defines just how to use it for the FDP. > Yes. How to use Bugzilla specifically for the Fedora docs would make a great addition. > - Karsten > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Tammy From tfox at redhat.com Sat Aug 14 00:05:06 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 13 Aug 2004 20:05:06 -0400 Subject: installation guide In-Reply-To: <1092428328.4488.36007.camel@erato.phig.org> References: <1092428328.4488.36007.camel@erato.phig.org> Message-ID: <1092441906.11376.648.camel@localhost.localdomain> On Fri, 2004-08-13 at 16:18, Karsten Wade wrote: > Today had to tell someone on #fedora-docs that we don't have an > Installation Guide, and just like many others, had to refer to RHL 9 IG > and other resources. > > Are a couple of people interested in taking on this task? It has some > tedium to it, but it's not that bad. Once completed, it will need > regular updating, so it's a good, valuable, and stable long-term > project. > > Anaconda has support for taking screenshots, iirc. A format can be > borrowed from existing guides, as a starting place. > > However ... this is a full guide, which requires more effort than a > shorter tutorial. Is it even worth it to throw this idea into the > bucket at this stage? If so, I'll file the bug and etc. This should be > an early one to be tackled, when we are ready. > Go ahead and open a bug for it since it needs to be done. What about creating a TOC for it on the mailing list? Then you or I can create empty files for it according to the TOC in CVS, and people can volunteer to write sections that are broken out into files. No one has to tackle the entire guide, and eventually it will be complete. One person can even be in charge of just taking screenshots with the method mentioned in the release notes. The RHEL IGs have been done this way in th past -- different writers responsible for a set of files in the IG, and it works great because you don't have to worry about working on the same files or topics. If we plan ahead, we can even make it expandable to multiple platforms. We did a lot of work to make the same set of files compile for different arches internally, so we might as well use that knowledge here as well. I've even written it up already for the internal docs. I could rewrite it for the Fedora docs without much effort. Tammy > And, yes, I know it's been discussed before. So, I bring it up again. > > - Karsten > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From mjohnson at redhat.com Sat Aug 14 00:42:12 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Fri, 13 Aug 2004 20:42:12 -0400 Subject: more defined process In-Reply-To: <1092441603.11376.642.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> Message-ID: <411D5FE4.7050108@redhat.com> Tammy Fox wrote: > On Fri, 2004-08-13 at 16:12, Karsten Wade wrote: > >>On Fri, 2004-08-13 at 10:02, Tammy Fox wrote: >> >>>I still haven't finished reading the mailing list since I started my >>>maternity leave, so forgive me if this has already been discussed. >> >>Most of the good stuff has been in the last month or so. :) >> >> >>>I am putting together a Quick Guide for this interested in learning how >>>to participate since I get emails daily asking. It also helps define the >>>life cycle of a tutorial. >> >>This is a good idea, a gap that needs filling. Mark Johnson is also >>starting work on something with a name like Quick Start Guide, but it >>has a different scope. The purpose is to get people who know the tools >>involved a way to get quickly started, a sort of distillation of the Doc >>Guide. >> >>Just bringing that up because the titles are similar, but the purposes >>are not, and there is room for both. Just not with the same title. :) >> > > > Mark, if you are on this list, can you add a Bugzilla entry for it and > link it to the tracker for docs in progress? That way, no one else will > start working on the same thing. That's a can-do, Tammy. Gimme a day or two, as I'm still learning the gudzilla system:) Cheers, Mark -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From rahulsundaram at yahoo.co.in Sat Aug 14 13:31:45 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Sat, 14 Aug 2004 06:31:45 -0700 (PDT) Subject: fedora-docs bugs In-Reply-To: <1092420728.2449.48.camel@berlin.east.gov> Message-ID: <20040814133145.58899.qmail@web8310.mail.in.yahoo.com> hi > Absolutely. But Red Hat is a US-based company and > thus has to abide by > US restrictions. The Fedora Project servers are (I > believe) located in > the US and thus similarly bound, I would guess. This > is probably a FAQ > topic on a Linux legal list somewhere. I would doubt > that the policy > will change from how Red Hat handles docs for their > RHEL product, or > previous incarnations of Red Hat Linux. i am not sure its illegal for *users* in US to download a mp3 player and use it. redhat probably doesnt feel safe to distribute an mp3 player but how about instructing users how to do it. is that really illegal?. how about xmms or others offering to download a coded and play it?. someone should probably clarify this regards Rahul Sundaram __________________________________ Do you Yahoo!? Yahoo! Mail Address AutoComplete - You start. We finish. http://promotions.yahoo.com/new_mail From tfox at redhat.com Sat Aug 14 15:25:57 2004 From: tfox at redhat.com (Tammy Fox) Date: Sat, 14 Aug 2004 11:25:57 -0400 Subject: more defined process In-Reply-To: <411D5FE4.7050108@redhat.com> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> Message-ID: <1092497156.11376.673.camel@localhost.localdomain> On Fri, 2004-08-13 at 20:42, Mark Johnson wrote: > Tammy Fox wrote: > > On Fri, 2004-08-13 at 16:12, Karsten Wade wrote: > > > >>On Fri, 2004-08-13 at 10:02, Tammy Fox wrote: > >> > >>>I still haven't finished reading the mailing list since I started my > >>>maternity leave, so forgive me if this has already been discussed. > >> > >>Most of the good stuff has been in the last month or so. :) > >> > >> > >>>I am putting together a Quick Guide for this interested in learning how > >>>to participate since I get emails daily asking. It also helps define the > >>>life cycle of a tutorial. > >> > >>This is a good idea, a gap that needs filling. Mark Johnson is also > >>starting work on something with a name like Quick Start Guide, but it > >>has a different scope. The purpose is to get people who know the tools > >>involved a way to get quickly started, a sort of distillation of the Doc > >>Guide. > >> > >>Just bringing that up because the titles are similar, but the purposes > >>are not, and there is room for both. Just not with the same title. :) > >> > > > > > > Mark, if you are on this list, can you add a Bugzilla entry for it and > > link it to the tracker for docs in progress? That way, no one else will > > start working on the same thing. > > That's a can-do, Tammy. Gimme a day or two, as I'm still learning > the gudzilla system:) > > Cheers, > Mark > -- I've been giving this some more thought this morning, and the more I think about having another guide that contains the same information, the more it reminds me of a project I worked on before as a contract writer using MS Word. I basically had to maintain the same set of manuals but for 2 different arches in 2 sets of files. One of the benefits of DocBook is that you can use conditionals to create multiple documents from the same source (like I was saying with the Installation Guides for multiple arches in a different thread). So, instead of creating a separate guide with some of the same information, I think we should use conditions in the existing source for the Docs Guide and create this Quick Start Guide instead, if it is determined that we need another one. This will make sure the 2 do not get out of sync, which can happen very quickly. Mark, since this is your idea, please share some more details about what you have in mind. How is it different from the existing guide? What problem does it solve? Karsten mentions that the purpose is to "get people who know the tools involved a way to get quickly started." However, I would just like to point out that even if you have used DocBook before, things like tag usage can be interpreted in different ways, so you still need to read the guide to make sure you are following the same rules as everyone else writing Fedora docs. I honestly don't think it is that long or verbose. Thanks, Tammy From kwade at redhat.com Sat Aug 14 16:40:35 2004 From: kwade at redhat.com (Karsten Wade) Date: Sat, 14 Aug 2004 09:40:35 -0700 Subject: more defined process In-Reply-To: <1092441603.11376.642.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> Message-ID: <1092445926.4488.36672.camel@erato.phig.org> On Fri, 2004-08-13 at 17:00, Tammy Fox wrote: > On Fri, 2004-08-13 at 16:12, Karsten Wade wrote: > > I think a person can fill both roles, depending on what he or she is > > doing. Unless there is a compelling reason not to, I'd suggest > > mentioning that you can fill both roles, but it's easier to fill just > > one to start. > > > > True. A person just can't be both the writer and the editor on the same > document. Oh, definitely not. I meant, same roles in the project overall. For example, we could edit each other's documents. This is a good collaboration technique. > > * For now, we will take initial submissions in other formats and > > volunteers will do the conversion to DocBook. This is on a case-by-case > > basis. > > > > * If the document is going to be maintained, and you are the maintainer, > > you must be willing to learn enough DocBook to maintain your document. > > > > I have found that once someone sees their own document in DocBook it > helps them learn it themselves. Ah, yes, you understand. :) This is an important thing to put up front in the Quick Intro[1]: you don't have to know DocBook to start a document. This removes a perceived barrier to entry. Give me a few days to turn the process document back around that came out of the discussion this week. It's in DocBook and I'm doing a style edit plus adding a few items that came up this week. - Karsten [1] I Tammy's piece could have a name like Quick Introduction to How to be a Fedora Writer, aka Quick Intro. For Mark's, I was leaning toward Quick Start to Fedora Documentation Project: Tools for Fools ... something like that ... aka Quick Start. -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Sat Aug 14 16:40:38 2004 From: kwade at redhat.com (Karsten Wade) Date: Sat, 14 Aug 2004 09:40:38 -0700 Subject: fedora-docs bugs In-Reply-To: <1092421880.4488.35482.camel@erato.phig.org> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092404743.2519.350.camel@homer> <1092411986.2449.4.camel@berlin.east.gov> <1092421880.4488.35482.camel@erato.phig.org> Message-ID: <1092501634.3459.1484.camel@erato.phig.org> (pardon the top post, want the below for background reference only) I forwarded this to Mark Webbink, Red Hat's intellectual property attorney extraordinaire. Here is his reply: [snip from Mark Webbink] Directing people to a Google search is fine. It also wouldn't hurt to include somewhere in the documentation at about this same place the following statement: "While we encourage FEDORA fans to find new software that is compatible with FEDORA, downloading software from an unfamiliar site carries some risks. One reason some technologies are not included in FEDORA is because of concerns over known patents. So as you download, be knowledgeable about intellectual property issues and don't hesitate to ask questions of the host site making the download available." [end snip] I think this is a good solution Paul came up with, probably the best compromise we have. Including example search terms may be too clever, I'm not sure. How about the following paragraphs in the References section of a document (if included): "One of the powers of Fedora is the enormous community behind it. You will find that community is your best resource for using Fedora. To find popular and useful websites with information, use your favorite Web search engine, such as http://www.google.com. Try search terms such as: using fedora to fedora multimedia software fedora packages While you are encouraged to find new software that is compatible with Fedora, downloading software from an unfamiliar website carries some risks. One reason some technologies are not included in Fedora is because of concerns over known patents. As you download, be knowledgeable about intellectual property issues and don't hesitate to ask questions of the host site making the download available." - Karsten On Fri, 2004-08-13 at 11:31, Karsten Wade wrote: > On Fri, 2004-08-13 at 08:46, Paul W. Frields wrote: > > > I think, frankly, directing people to Google is always best, that way > > they generally end up with the information they want, and it's up to > > them to provide the search parameters. I'm not saying that's the way to > > handle official documentation, I'm only saying it's an alternative > > that's free of legal entanglements. > > I wonder if we could direct people to google with suggestions on search > terminology and usage? For example: > > "One of the powers of Fedora Core is the enormous community behind it. > You will find that community is your best resource for using Fedora > Core. To find popular and useful websites with information, use your > favorite Web search engine, such as http://www.google.com. Try search > terms such as: > > using fedora to > fedora multimedia software > fedora packages" > > The search results that return for those search are not controlled by us > in any way. There are often more than 10,000 results. We can in no way > be held responsible for what is on those pages. > > Of course, IANAL, TINLA. Just an idea I personally am having. > > - Karsten > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Sat Aug 14 18:48:21 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 14 Aug 2004 19:48:21 +0100 Subject: fedora-docs bugs In-Reply-To: <1092420206.2449.38.camel@berlin.east.gov> References: <1092318823.18844.155.camel@berlin.east.gov> <1092357849.11376.235.camel@localhost.localdomain> <1092384405.2973.429.camel@albus.aeon.com.my> <200408130547.35778.hoyt@cavtel.net> <1092404743.2519.350.camel@homer> <1092411986.2449.4.camel@berlin.east.gov> <1092418203.2519.428.camel@homer> <1092420206.2449.38.camel@berlin.east.gov> Message-ID: <1092509300.4681.21.camel@homer> On Fri, 2004-08-13 at 19:03, Paul W. Frields wrote: > > > > I think, frankly, directing people to Google is always best, that way > > > they generally end up with the information they want, and it's up to > > > them to provide the search parameters. I'm not saying that's the way to > > > handle official documentation, I'm only saying it's an alternative > > > that's free of legal entanglements. > > > > And if it leads to yours or my website, > > then 'customers' will be happy? > > +1 > > Who gives a monkeys if its on RH website? > > Just because that's where customers expect it. > > I can't tell from your verbiage whether you're agreeing or not. :-) Nor I Paul. I'm simply saying that users want documentation that's good/usable etc. And don't care about the origin? > > When using Python, > > I find it quicker to use google to find > > documentation than using the actual documentation index. > > Does this mean we agree? I'm sorry, now I'm confused! :-) Simply saying that google can most often locate the python docs page more quickly than I can using the python docs index. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Aug 14 18:56:15 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 14 Aug 2004 19:56:15 +0100 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092420832.4488.35395.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> Message-ID: <1092509775.4681.29.camel@homer> On Fri, 2004-08-13 at 19:13, Karsten Wade wrote: > The value that you can get from an explicit section number and > associated ID tag are far less than the value of true modularity and the > ability to interleave documents. sect1..n can be enumerated just as readily as section. Equally stylesheets can generate id values for both. > > Since this is all FDL covered materials, we do our own licensing choice > a service by making it easier to use our works in a truly free manner. > > I'd recommend a standard of: > >
> Like The Title: The Details > > The ID has meaning to the content. the (nominal) typo there immediately hints at a weakness in doing this manually? > When moving chunks if
s > around, you can know what something is easily. Want an idea what > sections you have in what order? 'grep " something meaningful that directly corresponds to your table of > contents. If the content is sufficient to warrant that then the complexity will make it nominally difficult to re-use in alternate order? IBM have a structure which is more aligned to this class of re-use. > Any other thoughts on this? I'll hold off for a bit on filling out the > bug report. :) I wouldn't mandate either. There will be occasions when nested depths will be wanted. the only real difference is that the stylesheet treat sect1..n differently from recursive sections. sed will change sect(1|2|3|4) to section without much problem. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Aug 14 19:07:48 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 14 Aug 2004 20:07:48 +0100 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092428706.4488.36031.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> Message-ID: <1092510468.4681.34.camel@homer> On Fri, 2004-08-13 at 21:25, Karsten Wade wrote: > It is probably and properly lost in the annals of Red Hat documentation > history as to exactly why this format decision came about ... and as for > sed being your friend, I can tell you it gets harder when you have a > really big doc that has lots of tags throughout with hard-coded > LINKEND to IDs full of s1-, s2-, s3- and so forth. XSLT will resolve all of them, forward and reverse if needed. The source of the problem as I see it is the dual use of id attributes. Just because the stylesheets have an option of using sect1 id values as file names, it doesn't mean we have to. If the problems are separated, variant solutions will meet the different needs. id values should simply be document unique points used for cross reference. No more. As the schema says, they are optional. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From dataking at cox.net Sat Aug 14 20:46:14 2004 From: dataking at cox.net (D@7@k|N&) Date: Sat, 14 Aug 2004 13:46:14 -0700 Subject: status In-Reply-To: <1092416280.11376.350.camel@localhost.localdomain> Message-ID: -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Is there a document for system hardening? Is there interest for one? - -- - -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 - -----Original Message----- From: fedora-docs-list-bounces at redhat.com [mailto:fedora-docs-list-bounces at redhat.com] On Behalf Of Tammy Fox Sent: Friday, August 13, 2004 9:58 AM To: For participants of the docs project Subject: Re: status On Thu, 2004-08-12 at 21:07, Tammy Fox wrote: > On Thu, 2004-08-12 at 20:35, Tammy Fox wrote: > > Hi everyone, > > > > My maternity leave ends this month, so I am going through the Fedora > > docs bugs to start getting back in the swing of things. After that, I'll > > go through the mailing list to read about what I have missed. So far, > > here is a summary of the bug reports: > > > > Bug #129784 has been created to track docs ideas without owners > > > > Bug #129807 has been created to track docs in progress with a writer > > assigned to it > > > > A new bug report must be submitted for any new docs or docs changes so > > we can keep track of them (these should also be listed as blockers for > > bug #129807) > > > > I have fixed the following bugs: > > 122665, 123258, 123267, 125751, 125754, 129005 > > > > A new version of the Documentation Guide will appear on the website > > shortly. It is just a maintenance release after fixing the previously > > mentioned bugs. > > > > Version 0.2.2 is now on the website. > > I have also updated the main docs project page to include links to the > tracker bugs. This change should appear within the hour. > > Tammy Bugs 125759, 126101, and 129553, 129709 are also fixed. I put some in NEEDINFO state. Version 0.2.3 of the Docs Guide as well as the FC 2 SELinux FAQ are now on the website. I have company through Wednesday, so I probably won't find time to do any more work until after that. The only bugs left (that are mine) are in NEEDINFO or are new tutorial submissions. Hopefully I'll get to the new tutorial submissions next week. Have a great weekend! Tammy - -- fedora-docs-list mailing list fedora-docs-list at redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list -----BEGIN PGP SIGNATURE----- Version: PGP 8.0 iQA/AwUBQR56FqbnQHwVWKJjEQIv4QCfT9IQICJh+RUNqBjMkUVQsw7CXb0An3DU 2bmz0oc5J+0U8iP6rQOb89fj =5OAb -----END PGP SIGNATURE----- From mjohnson at redhat.com Sat Aug 14 21:39:02 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 14 Aug 2004 17:39:02 -0400 Subject: more defined process In-Reply-To: <1092497156.11376.673.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> Message-ID: <411E8676.7000204@redhat.com> Tammy Fox wrote: > One of the benefits of > DocBook is that you can use conditionals to create multiple documents > from the same source (like I was saying with the Installation Guides for > multiple arches in a different thread). Yeah, but not within the docs themselves. With XML the conditionals have to lie in the 'external subset', like a customization layer for the DTD. (Unless I'm really confused about XML...) > So, instead of creating a > separate guide with some of the same information, I think we should use > conditions in the existing source for the Docs Guide and create this > Quick Start Guide instead, if it is determined that we need another one. > This will make sure the 2 do not get out of sync, which can happen very > quickly. > > Mark, since this is your idea, please share some more details about what > you have in mind. How is it different from the existing guide? It would be a very brief tutorial on how to configure emacs for user-friendly DocBook XML editing. Naturally, I'd recommend that new users make use of my psgmlx[1] package for the psgml setup. [May have to do some tweaking to the package to provide the right stuff in the "Insert DTD" menu. I'll look inot this. Karsten & I are putting the package on Savannah 'real soon now'.] > What problem does it solve? Setting up emacsp/sgml, effectively, w/o having to do any setup. Truly a quick start to setting up a DocBook authoring environment in emacs. It's different from what's in the Docs guide in that psgmlx does all the setup for you, and provides sgml/xml-mode color themes as well. Put simply, it's aimed at newbie emacs users. It could be called a "Quick Start Setup Guide for Authoring DocBook docs with GNU Emacs", or something along those lines. The title isn't that important to me so long as it conveys the content of the document. [1] http://dulug.duke.edu/~mark/psgmlx > However, I would just like to > point out that even if you have used DocBook before, things like tag > usage can be interpreted in different ways, so you still need to read > the guide to make sure you are following the same rules as everyone else > writing Fedora docs. I agree. Some people do need a sort of 'best practices' or 'our practices' guide to tag usage, even though the online "DocBook, The Definitive Guide" is usually sufficient. For example, the use of 'filename' to tag a package is not at all obvious, as one could also use 'systemitem', or 'application', or many other things. So, yeah, I agree that there needs to be some sort of style guide to resolve ambiguities of these sorts. [FWIW, DocBook V4.4 now has a 'package' element, but is still only in the candidate release phase.] > I honestly don't think it is that long or verbose. It's long, but given the scope of the document, its length makes sense. I still am of the opinion that
should be recommended instead of the , etc. elements, and that the ID naming convention needs to be overhauled. But, hey, that's just my opinion:) Cheers, Mark -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From tfox at redhat.com Sat Aug 14 22:57:40 2004 From: tfox at redhat.com (Tammy Fox) Date: Sat, 14 Aug 2004 18:57:40 -0400 Subject: more defined process In-Reply-To: <411E8676.7000204@redhat.com> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> Message-ID: <1092524260.11376.685.camel@localhost.localdomain> On Sat, 2004-08-14 at 17:39, Mark Johnson wrote: > Tammy Fox wrote: > > > One of the benefits of > > DocBook is that you can use conditionals to create multiple documents > > from the same source (like I was saying with the Installation Guides for > > multiple arches in a different thread). > > Yeah, but not within the docs themselves. With XML the conditionals > have to lie in the 'external subset', like a customization layer for > the DTD. (Unless I'm really confused about XML...) > You can set conditionals within the docs themselves. DocBook XML has what is called profiling. http://www.sagehill.net/docbookxsl/Profiling.html I managed to figure this out for the Fedora Release Notes, and it works to have one master file from which all arch-specific release notes are built. There are built-in tag attributes for which you can assign keywords such as x86 for the arch attribute or linux for the os attribute. Then, when you build the HTML, you tell it which profiles to include. You can even include multiple profiles (unlike DocBook SGML conditional INCLUDE statements). For example: xsltproc -o index.html --nonet --xinclude \ -stringparam "profile.arch" "x86" \ -stringparam "profile.os" "linux" \ main.xsl example.xml As long as you use the built-in profile attributes, no customized DTD is needed. Tammy > > So, instead of creating a > > separate guide with some of the same information, I think we should use > > conditions in the existing source for the Docs Guide and create this > > Quick Start Guide instead, if it is determined that we need another one. > > This will make sure the 2 do not get out of sync, which can happen very > > quickly. > > > > Mark, since this is your idea, please share some more details about what > > you have in mind. How is it different from the existing guide? > > It would be a very brief tutorial on how to configure emacs for > user-friendly DocBook XML editing. Naturally, I'd recommend that new > users make use of my psgmlx[1] package for the psgml setup. [May > have to do some tweaking to the package to provide the right stuff > in the "Insert DTD" menu. I'll look inot this. Karsten & I are > putting the package on Savannah 'real soon now'.] > > > > What problem does it solve? > > Setting up emacsp/sgml, effectively, w/o having to do any setup. > Truly a quick start to setting up a DocBook authoring environment in > emacs. It's different from what's in the Docs guide in that psgmlx > does all the setup for you, and provides sgml/xml-mode color themes > as well. Put simply, it's aimed at newbie emacs users. > > It could be called a "Quick Start Setup Guide for Authoring DocBook > docs with GNU Emacs", or something along those lines. The title > isn't that important to me so long as it conveys the content of the > document. > > [1] http://dulug.duke.edu/~mark/psgmlx > > > However, I would just like to > > point out that even if you have used DocBook before, things like tag > > usage can be interpreted in different ways, so you still need to read > > the guide to make sure you are following the same rules as everyone else > > writing Fedora docs. > > I agree. Some people do need a sort of 'best practices' or 'our > practices' guide to tag usage, even though the online "DocBook, The > Definitive Guide" is usually sufficient. For example, the use of > 'filename' to tag a package is not at all obvious, as one could also > use 'systemitem', or 'application', or many other things. So, yeah, > I agree that there needs to be some sort of style guide to resolve > ambiguities of these sorts. [FWIW, DocBook V4.4 now has a 'package' > element, but is still only in the candidate release phase.] > > > I honestly don't think it is that long or verbose. > > It's long, but given the scope of the document, its length makes > sense. I still am of the opinion that
should be > recommended instead of the , etc. elements, and that > the ID naming convention needs to be overhauled. But, hey, that's > just my opinion:) > > Cheers, > Mark > > -- > ---------------------------------------------------------- > Mark Johnson > Red Hat Documentation Group > Tel: 919.754.4151 Fax: 919.754.3708 > GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Sat Aug 14 23:27:57 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 14 Aug 2004 19:27:57 -0400 Subject: more defined process In-Reply-To: <1092524260.11376.685.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> <1092524260.11376.685.camel@localhost.localdomain> Message-ID: <411E9FFD.7010809@redhat.com> You're talking about profiling based on attribute values. This is a different mechanism than conditional sections in SGML. I agree that this is the way to go, and has generally become the solution for the lack of support for conditional sections in XML. Just wanted to make it clear that we're no longer talking about conditional sections, that's all. Profiling is a different mechanism, and therefore shouldn't be referred to as using conditional sections. Doing so may confuse the authors, and potential authors. Thanks for clarifying what you meant. Cheers, Mark Tammy Fox wrote: > On Sat, 2004-08-14 at 17:39, Mark Johnson wrote: > >>Tammy Fox wrote: >> >> >>>One of the benefits of >>>DocBook is that you can use conditionals to create multiple documents >>>from the same source (like I was saying with the Installation Guides for >>>multiple arches in a different thread). >> >>Yeah, but not within the docs themselves. With XML the conditionals >>have to lie in the 'external subset', like a customization layer for >>the DTD. (Unless I'm really confused about XML...) >> > > > You can set conditionals within the docs themselves. DocBook XML has > what is called profiling. > > http://www.sagehill.net/docbookxsl/Profiling.html > > I managed to figure this out for the Fedora Release Notes, and it works > to have one master file from which all arch-specific release notes are > built. > > There are built-in tag attributes for which you can assign keywords such > as x86 for the arch attribute or linux for the os attribute. > > Then, when you build the HTML, you tell it which profiles to include. > You can even include multiple profiles (unlike DocBook SGML conditional > INCLUDE statements). For example: > > xsltproc -o index.html --nonet --xinclude \ > -stringparam "profile.arch" "x86" \ > -stringparam "profile.os" "linux" \ > main.xsl example.xml > > As long as you use the built-in profile attributes, no customized DTD is > needed. > > Tammy > > >>>So, instead of creating a >>>separate guide with some of the same information, I think we should use >>>conditions in the existing source for the Docs Guide and create this >>>Quick Start Guide instead, if it is determined that we need another one. >>>This will make sure the 2 do not get out of sync, which can happen very >>>quickly. >>> >>>Mark, since this is your idea, please share some more details about what >>>you have in mind. How is it different from the existing guide? >> >>It would be a very brief tutorial on how to configure emacs for >>user-friendly DocBook XML editing. Naturally, I'd recommend that new >>users make use of my psgmlx[1] package for the psgml setup. [May >>have to do some tweaking to the package to provide the right stuff >>in the "Insert DTD" menu. I'll look inot this. Karsten & I are >>putting the package on Savannah 'real soon now'.] >> >> >> >>>What problem does it solve? >> >>Setting up emacsp/sgml, effectively, w/o having to do any setup. >>Truly a quick start to setting up a DocBook authoring environment in >>emacs. It's different from what's in the Docs guide in that psgmlx >>does all the setup for you, and provides sgml/xml-mode color themes >>as well. Put simply, it's aimed at newbie emacs users. >> >>It could be called a "Quick Start Setup Guide for Authoring DocBook >>docs with GNU Emacs", or something along those lines. The title >>isn't that important to me so long as it conveys the content of the >>document. >> >>[1] http://dulug.duke.edu/~mark/psgmlx >> >> >>>However, I would just like to >>>point out that even if you have used DocBook before, things like tag >>>usage can be interpreted in different ways, so you still need to read >>>the guide to make sure you are following the same rules as everyone else >>>writing Fedora docs. >> >>I agree. Some people do need a sort of 'best practices' or 'our >>practices' guide to tag usage, even though the online "DocBook, The >>Definitive Guide" is usually sufficient. For example, the use of >>'filename' to tag a package is not at all obvious, as one could also >>use 'systemitem', or 'application', or many other things. So, yeah, >>I agree that there needs to be some sort of style guide to resolve >>ambiguities of these sorts. [FWIW, DocBook V4.4 now has a 'package' >>element, but is still only in the candidate release phase.] >> >> >>>I honestly don't think it is that long or verbose. >> >>It's long, but given the scope of the document, its length makes >>sense. I still am of the opinion that
should be >>recommended instead of the , etc. elements, and that >>the ID naming convention needs to be overhauled. But, hey, that's >>just my opinion:) >> >>Cheers, >>Mark >> >>-- >>---------------------------------------------------------- >>Mark Johnson >>Red Hat Documentation Group >>Tel: 919.754.4151 Fax: 919.754.3708 >>GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 > > > -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Sat Aug 14 23:38:06 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 14 Aug 2004 19:38:06 -0400 Subject: more defined process In-Reply-To: <411E9FFD.7010809@redhat.com> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> <1092524260.11376.685.camel@localhost.localdomain> <411E9FFD.7010809@redhat.com> Message-ID: <411EA25E.60801@redhat.com> FWIW, I have some experience in implementing profiling and would be happy to offer help as needed. From a quick scan of the fedora docs guide, I can't tell if it mentions conditional sections, but if it does, we ought to rewrite that section. 'Be happy to file the appropriate bug... In fact, the DocBook TC recently agreed to add another global attribute 'wordsize', which can be used via profiling to distinguish 32-bit relevant content from 64-bit content. fedora docs may find this attribute to be useful. (Caveat: the attribute was added to DocBook V4.4, which is still in the candidate-release phase.) Cheers, Mark Mark Johnson wrote: > You're talking about profiling based on attribute values. This is a > different mechanism than conditional sections in SGML. > > I agree that this is the way to go, and has generally become the > solution for the lack of support for conditional sections in XML. > > Just wanted to make it clear that we're no longer talking about > conditional sections, that's all. Profiling is a different mechanism, > and therefore shouldn't be referred to as using conditional sections. > Doing so may confuse the authors, and potential authors. > > Thanks for clarifying what you meant. > > Cheers, > Mark > > > > Tammy Fox wrote: > >> On Sat, 2004-08-14 at 17:39, Mark Johnson wrote: >> >>> Tammy Fox wrote: >>> >>> >>>> One of the benefits of >>>> DocBook is that you can use conditionals to create multiple documents >>>> from the same source (like I was saying with the Installation Guides >>>> for >>>> multiple arches in a different thread). >>> >>> >>> Yeah, but not within the docs themselves. With XML the conditionals >>> have to lie in the 'external subset', like a customization layer for >>> the DTD. (Unless I'm really confused about XML...) >>> >> >> >> You can set conditionals within the docs themselves. DocBook XML has >> what is called profiling. >> http://www.sagehill.net/docbookxsl/Profiling.html >> >> I managed to figure this out for the Fedora Release Notes, and it works >> to have one master file from which all arch-specific release notes are >> built. >> There are built-in tag attributes for which you can assign keywords such >> as x86 for the arch attribute or linux for the os attribute. >> >> Then, when you build the HTML, you tell it which profiles to include. >> You can even include multiple profiles (unlike DocBook SGML conditional >> INCLUDE statements). For example: >> >> xsltproc -o index.html --nonet --xinclude \ >> -stringparam "profile.arch" "x86" \ >> -stringparam "profile.os" "linux" \ >> main.xsl example.xml >> >> As long as you use the built-in profile attributes, no customized DTD is >> needed. >> >> Tammy >> >> >>>> So, instead of creating a >>>> separate guide with some of the same information, I think we should use >>>> conditions in the existing source for the Docs Guide and create this >>>> Quick Start Guide instead, if it is determined that we need another >>>> one. >>>> This will make sure the 2 do not get out of sync, which can happen very >>>> quickly. >>>> >>>> Mark, since this is your idea, please share some more details about >>>> what >>>> you have in mind. How is it different from the existing guide? >>> >>> >>> It would be a very brief tutorial on how to configure emacs for >>> user-friendly DocBook XML editing. Naturally, I'd recommend that new >>> users make use of my psgmlx[1] package for the psgml setup. [May have >>> to do some tweaking to the package to provide the right stuff in the >>> "Insert DTD" menu. I'll look inot this. Karsten & I are putting the >>> package on Savannah 'real soon now'.] >>> >>> >>> >>>> What problem does it solve? >>> >>> >>> Setting up emacsp/sgml, effectively, w/o having to do any setup. >>> Truly a quick start to setting up a DocBook authoring environment in >>> emacs. It's different from what's in the Docs guide in that psgmlx >>> does all the setup for you, and provides sgml/xml-mode color themes >>> as well. Put simply, it's aimed at newbie emacs users. >>> >>> It could be called a "Quick Start Setup Guide for Authoring DocBook >>> docs with GNU Emacs", or something along those lines. The title isn't >>> that important to me so long as it conveys the content of the document. >>> >>> [1] http://dulug.duke.edu/~mark/psgmlx >>> >>> >>>> However, I would just like to >>>> point out that even if you have used DocBook before, things like tag >>>> usage can be interpreted in different ways, so you still need to read >>>> the guide to make sure you are following the same rules as everyone >>>> else >>>> writing Fedora docs. >>> >>> >>> I agree. Some people do need a sort of 'best practices' or 'our >>> practices' guide to tag usage, even though the online "DocBook, The >>> Definitive Guide" is usually sufficient. For example, the use of >>> 'filename' to tag a package is not at all obvious, as one could also >>> use 'systemitem', or 'application', or many other things. So, yeah, I >>> agree that there needs to be some sort of style guide to resolve >>> ambiguities of these sorts. [FWIW, DocBook V4.4 now has a 'package' >>> element, but is still only in the candidate release phase.] >>> >>> >>>> I honestly don't think it is that long or verbose. >>> >>> >>> It's long, but given the scope of the document, its length makes >>> sense. I still am of the opinion that
should be recommended >>> instead of the , etc. elements, and that the ID naming >>> convention needs to be overhauled. But, hey, that's just my opinion:) >>> >>> Cheers, >>> Mark >>> >>> -- >>> ---------------------------------------------------------- >>> Mark Johnson >>> Red Hat Documentation Group >>> Tel: 919.754.4151 Fax: 919.754.3708 >>> GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 >> >> >> >> > > -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From tfox at redhat.com Sat Aug 14 23:58:51 2004 From: tfox at redhat.com (Tammy Fox) Date: Sat, 14 Aug 2004 19:58:51 -0400 Subject: more defined process In-Reply-To: <411EA25E.60801@redhat.com> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> <1092524260.11376.685.camel@localhost.localdomain> <411E9FFD.7010809@redhat.com> <411EA25E.60801@redhat.com> Message-ID: <1092527931.11376.692.camel@localhost.localdomain> On Sat, 2004-08-14 at 19:38, Mark Johnson wrote: > FWIW, I have some experience in implementing profiling and would be > happy to offer help as needed. > > From a quick scan of the fedora docs guide, I can't tell if it > mentions conditional sections, but if it does, we ought to rewrite > that section. 'Be happy to file the appropriate bug... > It isn't in there currently. I thought I wrote up the instructions after I figured it out for the Fedora Release Notes, but I can't find them now. So, go ahead and file a bug. I think it would make a great tutorial even if we don't end up using it for your quick start guide. Tammy > In fact, the DocBook TC recently agreed to add another global > attribute 'wordsize', which can be used via profiling to distinguish > 32-bit relevant content from 64-bit content. fedora docs may find > this attribute to be useful. (Caveat: the attribute was added to > DocBook V4.4, which is still in the candidate-release phase.) > > Cheers, > Mark > > > Mark Johnson wrote: > > You're talking about profiling based on attribute values. This is a > > different mechanism than conditional sections in SGML. > > > > I agree that this is the way to go, and has generally become the > > solution for the lack of support for conditional sections in XML. > > > > Just wanted to make it clear that we're no longer talking about > > conditional sections, that's all. Profiling is a different mechanism, > > and therefore shouldn't be referred to as using conditional sections. > > Doing so may confuse the authors, and potential authors. > > > > Thanks for clarifying what you meant. > > > > Cheers, > > Mark > > > > > > > > Tammy Fox wrote: > > > >> On Sat, 2004-08-14 at 17:39, Mark Johnson wrote: > >> > >>> Tammy Fox wrote: > >>> > >>> > >>>> One of the benefits of > >>>> DocBook is that you can use conditionals to create multiple documents > >>>> from the same source (like I was saying with the Installation Guides > >>>> for > >>>> multiple arches in a different thread). > >>> > >>> > >>> Yeah, but not within the docs themselves. With XML the conditionals > >>> have to lie in the 'external subset', like a customization layer for > >>> the DTD. (Unless I'm really confused about XML...) > >>> > >> > >> > >> You can set conditionals within the docs themselves. DocBook XML has > >> what is called profiling. > >> http://www.sagehill.net/docbookxsl/Profiling.html > >> > >> I managed to figure this out for the Fedora Release Notes, and it works > >> to have one master file from which all arch-specific release notes are > >> built. > >> There are built-in tag attributes for which you can assign keywords such > >> as x86 for the arch attribute or linux for the os attribute. > >> > >> Then, when you build the HTML, you tell it which profiles to include. > >> You can even include multiple profiles (unlike DocBook SGML conditional > >> INCLUDE statements). For example: > >> > >> xsltproc -o index.html --nonet --xinclude \ > >> -stringparam "profile.arch" "x86" \ > >> -stringparam "profile.os" "linux" \ > >> main.xsl example.xml > >> > >> As long as you use the built-in profile attributes, no customized DTD is > >> needed. > >> > >> Tammy > >> > >> > >>>> So, instead of creating a > >>>> separate guide with some of the same information, I think we should use > >>>> conditions in the existing source for the Docs Guide and create this > >>>> Quick Start Guide instead, if it is determined that we need another > >>>> one. > >>>> This will make sure the 2 do not get out of sync, which can happen very > >>>> quickly. > >>>> > >>>> Mark, since this is your idea, please share some more details about > >>>> what > >>>> you have in mind. How is it different from the existing guide? > >>> > >>> > >>> It would be a very brief tutorial on how to configure emacs for > >>> user-friendly DocBook XML editing. Naturally, I'd recommend that new > >>> users make use of my psgmlx[1] package for the psgml setup. [May have > >>> to do some tweaking to the package to provide the right stuff in the > >>> "Insert DTD" menu. I'll look inot this. Karsten & I are putting the > >>> package on Savannah 'real soon now'.] > >>> > >>> > >>> > >>>> What problem does it solve? > >>> > >>> > >>> Setting up emacsp/sgml, effectively, w/o having to do any setup. > >>> Truly a quick start to setting up a DocBook authoring environment in > >>> emacs. It's different from what's in the Docs guide in that psgmlx > >>> does all the setup for you, and provides sgml/xml-mode color themes > >>> as well. Put simply, it's aimed at newbie emacs users. > >>> > >>> It could be called a "Quick Start Setup Guide for Authoring DocBook > >>> docs with GNU Emacs", or something along those lines. The title isn't > >>> that important to me so long as it conveys the content of the document. > >>> > >>> [1] http://dulug.duke.edu/~mark/psgmlx > >>> > >>> > >>>> However, I would just like to > >>>> point out that even if you have used DocBook before, things like tag > >>>> usage can be interpreted in different ways, so you still need to read > >>>> the guide to make sure you are following the same rules as everyone > >>>> else > >>>> writing Fedora docs. > >>> > >>> > >>> I agree. Some people do need a sort of 'best practices' or 'our > >>> practices' guide to tag usage, even though the online "DocBook, The > >>> Definitive Guide" is usually sufficient. For example, the use of > >>> 'filename' to tag a package is not at all obvious, as one could also > >>> use 'systemitem', or 'application', or many other things. So, yeah, I > >>> agree that there needs to be some sort of style guide to resolve > >>> ambiguities of these sorts. [FWIW, DocBook V4.4 now has a 'package' > >>> element, but is still only in the candidate release phase.] > >>> > >>> > >>>> I honestly don't think it is that long or verbose. > >>> > >>> > >>> It's long, but given the scope of the document, its length makes > >>> sense. I still am of the opinion that
should be recommended > >>> instead of the , etc. elements, and that the ID naming > >>> convention needs to be overhauled. But, hey, that's just my opinion:) > >>> > >>> Cheers, > >>> Mark > >>> > >>> -- > >>> ---------------------------------------------------------- > >>> Mark Johnson > >>> Red Hat Documentation Group > >>> Tel: 919.754.4151 Fax: 919.754.3708 > >>> GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 > >> > >> > >> > >> > > > > > > > -- > ---------------------------------------------------------- > Mark Johnson > Red Hat Documentation Group > Tel: 919.754.4151 Fax: 919.754.3708 > GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From tfox at redhat.com Sun Aug 15 00:17:04 2004 From: tfox at redhat.com (Tammy Fox) Date: Sat, 14 Aug 2004 20:17:04 -0400 Subject: New tracker In-Reply-To: <1092352056.4488.33859.camel@erato.phig.org> References: <1092287259.2973.20.camel@albus.aeon.com.my> <1092352056.4488.33859.camel@erato.phig.org> Message-ID: <1092529024.11376.703.camel@localhost.localdomain> On Thu, 2004-08-12 at 19:07, Karsten Wade wrote: > On Wed, 2004-08-11 at 22:07, Colin Charles wrote: > > Since no one else started it, the tracker now is: > > > > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129722 > > > > I've added various docs that should be on the site, so to speak. > > Comments, etc.. welcome (on the bug) > > Saw Tammy this afternoon, she cleared through a few bugs (if you filed > them, you saw the resolution, changes coming to the website) and moved > some stuff along. We discussed the doc tracking process, and she > expanded the doc tracker bugs, so there is now: > > 1. http://bugzilla.redhat.com/129784 Docs ideas without owners - a > general bucket for ideas for new documents or conversions that come > _first_ through the list > > 2. http://bugzilla.redhat.com/129807 Docs in progress - for tracking > documents actively being written/developed/edited > > 3. http://bugzilla.redhat.com/129722 Docs ready for going to > fedora.redhat.com - when it is done with 129807, it comes here while it > undergoes final editing to go to the website. > > This means the process of idea -> publication is: > > 1. File a bug report for your document, or carry the on the one with the > idea in it. > > 2. Move the bug through the tracker in this order > > idea -> develop <-> publish > 129784 129807 129722 > > Note: there is a double-arrow between develop <-> publish because a > document should stay alive after it is published. Once you have > published a version and have moved to writing for the next version of > Fedora Core, your document's bug moves back to 129807. > > I'll add this into the process document, which Dave converted to XML and > I am editing for reposting back here for more comments. > Karsten, It seems like we have some duplication of effort here. Before I knew you had started a process document in XML, I started http://fedora.redhat.com/participate/documentation-quick-start/ Seems like we should combine our efforts and decide whether to use XML for this or just post it on the website. Since it isn't very long, I started it as a straight webpage thinking it would be faster to update. Which do you prefer? I do like your explanation here of the lifecycle of a tutorial so I'll incorporate it into my page as soon as I get a chance (within the next few days). We could even draw up a flow chart in Dia. Like I said previously, my page needs organization. I was just trying to get it up for everyone to see as soon as possible while everyone was interested in discussing the idea. Tammy > cheers - Karsten > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From byte at aeon.com.my Sun Aug 15 13:15:21 2004 From: byte at aeon.com.my (Colin Charles) Date: Sun, 15 Aug 2004 23:15:21 +1000 Subject: editors In-Reply-To: <1092333413.4488.33328.camel@erato.phig.org> References: <1092333413.4488.33328.camel@erato.phig.org> Message-ID: <1092575720.5424.93.camel@albus.aeon.com.my> On Fri, 2004-08-13 at 03:56, Karsten Wade wrote: (In re-response, since earlier I mentioned the editor list, and now I've re-read the post :P) > * Should there be an editorial board? Such a board would oversee the > Fedora docs, make sure we are adhering to our standards, filling in > holes, following or advancing our process, etc. Probably a good idea > * Separate mailing list for editors? Or just accept that > fedora-docs-list gets busier with traffic between editors and authors. No, one list. Mailing list, Bugzilla, and that's enough traffic - let's not have another list > * Also, much of the editing traffic can be in bugzilla, as each document > will have it's own bug throughout it's lifecycle. Yup, this is the way. Might I also discourage hosting documents on external sites? Using Bugzilla's "attach file" will work > * The board needs to have an odd number of people so that if consensus > can't be reached, a majority vote without a tie is possible. Good idea :P Or we can just set Tammy or you as the tie-breaker... > * Editorial board could just form like Voltron right now from available > interested parties (myself included there, please), and proceed with > some process defining. So there's you, there's Paul, Dave probably yes, Tammy is most likely a definite, I wouldn't mind, who else? Speak up folk :P -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From davep at dpawson.co.uk Sun Aug 15 15:21:24 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 15 Aug 2004 16:21:24 +0100 Subject: status In-Reply-To: References: Message-ID: <1092583284.4925.17.camel@homer> On Sat, 2004-08-14 at 21:46, D at 7@k|N& wrote: And I thought my name was odd! > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > Is there a document for system hardening? Is there interest for one? If I ask the obvious, will that provide some answer? What's system hardening? .. Or at least, hardening against what? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sun Aug 15 15:25:55 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 15 Aug 2004 16:25:55 +0100 Subject: more defined process In-Reply-To: <411EA25E.60801@redhat.com> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> <1092524260.11376.685.camel@localhost.localdomain> <411E9FFD.7010809@redhat.com> <411EA25E.60801@redhat.com> Message-ID: <1092583554.4925.21.camel@homer> On Sun, 2004-08-15 at 00:38, Mark Johnson wrote: > FWIW, I have some experience in implementing profiling and would be > happy to offer help as needed. > > From a quick scan of the fedora docs guide, I can't tell if it > mentions conditional sections, but if it does, we ought to rewrite > that section. 'Be happy to file the appropriate bug... > > In fact, the DocBook TC recently agreed to add another global > attribute 'wordsize', which can be used via profiling to distinguish > 32-bit relevant content from 64-bit content. fedora docs may find > this attribute to be useful. (Caveat: the attribute was added to > DocBook V4.4, which is still in the candidate-release phase.) Mark, I'd be more supportive of attribute based selection, rather than conditional sections? Then filter based on stylesheet parameters as Tammy suggested? Especially since the current DTD may well be the last for docbook? A move to relax NG would make any development work here redundant? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Sun Aug 15 15:27:24 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 15 Aug 2004 11:27:24 -0400 Subject: status In-Reply-To: <1092583284.4925.17.camel@homer> References: <1092583284.4925.17.camel@homer> Message-ID: <1092583643.9843.62.camel@bettie.internal.frields.org> On Sun, 2004-08-15 at 11:21, Dave Pawson wrote: > > Is there a document for system hardening? Is there interest for one? > If I ask the obvious, will that provide some answer? > What's system hardening? > .. > Or at least, hardening against what? Q.v.: http://en.wikipedia.org/wiki/Hardening "In Computing, hardening is known as the process of securing a system. This work especially is done to protect systems against attackers. "This would typically include removal of unnecessary usernames / logins and the disabling or removal of unecessary services. On a typical Windows based server, one example would be the disabling of the "print spooler" as this may not be needed." -- Paul W. Frields, RHCE From davep at dpawson.co.uk Sun Aug 15 15:29:23 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 15 Aug 2004 16:29:23 +0100 Subject: more defined process In-Reply-To: <411E8676.7000204@redhat.com> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> Message-ID: <1092583762.4925.25.camel@homer> On Sat, 2004-08-14 at 22:39, Mark Johnson wrote: > > What problem does it solve? > > Setting up emacsp/sgml, effectively, w/o having to do any setup. Except add to a 'standard' emacs+psgml setup? What of people who already are balancing ten different emacs 'standard' configurations? Any conditional sections btw, doesn't matter if they are internal or external schema, its still a docbook extension. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Sun Aug 15 15:55:55 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 15 Aug 2004 11:55:55 -0400 Subject: Emacs/psgml problem Message-ID: <1092585354.9843.110.camel@bettie.internal.frields.org> I'm hoping someone here has a quick solution. I'm working on a document and my tags are giving me a problem under psgml. At a certain point in my document, when I use a tag, slashes in the file name content (not inside the tag marker) are being interpreted as ending tags for the content outside "filename." So when I type: /etc/fstab the first slash is being seen as , and the second as . (Yes, I know, I haven't converted this to
usage yet.) I've looked through the document and used C-C C-C to check context all the way up to the tag in question, and can't seem to find any funkiness. I even used TAB to see if the indentation would show me where there was a problem. Nothing seems to be wrong until I type that tag. When I save and "make html," for example, the code validates properly. Does anyone have any suggestions? Please be gentle, and remember that I am a DocBook, XML, and Emacs idiot. I've learned enough to write and markup, but am not familiar with the internals of any of these tools. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Sun Aug 15 16:20:34 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 15 Aug 2004 17:20:34 +0100 Subject: Emacs/psgml problem In-Reply-To: <1092585354.9843.110.camel@bettie.internal.frields.org> References: <1092585354.9843.110.camel@bettie.internal.frields.org> Message-ID: <1092586698.4925.44.camel@homer> On Sun, 2004-08-15 at 16:55, Paul W. Frields wrote: > I'm hoping someone here has a quick solution. I'm working on a document > and my tags are giving me a problem under psgml. At a certain point in > my document, when I use a tag, slashes in the file name > content (not inside the tag marker) are being interpreted as ending tags > for the content outside "filename." So when I type: > > /etc/fstab > > the first slash is being seen as , and the second as . Something is wrong Paul. The electric close should operate on References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> Message-ID: <1092588883.9843.184.camel@bettie.internal.frields.org> On Sun, 2004-08-15 at 12:20, Dave Pawson wrote: > On Sun, 2004-08-15 at 16:55, Paul W. Frields wrote: > > I'm hoping someone here has a quick solution. I'm working on a document > > and my tags are giving me a problem under psgml. At a certain point in > > my document, when I use a tag, slashes in the file name > > content (not inside the tag marker) are being interpreted as ending tags > > for the content outside "filename." So when I type: > > > > /etc/fstab > > > > the first slash is being seen as , and the second as . > Something is wrong Paul. > The electric close should operate on Unless some clever person has added even more brevity? > I.e. you shouldn't get tag closure until the > This is code to do it > > (defun sgml-slash-check () "For psgml-mode, if you type `/' after `<', > insert the appropriate end tag, if there is an open element." > (interactive) > (if (= (char-before) 60) > ;; Slash after <, let's end the current open element if we can > (progn > (sgml-parse-to-here) > (cond > ((eq sgml-current-tree sgml-top-tree) > (insert "/")) > ((not (sgml-final-p sgml-current-state)) > (insert "/")) > (t (progn > (delete-backward-char 1) > (insert (sgml-end-tag-of sgml-current-tree)))))) > (insert "/"))) > > > (add-hook 'xml-mode-hook > (lambda () (define-key xml-mode-map "/" `sgml-slash-check))) > > > Its a tortuous path to chase through emacs site-lisp and all > included .el files, but somewhere there should be similar code > to do this. I think its a part of psgml, but the code above > is for xsl-mode, so may be different. > > psgml-edit.el is the file it's normally found it. > > No idea of the 'standard' rh setup. I've been using the same setup since I first started doing FDP stuff; I added the code listed in the Doc Guide to my .emacs file, and haven't changed it. rpm -V psgml looks fine. I think after having battled it for a little while that it's related to doing this: instead of: Exiting Emacs and restarting it seems to "fix" the problem. It only happens using after tags. I'm confused but I'm not sure how to Bugzilla the problem since it could be the Big OE (Operator Error). -- Paul W. Frields, RHCE From kwade at redhat.com Sun Aug 15 17:00:38 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 15 Aug 2004 10:00:38 -0700 Subject: status In-Reply-To: References: Message-ID: <1092589237.3459.4393.camel@erato.phig.org> On Sat, 2004-08-14 at 13:46, D at 7@k|N& wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > Is there a document for system hardening? Not from the FDP for Fedora. > Is there interest for one? Definitely. I'll even volunteer to be your editor[1]. :) File a bug for your idea, and set it to block bug # 129784. You can put me on the Cc: for the bug, and, as Colin suggested, you can attach your draft files to the bug. - Karsten [1] - this is because I have just a little bit of experience with hardening; if we have a security expert available, by all means that person should do technical editing. -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Sun Aug 15 17:16:04 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 15 Aug 2004 10:16:04 -0700 Subject: more defined process In-Reply-To: <411E8676.7000204@redhat.com> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> Message-ID: <1092590164.3459.4434.camel@erato.phig.org> On Sat, 2004-08-14 at 14:39, Mark Johnson wrote: > Tammy Fox wrote: > > > Mark, since this is your idea, please share some more details about what > > you have in mind. How is it different from the existing guide? > > It would be a very brief tutorial on how to configure emacs for > user-friendly DocBook XML editing. Naturally, I'd recommend that new > users make use of my psgmlx[1] package for the psgml setup. [May > have to do some tweaking to the package to provide the right stuff > in the "Insert DTD" menu. I'll look inot this. Karsten & I are > putting the package on Savannah 'real soon now'.] > > > > What problem does it solve? > > Setting up emacsp/sgml, effectively, w/o having to do any setup. > Truly a quick start to setting up a DocBook authoring environment in > emacs. It's different from what's in the Docs guide in that psgmlx > does all the setup for you, and provides sgml/xml-mode color themes > as well. Put simply, it's aimed at newbie emacs users. > IMO, we should continue to focus on smaller, modular . Internally at Red Hat, I push for all processes and how-to material for the Engineering Docs team to be in the one Doc Guide. However, we don't want the Fedora docs project Doc Guide to become a massive tome. This is just an extension of the argument that we don't want too grow our document set by making bigger books until we have a solid, experienced team. Working on smaller books that snap together is much more feasible and scalable. For that reason, I'd suggest Mark do his doc as a stand-alone. It will be easy enough to convert it to a and include it in the Doc Guide when we are ready to support even just that one guide more completely. Oh, FWIW, psgmlx works really well. I don't use the right-click insert element, or many of the other fancy mouse tricks that Mark included and that are perfect for new users. What I love is that the _awesome_ psgml keybindings are available for XML. I understand that nXML is probably the way of the future (considering James Clark is behind it), but for now psgmlx has a better feature set, IMHO. - Karsten > [1] http://dulug.duke.edu/~mark/psgmlx -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Sun Aug 15 17:23:07 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 15 Aug 2004 10:23:07 -0700 Subject: Emacs/psgml problem In-Reply-To: <1092588883.9843.184.camel@bettie.internal.frields.org> References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> <1092588883.9843.184.camel@bettie.internal.frields.org> Message-ID: <1092590587.3459.4455.camel@erato.phig.org> On Sun, 2004-08-15 at 09:54, Paul W. Frields wrote: > I've been using the same setup since I first started doing FDP stuff; I > added the code listed in the Doc Guide to my .emacs file, and haven't > changed it. rpm -V psgml looks fine. > > I think after having battled it for a little while that it's related to > doing this: > > instead of: > > > Exiting Emacs and restarting it seems to "fix" the problem. It only > happens using after tags. I'm confused but I'm not > sure how to Bugzilla the problem since it could be the Big OE (Operator > Error). I was first going to ask if you had a stuck Ctrl key on your keyboard. :) Mark may lend more enlightenment here, but I'm wondering if the problem is that PSGML is written to work in a valid SGML environment, where < /> isn't legal. Even though it's presumably validated against the DTD (C-c C-p), it might still be hardwired to do something different. Restarting Emacs might just be revalidating against the XML DTD and that works fine, but later PSGML "forgets" and falls back on some hardwired expectation? FWIW, in SGML I have never had a problem with an unclosed . I've always written it as just plain without a . Of course, this is not legal in XML, so you have to include it. Another thing you might try (being a self-professed newbie who seems to be doing quite well anyway) is Mark's PSGMLX package: http://dulug.duke.edu/~mark/psgmlx . It will validate against the XML DTD properly, afaict. Just don't find any bugs in it, Mark doesn't have any time to fix them. :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Sun Aug 15 17:28:46 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 15 Aug 2004 13:28:46 -0400 Subject: Emacs/psgml problem In-Reply-To: <1092590587.3459.4455.camel@erato.phig.org> References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> <1092588883.9843.184.camel@bettie.internal.frields.org> <1092590587.3459.4455.camel@erato.phig.org> Message-ID: <1092590926.9843.218.camel@bettie.internal.frields.org> On Sun, 2004-08-15 at 13:23, Karsten Wade wrote: > On Sun, 2004-08-15 at 09:54, Paul W. Frields wrote: > > I've been using the same setup since I first started doing FDP stuff; I > > added the code listed in the Doc Guide to my .emacs file, and haven't > > changed it. rpm -V psgml looks fine. > > > > I think after having battled it for a little while that it's related to > > doing this: > > > > instead of: > > > > > > Exiting Emacs and restarting it seems to "fix" the problem. It only > > happens using after tags. I'm confused but I'm not > > sure how to Bugzilla the problem since it could be the Big OE (Operator > > Error). > > I was first going to ask if you had a stuck Ctrl key on your keyboard. > :) Out of genuine curiosity, would this have caused a problem like what I observed? > Mark may lend more enlightenment here, but I'm wondering if the problem > is that PSGML is written to work in a valid SGML environment, where < /> > isn't legal. Even though it's presumably validated against the DTD (C-c > C-p), it might still be hardwired to do something different. > Restarting Emacs might just be revalidating against the XML DTD and that > works fine, but later PSGML "forgets" and falls back on some hardwired > expectation? I rewrote those tags with explicit and the problem did seem to disappear. Hmmm. > FWIW, in SGML I have never had a problem with an unclosed . I've > always written it as just plain without a > . Of course, this is not legal in XML, so you have to include > it. > > Another thing you might try (being a self-professed newbie who seems to > be doing quite well anyway) is Mark's PSGMLX package: > http://dulug.duke.edu/~mark/psgmlx . It will validate against the XML > DTD properly, afaict. Just don't find any bugs in it, Mark doesn't have > any time to fix them. :) It's on my to-do list! Am I correct that you just indicated (in another thread, sorry) that I can use all the same keybindings as in PSGML? If I don't have to unlearn what I've only recently learned for psgml, I'm more likely to try psgmlx. -- Paul W. Frields, RHCE From kwade at redhat.com Sun Aug 15 17:28:59 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 15 Aug 2004 10:28:59 -0700 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092510468.4681.34.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> Message-ID: <1092590939.3459.4473.camel@erato.phig.org> On Sat, 2004-08-14 at 12:07, Dave Pawson wrote: > On Fri, 2004-08-13 at 21:25, Karsten Wade wrote: > > > It is probably and properly lost in the annals of Red Hat documentation > > history as to exactly why this format decision came about ... and as for > > sed being your friend, I can tell you it gets harder when you have a > > really big doc that has lots of tags throughout with hard-coded > > LINKEND to IDs full of s1-, s2-, s3- and so forth. > > XSLT will resolve all of them, forward and reverse if needed. > > The source of the problem as I see it is the dual use of id attributes. > Just because the stylesheets have an option of using sect1 id values > as file names, it doesn't mean we have to. I think the reasoning behind it is that when you are reading/editing a very large guide with many sections, it's easy in the HTML to tell what
you are in by referencing the HTML file name that came from the ID tag. I think this was more daunting to resolve using DSSSL, so a process work around was configured inside Red Hat. Since it is not so daunting, perhaps we should just eliminate the process and customize our XSL. Lot easier to maintain than getting dozens of writers to make accurate ID tags. :) > id values should simply be document unique points used for cross > reference. No more. As the schema says, they are optional. It is nice for xref. We could have ID tags for only sections that you wanted to xref? Again, the ID needs to be only meaningful enough for the author to figure out what it is, since, as you say, we can have XSL give meaningful file names separately from the ID tag. So ... where will the XSL get the information from for making meaningful file names on the opposite side? From the ? - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Sun Aug 15 17:44:48 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 15 Aug 2004 10:44:48 -0700 Subject: <section> vs <sect1>, ... [was: Re: usb-keys] In-Reply-To: <1092509775.4681.29.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092509775.4681.29.camel@homer> Message-ID: <1092591887.3459.4522.camel@erato.phig.org> On Sat, 2004-08-14 at 11:56, Dave Pawson wrote: > On Fri, 2004-08-13 at 19:13, Karsten Wade wrote: > > Since this is all FDL covered materials, we do our own licensing choice > > a service by making it easier to use our works in a truly free manner. > > > > I'd recommend a standard of: > > > > <section id="like-the-title"> > > <title>Like The Title: The Details > > > > The ID has meaning to the content. > > the (nominal) typo there immediately hints at a weakness in > doing this manually? I intentionally gave the ID a shorter version of the title. The way I wrote it was confusing, I should have written:
The Title That Is Longer > > > When moving chunks if
s > > around, you can know what something is easily. Want an idea what > > sections you have in what order? 'grep " > something meaningful that directly corresponds to your table of > > contents. > If the content is sufficient to warrant that then the complexity > will make it nominally difficult to re-use in alternate order? Not at all. Even a short
can benefit from this. Since not all of the are revealed in our table of contents (by choice), this is the best way to see every
.[1] While writing, I will move and combine sections all the time, especially on a larger work. The initial outline represents about 60% of what I expect to see in the final. This is just my style, but I'm not unique in this style. To me, outline == guideline. FWIW, without ID attributes, it's still possible to gain mainly the same meaning[2]: grep -A1 " > > > Any other thoughts on this? I'll hold off for a bit on filling out the > > bug report. :) > > I wouldn't mandate either. There will be occasions when nested depths > will be wanted. Can you give some examples? If are automatically nested, what value is there in having fixed ? Especially if the practice is deprecated? - Karsten [1] This is what grepping for " [2] Here's the same file, grepping for "Categorization Tutorial Overview Classes Categorization Scenarios Creating a new Category Deleting a Category Adding more Parent Categories Removing Parent Categories Retrieving all Subcategories of a given Category Retrieving all child objects of a given Category Notification Tutorial Creating a Simple Notification Creating a Simple Notification with an Attachment Creating an Hourly Digest Email Alerts Workflow Tutorial Simple Workflow Adding a Task to a Workflow Rolling Back a Task Completing a Task Versioning Tutorial Data-Object-Level Service Fully versioned types Recoverable types Versioning service API PDL Syntax Differences between &WAFX; 5.2 and 6.0 Search Tutorial Making a domain object searchable Core search metadata Supplementary search metadata Content provision Metadata provider registration Creating a search user interface Basic search form Displaying results Filtering results Note search component Providing a new Query engine Providing a new Search indexer -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Sun Aug 15 17:51:09 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 15 Aug 2004 10:51:09 -0700 Subject: Emacs/psgml problem In-Reply-To: <1092590926.9843.218.camel@bettie.internal.frields.org> References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> <1092588883.9843.184.camel@bettie.internal.frields.org> <1092590587.3459.4455.camel@erato.phig.org> <1092590926.9843.218.camel@bettie.internal.frields.org> Message-ID: <1092592269.3459.4541.camel@erato.phig.org> On Sun, 2004-08-15 at 10:28, Paul W. Frields wrote: > On Sun, 2004-08-15 at 13:23, Karsten Wade wrote: > > On Sun, 2004-08-15 at 09:54, Paul W. Frields wrote: > > > I've been using the same setup since I first started doing FDP stuff; I > > > added the code listed in the Doc Guide to my .emacs file, and haven't > > > changed it. rpm -V psgml looks fine. > > > > > > I think after having battled it for a little while that it's related to > > > doing this: > > > > > > instead of: > > > > > > > > > Exiting Emacs and restarting it seems to "fix" the problem. It only > > > happens using after tags. I'm confused but I'm not > > > sure how to Bugzilla the problem since it could be the Big OE (Operator > > > Error). > > > > I was first going to ask if you had a stuck Ctrl key on your keyboard. > > :) > > Out of genuine curiosity, would this have caused a problem like what I > observed? Not sure. An nXML keybinding is C-/ to close the previous open tag, iirc. That was why my first thought was, stuck keyboard? But yeah, in PSGML, it's different as Dave pointed out. > > > > Another thing you might try (being a self-professed newbie who seems to > > be doing quite well anyway) is Mark's PSGMLX package: > > http://dulug.duke.edu/~mark/psgmlx . It will validate against the XML > > DTD properly, afaict. Just don't find any bugs in it, Mark doesn't have > > any time to fix them. :) > > It's on my to-do list! Am I correct that you just indicated (in another > thread, sorry) that I can use all the same keybindings as in PSGML? If I > don't have to unlearn what I've only recently learned for psgml, I'm > more likely to try psgmlx. Yeah, it was on my list for too long, and it turned out to be stupidly easy to setup. :D Right, it's exactly like PSGML keybindings. I think Mark adds some stuff, but nothing is taken away, iirc. Still, like I alluded to, it's an extension of PSGML, so it may have different (i.e., buggy) behavior. Definitely worth a try, though. Examples of stuff added - when you are in a mode that is editing a script (Perl, bash, etc.) and you put your cursor is over any bracket {} [] (), the opening and closing brackets are highlighted. Right-click in SGML files pulls up an insert element menu that only lets you insert legal tags -- fast way of checking for what is valid, which may be part of troubleshooting. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From thave.thurai at rogers.com Sun Aug 15 18:09:27 2004 From: thave.thurai at rogers.com (thave thurai) Date: Sun, 15 Aug 2004 14:09:27 -0400 Subject: Fedroa2 hangs while probing aic 7896 References: <1092287259.2973.20.camel@albus.aeon.com.my><1092352056.4488.33859.camel@erato.phig.org> <1092529024.11376.703.camel@localhost.localdomain> Message-ID: <001901c482f3$018ba7d0$0300a8c0@home> Hi all AIC 7896 hangs while installing , used liunx acpi=force that works, but when reboots is hangs for a while then comes up. Any body having any idea why is this Thanks in advance Thave From paul at frields.com Sun Aug 15 18:11:56 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 15 Aug 2004 14:11:56 -0400 Subject: Fedroa2 hangs while probing aic 7896 (REDIRECT) In-Reply-To: <001901c482f3$018ba7d0$0300a8c0@home> References: <1092287259.2973.20.camel@albus.aeon.com.my> <1092352056.4488.33859.camel@erato.phig.org> <1092529024.11376.703.camel@localhost.localdomain> <001901c482f3$018ba7d0$0300a8c0@home> Message-ID: <1092593516.11066.1.camel@bettie.internal.frields.org> On Sun, 2004-08-15 at 14:09, thave thurai wrote: > AIC 7896 hangs while installing , used liunx acpi=force that works, but > when reboots is hangs for a while then comes up. Any body having any idea > why is this Hi Thave, You will probably want to post this to fedora-list instead of fedora-docs-list. The fedora-docs-list is for discussion of Fedora documentation. While we're at it though, could you be so kind as to tell us why you decided to post here? We are always interested in finding out how we can make it easier for people to find the right place to go for help. -- Paul W. Frields, RHCE From dataking at cox.net Sun Aug 15 18:28:54 2004 From: dataking at cox.net (D@7@k|N&) Date: Sun, 15 Aug 2004 11:28:54 -0700 Subject: status In-Reply-To: <1092589237.3459.4393.camel@erato.phig.org> Message-ID: -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Submitted bug 129957. Found it on the tracker bug (#129784). I have not started writing, but will attach documents as they are available. If you need anything, or if I need to do anything else, please let me know. Thanks. - -- - -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 - -----Original Message----- From: fedora-docs-list-bounces at redhat.com [mailto:fedora-docs-list-bounces at redhat.com] On Behalf Of Karsten Wade Sent: Sunday, August 15, 2004 10:01 AM To: dataking at cox.net; For participants of the docs project Subject: RE: status On Sat, 2004-08-14 at 13:46, D at 7@k|N& wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > Is there a document for system hardening? Not from the FDP for Fedora. > Is there interest for one? Definitely. I'll even volunteer to be your editor[1]. :) File a bug for your idea, and set it to block bug # 129784. You can put me on the Cc: for the bug, and, as Colin suggested, you can attach your draft files to the bug. - - Karsten [1] - this is because I have just a little bit of experience with hardening; if we have a security expert available, by all means that person should do technical editing. - -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 - -- fedora-docs-list mailing list fedora-docs-list at redhat.com To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list -----BEGIN PGP SIGNATURE----- Version: PGP 8.0 iQA/AwUBQR+rZabnQHwVWKJjEQKdUwCglMfnFMgGYZyt0E8qV/5+a8a2sikAoOjC LC+AS2E4vr6+ujGb64xhJYj3 =Budb -----END PGP SIGNATURE----- From mjohnson at redhat.com Sun Aug 15 19:11:20 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sun, 15 Aug 2004 15:11:20 -0400 Subject: Emacs/psgml problem In-Reply-To: <1092592269.3459.4541.camel@erato.phig.org> References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> <1092588883.9843.184.camel@bettie.internal.frields.org> <1092590587.3459.4455.camel@erato.phig.org> <1092590926.9843.218.camel@bettie.internal.frields.org> <1092592269.3459.4541.camel@erato.phig.org> Message-ID: <411FB558.9090203@redhat.com> Karsten Wade wrote: > On Sun, 2004-08-15 at 10:28, Paul W. Frields wrote: > >>On Sun, 2004-08-15 at 13:23, Karsten Wade wrote: >> >>>On Sun, 2004-08-15 at 09:54, Paul W. Frields wrote: >>> >>>>I've been using the same setup since I first started doing FDP stuff; I >>>>added the code listed in the Doc Guide to my .emacs file, and haven't >>>>changed it. rpm -V psgml looks fine. >>>> >>>>I think after having battled it for a little while that it's related to >>>>doing this: >>>> >>>>instead of: >>>> >>>> >>>>Exiting Emacs and restarting it seems to "fix" the problem. It only >>>>happens using after tags. I'm confused but I'm not >>>>sure how to Bugzilla the problem since it could be the Big OE (Operator >>>>Error). >>> >>>I was first going to ask if you had a stuck Ctrl key on your keyboard. >>>:) >> >>Out of genuine curiosity, would this have caused a problem like what I >>observed? > > > Not sure. An nXML keybinding is C-/ to close the previous open tag, > iirc. That was why my first thought was, stuck keyboard? But yeah, in > PSGML, it's different as Dave pointed out. > > >>>Another thing you might try (being a self-professed newbie who seems to >>>be doing quite well anyway) is Mark's PSGMLX package: >>>http://dulug.duke.edu/~mark/psgmlx . It will validate against the XML >>>DTD properly, afaict. Just don't find any bugs in it, Mark doesn't have >>>any time to fix them. :) >> >>It's on my to-do list! Am I correct that you just indicated (in another >>thread, sorry) that I can use all the same keybindings as in PSGML? If I >>don't have to unlearn what I've only recently learned for psgml, I'm >>more likely to try psgmlx. > > > Yeah, it was on my list for too long, and it turned out to be stupidly > easy to setup. :D > > Right, it's exactly like PSGML keybindings. I think Mark adds some > stuff, but nothing is taken away, iirc. Yeah, I did add a couple of keyboard macros:.e.g. - C-x C-p inserts and places the cursor in the middle. - Another one allows you to tag a marked region (start & end points matter) by hitting M-p (aka -p). - another one allows you to tag the marked region with tags with "C-x e" None of the above should affect the default psgml keybindings, they're simply add-ons. At any rate, they can be turned off by commenting them out in the following files in the psgmlx directory: [psgmlx-dir]/conf/psgml/macros-sgml.el [psgmlx-dir]/conf/psgml/macros-docbook.el FWIW, I got the material, or at least the ideas, from Bob DuCharme's "PSGML Tricks" page: http://www.snee.com/bob/sgmlfree/emcspsgm.html which has somewhat more advanced material than his *very* useful "Emacs/PSGML Quick Reference" page: http://www.snee.com/bob/sgmlfree/psgmqref.html Knowing some simple things like C-c C-q (sgml-fill-element) M-C-\ (indent-region) C-c [ENTER] (sgml-split element) C-c C-o (move to next trouble spot) C-c C-v (validate) Can really enhance your productivity. I highly recommend learning the stuff in the "Moving Your Cursor Around: PSGML Keystrokes" section. Really speeds things up. HTH, Mark > Still, like I alluded to, it's > an extension of PSGML, so it may have different (i.e., buggy) behavior. > Definitely worth a try, though. > > Examples of stuff added - when you are in a mode that is editing a > script (Perl, bash, etc.) and you put your cursor is over any bracket {} > [] (), the opening and closing brackets are highlighted. Right-click in > SGML files pulls up an insert element menu that only lets you insert > legal tags -- fast way of checking for what is valid, which may be part > of troubleshooting. > > - Karsten > -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Sun Aug 15 19:21:39 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sun, 15 Aug 2004 15:21:39 -0400 Subject: more defined process In-Reply-To: <1092583554.4925.21.camel@homer> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> <1092524260.11376.685.camel@localhost.localdomain> <411E9FFD.7010809@redhat.com> <411EA25E.60801@redhat.com> <1092583554.4925.21.camel@homer> Message-ID: <411FB7C3.8030306@redhat.com> Dave Pawson wrote: > On Sun, 2004-08-15 at 00:38, Mark Johnson wrote: > > Mark, I'd be more supportive of attribute based selection, > rather than conditional sections? Then filter based on stylesheet > parameters as Tammy suggested? Yep, me too. Putting true conditional sections in a DTD customization layer would be a major PITA, and would require us to change the DocBook FPI. Time to move to the XML method of attribute-based content selection. And, yes, the stylesheets are where all the filtering occurs. > Especially since the current DTD may well be the last for docbook? Yes, but the proposed RELAX-NG design would allow one to easily generate DTDs (even customized ones) from the customized RELAX-NG schema. One difficulty there, though, is that the generated DTD will not be customizable, i.e. it won't contain any paramter entities. > A move to relax NG would make any development work here redundant? Not sure I understand your question, Dave, but I suspect the answer is yes:) Cheers, Mark -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Sun Aug 15 19:26:35 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sun, 15 Aug 2004 15:26:35 -0400 Subject: more defined process In-Reply-To: <1092583762.4925.25.camel@homer> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> <411D5FE4.7050108@redhat.com> <1092497156.11376.673.camel@localhost.localdomain> <411E8676.7000204@redhat.com> <1092583762.4925.25.camel@homer> Message-ID: <411FB8EB.5080100@redhat.com> Dave Pawson wrote: > On Sat, 2004-08-14 at 22:39, Mark Johnson wrote: > > >>>What problem does it solve? >> >>Setting up emacsp/sgml, effectively, w/o having to do any setup. > > Except add to a 'standard' emacs+psgml setup? Well, yeah. If one has a bunch of psgml configurations, they do tend to pile up and often act funny as a result. > What of people who already are balancing ten different emacs 'standard' > configurations? Then they're not newbies and probably wouldn't benefit from adopting psgmlx. > Any conditional sections btw, doesn't matter if they are internal or > external schema, its still a docbook extension. Right, which would *require* us to use a modified FPI and a different system identifier, all of which would unnecessarily complicate things. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Sun Aug 15 19:40:01 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sun, 15 Aug 2004 15:40:01 -0400 Subject: editors In-Reply-To: <1092575720.5424.93.camel@albus.aeon.com.my> References: <1092333413.4488.33328.camel@erato.phig.org> <1092575720.5424.93.camel@albus.aeon.com.my> Message-ID: <411FBC11.4060605@redhat.com> Colin Charles wrote: >>* Editorial board could just form like Voltron right now from available >>interested parties (myself included there, please), and proceed with >>some process defining. > > > So there's you, there's Paul, Dave probably yes, Tammy is most likely a > definite, I wouldn't mind, who else? Speak up folk :P If you're short-handed, I can probably donate some cycles. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From kwade at redhat.com Sun Aug 15 23:50:54 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 15 Aug 2004 16:50:54 -0700 Subject: New tracker In-Reply-To: <1092529024.11376.703.camel@localhost.localdomain> References: <1092287259.2973.20.camel@albus.aeon.com.my> <1092352056.4488.33859.camel@erato.phig.org> <1092529024.11376.703.camel@localhost.localdomain> Message-ID: <1092613854.3459.5272.camel@erato.phig.org> On Sat, 2004-08-14 at 17:17, Tammy Fox wrote: > It seems like we have some duplication of effort here. Before I knew you > had started a process document in XML, I started > > http://fedora.redhat.com/participate/documentation-quick-start/ Yeah, sorry you missed that, it predated your work by a few days. Just represents accumulation of consensus + my own idea wackiness. > Seems like we should combine our efforts and decide whether to use XML > for this or just post it on the website. Since it isn't very long, I > started it as a straight webpage thinking it would be faster to update. > Which do you prefer? I do like your explanation here of the lifecycle of > a tutorial so I'll incorporate it into my page as soon as I get a chance > (within the next few days). We could even draw up a flow chart in Dia. > Like I said previously, my page needs organization. I was just trying to > get it up for everyone to see as soon as possible while everyone was > interested in discussing the idea. Well, it was plain text, but Dave converted it, so I thought we might as well use it now. I think it should end up in the Doc Guide as an chapter. I don't quite think of our two output as duplication, although our content might be. I think your Quick Intro... serves as something we can easily find on the Web, and it quickly distills the ideas that should be fleshed out in the part that I wrote (which is pretty fleshy). How about this? Fedora Doc Guide Doc Lifecycle Process Quick Introduction to Writing for Fedora Documentation Project Lifecycle Process The Quick Intro... is a distillation of the ideas covered in detail in the Lifecycle Process. We then link directly to the Quick Intro... from fedora.redhat.com/projects/docs _and_ from fedora.redhat.com/docs as "how to get involved with writing or editing Fedora documentation." The chapter Lifecycle Process is what project members must learn, follow, and improve via consensus. To get to that point, we need to be sure that the two accurately describe each other. I'll finish the process in XML, create a bug report for it, attach it, compare that against the work you did, attach a patch to that on the same bug, and start a fresh thread on the list about the whole thing. When that is done, you and the other editor-minded people can have at it again for a final consensus. Sound good? - Karsten, off to prep an old window for painting -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 16 11:55:00 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 04:55:00 -0700 Subject: editors In-Reply-To: <1092384557.2519.38.camel@homer> References: <1092333413.4488.33328.camel@erato.phig.org> <1092384557.2519.38.camel@homer> Message-ID: <1092657300.3459.6740.camel@erato.phig.org> On Fri, 2004-08-13 at 01:09, Dave Pawson wrote: > On Thu, 2004-08-12 at 18:56, Karsten Wade wrote: > > Here are some further ideas about the role of an editor: > > > * Should there be an editorial board? Such a board would oversee the > > Fedora docs, make sure we are adhering to our standards, filling in > > holes, following or advancing our process, etc. > Were there enough of us here I might agree. Beginning to sniff > bureaucracy? I was just writing up some more about the roles, and realized that this might be true, that it's a lot of silly bureaucracy right now. The idea was to just make proper the role that most of us are taking right now, doing the kind of work I figure the editorial board will be in charge of. At the moment we can do it ad-hoc on the list, but hopefully we will get too busy to handle that, and having a process in place around how discussions and decisions are handled will be a very good thing. As an analogy, in construction you might leave a hot and cold water pipe with a drain capped off in a utility closet, as stubs you can tie into later to turn into a laundry sink. Programmers do this with code stubs. Think of this as an editorial board stub, useful for when we need it. :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From redwire at therockmere.com Mon Aug 16 12:44:26 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Mon, 16 Aug 2004 08:44:26 -0400 (EDT) Subject: Release Point Message-ID: <29729.199.224.21.254.1092660266.squirrel@TheRockmere.com> The Mailing list sure has been active the last few days. I think it took almost an hour to get thru the digests. I have propagated the following URL for Fedora Documents:: www.FedoraDocs.com I have place a mission statement and an overview of what I hope to accomplish with this site. I am hoping to provide a release point for a large number of Fedora Documents. This may, or may not, be a new paradigm ~ But I was trying to visualize howto release a large # of docs, but not bog my server down with traffic for indiv. files. If you have any documentation that you wish to submit, please send it via email to :: deposit at fedoradocs.com. I will use it to create the first batch release. I am still working out, fielding suggestions, on whether to tarball, RPM or other such release details. Also, I don't want to infringe on the GNU, FDL licensure, but I need to annotate the files in some way to allow verisoning and details about the file to be noted in a TOC or some such thing. Any clarification on howto preserve this would be helpful. Ideas, submissions are requested and encouraged. Thanks, Brad From kwade at redhat.com Mon Aug 16 13:50:00 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 06:50:00 -0700 Subject: FDP docs process - round 2 Message-ID: <1092664199.3459.7055.camel@erato.phig.org> As detailed in https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129993. Please read and comment; main discussion on the list, I think, since this is a pretty important document for all of us to agree upon. [snarf_from_bz129993] This is the current version of the process document. It has been converted to XML for easy creation as a stand-alone process document or inclusion as a chapter in the Doc Guide. I went through Tammy's document at http://fedora.redhat.com//participate/documentation-quick-start/ with the file I wrote side-by-side, and tried to reconcile any differences. It will still need be read thoroughly make sure it represents what we want, i.e., our consensus. I will attach a plain, nochunks HTML output, as well as the XML, to this bug report, but for continuity sake it will also be available at: http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en.xml http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en.html http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process/index.html ## 30 -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Mon Aug 16 17:05:20 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 13:05:20 -0400 Subject: mirror-tutorial Message-ID: <1092675920.2244.86.camel@berlin.east.gov> I am working on a mirror-tutorial that walks an administrator through the process of setting up a mirror on the local network. It will also include preparation of repositories on the mirror for use with up2date, and how to configure clients to use the mirror for the most seamless user experience. I have set these mirrors up on request for a number of customers, for classrooms, small offices, development networks, and the like. They're also useful on home networks where the user has multiple Linux boxes on the inside. Level of interest? -- Paul W. Frields, RHCE From paul at frields.com Mon Aug 16 17:27:41 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 13:27:41 -0400 Subject: updfstab-tutorial: Status Message-ID: <1092677261.2244.109.camel@berlin.east.gov> I have a new, improved version of the updfstab-tutorial (soon to be renamed) available. If you visit you'll find instructions for grabbing the latest version of my docs from my subversion (SVN) server. Dave Pawson spent some valuable time giving me comments and input which (hopefully) is incorporated in the new version. N.B. that my SVN server is not intended as a repository for anyone's work except that which I'm doing myself, or on which I'm collaborating with others. I found myself doing work on these docs both at home and away, and got really tired of the revision control, updating the Web site with new tarballs, etc. I'm sure every developer is smart enough to solve the problem before it crops up, but since I'm not much of a developer this was my first foray into RCS/SCCS/CVS/SVN, et al. If someone has a problem with my instructions or getting the stuff, I hope you'll let me know so I can fix it. Currently it works for me at work and home. The anonymous access is, of course, read-only. I've been told that ViewCVS works with SVN now, but I haven't been able to make it work. The best I get is generation of a web page that basically just generates a directory listing of the Berkeley db files -- basically useless as a Web interface. And I think I broke that, in any case. But at least I still have both pieces. :-) Tech help will gladly be accepted off-list, since it will likely bore the subscribers to tears or violence. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Mon Aug 16 17:32:30 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 18:32:30 +0100 Subject: Emacs/psgml problem In-Reply-To: <1092588883.9843.184.camel@bettie.internal.frields.org> References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> <1092588883.9843.184.camel@bettie.internal.frields.org> Message-ID: <1092677549.2674.32.camel@homer> On Sun, 2004-08-15 at 17:54, Paul W. Frields wrote: > I've been using the same setup since I first started doing FDP stuff; I > added the code listed in the Doc Guide to my .emacs file, and haven't > changed it. rpm -V psgml looks fine. > > I think after having battled it for a little while that it's related to > doing this: > > instead of: > Which implies you are using sgml mode, not xml mode. Since the former s valid xml, not sgml. Look at the status line for xml-mode or sgml-mode M-x xml-mode might fix it. Alt-x xml-mode. HTH -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Mon Aug 16 17:35:47 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 18:35:47 +0100 Subject: Emacs/psgml problem In-Reply-To: <1092590587.3459.4455.camel@erato.phig.org> References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> <1092588883.9843.184.camel@bettie.internal.frields.org> <1092590587.3459.4455.camel@erato.phig.org> Message-ID: <1092677746.2674.35.camel@homer> On Sun, 2004-08-15 at 18:23, Karsten Wade wrote: > > FWIW, in SGML I have never had a problem with an unclosed . I've > always written it as just plain without a > . Of course, this is not legal in XML, so you have to include > it. You are probably using the old SGML processing chain then Karsten? Surely we don't want SGML docs around? James Clark's sx will convert, but having done a few megs of SGML to XML for xfree-86, I can say its a PITA. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Mon Aug 16 17:43:56 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 18:43:56 +0100 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092590939.3459.4473.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> <1092590939.3459.4473.camel@erato.phig.org> Message-ID: <1092678236.2674.43.camel@homer> On Sun, 2004-08-15 at 18:28, Karsten Wade wrote: > I think the reasoning behind it is that when you are reading/editing a > very large guide with many sections, it's easy in the HTML to tell what >
you are in by referencing the HTML file name that came from > the ID tag. I think this was more daunting to resolve using DSSSL, so a > process work around was configured inside Red Hat. Since it is not so > daunting, perhaps we should just eliminate the process and customize our > XSL. Lot easier to maintain than getting dozens of writers to make > accurate ID tags. :) I'll leave that to Tammy. > > > id values should simply be document unique points used for cross > > reference. No more. As the schema says, they are optional. > > It is nice for xref. Essential for cross referencing. > We could have ID tags for only sections that you > wanted to xref? That was the intent of the id attribute in XML, i.e. only add it on those elements which are targets. > Again, the ID needs to be only meaningful enough for > the author to figure out what it is, since, as you say, we can have XSL > give meaningful file names separately from the ID tag. Not even meaningful, just unique to the instance? The standard XSLT stylesheets have a configuration (split output) option to use id values as filenames. But that only applies at ... Tammy? is it sect1 elements? For any other id values, its arbitrary. > > So ... where will the XSL get the information from for making meaningful > file names on the opposite side? From the ? Dangerous. The title content, as well as having spaces, could have all sorts of Unicode in it. That would make for bad filenames. Depends on what is currently in use. http://www.sagehill.net/docbookxsl/Chunking.html#ChunkFilenames shows the options for xslt processing. Take your pick. I'd personally let the processor pick the filenames, but I don't attach much importance to them. YMMV :-) -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Mon Aug 16 17:48:34 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 18:48:34 +0100 Subject: <section> vs <sect1>, ... [was: Re: usb-keys] In-Reply-To: <1092591887.3459.4522.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092509775.4681.29.camel@homer> <1092591887.3459.4522.camel@erato.phig.org> Message-ID: <1092678514.2674.48.camel@homer> On Sun, 2004-08-15 at 18:44, Karsten Wade wrote: > > I wouldn't mandate either. There will be occasions when nested depths > > will be wanted. > > Can you give some examples? If <sections> are automatically nested, > what value is there in having fixed <sectn>? Especially if the practice > is deprecated? I'd be very surprised to see it deprecated. Where was the origin of this? I'd be happy to live with either way, but like the option of both. Certainly the standard docbook processing favours sect1... as I see it. It does perhaps beg the question why does fedora-docs start at article, when it can go all the way up to set. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Mon Aug 16 17:50:28 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 13:50:28 -0400 Subject: Elements of Style, redux Message-ID: <1092678627.2244.113.camel@berlin.east.gov> I don't have an original copy of the 1918 edition of Strunk's book. Does anyone on this list have one, which they might be able to use to scan the title and verso pages for me? My eos-guide is finished, and I've constructed a couple Makefile changes that allow me to build either the 1918 original or patch to build a (still forthcoming) FDP edition. I'd like to send the original sources for the 1918 edition to Project Gutenberg and they require the aforementioned scans. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Mon Aug 16 17:58:21 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 18:58:21 +0100 Subject: editors In-Reply-To: <1092657300.3459.6740.camel@erato.phig.org> References: <1092333413.4488.33328.camel@erato.phig.org> <1092384557.2519.38.camel@homer> <1092657300.3459.6740.camel@erato.phig.org> Message-ID: <1092679101.2674.56.camel@homer> On Mon, 2004-08-16 at 12:55, Karsten Wade wrote: > > Were there enough of us here I might agree. Beginning to sniff > > bureaucracy? > > I was just writing up some more about the roles, and realized that this > might be true, that it's a lot of silly bureaucracy right now. The idea > was to just make proper the role that most of us are taking right now, > doing the kind of work I figure the editorial board will be in charge > of. > > At the moment we can do it ad-hoc on the list, but hopefully we will get > too busy to handle that, and having a process in place around how > discussions and decisions are handled will be a very good thing. Now that would be a really nice position to be in Karsten. When it happens is the time to add the bureaucratic layers perhaps? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From mjohnson at redhat.com Mon Aug 16 18:03:03 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Mon, 16 Aug 2004 14:03:03 -0400 Subject: more defined process In-Reply-To: <1092441603.11376.642.camel@localhost.localdomain> References: <1092416559.11376.356.camel@localhost.localdomain> <1092427973.4488.35981.camel@erato.phig.org> <1092441603.11376.642.camel@localhost.localdomain> Message-ID: <4120F6D7.6020907@redhat.com> Tammy Fox wrote: >>>I am putting together a Quick Guide for this interested in learning how >>>to participate since I get emails daily asking. It also helps define the >>>life cycle of a tutorial. >> >>This is a good idea, a gap that needs filling. Mark Johnson is also >>starting work on something with a name like Quick Start Guide, but it >>has a different scope. The purpose is to get people who know the tools >>involved a way to get quickly started, a sort of distillation of the Doc >>Guide. >> >>Just bringing that up because the titles are similar, but the purposes >>are not, and there is room for both. Just not with the same title. :) >> > > > Mark, if you are on this list, can you add a Bugzilla entry for it and > link it to the tracker for docs in progress? That way, no one else will > start working on the same thing. Done. Mark -- ---------------------------------------------------------- Mark Johnson <mjohnson at redhat.com> Red Hat Documentation Group <http://www.redhat.com> Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From paul at frields.com Mon Aug 16 18:05:59 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 14:05:59 -0400 Subject: editors In-Reply-To: <1092679101.2674.56.camel@homer> References: <1092333413.4488.33328.camel@erato.phig.org> <1092384557.2519.38.camel@homer> <1092657300.3459.6740.camel@erato.phig.org> <1092679101.2674.56.camel@homer> Message-ID: <1092679559.2244.128.camel@berlin.east.gov> On Mon, 2004-08-16 at 13:58, Dave Pawson wrote: > > At the moment we can do it ad-hoc on the list, but hopefully we will get > > too busy to handle that, and having a process in place around how > > discussions and decisions are handled will be a very good thing. > > Now that would be a really nice position to be in Karsten. > When it happens is the time to add the bureaucratic layers perhaps? My boss would love to insert a lecture here about the 5 P's: old military jargon for "Prior Planning Prevents P!$$-poor Performance." Arguably a bit more critical when you're dealing with where exactly a 50mm shell is going to hit the ground at high velocity, but if a project's serious to you, then it's probably apt anyway. :-) (Oops, let's not tell my boss about my lag time on setting up SVN, OK?) -- Paul W. Frields, RHCE From davep at dpawson.co.uk Mon Aug 16 18:07:16 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 19:07:16 +0100 Subject: Fedora links Message-ID: <1092679636.2674.63.camel@homer> I dutifully put a 'bug' report on the fedora bugzilla thingy, but also wanted to announce that (over time) I'll be collating a list of links all related to Fedora based software. I probably will add a documentation section, since Mark was the first in there, but my primary aim is to link to alternatives until we have our own suite of documentation. E.g. If I can figure out how, whilst plowing through that buzilla form, I came across a pull-down menu which seemed to list the applications/tools in Fedora? Be nice to have such a list with links to the home pages, LDP pages etc. All contributions of the format: Link: two line comment about 'why I think its useful' Ideally only links to uri's which might be there in a few months time, but yes, I agree.... http://www.dpawson.co.uk/fedora/links-en.html shows it 'as is' today. I'll group it by subject over time and feed it to Tammy when it is less empty. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Mon Aug 16 18:08:32 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 19:08:32 +0100 Subject: Release Point In-Reply-To: <29729.199.224.21.254.1092660266.squirrel@TheRockmere.com> References: <29729.199.224.21.254.1092660266.squirrel@TheRockmere.com> Message-ID: <1092679710.2674.65.camel@homer> On Mon, 2004-08-16 at 13:44, redwire at therockmere.com wrote: > The Mailing list sure has been active the last few days. I think it took > almost an hour to get thru the digests. > > I have propagated the following URL for Fedora Documents:: www.FedoraDocs.com Is that a domain you've bought Brad, or a part of RH? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From mjohnson at redhat.com Mon Aug 16 18:17:48 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Mon, 16 Aug 2004 14:17:48 -0400 Subject: Fedora links In-Reply-To: <1092679636.2674.63.camel@homer> References: <1092679636.2674.63.camel@homer> Message-ID: <4120FA4C.4050708@redhat.com> Dave Pawson wrote: > I dutifully put a 'bug' report on the fedora bugzilla thingy, > but also wanted to announce that (over time) I'll be collating > a list of links all related to Fedora based software. > > I probably will add a documentation section, since Mark was the > first in there, Woo-Hoo! ;-) > [...] but my primary aim is to link to alternatives > until we have our own suite of documentation. -- ---------------------------------------------------------- Mark Johnson <mjohnson at redhat.com> Red Hat Documentation Group <http://www.redhat.com> Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From kwade at redhat.com Mon Aug 16 18:38:57 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 11:38:57 -0700 Subject: <section> vs <sect1>, ... [was: Re: usb-keys] In-Reply-To: <1092678514.2674.48.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092509775.4681.29.camel@homer> <1092591887.3459.4522.camel@erato.phig.org> <1092678514.2674.48.camel@homer> Message-ID: <1092681537.3459.7936.camel@erato.phig.org> On Mon, 2004-08-16 at 10:48, Dave Pawson wrote: > On Sun, 2004-08-15 at 18:44, Karsten Wade wrote: > > > > I wouldn't mandate either. There will be occasions when nested depths > > > will be wanted. > > > > Can you give some examples? If <sections> are automatically nested, > > what value is there in having fixed <sectn>? Especially if the practice > > is deprecated? > > I'd be very surprised to see it deprecated. Where was the origin of > this? Word of mouth, Mark Johnson mentioned it several times on this list. Since he is an active member of the DocBook steering committee, I figure he has some clue there. > I'd be happy to live with either way, but like the option of both. > Certainly the standard docbook processing favours sect1... as I see it. It's possible we could make it optional, but I still don't understand what the value is in fixed nesting values for <section> tags. I always understood it to have been a self-limitation to keep newbies from overly nesting. Can you give some examples of where it is useful? > It does perhaps beg the question why does fedora-docs start at article, > when it can go all the way up to set. If I understand your statement correctly, I think this has been answered a number of times. We are doing <article> sized docs because it's a bite that we can chew. Look at how well we've done so far, which is not really that well. If we had massive <book>s to create as part of <set>s, we'd be finishing the set for FC2 just about the time that FC5test2 was being released. Have patience, it is through these tiny steps that we will walk our first mile. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 16 18:39:55 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 11:39:55 -0700 Subject: <section> vs <sect1>, ... [was: Re: usb-keys] In-Reply-To: <1092678236.2674.43.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> <1092590939.3459.4473.camel@erato.phig.org> <1092678236.2674.43.camel@homer> Message-ID: <1092681595.3459.7942.camel@erato.phig.org> On Mon, 2004-08-16 at 10:43, Dave Pawson wrote: > On Sun, 2004-08-15 at 18:28, Karsten Wade wrote: > > So ... where will the XSL get the information from for making meaningful > > file names on the opposite side? From the <title>? > > Dangerous. > The title content, as well as having spaces, could have all sorts of > Unicode in it. That would make for bad filenames. > > Depends on what is currently in use. > > http://www.sagehill.net/docbookxsl/Chunking.html#ChunkFilenames shows > the options for xslt processing. > > Take your pick. > I'd personally let the processor pick the filenames, but I don't attach > much importance to them. YMMV :-) I don't attach much importance to them in a short <article> with a few <section>s, but it does help with a 200 page book to be able to tell from the HTML filename roughly where you are in which file. We're trying to create process that can support us in the future, when we have guides that size. In the SGML toolchain we use internally, all of the ID tags are used. <sect1> become the main filename, but every <section> has an <a name> that is the same as the ID (all in caps), e.g. s1-srv-ttr-help.sgml#S3-SRV-TTR-STANDING-STILL . I think that an ID that has contextual meaning to the associated content is useful. You don't care either way. So, it seems we have reached some consensus. :) Without a compelling reasons to have both <sect1...5> and <section> as FDP style, can we agree to use the more modular <section>? - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 16 18:45:57 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 11:45:57 -0700 Subject: Emacs/psgml problem In-Reply-To: <1092677746.2674.35.camel@homer> References: <1092585354.9843.110.camel@bettie.internal.frields.org> <1092586698.4925.44.camel@homer> <1092588883.9843.184.camel@bettie.internal.frields.org> <1092590587.3459.4455.camel@erato.phig.org> <1092677746.2674.35.camel@homer> Message-ID: <1092681956.3459.7966.camel@erato.phig.org> On Mon, 2004-08-16 at 10:35, Dave Pawson wrote: > On Sun, 2004-08-15 at 18:23, Karsten Wade wrote: > > > > > > FWIW, in SGML I have never had a problem with an unclosed <xref>. I've > > always written it as just plain <xref linkend="target"> without a > > </xref>. Of course, this is not legal in XML, so you have to include > > it. > > You are probably using the old SGML processing chain then Karsten? > Surely we don't want SGML docs around? $DAYJOB still uses SGML, whenever I refer to "my" or "our" SGML experience, it's from that. FWIW, this is part of the reason why companies like Red Hat Enterprise Linux over Fedora or any other fast moving project. By the time we reached the go/no-go decision on using XML for the next release of RHEL, the toolchain wasn't mature enough. Regardless of what happens after that decision moment, we're stuck with what we have until we put the fancy wrappings on the next release. Another reason I hang out here, it keeps me from going crazy stuck in SGML-land. :) > James Clark's sx will convert, but having done a few megs of SGML to XML > for xfree-86, I can say its a PITA. Ouch. Ouch. I'm sorry to hear you say that. I was hoping that it was going to be as easy as changing the DOCTYPE header. We try to be XML compliant with our SGML ... we'll see how it goes in the future. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 16 18:49:03 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 11:49:03 -0700 Subject: mirror-tutorial In-Reply-To: <1092675920.2244.86.camel@berlin.east.gov> References: <1092675920.2244.86.camel@berlin.east.gov> Message-ID: <1092682143.3459.7980.camel@erato.phig.org> On Mon, 2004-08-16 at 10:05, Paul W. Frields wrote: > I am working on a mirror-tutorial that walks an administrator through > the process of setting up a mirror on the local network. It will also > include preparation of repositories on the mirror for use with up2date, > and how to configure clients to use the mirror for the most seamless > user experience. > > I have set these mirrors up on request for a number of customers, for > classrooms, small offices, development networks, and the like. They're > also useful on home networks where the user has multiple Linux boxes on > the inside. > > Level of interest? Very. I have a yum repository that mirrors all the the Fedora versions I have installed, and I can do a local HTTP based install so much faster than via CD (I don't use NFS locally). It's fantastic. I had a few pieces I was going to write up to contribute to FedoraNEWS.org about how to use ISOs as the source for the mirrored base. This lets you save disk space, and I'm sure I'm not the first person to figure it out, but I've never seen exactly how to do it. Is this something you do? I'd be happy to contribute the pieces to both the FDP and FedoraNEWS.org. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Mon Aug 16 18:54:31 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 16 Aug 2004 19:54:31 +0100 Subject: <section> vs <sect1>, ... [was: Re: usb-keys] In-Reply-To: <1092681595.3459.7942.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> <1092590939.3459.4473.camel@erato.phig.org> <1092678236.2674.43.camel@homer> <1092681595.3459.7942.camel@erato.phig.org> Message-ID: <1092682471.4231.4.camel@homer> On Mon, 2004-08-16 at 19:39, Karsten Wade wrote: > I don't attach much importance to them in a short <article> with a few > <section>s, but it does help with a 200 page book to be able to tell > from the HTML filename roughly where you are in which file. If its sizable then you shouldn't need to rely on filenames? The structure of presented content should enable that, through toc's, headers and footers etc. See any standard docbook presented as a series of html files for examples. > > In the SGML toolchain we use internally, all of the ID tags are used. > <sect1> become the main filename, but every <section> has an <a name> > that is the same as the ID (all in caps), e.g. > s1-srv-ttr-help.sgml#S3-SRV-TTR-STANDING-STILL . Even if unused? > Without a compelling reasons to have both <sect1...5> and <section> as > FDP style, can we agree to use the more modular <section>? Infinitely recursive, not more modular. If you need to nest to more than 4 then the document outline needs a review IMHO. Give me a reason to change, or persuade Tammy to change the guidelines. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From hoyt at cavtel.net Mon Aug 16 18:58:49 2004 From: hoyt at cavtel.net (Hoyt) Date: Mon, 16 Aug 2004 14:58:49 -0400 Subject: mirror-tutorial In-Reply-To: <1092682143.3459.7980.camel@erato.phig.org> References: <1092675920.2244.86.camel@berlin.east.gov> <1092682143.3459.7980.camel@erato.phig.org> Message-ID: <200408161458.49039.hoyt@cavtel.net> On Monday 16 August 2004 02:49 pm, Karsten Wade wrote: > I had a few pieces I was going to write up to contribute to > FedoraNEWS.org about how to use ISOs as the source for the mirrored > base. ?This lets you save disk space, and I'm sure I'm not the first > person to figure it out, but I've never seen exactly how to do it. ?Is > this something you do? ?I'd be happy to contribute the pieces to both > the FDP and FedoraNEWS.org. I think it's better to use the DVD ISO images. (Use Chris Kloiber' mkdvdiso.sh script on CD-ROM images.) Simply mount them using the loopback option. When satisfied, put all the entries in fstab. If you want to mount selected directories in different places to conform to the ftp file directory structure, use the mount --bind olddir newdir form of the mount command. -- Hoyt A: Top Posting Q: What's one of the most annoying email practices? From kwade at redhat.com Mon Aug 16 19:29:13 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 12:29:13 -0700 Subject: mirror-tutorial In-Reply-To: <200408161458.49039.hoyt@cavtel.net> References: <1092675920.2244.86.camel@berlin.east.gov> <1092682143.3459.7980.camel@erato.phig.org> <200408161458.49039.hoyt@cavtel.net> Message-ID: <1092684553.3459.8119.camel@erato.phig.org> On Mon, 2004-08-16 at 11:58, Hoyt wrote: > On Monday 16 August 2004 02:49 pm, Karsten Wade wrote: > > I had a few pieces I was going to write up to contribute to > > FedoraNEWS.org about how to use ISOs as the source for the mirrored > > base. This lets you save disk space, and I'm sure I'm not the first > > person to figure it out, but I've never seen exactly how to do it. Is > > this something you do? I'd be happy to contribute the pieces to both > > the FDP and FedoraNEWS.org. > > I think it's better to use the DVD ISO images. (Use Chris Kloiber' mkdvdiso.sh > script on CD-ROM images.) I've never downloaded one, since I only have a CD burner and am conservative with my disk usage. It looks as if the DVD is both the RPMS and SRPMS? > Simply mount them using the loopback option. When satisfied, put all the > entries in fstab. Right, much easier than my method, which involves an additional layer -- mounting them to /foo/disc{1,2,3,4} and making symlinks to the packages into one monolithic folder, where some of the folders are real and some are symlinks. > If you want to mount selected directories in different places to conform to > the ftp file directory structure, use the mount --bind olddir newdir form of > the mount command. Since I like to be able to burn CDs for various reasons, I probably won't download the DVD until I have more disk space. In terms of the tutorial, I'd recommend covering both methods, for the same reason -- bandwidth and disk space issues. Some people will create their initial mirror set from a CDs they get in the postal mail, because their connection is too slow or costly to download 4+ gigs. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From redwire at therockmere.com Mon Aug 16 19:04:26 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Mon, 16 Aug 2004 15:04:26 -0400 (EDT) Subject: fedora-docs-list Digest, Vol 6, Issue 20 In-Reply-To: <20040816185341.C1BDC73383@hormel.redhat.com> References: <20040816185341.C1BDC73383@hormel.redhat.com> Message-ID: <36079.199.224.21.254.1092683066.squirrel@TheRockmere.com> > On Mon, 2004-08-16 at 13:44, redwire at therockmere.com wrote: >> The Mailing list sure has been active the last few days. I think it took >> almost an hour to get thru the digests. >> >> I have propagated the following URL for Fedora Documents:: >> www.FedoraDocs.com > > Is that a domain you've bought Brad, or a part of RH? > > -- > Regards DaveP. > XSLT&Docbook FAQ > http://www.dpawson.co.uk/xsl > > Dave; I have purchased the site myself. I am not associated with Red Hat on a professional level. I was looking for a name that would be discriptive. From paul at frields.com Mon Aug 16 20:05:56 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 16:05:56 -0400 Subject: mirror-tutorial In-Reply-To: <1092682143.3459.7980.camel@erato.phig.org> References: <1092675920.2244.86.camel@berlin.east.gov> <1092682143.3459.7980.camel@erato.phig.org> Message-ID: <1092686756.4624.32.camel@berlin.east.gov> On Mon, 2004-08-16 at 14:49, Karsten Wade wrote: > > Level of interest? > > Very. I have a yum repository that mirrors all the the Fedora versions > I have installed, and I can do a local HTTP based install so much faster > than via CD (I don't use NFS locally). It's fantastic. > > I had a few pieces I was going to write up to contribute to > FedoraNEWS.org about how to use ISOs as the source for the mirrored > base. This lets you save disk space, and I'm sure I'm not the first > person to figure it out, but I've never seen exactly how to do it. Is > this something you do? I'd be happy to contribute the pieces to both > the FDP and FedoraNEWS.org. I've done it both ways. In some cases I've simply had to have both ISO's and an exploded tree, because the customer wanted to be able to roll a customized distribution complete with CD's, but still have access to the "pristine" distro. Perhaps we could collaborate on this when you have time? I will try to get a better outline together than the one which I would have used just for myself. :-) -- Paul W. Frields, RHCE From paul at frields.com Mon Aug 16 20:08:43 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 16:08:43 -0400 Subject: mirror-tutorial In-Reply-To: <1092684553.3459.8119.camel@erato.phig.org> References: <1092675920.2244.86.camel@berlin.east.gov> <1092682143.3459.7980.camel@erato.phig.org> <200408161458.49039.hoyt@cavtel.net> <1092684553.3459.8119.camel@erato.phig.org> Message-ID: <1092686923.4624.39.camel@berlin.east.gov> On Mon, 2004-08-16 at 15:29, Karsten Wade wrote: [...snip...] > In terms of the tutorial, I'd recommend covering both methods, for the > same reason -- bandwidth and disk space issues. Some people will create > their initial mirror set from a CDs they get in the postal mail, because > their connection is too slow or costly to download 4+ gigs. Yup, I tried to start by mapping out possibilities/permutations and then figure out the tutorial layout by thinking about flow for each possibility. -- Paul W. Frields, RHCE From paul at frields.com Mon Aug 16 20:10:02 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 16:10:02 -0400 Subject: <section> vs <sect1>, ... [was: Re: usb-keys] In-Reply-To: <1092682471.4231.4.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> <1092590939.3459.4473.camel@erato.phig.org> <1092678236.2674.43.camel@homer> <1092681595.3459.7942.camel@erato.phig.org> <1092682471.4231.4.camel@homer> Message-ID: <1092687002.4624.42.camel@berlin.east.gov> On Mon, 2004-08-16 at 14:54, Dave Pawson wrote: > On Mon, 2004-08-16 at 19:39, Karsten Wade wrote: > > > I don't attach much importance to them in a short <article> with a few > > <section>s, but it does help with a 200 page book to be able to tell > > from the HTML filename roughly where you are in which file. > > If its sizable then you shouldn't need to rely on filenames? > The structure of presented content should enable that, through > toc's, headers and footers etc. > See any standard docbook presented as a series of html files > for examples. "Be able to tell" != "rely on"... If I open a directory full of chunked HTML in a browser, and see files marked "node0592.html" or some such, that's just not as helpful as "sn-srv-ttr-help.html". This happens frequently when using manuals installed in /usr/share/doc. Yes, I can always open "index.html" and navigate there, but why make me (the user) take those steps? Didn't you mention something to me about the system being user friendly and not the other way around? ;-) We don't yet know how these docs will make it onto an installed FC system, so let's not discount the possibility. > > In the SGML toolchain we use internally, all of the ID tags are used. > > <sect1> become the main filename, but every <section> has an <a name> > > that is the same as the ID (all in caps), e.g. > > s1-srv-ttr-help.sgml#S3-SRV-TTR-STANDING-STILL . > Even if unused? Moment of clarity needed. I went back and re-read this thread because I couldn't remember what was being argued here. Let me see if I can summarize this right. Originally the topic was whether to use <sectN> vs. <section>. Everybody agrees that's easy to change in existing documents. It looks to me, a relatively non-stupid individual (relative to whom? *shrugs*), that e.g. promoting <sect2> to <sect1> is: - considerably more difficult if all the "id" attributes include "s2-..." due to <xref>s and such. - not much more difficult if the "id" attributes don't include "s2-..." However, since "id" tags are used in the current XSLT's to set filenames for HTML transforms, include graphics, and so forth, they do have some use if we keep the current XSLT's. I assume that if we change to using <section id="configuring-foobar"> instead of <sect1 id="s1-configuring-foobar">, the XSLT can be set to recognize the section as a new HTML chunk file only if <section> is at level 1, right? If that's the case, I have yet to see a convincing argument why we shouldn't use <section id="configuring-foobar">. I still think having an id for every element currently listed in the naming conventions is a good idea. I see a good bit of value in: grep "id=" doc-source.xml Not quite as much as "grep 'section'", but quite a bit. -- Paul W. Frields, RHCE From tfox at redhat.com Mon Aug 16 20:19:43 2004 From: tfox at redhat.com (Tammy Fox) Date: Mon, 16 Aug 2004 16:19:43 -0400 Subject: Release Point In-Reply-To: <29729.199.224.21.254.1092660266.squirrel@TheRockmere.com> References: <29729.199.224.21.254.1092660266.squirrel@TheRockmere.com> Message-ID: <1092687583.2709.41.camel@localhost.localdomain> On Mon, 2004-08-16 at 08:44, redwire at therockmere.com wrote: > The Mailing list sure has been active the last few days. I think it took > almost an hour to get thru the digests. > > I have propagated the following URL for Fedora Documents:: www.FedoraDocs.com > > I have place a mission statement and an overview of what I hope to > accomplish with this site. > I am hoping to provide a release point for a large number of Fedora > Documents. This may, or may not, be a new paradigm ~ But I was trying to > visualize howto release a large # of docs, but not bog my server down with > traffic for indiv. files. > > If you have any documentation that you wish to submit, please send it via > email to :: deposit at fedoradocs.com. > I will use it to create the first batch release. I am still working out, > fielding suggestions, on whether to tarball, RPM or other such release > details. > Also, I don't want to infringe on the GNU, FDL licensure, but I need to > annotate the files in some way to allow verisoning and details about the > file to be noted in a TOC or some such thing. Any clarification on howto > preserve this would be helpful. > > Ideas, submissions are requested and encouraged. > > Thanks, > Brad Brad, I would like to encourage you to add your documents to the Fedora Documentation Project and have them hosted on the official Fedora website instead of creating yet another unofficial domain for Fedora. The point of this list is to join efforts to create documentation for Fedora as part of the official project so that when users go to http://fedora.redhat.com/ they can find all the documentation they need to successfully use it. Thanks, Tammy From tfox at redhat.com Mon Aug 16 20:35:08 2004 From: tfox at redhat.com (Tammy Fox) Date: Mon, 16 Aug 2004 16:35:08 -0400 Subject: New tracker In-Reply-To: <1092613854.3459.5272.camel@erato.phig.org> References: <1092287259.2973.20.camel@albus.aeon.com.my> <1092352056.4488.33859.camel@erato.phig.org> <1092529024.11376.703.camel@localhost.localdomain> <1092613854.3459.5272.camel@erato.phig.org> Message-ID: <1092688508.2709.43.camel@localhost.localdomain> On Sun, 2004-08-15 at 19:50, Karsten Wade wrote: > On Sat, 2004-08-14 at 17:17, Tammy Fox wrote: > > > It seems like we have some duplication of effort here. Before I knew you > > had started a process document in XML, I started > > > > http://fedora.redhat.com/participate/documentation-quick-start/ > > Yeah, sorry you missed that, it predated your work by a few days. Just > represents accumulation of consensus + my own idea wackiness. > > > Seems like we should combine our efforts and decide whether to use XML > > for this or just post it on the website. Since it isn't very long, I > > started it as a straight webpage thinking it would be faster to update. > > Which do you prefer? I do like your explanation here of the lifecycle of > > a tutorial so I'll incorporate it into my page as soon as I get a chance > > (within the next few days). We could even draw up a flow chart in Dia. > > Like I said previously, my page needs organization. I was just trying to > > get it up for everyone to see as soon as possible while everyone was > > interested in discussing the idea. > > Well, it was plain text, but Dave converted it, so I thought we might as > well use it now. I think it should end up in the Doc Guide as an > chapter. > > I don't quite think of our two output as duplication, although our > content might be. I think your Quick Intro... serves as something we > can easily find on the Web, and it quickly distills the ideas that > should be fleshed out in the part that I wrote (which is pretty fleshy). > > How about this? > > Fedora Doc Guide > Doc Lifecycle Process > Quick Introduction to Writing for Fedora Documentation Project > Lifecycle Process > > The Quick Intro... is a distillation of the ideas covered in detail in > the Lifecycle Process. We then link directly to the Quick Intro... from > fedora.redhat.com/projects/docs _and_ from fedora.redhat.com/docs as > "how to get involved with writing or editing Fedora documentation." > > The chapter Lifecycle Process is what project members must learn, > follow, and improve via consensus. > > To get to that point, we need to be sure that the two accurately > describe each other. I'll finish the process in XML, create a bug > report for it, attach it, compare that against the work you did, attach > a patch to that on the same bug, and start a fresh thread on the list > about the whole thing. > > When that is done, you and the other editor-minded people can have at it > again for a final consensus. Sound good? > The webpage I started is a quick version to get you started, and the one you are working on to be included in the Docs Guide is the detailed version. Sure, sounds good. Tammy > - Karsten, off to prep an old window for painting > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From tfox at redhat.com Mon Aug 16 20:39:58 2004 From: tfox at redhat.com (Tammy Fox) Date: Mon, 16 Aug 2004 16:39:58 -0400 Subject: editors In-Reply-To: <1092575720.5424.93.camel@albus.aeon.com.my> References: <1092333413.4488.33328.camel@erato.phig.org> <1092575720.5424.93.camel@albus.aeon.com.my> Message-ID: <1092688798.2709.47.camel@localhost.localdomain> On Sun, 2004-08-15 at 09:15, Colin Charles wrote: > On Fri, 2004-08-13 at 03:56, Karsten Wade wrote: > > (In re-response, since earlier I mentioned the editor list, and now I've > re-read the post :P) > > > * Should there be an editorial board? Such a board would oversee the > > Fedora docs, make sure we are adhering to our standards, filling in > > holes, following or advancing our process, etc. > > Probably a good idea > > > * Separate mailing list for editors? Or just accept that > > fedora-docs-list gets busier with traffic between editors and authors. > > No, one list. Mailing list, Bugzilla, and that's enough traffic - let's > not have another list > > > * Also, much of the editing traffic can be in bugzilla, as each document > > will have it's own bug throughout it's lifecycle. > > Yup, this is the way. Might I also discourage hosting documents on > external sites? Using Bugzilla's "attach file" will work > > > * The board needs to have an odd number of people so that if consensus > > can't be reached, a majority vote without a tie is possible. > > Good idea :P Or we can just set Tammy or you as the tie-breaker... > > > * Editorial board could just form like Voltron right now from available > > interested parties (myself included there, please), and proceed with > > some process defining. > > So there's you, there's Paul, Dave probably yes, Tammy is most likely a > definite, I wouldn't mind, who else? Speak up folk :P > -- Having non-Red Hat editors is fine and highly encouraged. Just keep in mind that someone from Red Hat must have final say as to what goes up on the website just to make sure it fits into the scope of the Fedora Project and to verify that it is sound from a legal point of view. Tammy > Colin Charles, byte at aeon.com.my > http://www.bytebot.net/ > "First they ignore you, then they laugh at you, then they fight you, > then you win." -- Mohandas Gandhi From mjohnson at redhat.com Mon Aug 16 20:52:51 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Mon, 16 Aug 2004 16:52:51 -0400 Subject: <section> vs <sect1>, ... [was: Re: usb-keys] In-Reply-To: <1092681537.3459.7936.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092509775.4681.29.camel@homer> <1092591887.3459.4522.camel@erato.phig.org> <1092678514.2674.48.camel@homer> <1092681537.3459.7936.camel@erato.phig.org> Message-ID: <41211EA3.20003@redhat.com> Karsten Wade wrote: >>> >>> [...] Especially if the practice >>>is deprecated? >> >>I'd be very surprised to see it deprecated. Where was the origin of >>this? > > > Word of mouth, Mark Johnson mentioned it several times on this list. > Since he is an active member of the DocBook steering committee, I figure > he has some clue there. I recall a "DocBook Best Practices" tutorial at OSCON (2001??), presented by members of the DocBook Technical Committee, where the use of <section> over <sect1> was recommended. I also recall some posts to the docbook (or docbook-apps) list on this same question, and the general consensus was that <section> is the preferred element. I also recall asking during a DocBook TC telcon whether <sect1>, ... <sect5> where going to disappear in DocBook V5, and Norm responded with something to the effect that he honestly didn't know, and that the decision may eventually lie in the hands of the user community. (To the best of my recollection.) Having said that, let me remind you that the policy for changes in major revision numbers in DocBook is to allow for backwards incompatibilities, but does certainly not require them. So there is no clear answer. OTOH, just out of curiousity, I downloaded the DocBook source XML for the latest working draft of the OASIS XML Catalogs Specification [1], which Norm Walsh edits/authors and noted that (1) he uses <section>s, and (2) that his ID attributes are more semantically derived, than structurally derived (though notice the "s." prefixes). Some examples: <section id="s.ext.ent"><title>External Identifier Entries
The <sgmltag class="attribute">prefer</sgmltag> attribute
Using Catalogs
URI Entries
Rewrite Entries I think his example is a nice compromise. If someone's source XML has nested
s that are truly difficult to unravel, then that author needs to reconsider his/her document structure. My $0.02, Mark [1] http://www.oasis-open.org/committees/download.php/4952/wd-entity-xml-catalogs-1.0_2e.xml > > >>I'd be happy to live with either way, but like the option of both. >>Certainly the standard docbook processing favours sect1... as I see it. > > > It's possible we could make it optional, but I still don't understand > what the value is in fixed nesting values for
tags. I always > understood it to have been a self-limitation to keep newbies from overly > nesting. > > Can you give some examples of where it is useful? > > >>It does perhaps beg the question why does fedora-docs start at article, >>when it can go all the way up to set. > > > If I understand your statement correctly, I think this has been answered > a number of times. We are doing
sized docs because it's a > bite that we can chew. Look at how well we've done so far, which is not > really that well. If we had massive s to create as part of > s, we'd be finishing the set for FC2 just about the time that > FC5test2 was being released. > > Have patience, it is through these tiny steps that we will walk our > first mile. > > - Karsten -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From kwade at redhat.com Mon Aug 16 21:05:41 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 14:05:41 -0700 Subject: editors In-Reply-To: <1092575720.5424.93.camel@albus.aeon.com.my> References: <1092333413.4488.33328.camel@erato.phig.org> <1092575720.5424.93.camel@albus.aeon.com.my> Message-ID: <1092690341.3459.8409.camel@erato.phig.org> On Sun, 2004-08-15 at 06:15, Colin Charles wrote: > On Fri, 2004-08-13 at 03:56, Karsten Wade wrote: > > * Also, much of the editing traffic can be in bugzilla, as each document > > will have it's own bug throughout it's lifecycle. > > Yup, this is the way. Might I also discourage hosting documents on > external sites? Using Bugzilla's "attach file" will work I just reached that part in the process ... I'm sort of torn here. I see the obvious value in not having random DRAFT copies in the wild. At the same time, it is quite onerous to update bugzilla each time you fix a typo in your file. Hosting on a personal site keeps down excessive attachments to bugzilla and the list. There is also a psychological boost while writing to see your work take shape with each consecutive build. How about a big CAUTION that you don't want personal hosting to become a de facto location for the document, so don't advertise it, and make certain to post point released and other significant updates to the bugzilla in preference to any hosting? Reduce it from a recommended practice to a cautioned practice, in other words. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 16 21:12:00 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 14:12:00 -0700 Subject: mirror-tutorial In-Reply-To: <1092686923.4624.39.camel@berlin.east.gov> References: <1092675920.2244.86.camel@berlin.east.gov> <1092682143.3459.7980.camel@erato.phig.org> <200408161458.49039.hoyt@cavtel.net> <1092684553.3459.8119.camel@erato.phig.org> <1092686923.4624.39.camel@berlin.east.gov> Message-ID: <1092690720.3459.8429.camel@erato.phig.org> On Mon, 2004-08-16 at 13:08, Paul W. Frields wrote: > On Mon, 2004-08-16 at 15:29, Karsten Wade wrote: > [...snip...] > > In terms of the tutorial, I'd recommend covering both methods, for the > > same reason -- bandwidth and disk space issues. Some people will create > > their initial mirror set from a CDs they get in the postal mail, because > > their connection is too slow or costly to download 4+ gigs. > > Yup, I tried to start by mapping out possibilities/permutations and then > figure out the tutorial layout by thinking about flow for each > possibility. Just to get this link into the archives, perhaps throw it into the bugzilla when it's generated: http://www.fedoranews.org/alex/tutorial/yum/ The script included in that tutorial does a nice job of getting updated packages from the mirror I point it at, set at my time interval. I don't know how CC and FDL licensed documents mix. It'd be a shame to have to redo the implementation. Has anyone encountered this yet? It's covered by the Attribution-NonCommercial-ShareAlike 1.0 (http://creativecommons.org/licenses/by-nc-sa/1.0/). - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Mon Aug 16 21:15:39 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 17:15:39 -0400 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092687002.4624.42.camel@berlin.east.gov> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> <1092590939.3459.4473.camel@erato.phig.org> <1092678236.2674.43.camel@homer> <1092681595.3459.7942.camel@erato.phig.org> <1092682471.4231.4.camel@homer> <1092687002.4624.42.camel@berlin.east.gov> Message-ID: <1092690939.15287.5.camel@bettie.internal.frields.org> Let me restate a couple things, I was in a hurry to leave work... On Mon, 2004-08-16 at 16:10, Paul W. Frields wrote: > Moment of clarity needed. I went back and re-read this thread because I > couldn't remember what was being argued here. Let me see if I can > summarize this right. > > Originally the topic was whether to use vs.
. Everybody > agrees that's easy to change in existing documents. It looks to me, a > relatively non-stupid individual (relative to whom? *shrugs*), that e.g. > promoting to is: > > - considerably more difficult if all the "id" attributes include > "s2-..." due to s and such. > - not much more difficult if the "id" attributes don't include "s2-..." And if we use
then it's somewhere in the middle, maybe closer to the latter, since the
might someday want to be a , right? > However, since "id" tags are used in the current XSLT's to set filenames > for HTML transforms, include graphics, and so forth, they do have some > use if we keep the current XSLT's. That should be "'id' attributes," of course, sorry. And, some would argue, they're less useful if we saddle them with information about the tag they're attributing, like
, since if the
becomes a you have to go around changing all the instances. Not much more than irksome, but maybe unnecessary. > I assume that if we change to using
> instead of , the XSLT can be set to > recognize the section as a new HTML chunk file only if
is at > level 1, right? If that's the case, I have yet to see a convincing > argument why we shouldn't use
. That should read better this way: I assume that if we change to using
instead of , the XSLT can be set to *only* recognize a level 1 section as the place to break a new HTML chunk file, right?.... > I still think having an id for every element currently listed in the > naming conventions is a good idea. I see a good bit of value in: > grep "id=" doc-source.xml > Not quite as much as "grep 'section'", but quite a bit. -- Paul W. Frields, RHCE From kwade at redhat.com Mon Aug 16 21:40:36 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 14:40:36 -0700 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092682471.4231.4.camel@homer> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> <1092590939.3459.4473.camel@erato.phig.org> <1092678236.2674.43.camel@homer> <1092681595.3459.7942.camel@erato.phig.org> <1092682471.4231.4.camel@homer> Message-ID: <1092692436.3459.8494.camel@erato.phig.org> On Mon, 2004-08-16 at 11:54, Dave Pawson wrote: > On Mon, 2004-08-16 at 19:39, Karsten Wade wrote: > > > I don't attach much importance to them in a short
with a few > >
s, but it does help with a 200 page book to be able to tell > > from the HTML filename roughly where you are in which file. > > If its sizable then you shouldn't need to rely on filenames? > The structure of presented content should enable that, through > toc's, headers and footers etc. > See any standard docbook presented as a series of html files > for examples. I've never seen HTML output that made sense to me from DocBook, unless the ID tags were used. The link you posted, http://www.sagehill.net/docbookxsl/Chunking.html#ChunkFilenames, didn't have any solution that I saw that gave HTML files with meaning, with the exception of bk01ch02s01.html. However, that gives you something which corresponds to the ToC rather than giving you contextual information (what is the meaning in this file) or location information (what the current practice of "s1-foo-bar" gives you.) > > > > > In the SGML toolchain we use internally, all of the ID tags are used. > > become the main filename, but every
has an > > that is the same as the ID (all in caps), e.g. > > s1-srv-ttr-help.sgml#S3-SRV-TTR-STANDING-STILL . > Even if unused? > > > Without a compelling reasons to have both and
as > > FDP style, can we agree to use the more modular
? > Infinitely recursive, not more modular. > If you need to nest to more than 4 then the document outline needs a > review IMHO. > Give me a reason to change, or persuade Tammy to change the guidelines. Agreed about nesting, I don't even like to see four levels nested, that cries out to me for a or somesuch. As for modular .. modular adj : constructed with standardized units or dimensions allowing flexibility and variety in use; "modular furniture"; "modular homes" What I'm saying is that moving
s with context-only ID tags is a no-brainer, you just move them. Moving s with context-only IDs is just grunt work. As soon as you start to get up to IDs with location information (sn), you are changing s all over the document, fixing the strings in the id="", changing the -> , and so forth. And, yes,
is also infinitely recursive, but that has nothing to do with why I recommend we use it. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Mon Aug 16 21:45:49 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 17:45:49 -0400 Subject: mirror-tutorial In-Reply-To: <1092690720.3459.8429.camel@erato.phig.org> References: <1092675920.2244.86.camel@berlin.east.gov> <1092682143.3459.7980.camel@erato.phig.org> <200408161458.49039.hoyt@cavtel.net> <1092684553.3459.8119.camel@erato.phig.org> <1092686923.4624.39.camel@berlin.east.gov> <1092690720.3459.8429.camel@erato.phig.org> Message-ID: <1092692749.15287.34.camel@bettie.internal.frields.org> On Mon, 2004-08-16 at 17:12, Karsten Wade wrote: > > [...snip...] > > > In terms of the tutorial, I'd recommend covering both methods, for the > > > same reason -- bandwidth and disk space issues. Some people will create > > > their initial mirror set from a CDs they get in the postal mail, because > > > their connection is too slow or costly to download 4+ gigs. > > > > Yup, I tried to start by mapping out possibilities/permutations and then > > figure out the tutorial layout by thinking about flow for each > > possibility. > > Just to get this link into the archives, perhaps throw it into the > bugzilla when it's generated: > > http://www.fedoranews.org/alex/tutorial/yum/ > > The script included in that tutorial does a nice job of getting updated > packages from the mirror I point it at, set at my time interval. > > I don't know how CC and FDL licensed documents mix. It'd be a shame to > have to redo the implementation. Has anyone encountered this yet? It's > covered by the Attribution-NonCommercial-ShareAlike 1.0 > (http://creativecommons.org/licenses/by-nc-sa/1.0/). Karsten, This brings up an interesting point which might be outside the scope of this list, but I'm hoping you, Tammy and Mark especially (given your FTE at Red Hat) might have some experience. I see your link above, and want to be clear that, to this point, I have not visited it. It looks to me like the CC BY-NC-SA is incompatible with the GNU FDL in that it (a) requires identical licensing (SA), and (b) prevents commercial use (NC). It does, however, grant the licensor the right to waive any of these provisions upon request. It does make me a little leery about reading too much before I write my tutorial! My head started spinning with "clean room implementation" and other nonsense, until I decided to simply write mine and see how it comes out. In general, the law says that "fair use" isn't affected by copyright of any kind, including a CC license, as stated explicitly even on the CC site. Just as a copyrighted work may quote from a copyrighted source without permission, I may review Alex's work and draw an idea from it, and expand on it. I may *not* reproduce a substantial portion of his work verbatim without permission. I plan to write my tutorial and then, once it's done, post about it here and in Bugzilla. I'll leave it up to others to review my original work and tell me if there are shortcomings at that time. If someone would then like to point out deficiencies, I'd try and address them myself up until the point my skills give out. Oh, in the above, feel free to s/I/we/ for collaborative documents, I'm not intending any autocracy here. -- Paul W. Frields, RHCE From paul at frields.com Mon Aug 16 21:50:16 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 16 Aug 2004 17:50:16 -0400 Subject:
vs , ... [was: Re: usb-keys] In-Reply-To: <1092692436.3459.8494.camel@erato.phig.org> References: <1092303921.2516.14.camel@homer> <1092318074.18844.126.camel@berlin.east.gov> <1092323652.2541.4.camel@homer> <1092327882.18844.186.camel@berlin.east.gov> <1092333660.4488.33339.camel@erato.phig.org> <1092384657.2519.41.camel@homer> <411CD4D5.4090605@redhat.com> <1092420832.4488.35395.camel@erato.phig.org> <1092421685.2449.62.camel@berlin.east.gov> <411D1F1B.4080306@redhat.com> <1092428296.4241.2.camel@berlin.east.gov> <1092428706.4488.36031.camel@erato.phig.org> <1092510468.4681.34.camel@homer> <1092590939.3459.4473.camel@erato.phig.org> <1092678236.2674.43.camel@homer> <1092681595.3459.7942.camel@erato.phig.org> <1092682471.4231.4.camel@homer> <1092692436.3459.8494.camel@erato.phig.org> Message-ID: <1092693016.15287.38.camel@bettie.internal.frields.org> On Mon, 2004-08-16 at 17:40, Karsten Wade wrote: > As for modular .. > > modular > adj : constructed with standardized units or dimensions allowing > flexibility and variety in use; "modular furniture"; > "modular homes" > > What I'm saying is that moving
s with context-only ID tags is a > no-brainer, you just move them. Moving s with context-only > IDs is just grunt work. As soon as you start to get up to IDs with > location information (sn), you are changing s all over the > document, fixing the strings in the id="", changing the -> > , and so forth. > > And, yes,
is also infinitely recursive, but that has nothing > to do with why I recommend we use it. WRT my previous post(s), I'd like to add, "erm, yeah, what he said." -- Paul W. Frields, RHCE From kwade at redhat.com Mon Aug 16 23:11:28 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 16 Aug 2004 16:11:28 -0700 Subject: mirror-tutorial In-Reply-To: <1092692749.15287.34.camel@bettie.internal.frields.org> References: <1092675920.2244.86.camel@berlin.east.gov> <1092682143.3459.7980.camel@erato.phig.org> <200408161458.49039.hoyt@cavtel.net> <1092684553.3459.8119.camel@erato.phig.org> <1092686923.4624.39.camel@berlin.east.gov> <1092690720.3459.8429.camel@erato.phig.org> <1092692749.15287.34.camel@bettie.internal.frields.org> Message-ID: <1092697888.3459.8688.camel@erato.phig.org> On Mon, 2004-08-16 at 14:45, Paul W. Frields wrote: > On Mon, 2004-08-16 at 17:12, Karsten Wade wrote: > > > > http://www.fedoranews.org/alex/tutorial/yum/ { tainted URL? } > > I don't know how CC and FDL licensed documents mix. It'd be a shame to > > have to redo the implementation. Has anyone encountered this yet? It's > > covered by the Attribution-NonCommercial-ShareAlike 1.0 > > (http://creativecommons.org/licenses/by-nc-sa/1.0/). > > Karsten, > > This brings up an interesting point which might be outside the scope of > this list, but I'm hoping you, Tammy and Mark especially (given your FTE > at Red Hat) might have some experience. I see your link above, and want > to be clear that, to this point, I have not visited it. > > It looks to me like the CC BY-NC-SA is incompatible with the GNU FDL in > that it (a) requires identical licensing (SA), and (b) prevents > commercial use (NC). It does, however, grant the licensor the right to > waive any of these provisions upon request. It does make me a little > leery about reading too much before I write my tutorial! My head started > spinning with "clean room implementation" and other nonsense, until I > decided to simply write mine and see how it comes out. Oh, man, I know where you are coming from. I hope we don't have to worry about being tainted by other open source projects using different licenses. I can see that we can't mix the two. I'd been hoping that the script was covered by a different license, but it doesn't say anything else so I'm assuming it's the CC BY-NC-SA. > In general, the law says that "fair use" isn't affected by copyright of > any kind, including a CC license, as stated explicitly even on the CC > site. Just as a copyrighted work may quote from a copyrighted source > without permission, I may review Alex's work and draw an idea from it, > and expand on it. I may *not* reproduce a substantial portion of his > work verbatim without permission. I plan to write my tutorial and then, > once it's done, post about it here and in Bugzilla. > > I'll leave it up to others to review my original work and tell me if > there are shortcomings at that time. If someone would then like to point > out deficiencies, I'd try and address them myself up until the point my > skills give out. Fair enough. If I raise the point that such-and-such a script would be a Good Thing, we'll see if Alex wants to re-license or dual-license the script under the GPL, if it's worth it. In the end, I don't think you are going to be tainted by reading his tutorial or script, but I understand recreating the functionality he has may be beyond your and my skills. If it is, perhaps someone else will step-up and write a GPL'd script to use, if we can't use Alex's. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From hoyt at cavtel.net Tue Aug 17 06:19:30 2004 From: hoyt at cavtel.net (Hoyt) Date: Tue, 17 Aug 2004 02:19:30 -0400 Subject: mirror-tutorial In-Reply-To: <1092697888.3459.8688.camel@erato.phig.org> References: <1092675920.2244.86.camel@berlin.east.gov> <1092692749.15287.34.camel@bettie.internal.frields.org> <1092697888.3459.8688.camel@erato.phig.org> Message-ID: <200408170219.30302.hoyt@cavtel.net> On Monday 16 August 2004 07:11 pm, Karsten Wade wrote: > My head started > > > spinning with "clean room implementation" and other nonsense, until I > > decided to simply write mine and see how it comes out. > > Oh, man, I know where you are coming from. ?I hope we don't have to > worry about being tainted by other open source projects using different > licenses. Remember that facts are not copyrightable, but the manner in which those facts are presented may be. You may make lists of facts on a subject, then use your own words to write about them. That "fleshing out the skeleton" process is the intellectual property that you provide. A good writer can always find a different way to say something, but we are universally condemned when we find other ways of spelling. 8) -- Hoyt Linux _is_ foolproof; just look at all the Windows gurus who won't use it. From davep at dpawson.co.uk Wed Aug 18 16:28:15 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 18 Aug 2004 17:28:15 +0100 Subject: Test email. Too quiet? Message-ID: <1092846495.2520.9.camel@homer> Nothing received for two days; Wondering if the listserv has gone down. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Wed Aug 18 16:34:02 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 18 Aug 2004 12:34:02 -0400 Subject: Test email. Too quiet? In-Reply-To: <1092846495.2520.9.camel@homer> References: <1092846495.2520.9.camel@homer> Message-ID: <1092846841.7823.12.camel@berlin.east.gov> On Wed, 2004-08-18 at 12:28, Dave Pawson wrote: > Nothing received for two days; > Wondering if the listserv has gone down. "Tired and shagged out following a prolonged squawk." I'm trying to get through some of the work I'm actually *paid* for , followed by another go (tonight, hopefully) at some of Tammy and Karsten's work on the process guidelines. -- Paul W. Frields, RHCE From qralston+ml.redhat-fedora-docs at andrew.cmu.edu Wed Aug 18 21:37:59 2004 From: qralston+ml.redhat-fedora-docs at andrew.cmu.edu (James Ralston) Date: Wed, 18 Aug 2004 17:37:59 -0400 Subject: RPM of latest nxml-mode? Message-ID: <81BA514B75CD107FFB82FC7A@pcmy.sei.cmu.edu> I noticed that James Clark released a more recent version of nxml-mode on 2004-07-26. Has anyone packaged this yet? (There's an interaction problem between nxml-mode and VC that I'm trying to track down; I'd like to test against the most recent nxml-mode before sending a bug report...) -- James Ralston, Information Technology Software Engineering Institute Carnegie Mellon University, Pittsburgh, PA, USA From kwade at redhat.com Wed Aug 18 23:35:13 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 18 Aug 2004 16:35:13 -0700 Subject: RPM of latest nxml-mode? In-Reply-To: <81BA514B75CD107FFB82FC7A@pcmy.sei.cmu.edu> References: <81BA514B75CD107FFB82FC7A@pcmy.sei.cmu.edu> Message-ID: <1092872112.3459.15778.camel@erato.phig.org> On Wed, 2004-08-18 at 14:37, James Ralston wrote: > I noticed that James Clark released a more recent version of nxml-mode > on 2004-07-26. > > Has anyone packaged this yet? Tim has packages with the same date; he's usually quite prompt at updating the packages: http://people.redhat.com/twaugh/ftp/docbook/nxml-mode/ Not part of Fedora yet, though, right? - Karsten > (There's an interaction problem between nxml-mode and VC that I'm > trying to track down; I'd like to test against the most recent > nxml-mode before sending a bug report...) > > -- > James Ralston, Information Technology > Software Engineering Institute > Carnegie Mellon University, Pittsburgh, PA, USA -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Thu Aug 19 09:04:58 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 19 Aug 2004 02:04:58 -0700 Subject: Test email. Too quiet? In-Reply-To: <1092846841.7823.12.camel@berlin.east.gov> References: <1092846495.2520.9.camel@homer> <1092846841.7823.12.camel@berlin.east.gov> Message-ID: <1092906298.17095.5.camel@erato.phig.org> On Wed, 2004-08-18 at 09:34, Paul W. Frields wrote: > On Wed, 2004-08-18 at 12:28, Dave Pawson wrote: > > Nothing received for two days; > > Wondering if the listserv has gone down. > > "Tired and shagged out following a prolonged squawk." > > I'm trying to get through some of the work I'm actually *paid* for > , followed by another go (tonight, hopefully) at some of Tammy > and Karsten's work on the process guidelines. HA HA HA I was going to reply with the same thing. Besides, I put out the ver. 2 of the process doc the other day, so I'm waiting for feedback. :) http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en.xml http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en.html http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process/index.html - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Thu Aug 19 17:27:32 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 19 Aug 2004 18:27:32 +0100 Subject: Test email. Too quiet? In-Reply-To: <1092906298.17095.5.camel@erato.phig.org> References: <1092846495.2520.9.camel@homer> <1092846841.7823.12.camel@berlin.east.gov> <1092906298.17095.5.camel@erato.phig.org> Message-ID: <1092936451.2544.20.camel@homer> On Thu, 2004-08-19 at 10:04, Karsten Wade wrote: > Besides, I put out the ver. 2 of the process doc the other day, so I'm > waiting for feedback. :) > http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en.html If you want a fast, Emacs based entry, read the Quick Start... Need a link to the quick start ... or a statement its tba Know what documents are in progress; refer to bug 129807 Need more? If you are going to (ab)use the bug system, at least document how its going to be used. Ditto with 129784 One of the reasons for using Emacs is that it is capable of indenting the code according to the DTD. DTD's aren't fashion or style statements. No such thing as indenting in a DTD. If this project is going to use non-xml tools for diff generation, admit it as a shortcoming and apologise :-) If you do not have usable Web space, look for willing hosting partners in the project, who can build and host your beta documents. controversial recommendation? open +1. I'll host it. Maybe also Brad? Less sure about the XML. My principle has always been keep the source to yourself until you're ready? Issue of two people concurrently making mods? XML patches are (IMHO) better against a finished document? Comments yes, but that can be against html. Spell check all files. How, if emacs is used? spellcheck in xml I haven't done. (Or is that obvious?) Verify that all sections have an id so all HTML files generated have static filenames. Disagree. Overboard | unnecessary IMHO. Chunking is currently at sect1 level. Verify the HTML Output: Redundant, since its not the authors html that will be used. If we can't trust the toolchain to generate good links .... +1 on editor outline tasks. General. How about a list of links (appendix)? Not mentioned: Managing revisionss (fc2 vs fc3 etc) Should be in author section? I like it. regards DaveP -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From mjohnson at redhat.com Thu Aug 19 17:56:04 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Thu, 19 Aug 2004 13:56:04 -0400 Subject: Doc-Process Feedback [was Re: Test email. Too quiet?] In-Reply-To: <1092936451.2544.20.camel@homer> References: <1092846495.2520.9.camel@homer> <1092846841.7823.12.camel@berlin.east.gov> <1092906298.17095.5.camel@erato.phig.org> <1092936451.2544.20.camel@homer> Message-ID: <4124E9B4.7040000@redhat.com> Dave Pawson wrote: > On Thu, 2004-08-19 at 10:04, Karsten Wade wrote: > > >>Besides, I put out the ver. 2 of the process doc the other day, so I'm >>waiting for feedback. :) > > >>http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en.html > > > > If you want a fast, Emacs based entry, read the Quick Start... > > Need a link to the quick start ... or a statement its tba Guess it's time for me to write that Emacs/PSGML Quick Start thingee, eh? BTW, some good notes, Dave! Cheers, Mark > Know what documents are in progress; refer to bug 129807 > Need more? If you are going to (ab)use the bug system, at least > document how its going to be used. > > Ditto with 129784 > > One of the reasons for using Emacs is that it is capable of indenting > the code according to the DTD. > DTD's aren't fashion or style statements. No such thing as indenting > in a DTD. > If this project is going to use non-xml tools for diff generation, > admit it as a shortcoming and apologise :-) > > If you do not have usable Web space, look for willing hosting partners > in the project, who can build and host your beta documents. > controversial recommendation? open > +1. I'll host it. Maybe also Brad? > Less sure about the XML. My principle has always been keep the source > to yourself until you're ready? Issue of two people concurrently making > mods? XML patches are (IMHO) better against a finished document? > Comments yes, but that can be against html. > > Spell check all files. > How, if emacs is used? spellcheck in xml I haven't done. (Or is that > obvious?) > > Verify that all sections have an id so all HTML files generated have > static filenames. > Disagree. Overboard | unnecessary IMHO. Chunking is currently at sect1 > level. > > Verify the HTML Output: > Redundant, since its not the authors html that will be used. > If we can't trust the toolchain to generate good links .... > > +1 on editor outline tasks. > > > > > General. > > How about a list of links (appendix)? > Not mentioned: Managing revisionss (fc2 vs fc3 etc) Should be in > author section? > > > I like it. > > regards DaveP > > > > > > > > -- ---------------------------------------------------------- Mark Johnson Red Hat Documentation Group Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From kwade at redhat.com Thu Aug 19 18:51:28 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 19 Aug 2004 11:51:28 -0700 Subject: Test email. Too quiet? In-Reply-To: <1092936451.2544.20.camel@homer> References: <1092846495.2520.9.camel@homer> <1092846841.7823.12.camel@berlin.east.gov> <1092906298.17095.5.camel@erato.phig.org> <1092936451.2544.20.camel@homer> Message-ID: <1092941487.17095.2405.camel@erato.phig.org> On Thu, 2004-08-19 at 10:27, Dave Pawson wrote: > On Thu, 2004-08-19 at 10:04, Karsten Wade wrote: > Thanks for the fast reply; glad you like it overall. I wanted to address a few of your points ... > One of the reasons for using Emacs is that it is capable of indenting > the code according to the DTD. > DTD's aren't fashion or style statements. No such thing as indenting > in a DTD. > If this project is going to use non-xml tools for diff generation, > admit it as a shortcoming and apologise :-) I think we are talking about different things here. Clearly, I'm not the expert, so perhaps you can clue me in as to what I _am_ talking about. :) a) Emacs can auto-indent according to PSGML(X)'s understanding of ___________ (I thought it indented according to nesting defined in the DTD) b) The indenting I am interested in has to do with code readability, not directly about making sane diffs. Was your clever XSLT trick for standardizing indenting prior to diff'ing, to make for a sane diff? I can see where it would resolve that area, but we have to consider other areas: * Shared authoring in a single XML file. * The need for code standardization across the project, as is common in other open source projects. * An editor's ability to quickly supply useful patches instead of hunt-and-paste comments. > If you do not have usable Web space, look for willing hosting partners > in the project, who can build and host your beta documents. > controversial recommendation? open > +1. I'll host it. Maybe also Brad? > Less sure about the XML. My principle has always been keep the source > to yourself until you're ready? Issue of two people concurrently making > mods? XML patches are (IMHO) better against a finished document? > Comments yes, but that can be against html. I think we need to release the source code with the beta documentation. * It's a good learning experience for other writers. * It helps editors/other contributors catch XML coding, syntax, etc. mistakes early before they are used throughout a document Not to be harsh, but if you mean "comments ... against html" in the style of what you did in this email, that is *very* hard to work with. I have to open my source file separately and guess where you are talking about. Context is lost entirely, and there are no semantic marks (+,-, >, # etc.) to differentiate between what I wrote and what you wrote. I'd much prefer a diff, even if I can't patch it but have to manually paste it into the XML. > Spell check all files. > How, if emacs is used? spellcheck in xml I haven't done. (Or is that > obvious?) M-x ispell-buffer If you don't have ispell installed, you can do 'M-x spell-buffer'. Not sure off-hand why ispell is better, shared system dictionary perhaps? > Verify that all sections have an id so all HTML files generated have > static filenames. > Disagree. Overboard | unnecessary IMHO. Chunking is currently at sect1 > level. YHO is very strong in this area, but you haven't answered the issues raised so far. Until you do, how can we reach consensus? * No DocBook automatic filenames are useful, that I have seen so far. The best so far, ch06s02.html, does not help find where in the XML that page came from. The meaning in a name like ch06s02 relates to the Table of Contents only, which only shows what order the XML files are called in by the parent file, not which file something is in. My only choice is to open up the document, go to the ToC, and start counting down for Chapter 6, Section 2, and hope that it's not in fact a third or fourth level of nesting, because the ToC doesn't display those, and then I'm entirely lost. * Filenames that correspond to ID tags that are searchable are useful for editors, collaborators, and inheritors of a document. It makes it easier to learn the document, and faster to fix bugs and author new content. * All of this is magnified when you are dealing with a book that is hundreds of printed pages and dozens of lengthy XML files. The last point is really important ... I have saved myself _hours_ of hunting for file locations because of HTML filenames based on ID tags. I can't see dropping that contextually valuable information for any reason. BTW, the usage of the word 'static' in this directive means, predictable HTML filenames based on the ID tag. For example, without ID tags, HTML filenames in some toolchains will be changed if you didn't clean out the target directory. > Verify the HTML Output: > Redundant, since its not the authors html that will be used. > If we can't trust the toolchain to generate good links .... This is mainly for external URLs, rather than internal linking. I agree, I've never seen the toolchain build a link that was broken, although it sometimes goes to the incorrect location (i.e., writer target error.) That is usually visually understood -- as you read through the document, the is not where you expect it to be; no need to click, just fix in XML. > How about a list of links (appendix)? A "References" section should be mentioned; that's pretty common. I will include that if it's not in e.g. the example-tutorial. > Not mentioned: Managing revisionss (fc2 vs fc3 etc) Should be in > author section? Good point. We haven't discussed this. Areas I see are: * CVS branching process (file a bug, basically) * How to handle this at f.r.c/docs * ??? Thanks - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Thu Aug 19 22:11:46 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 19 Aug 2004 18:11:46 -0400 Subject: Style guide Message-ID: <1092953506.25915.8.camel@bettie.internal.frields.org> As I write docs, e.g. my mirror-tutorial, I'm making stylistic decisions (i.e. self-editing). As I edit myself, I'm trying to make notes in my TODO for the eos-guide, which I hope will be incorporated in the eventual Style Guide. I'm hoping to do some major contribution to that guide, especially after having XML coded Strunk's book recently. If you notice a stylistic decision that you are making consciously as you write, whether you think it is glaringly obvious or not, please feel free to send me a note about it -- off-list please, since I'll have the TODO available at my repo if you would like to look at or add to it. See * for more information; the TODO is in the eos-guide folder. I intend to use not just EOS, but also the GNOME Style Guidelines (which are licensed via the FDL), as source material for any work I can do on the Style Guide. If, perchance, anyone else has already started, I hope you'll consider this an offer of help. :-) - - - - *Umm, I have mentioned that repo a few times, and I hope (Karsten, this means you especially) that *someone* will say something if my doing so is a faux pas. I am fully aware that it's not part of the FDP, nor is it intended to be. It's only a nice way for me to work on this stuff at remote locations, until the One True CVS appears, but I also wanted editors and collaborators to be able to reach it too. -- Paul W. Frields, RHCE From kwade at redhat.com Fri Aug 20 01:34:23 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 19 Aug 2004 18:34:23 -0700 Subject: Style guide In-Reply-To: <1092953506.25915.8.camel@bettie.internal.frields.org> References: <1092953506.25915.8.camel@bettie.internal.frields.org> Message-ID: <1092965662.17095.4056.camel@erato.phig.org> On Thu, 2004-08-19 at 15:11, Paul W. Frields wrote: > As I write docs, e.g. my mirror-tutorial, I'm making stylistic decisions > (i.e. self-editing). As I edit myself, I'm trying to make notes in my > TODO for the eos-guide, which I hope will be incorporated in the > eventual Style Guide. I'm hoping to do some major contribution to that > guide, especially after having XML coded Strunk's book recently. > > If you notice a stylistic decision that you are making consciously as > you write, whether you think it is glaringly obvious or not, please feel > free to send me a note about it -- off-list please, since I'll have the > TODO available at my repo if you would like to look at or add to it. See > * for more information; the TODO is in the > eos-guide folder. > > I intend to use not just EOS, but also the GNOME Style Guidelines (which > are licensed via the FDL), as source material for any work I can do on > the Style Guide. If, perchance, anyone else has already started, I hope > you'll consider this an offer of help. :-) Awesome offer, both to get the Style Guidelines[1] started, and to collect style tips from all of us. I'll certainly send them. I'd also argue that your interest and activity so far should let you be the author/compiler of the Style Guidelines, at least initially. As much as the Doc Guide, the Style Guidelines will require group and editorial approval, so you will have to return to us for consensus on what you create more than any other doc you are likely to work on. Once a style is set for a group, adherence to the style becomes the goblin of the editors. Changing even a small rule about punctuation can have big ramifications. We may want to consider that in terms of keeping our rules light, meaningful, and standardized. [1] I'm trying the sound-out the idea of "Guidelines" instead of "Guide". This way we can include outside resources by reference as part of the guidelines, or just include sections of free sources like the GNOME Style Guide (not Guidelines, I think) in their entirety. > *Umm, I have mentioned that repo a few times, and I hope (Karsten, this > means you especially) that *someone* will say something if my doing so > is a faux pas. I am fully aware that it's not part of the FDP, nor is it > intended to be. It's only a nice way for me to work on this stuff at > remote locations, until the One True CVS appears, but I also wanted > editors and collaborators to be able to reach it too. I think the consensus so far is: * We don't want outside repositories or hosted draft documents to be seen _at_all_ as official, supported, backed-up, unrootkitted, or anything sources for FDP docs or SCM (software configuration management). * We don't specifically recommend using personal hosting, but we do mention it as an allowable part of the *writing* process (not the *publishing* process) for FDP. In essence, what you are doing isn't much different than my hosting stuff at people.redhat.com. Personally, I should be keeping all my local work in local source control, anyway. :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Fri Aug 20 13:07:51 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 20 Aug 2004 09:07:51 -0400 Subject: Style guide In-Reply-To: <1092965662.17095.4056.camel@erato.phig.org> References: <1092953506.25915.8.camel@bettie.internal.frields.org> <1092965662.17095.4056.camel@erato.phig.org> Message-ID: <1093007270.2319.7.camel@berlin.east.gov> On Thu, 2004-08-19 at 21:34, Karsten Wade wrote: > On Thu, 2004-08-19 at 15:11, Paul W. Frields wrote: > > As I write docs, e.g. my mirror-tutorial, I'm making stylistic decisions > > (i.e. self-editing). As I edit myself, I'm trying to make notes in my > > TODO for the eos-guide, which I hope will be incorporated in the > > eventual Style Guide. I'm hoping to do some major contribution to that > > guide, especially after having XML coded Strunk's book recently. > > > > If you notice a stylistic decision that you are making consciously as > > you write, whether you think it is glaringly obvious or not, please feel > > free to send me a note about it -- off-list please, since I'll have the > > TODO available at my repo if you would like to look at or add to it. See > > * for more information; the TODO is in the > > eos-guide folder. > > > > I intend to use not just EOS, but also the GNOME Style Guidelines (which > > are licensed via the FDL), as source material for any work I can do on > > the Style Guide. If, perchance, anyone else has already started, I hope > > you'll consider this an offer of help. :-) > > Awesome offer, both to get the Style Guidelines[1] started, and to > collect style tips from all of us. I'll certainly send them. I'd also > argue that your interest and activity so far should let you be the > author/compiler of the Style Guidelines, at least initially. As much as > the Doc Guide, the Style Guidelines will require group and editorial > approval, so you will have to return to us for consensus on what you > create more than any other doc you are likely to work on. Thanks for the vote of confidence. As for passing everything back through the group, I wouldn't have it any other way! :-) > Once a style is set for a group, adherence to the style becomes the > goblin of the editors. Changing even a small rule about punctuation can > have big ramifications. We may want to consider that in terms of > keeping our rules light, meaningful, and standardized. > > [1] I'm trying the sound-out the idea of "Guidelines" instead of > "Guide". This way we can include outside resources by reference as part > of the guidelines, or just include sections of free sources like the > GNOME Style Guide (not Guidelines, I think) in their entirety. Right, it's GNOME Documentation Style Guide. Already showing my keen attention to detail, aren't I? ;-D > > *Umm, I have mentioned that repo a few times, and I hope (Karsten, this > > means you especially) that *someone* will say something if my doing so > > is a faux pas. I am fully aware that it's not part of the FDP, nor is it > > intended to be. It's only a nice way for me to work on this stuff at > > remote locations, until the One True CVS appears, but I also wanted > > editors and collaborators to be able to reach it too. > > I think the consensus so far is: > > * We don't want outside repositories or hosted draft documents to be > seen _at_all_ as official, supported, backed-up, unrootkitted, or > anything sources for FDP docs or SCM (software configuration ^^^^^ other than? (not nitpicking, just making sure I understand.) > management). > * We don't specifically recommend using personal hosting, but we do > mention it as an allowable part of the *writing* process (not the > *publishing* process) for FDP. > > In essence, what you are doing isn't much different than my hosting > stuff at people.redhat.com. Personally, I should be keeping all my > local work in local source control, anyway. :) I think I'm on the right side of both conscience and consensus then. I'll continue to direct people to my working drafts when appropriate, with a constant notation that anything found there is a work in progress. I will make it a point to mess with the ViewCVS templates to indicate same on the site. -- Paul W. Frields, RHCE From kwade at redhat.com Fri Aug 20 17:00:06 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 20 Aug 2004 10:00:06 -0700 Subject: Style guide In-Reply-To: <1093007270.2319.7.camel@berlin.east.gov> References: <1092953506.25915.8.camel@bettie.internal.frields.org> <1092965662.17095.4056.camel@erato.phig.org> <1093007270.2319.7.camel@berlin.east.gov> Message-ID: <1093021205.17095.7768.camel@erato.phig.org> On Fri, 2004-08-20 at 06:07, Paul W. Frields wrote: > On Thu, 2004-08-19 at 21:34, Karsten Wade wrote: > > * We don't want outside repositories or hosted draft documents to be > > seen _at_all_ as official, supported, backed-up, unrootkitted, or > > anything sources for FDP docs or SCM (software configuration > ^^^^^ other than? (not nitpicking, just making sure I > understand.) > > management). Bad idiomatic usage ... it should parse like, "we don't want outside repositories to be seen at all as official anything to do with FDP." Still awkward. How about: * Because of concerns over support, availability, redundancy, and security, we don't want non-FDP doc or source repositories to be seen as "officially" connected to the project. For example, if someone's SCM gets compromised and a rootkit trojan is loaded into document tarball ... well, bad things could happen. Hope that is clearer, - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Sat Aug 21 11:55:05 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 21 Aug 2004 12:55:05 +0100 Subject: Process In-Reply-To: <1092941487.17095.2405.camel@erato.phig.org> References: <1092846495.2520.9.camel@homer> <1092846841.7823.12.camel@berlin.east.gov> <1092906298.17095.5.camel@erato.phig.org> <1092936451.2544.20.camel@homer> <1092941487.17095.2405.camel@erato.phig.org> Message-ID: <1093089305.2522.18.camel@homer> On Thu, 2004-08-19 at 19:51, Karsten Wade wrote: > > If this project is going to use non-xml tools for diff generation, > > admit it as a shortcoming and apologise :-) > > I think we are talking about different things here. Clearly, I'm not > the expert, so perhaps you can clue me in as to what I _am_ talking > about. :) > > a) Emacs can auto-indent according to PSGML(X)'s understanding of > ___________ > > (I thought it indented according to nesting defined in the DTD) No, its to make it look pretty for humans. The identity transform I mailed to the list can do the same thing, quicker and better. > > b) The indenting I am interested in has to do with code readability, not > directly about making sane diffs. Was your clever XSLT trick for > standardizing indenting prior to diff'ing, to make for a sane diff? Your prior comment indicated you were utilising plain text differences for a revision changes? Rather than an XML diff. That was my point. XML has no respect for whitespace in general, hence document layout, which may be of use in a python or tcl program, has little utility in XML. > * Shared authoring in a single XML file. How does layout impact this Karsten? > > * The need for code standardization across the project, as is common in > other open source projects. That's the markup and which tag to use surely? Not pretty printing? > > * An editor's ability to quickly supply useful patches instead of > hunt-and-paste comments. Inserts and deletes can be xml markup. plain text diff is far less useful. I'd suggest using My addition and old content and then use xml processing to remove deletions, add new material, but perhaps thats not in line with older processes? > I think we need to release the source code with the beta documentation. > > * It's a good learning experience for other writers. > > * It helps editors/other contributors catch XML coding, syntax, etc. > mistakes early before they are used throughout a document Fair comment; My objection would be someone else making changes when an original author hasn't reviewed it for release? Bit of a waste. > > Not to be harsh, but if you mean "comments ... against html" in the > style of what you did in this email, that is *very* hard to work with. Works for me. Whatever. > > I have to open my source file separately and guess where you are talking > about. Context is lost entirely, and there are no semantic marks (+,-, > >, # etc.) to differentiate between what I wrote and what you wrote. I'd > much prefer a diff, even if I can't patch it but have to manually paste > it into the XML. I'd much prefer an xml diff, or semantic markup (ins del). Makes more sense in an xml process IMHO. > M-x ispell-buffer AFAIK that doesn't work in a windows emacs. 'tis all. I'll try it now I'm on rh! Tks. > > If you don't have ispell installed, you can do 'M-x spell-buffer'. Not > sure off-hand why ispell is better, shared system dictionary perhaps? Isn't there (wasn't there) debate over aspell replacing ispell? > > > Verify that all sections have an id so all HTML files generated have > > static filenames. > > Disagree. Overboard | unnecessary IMHO. Chunking is currently at sect1 > > level. > > YHO is very strong in this area, but you haven't answered the issues > raised so far. Until you do, how can we reach consensus? AFAICS there is no reason to use readable id values for other than chunked elements, sect1 following current guidelines. Any more is pure waste of effort. Tammy? > The meaning in a name like ch06s02 relates to the Table of Contents > only, which only shows what order the XML files are called in by the > parent file, not which file something is in. Repeating myself; Don't navigate by id values, that's not why they are there. > > * All of this is magnified when you are dealing with a book that is > hundreds of printed pages and dozens of lengthy XML files. Find a more reasonable way of navigating. One that's meant for people, not machines. > BTW, the usage of the word 'static' in this directive means, predictable > HTML filenames based on the ID tag. For example, without ID tags, HTML > filenames in some toolchains will be changed if you didn't clean out the > target directory. If you wish to use last centuries toolchain, there may be a price to pay. > > > Verify the HTML Output: > > Redundant, since its not the authors html that will be used. > > If we can't trust the toolchain to generate good links .... > > This is mainly for external URLs, rather than internal linking. Which you state elsewhere? > > I agree, I've never seen the toolchain build a link that was broken, > although it sometimes goes to the incorrect location (i.e., writer > target error.) That is usually visually understood -- as you read > through the document, the is not where you expect it to be; no > need to click, just fix in XML. The tool resolving the link should report that as an error. docbook stylesheets do that, xslt version. > > > How about a list of links (appendix)? > > A "References" section should be mentioned; that's pretty common. I will > include that if it's not in e.g. the example-tutorial. I meant in your document? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Sat Aug 21 19:24:20 2004 From: paul at frields.com (Paul W. Frields) Date: Sat, 21 Aug 2004 15:24:20 -0400 Subject: GNOME Documentation Style Guide Message-ID: <1093116260.8882.11.camel@bettie.internal.frields.org> I am one of the writer/editors working on the Fedora Documentation Project , and we are preparing a set of Style Guidelines for aspiring writers and editors. In doing a short survey of related sites, I came across the captioned guide ("GDSG"). Since all our documentation will be licensed under the GNU FDL, as is the GDSG, we are very interested in using portions of your Guide as source material. Your use of the GNU FDL makes this effort possible. As the individual who will likely take the lead on preparing the Fedora Documentation Style Guidelines, I'm writing partly out of a sense of courtesy, but also to commend you on an exceptionally concise and readable guide. We hope that our use of the GDSG will make the process of creating useful, contemporary Fedora documentation a more pleasant experience for all our contributors. We also hope that we may be able to build upon the exceptional work you've done in preparing the GDSG. Please feel free to contact me back, or visit our list archives at . (cc: fedora-docs-list) -- Paul W. Frields, RHCE -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From paul at frields.com Sun Aug 22 13:34:04 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 22 Aug 2004 09:34:04 -0400 Subject: FDP docs process - round 2 In-Reply-To: <1092664199.3459.7055.camel@erato.phig.org> References: <1092664199.3459.7055.camel@erato.phig.org> Message-ID: <1093181644.7704.23.camel@bettie.internal.frields.org> On Mon, 2004-08-16 at 09:50, Karsten Wade wrote: > As detailed in > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129993. > > Please read and comment; main discussion on the list, I think, since > this is a pretty important document for all of us to agree upon. > > [snarf_from_bz129993] [...snip...] I think we need a short statement at that states: "If you think a specific piece of documentation is needed, enter a request for enhancement (RFE) in Bugzilla. Look over the _current_list_of_bugs_[1] first to be sure your request is not already in progress. If it is not, _enter_a_new_RFE_bug_[2] and it will enter the queue." ...or something to that effect. ([1] & [2] can duplicate the links at the Docs Project page. ) This came up today as I look over fedora-devel-list and see that there is a great deal of confusion starting to arise over the way Arjan is preparing the kernel RPM these days. Bear with me while I describe the problem for those on this list who may not read that one. Case in point, kernel-sourcecode has been dropped in favor of having the user simply download kernel-.src.rpm. He indicates there will be documentation about how to use this for building new kernels from scratch. This process will be very different from the old one, and the FDP should probably get in on (or maybe just above) the ground floor WRT producing it. I tried to put myself in the mindset of someone who wanted to ask for docs, but didn't know where to start. I think many people who might helpfully be entering RFE's for us are not making it down to the bottom of the FDP page at , and don't understand what those links are for. In addition, the fact that the entire first section of the FDP page would lead fast readers to believe that no resources exist on that page for them, unless they want to do some writing themselves. A very short statement on what a non-writer can do, at the gateway most users will likely enter, would go a long way; we want to encourage even small contributions from people who aren't able to make large ones. This is in Karsten's FDP docs process thread because it also is oriented toward people who want to be FDP contributors, as opposed to Joe User (or even Sally Developer), who may simply want to ask that we consider writing a certain doc. This is not to say that case needs to be in the FDP process guide, but certainly we should be considering it to make the Fedora home page more usable. Unless anyone has objections, I'll Bugzilla this as a RFE of the page... and I'll likely RFE the kernel situation too. -- Paul W. Frields, RHCE From paul at frields.com Sun Aug 22 13:40:41 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 22 Aug 2004 09:40:41 -0400 Subject: FDP docs process - round 2 In-Reply-To: <1093181644.7704.23.camel@bettie.internal.frields.org> References: <1092664199.3459.7055.camel@erato.phig.org> <1093181644.7704.23.camel@bettie.internal.frields.org> Message-ID: <1093182041.7704.26.camel@bettie.internal.frields.org> On Sun, 2004-08-22 at 09:34, Paul W. Frields wrote: > "If you think a specific piece of documentation is needed, enter a > request for enhancement (RFE) in Bugzilla. Look over the > _current_list_of_bugs_[1] first to be sure your request is not already > in progress. If it is not, _enter_a_new_RFE_bug_[2] and it will enter > the queue." > > ...or something to that effect. > > ([1] & [2] can duplicate the links at the Docs Project page. ) ^^^ [2] should not *duplicate* the link at the FDP page. It needs to be a link to a (possibly partially completed?) Bugzilla entry form, not a query. -- Paul W. Frields, RHCE From kwade at redhat.com Mon Aug 23 11:36:33 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 23 Aug 2004 04:36:33 -0700 Subject: GNOME Documentation Style Guide In-Reply-To: <1093116260.8882.11.camel@bettie.internal.frields.org> References: <1093116260.8882.11.camel@bettie.internal.frields.org> Message-ID: <1093260993.17095.27281.camel@erato.phig.org> Bravo! On Sat, 2004-08-21 at 12:24, Paul W. Frields wrote: > I am one of the writer/editors working on the Fedora Documentation > Project , and we are preparing a > set of Style Guidelines for aspiring writers and editors. In doing a > short survey of related sites, I came across the captioned guide > ("GDSG"). Since all our documentation will be licensed under the GNU > FDL, as is the GDSG, we are very interested in using portions of your > Guide as source material. Your use of the GNU FDL makes this effort > possible. > > As the individual who will likely take the lead on preparing the Fedora > Documentation Style Guidelines, I'm writing partly out of a sense of > courtesy, but also to commend you on an exceptionally concise and > readable guide. We hope that our use of the GDSG will make the process > of creating useful, contemporary Fedora documentation a more pleasant > experience for all our contributors. We also hope that we may be able to > build upon the exceptional work you've done in preparing the GDSG. > > Please feel free to contact me back, or visit our list archives at > . > > (cc: fedora-docs-list) The debian-docs list had a similar result recently, someone recommending the GDSG as a baseline for a Debian style guide. http://lists.debian.org/debian-doc/2004/08/msg00026.html This came about because of a heated discussion about sexist language. I heard about this from someone saying, "Look at these idiots on this mailing list arguing such dumb stuff!" http://lists.debian.org/debian-doc/2004/08/msg00006.html (start 1) http://lists.debian.org/debian-doc/2004/08/msg00015.html (next continuation) I think the GDSG guideline stands, and it is the one I have always used. Avoid sexist language, mainly by avoiding the third-person pronoun. We should specify that all of our docs refer to the second-person pronoun 'you.' Happy reading, Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Mon Aug 23 12:32:13 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 23 Aug 2004 08:32:13 -0400 Subject: More docs ideas? In-Reply-To: <4128E9E6.7090308@rincon.com> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> Message-ID: <1093264333.2522.27.camel@berlin.east.gov> (Top posting because I'm basically forwarding.) There's another docs idea toward the bottom of this post. Unfortunately, recent changes in the kernel building schema for FC2 and FC3test* have started some flamewars, mostly (methinks) because of misunderstanding. (C'est la vie.) But it does argue for some quick docs work. There is a link below to a write-up that Arjan van de Ven did for FedoraNews.org not too long ago. I'm sticking it in the archives for reference. Again, if no one has a quibble, I'll Bugzilla this. On Sun, 2004-08-22 at 14:45, Bob Arendt wrote: > Arjan van de Ven wrote: > >>If fedora.us accepts the fact that multiple-repos (co)exist, and would > >>be willing to work on interoperability/compatibility I would very much > >>welcome a new kernel module framework outside of Arjan's reach ;) > > > > You know, YOU and 2 or 3 other people are the reason I entirely stopped > > caring about this. No matter what I do you or those others will just > > flame me and personally attack me. So I rather do just nothing and > > ignore the entire thing. > As a kernel source user, module builder, I'd like to speak in *favor* > of the new kernel src.rpm scheme. > > Using mod-versioned kernels, I used to have to rebuild kernel-source > up through the "make dep" stage to get valid kernel headers to compile > against. It was error-prone; If I didn't change the Makefile > EXTRAVERSION, or copy the correct architecture config file to start > with, I got incompatible headers. Building a module for multiple > archs, this was repetitious. OR - I could burn a *lot* of disk space > replicating the kernel source just to build the headers to build > modules against. Yech. > > Now the kernel headers are included with each kernel install! > Fantastic! No more special builds. ASCII headers compress really > well, so there's little inflation in binary-kernel rpm size. And it's > much easier to build & install the 3rd party hardware drivers we use. > Now 3rd party delivered build scripts "just work" since the correct > headers can always be found with the kernel. Vendors have gotten > fewer callbacks regarding installation. It no longer depends on the > last state of the /usr/src/linux* since someone last used the > kernel-source. In fact, it removes the kernel-source requirement > entirely. > > Better yet, the kernel src.rpm now gives me direct visibility into the > patches that RedHat's applied. kernel-source always used to bug me, > since all I got was the post-patched kernel-source without much info > on how it differed from kernel.org's version. If I just "rpm -i", I > get the virgin kernel source tarball in the ./SOURCES directory. With > "rpmbuild -bp " I get the RedHat patched kernel, equivalent to > kernel-source. Better yet, I can look in kernel.spec and see the > patches applied (with comments) one-by-one. Though the src.rpm had > been available, I'd never really looked at it since most of the > literature (well .. web-searches) steered me towards kernel-source. > > Arjan's write-up here: http://fedoranews.org/colin/fnu/issue14.shtml > seemed to cover the history and issues pretty well. It would be good > to get this written up in a HOWTO or some more easily findable docs. > Especially prior to RHEL4, where I'd expect to see some quality docs > on these procedures, delivered as part of RHEL4 documentation. > > Good work Arjan. -- Paul W. Frields, RHCE From paul at frields.com Mon Aug 23 12:38:55 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 23 Aug 2004 08:38:55 -0400 Subject: GNOME Documentation Style Guide In-Reply-To: <1093260993.17095.27281.camel@erato.phig.org> References: <1093116260.8882.11.camel@bettie.internal.frields.org> <1093260993.17095.27281.camel@erato.phig.org> Message-ID: <1093264734.2522.35.camel@berlin.east.gov> On Mon, 2004-08-23 at 07:36, Karsten Wade wrote: [...snip...] > This came about because of a heated discussion about sexist language. I > heard about this from someone saying, "Look at these idiots on this > mailing list arguing such dumb stuff!" > > http://lists.debian.org/debian-doc/2004/08/msg00006.html (start 1) > > http://lists.debian.org/debian-doc/2004/08/msg00015.html (next > continuation) > > I think the GDSG guideline stands, and it is the one I have always > used. Avoid sexist language, mainly by avoiding the third-person > pronoun. We should specify that all of our docs refer to the > second-person pronoun 'you.' I agree whole-heartedly. If documentation avoids referring to users by pronouns at all, it shifts to passive voice, and there's nothing that irritates me more. Well OK, that and people who take the last bit of coffee without making another pot. My workplace practically insists on passive voice, and I fight it at every opportunity. My last job here was as a forensic examiner, and all my work products could potentially wind up in court at some point. For some reason, it was de rigeur to write all the lab reports in passive voice, such as "this test was performed." I started writing my reports as "I ran this test," and it caused a bit of an uproar. My position was that if I had to sit on the stand and say I did something, why should my reports not say the same thing? There is the indefinite subject "one," but that's too dry and effete for my taste. I also prefer "you," since it gives readers the sense that the documentation is at least *attempting* to address their personal needs. It also reduces unnecessary formality, without making the documentation seem inauthoritative. I've only skimmed the GDSG so far, but will read it in its entirety this week and start making notes on what I think we should cleave to or depart from. (Paying attention to dangling prepositions, of course. And sentence fragments.) -- Paul W. Frields, RHCE From redwire at therockmere.com Mon Aug 23 12:02:15 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Mon, 23 Aug 2004 08:02:15 -0400 (EDT) Subject: fedora-docs-list Digest, Vol 6, Issue 25 In-Reply-To: <20040821160013.2619A735B3@hormel.redhat.com> References: <20040821160013.2619A735B3@hormel.redhat.com> Message-ID: <26597.199.224.21.254.1093262535.squirrel@TheRockmere.com> > > ---------------------------------------------------------------------- > > Message: 1 > Date: Fri, 20 Aug 2004 10:00:06 -0700 > From: Karsten Wade > Subject: Re: Style guide > To: For participants of the docs project > Message-ID: <1093021205.17095.7768.camel at erato.phig.org> > Content-Type: text/plain > > On Fri, 2004-08-20 at 06:07, Paul W. Frields wrote: >> On Thu, 2004-08-19 at 21:34, Karsten Wade wrote: > >> > * We don't want outside repositories or hosted draft documents to be >> > seen _at_all_ as official, supported, backed-up, unrootkitted, or >> > anything sources for FDP docs or SCM (software configuration >> ^^^^^ other than? (not nitpicking, just making sure I >> understand.) >> > management). > > Bad idiomatic usage ... it should parse like, "we don't want outside > repositories to be seen at all as official anything to do with FDP." > > Still awkward. How about: > > * Because of concerns over support, availability, redundancy, and > security, we don't want non-FDP doc or source repositories to be seen as > "officially" connected to the project. For example, if someone's SCM > gets compromised and a rootkit trojan is loaded into document tarball > ... well, bad things could happen. > > Hope that is clearer, > > - Karsten > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 If RH is THAT worried about contamination, then maybe THEY should release SOME documentation... You may not want the appearance of some site appearing to be 'official', but I think that this is a little bit of a scare tactic. Thousands of programs are released via apt, rpm repositories and yum... ALL without the fear of contamination or appearance of impropropiety. And all done with the help of willing participanting websites AND ENCOURAGEMENT from the authors. MANY run with the sole support of the webmaster. Why is the thought of spreading the information such a fearful subject? Brad From kwade at redhat.com Mon Aug 23 17:28:30 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 23 Aug 2004 10:28:30 -0700 Subject: Style Guide (was not Re: fedora-docs-list Digest, Vol 6, Issue 25) In-Reply-To: <26597.199.224.21.254.1093262535.squirrel@TheRockmere.com> References: <20040821160013.2619A735B3@hormel.redhat.com> <26597.199.224.21.254.1093262535.squirrel@TheRockmere.com> Message-ID: <1093282110.17095.29052.camel@erato.phig.org> On Mon, 2004-08-23 at 05:02, redwire at therockmere.com wrote: > > > >> On Thu, 2004-08-19 at 21:34, Karsten Wade wrote: > > > > * Because of concerns over support, availability, redundancy, and > > security, we don't want non-FDP doc or source repositories to be seen as > > "officially" connected to the project. For example, if someone's SCM > > gets compromised and a rootkit trojan is loaded into document tarball > > ... well, bad things could happen. > > > If RH is THAT worried about contamination, then maybe THEY should release > SOME documentation... Red Hat releases plenty of documentation, but not about Fedora. It is up to the Fedora docs project to release documentation. That's us. Doesn't matter what is after the @ in an email address. > You may not want the appearance of some site appearing to be 'official', > but I think that this is a little bit of a scare tactic. The desire for documentation that comes from Fedora and is closely aligned with the overall project from the inside ... that request is coming from users. It is not FUD. You, like anyone else, are welcome to make as many docs repositories as you desire. You can feature the FDL docs from the Fedora docs project. I'm just not going to recommend that people here spend their time working on non-FDP docs repositories. We have a huge amount of work to accomplish and don't need more distractions. > Thousands of programs are released via apt, rpm repositories and yum... > ALL without the fear of contamination or appearance of impropropiety. And > all done with the help of willing participanting websites AND > ENCOURAGEMENT from the authors. MANY run with the sole support of the > webmaster. Yes, and the same is true of documentation. However, the wise RPM consumer will want to get packages from a safe and proven location. Concern about trojaned packages is not just some delusion. There is a reason why packages are signed and MD5SUM values are provided from proper mirrors and repositories. That's just a reality, not a slight directed at your website. > Why is the thought of spreading the information such a fearful subject? I think you have misinterpreted this discussion. AFAIK, no one has said anything about being afraid of spreading information and knowledge. I did say that I thought your idea sounded like it was breaking off from this project, instead of just providing temporary support services. Your email about FedoraDocs.com shows that you are in fact starting a separate project. Good. This is one of the many good facets of open source, the ability to go one's own way. My concern is that spreading ourselves thin into various one-off docs projects that don't know how to support themselves in the long term is a waste of our energy, and does little for the community other than to create yet another site with aging docs. We all share the responsibility in the FDP for the lack of progress so far, just as we all share responsibility for the progress we've made and will continue to make. As much as anyone, I _know_ how lame the last ten months have been. Two full releases with zero documentation[1]. Shameful. But I know just as vehemently that losing our direction now will mean the death of the project as it now stands. Maybe that would be a good thing eventually if we can't get our act together, but not yet. - Karsten [1] Okay, I'm exaggerating to make a point. We've had stellar release notes, the Jargon Buster, the SELinux FAQ. Still, pretty thin compared to what we could have done in the same amount of time. -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 23 17:35:18 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 23 Aug 2004 10:35:18 -0700 Subject: FDP docs process - round 2 In-Reply-To: <1093182041.7704.26.camel@bettie.internal.frields.org> References: <1092664199.3459.7055.camel@erato.phig.org> <1093181644.7704.23.camel@bettie.internal.frields.org> <1093182041.7704.26.camel@bettie.internal.frields.org> Message-ID: <1093282517.17095.29094.camel@erato.phig.org> On Sun, 2004-08-22 at 06:40, Paul W. Frields wrote: > On Sun, 2004-08-22 at 09:34, Paul W. Frields wrote: > > "If you think a specific piece of documentation is needed, enter a > > request for enhancement (RFE) in Bugzilla. Look over the > > _current_list_of_bugs_[1] first to be sure your request is not already > > in progress. If it is not, _enter_a_new_RFE_bug_[2] and it will enter > > the queue." > > > > ...or something to that effect. > > > > ([1] & [2] can duplicate the links at the Docs Project page. ) > ^^^ > > [2] should not *duplicate* the link at the FDP page. It needs to > be a link to a (possibly partially completed?) Bugzilla entry form, not > a query. +1 for a saved (bookmarked) Bugzilla entry form. This has worked well for the SELinux FAQ for me and for Ed for the release notes. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 23 17:43:45 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 23 Aug 2004 10:43:45 -0700 Subject: More docs ideas? In-Reply-To: <1093264333.2522.27.camel@berlin.east.gov> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> Message-ID: <1093283024.17095.29142.camel@erato.phig.org> On Mon, 2004-08-23 at 05:32, Paul W. Frields wrote: > (Top posting because I'm basically forwarding.) > > There's another docs idea toward the bottom of this post. Unfortunately, > recent changes in the kernel building schema for FC2 and FC3test* have > started some flamewars, mostly (methinks) because of misunderstanding. > (C'est la vie.) But it does argue for some quick docs work. There is a > link below to a write-up that Arjan van de Ven did for FedoraNews.org > not too long ago. I'm sticking it in the archives for reference. > > Again, if no one has a quibble, I'll Bugzilla this. This is a super-important document that we could produce fairly quickly - Fedora Kernel Short Guide to Changes, or something. If one or more people have the time to tackle this, I recommend we approach Arjan with something like, "Fedora docs project would like to assign this writer to work with you on getting this new kernel document written. We've started with what you did for FedoraNEWS.org, put it into our template, and are ready to work on it further." If anyone can reliably tackle this, it requires existing knowledge of the history of kernel and kernel-source, as well as the time to get familiar with the current discussion. I'll be happy to handle the introduction to Arjan. - Karsten > > On Sun, 2004-08-22 at 14:45, Bob Arendt wrote: > > Arjan van de Ven wrote: > > >>If fedora.us accepts the fact that multiple-repos (co)exist, and would > > >>be willing to work on interoperability/compatibility I would very much > > >>welcome a new kernel module framework outside of Arjan's reach ;) > > > > > > You know, YOU and 2 or 3 other people are the reason I entirely stopped > > > caring about this. No matter what I do you or those others will just > > > flame me and personally attack me. So I rather do just nothing and > > > ignore the entire thing. > > > As a kernel source user, module builder, I'd like to speak in *favor* > > of the new kernel src.rpm scheme. > > > > Using mod-versioned kernels, I used to have to rebuild kernel-source > > up through the "make dep" stage to get valid kernel headers to compile > > against. It was error-prone; If I didn't change the Makefile > > EXTRAVERSION, or copy the correct architecture config file to start > > with, I got incompatible headers. Building a module for multiple > > archs, this was repetitious. OR - I could burn a *lot* of disk space > > replicating the kernel source just to build the headers to build > > modules against. Yech. > > > > Now the kernel headers are included with each kernel install! > > Fantastic! No more special builds. ASCII headers compress really > > well, so there's little inflation in binary-kernel rpm size. And it's > > much easier to build & install the 3rd party hardware drivers we use. > > Now 3rd party delivered build scripts "just work" since the correct > > headers can always be found with the kernel. Vendors have gotten > > fewer callbacks regarding installation. It no longer depends on the > > last state of the /usr/src/linux* since someone last used the > > kernel-source. In fact, it removes the kernel-source requirement > > entirely. > > > > Better yet, the kernel src.rpm now gives me direct visibility into the > > patches that RedHat's applied. kernel-source always used to bug me, > > since all I got was the post-patched kernel-source without much info > > on how it differed from kernel.org's version. If I just "rpm -i", I > > get the virgin kernel source tarball in the ./SOURCES directory. With > > "rpmbuild -bp " I get the RedHat patched kernel, equivalent to > > kernel-source. Better yet, I can look in kernel.spec and see the > > patches applied (with comments) one-by-one. Though the src.rpm had > > been available, I'd never really looked at it since most of the > > literature (well .. web-searches) steered me towards kernel-source. > > > > Arjan's write-up here: http://fedoranews.org/colin/fnu/issue14.shtml > > seemed to cover the history and issues pretty well. It would be good > > to get this written up in a HOWTO or some more easily findable docs. > > Especially prior to RHEL4, where I'd expect to see some quality docs > > on these procedures, delivered as part of RHEL4 documentation. > > > > Good work Arjan. > > -- > Paul W. Frields, RHCE -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 23 18:23:46 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 23 Aug 2004 11:23:46 -0700 Subject: More docs ideas? In-Reply-To: <1093283024.17095.29142.camel@erato.phig.org> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> Message-ID: <1093285425.17095.29377.camel@erato.phig.org> On Mon, 2004-08-23 at 10:43, Karsten Wade wrote: > On Mon, 2004-08-23 at 05:32, Paul W. Frields wrote: > > (Top posting because I'm basically forwarding.) > > > > There's another docs idea toward the bottom of this post. Unfortunately, > > recent changes in the kernel building schema for FC2 and FC3test* have > > started some flamewars, mostly (methinks) because of misunderstanding. > > (C'est la vie.) But it does argue for some quick docs work. There is a > > link below to a write-up that Arjan van de Ven did for FedoraNews.org > > not too long ago. I'm sticking it in the archives for reference. > > > > Again, if no one has a quibble, I'll Bugzilla this. > > This is a super-important document that we could produce fairly quickly > - Fedora Kernel Short Guide to Changes, or something. It's so funny how seeing your own email in a thread can make something clearer ... As important as this issue is, does it fit into the focus of the Fedora docs project? It is actually just the kind of thing that FedoraNEWS.org was created for. OTOH, it is good background about changes in the kernel packages, and may be most of a tutorial on How To Do Funky Things to Your Kernel, aka, You Break It, You Keep It. Short term best might be a more formal FedoraNEWS.org article, and longer term best might be to include these changes in a short tutorial for FC3. Other ideas? - Karsten > If one or more people have the time to tackle this, I recommend we > approach Arjan with something like, "Fedora docs project would like to > assign this writer to work with you on getting this new kernel document > written. We've started with what you did for FedoraNEWS.org, put it > into our template, and are ready to work on it further." > > If anyone can reliably tackle this, it requires existing knowledge of > the history of kernel and kernel-source, as well as the time to get > familiar with the current discussion. I'll be happy to handle the > introduction to Arjan. > > - Karsten > > > > On Sun, 2004-08-22 at 14:45, Bob Arendt wrote: > > > Arjan van de Ven wrote: > > > >>If fedora.us accepts the fact that multiple-repos (co)exist, and would > > > >>be willing to work on interoperability/compatibility I would very much > > > >>welcome a new kernel module framework outside of Arjan's reach ;) > > > > > > > > You know, YOU and 2 or 3 other people are the reason I entirely stopped > > > > caring about this. No matter what I do you or those others will just > > > > flame me and personally attack me. So I rather do just nothing and > > > > ignore the entire thing. > > > > > As a kernel source user, module builder, I'd like to speak in *favor* > > > of the new kernel src.rpm scheme. > > > > > > Using mod-versioned kernels, I used to have to rebuild kernel-source > > > up through the "make dep" stage to get valid kernel headers to compile > > > against. It was error-prone; If I didn't change the Makefile > > > EXTRAVERSION, or copy the correct architecture config file to start > > > with, I got incompatible headers. Building a module for multiple > > > archs, this was repetitious. OR - I could burn a *lot* of disk space > > > replicating the kernel source just to build the headers to build > > > modules against. Yech. > > > > > > Now the kernel headers are included with each kernel install! > > > Fantastic! No more special builds. ASCII headers compress really > > > well, so there's little inflation in binary-kernel rpm size. And it's > > > much easier to build & install the 3rd party hardware drivers we use. > > > Now 3rd party delivered build scripts "just work" since the correct > > > headers can always be found with the kernel. Vendors have gotten > > > fewer callbacks regarding installation. It no longer depends on the > > > last state of the /usr/src/linux* since someone last used the > > > kernel-source. In fact, it removes the kernel-source requirement > > > entirely. > > > > > > Better yet, the kernel src.rpm now gives me direct visibility into the > > > patches that RedHat's applied. kernel-source always used to bug me, > > > since all I got was the post-patched kernel-source without much info > > > on how it differed from kernel.org's version. If I just "rpm -i", I > > > get the virgin kernel source tarball in the ./SOURCES directory. With > > > "rpmbuild -bp " I get the RedHat patched kernel, equivalent to > > > kernel-source. Better yet, I can look in kernel.spec and see the > > > patches applied (with comments) one-by-one. Though the src.rpm had > > > been available, I'd never really looked at it since most of the > > > literature (well .. web-searches) steered me towards kernel-source. > > > > > > Arjan's write-up here: http://fedoranews.org/colin/fnu/issue14.shtml > > > seemed to cover the history and issues pretty well. It would be good > > > to get this written up in a HOWTO or some more easily findable docs. > > > Especially prior to RHEL4, where I'd expect to see some quality docs > > > on these procedures, delivered as part of RHEL4 documentation. > > > > > > Good work Arjan. > > > > -- > > Paul W. Frields, RHCE > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Mon Aug 23 19:44:00 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 23 Aug 2004 15:44:00 -0400 Subject: More docs ideas? In-Reply-To: <1093285425.17095.29377.camel@erato.phig.org> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> Message-ID: <1093290239.3627.18.camel@berlin.east.gov> On Mon, 2004-08-23 at 14:23, Karsten Wade wrote: > > > (Top posting because I'm basically forwarding.) > > > > > > There's another docs idea toward the bottom of this post. Unfortunately, > > > recent changes in the kernel building schema for FC2 and FC3test* have > > > started some flamewars, mostly (methinks) because of misunderstanding. > > > (C'est la vie.) But it does argue for some quick docs work. There is a > > > link below to a write-up that Arjan van de Ven did for FedoraNews.org > > > not too long ago. I'm sticking it in the archives for reference. > > > > > > Again, if no one has a quibble, I'll Bugzilla this. > > > > This is a super-important document that we could produce fairly quickly > > - Fedora Kernel Short Guide to Changes, or something. > > It's so funny how seeing your own email in a thread can make something > clearer ... > > As important as this issue is, does it fit into the focus of the Fedora > docs project? It is actually just the kind of thing that FedoraNEWS.org > was created for. > > OTOH, it is good background about changes in the kernel packages, and > may be most of a tutorial on How To Do Funky Things to Your Kernel, aka, > You Break It, You Keep It. I think it works as a short tutorial, maybe "Kernel Compilation for &FC;." It would be good to have on the &FDPDOCS-URL; site because many, *many* users do not follow fedora-devel-list (including a lot of those who read fedora-list). If we have a short tutorial there, it will stave off many repetitive threads on fedora-list and eliminate user misunderstandings or confusion. I believe it definitely falls into our charter. My idea of the outcome would be a document that simply states the steps used in &FC; 1 and 2 (old way), and then for &FC; 3 and (hopefully) beyond. Additional sections could be added for later revisions of the process without too much of a hassle. > Short term best might be a more formal FedoraNEWS.org article, and > longer term best might be to include these changes in a short tutorial > for FC3. Other ideas? I think you've the right idea, but after all &FDPDOCS-URL; is straight from the horse's mouth, so to speak. I don't believe we need to scoop anyone, but by the same token, ignoring all the low-hanging fruit simply means our arms get tired faster. (I am the Master of Metaphor Mixture! Bow before my compositional ineptitude!) Ahem. In any case, being able to point users to this document is a nice way also to advertise that our project is indeed alive, well, kicking, and productive. Yet, it's not simply busy work. I think users will really benefit from this guide, maybe more than other more fundamental docs, since there are so many Fedora users out there who, for better or worse, make kernel compilation one of the first things they do "out of the box." Best of all, this document could be easily snipped to fit into a larger reference manual later, so we're getting some addition ROI there. > - Karsten > > If one or more people have the time to tackle this, I recommend we > > approach Arjan with something like, "Fedora docs project would like to > > assign this writer to work with you on getting this new kernel document > > written. We've started with what you did for FedoraNEWS.org, put it > > into our template, and are ready to work on it further." > > > > If anyone can reliably tackle this, it requires existing knowledge of > > the history of kernel and kernel-source, as well as the time to get > > familiar with the current discussion. I'll be happy to handle the > > introduction to Arjan. [...snip...] Agreed for this part. I wish I had the time to do this myself, but I don't, so is there someone on the list who is interested, before we Bugzilla this? -- Paul W. Frields, RHCE From kwade at redhat.com Mon Aug 23 20:59:44 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 23 Aug 2004 13:59:44 -0700 Subject: FDP docs process - round 2 In-Reply-To: <1092664199.3459.7055.camel@erato.phig.org> References: <1092664199.3459.7055.camel@erato.phig.org> Message-ID: <1093294783.17095.30196.camel@erato.phig.org> On Mon, 2004-08-16 at 06:50, Karsten Wade wrote: > As detailed in > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129993. I'm quoting from the last two paragraphs of: https://bugzilla.redhat.com/bugzilla/attachment.cgi?id=102760&action=view ## snip "There is likely a reason to maintain an old document for at least one or more versions of FC. A worthy document can be carried on by the Fedora Legacy project, if they see fit, when a version of FC is handed off by the FC developers to the Legacy project. If you do find that it's necessary to maintain multiple versions, you will want to have the CVS branched. File a bug report for that, assigned to the fedora-docs CVS maintainer, who may pass the ticket on to the FC CVS maintainer. If you come to a time when you realize you no longer want to or are able to maintain your document, you should evaluate if the document deserves to be continued. Either way, announce to the mailing list and specifically the editor(s) about your decision and recommendations about the fate of your document. If possible, look for a person to hand-off maintenance to, and work with him/her/them for as long as possible to do the hand-off. For more details, see the (unwritten) chapter in the Documentation Guide about document hand-off." ## fin snip I think there's a step/process missing in the middle there. I just encountered having two active versions of the "same" document and need another doc-bug for it. I got to thinking about how this could be handled in the process, and so am proposing a solution, presented as a *new* lifecycle for a document, DocA: 1. Open BugA1 for DocA while you are writing it, assigned to the in-progress doc tracker bug, TrackProgress. BugA1 is the bug you pass to editors, QA and release, etc. as defined in the process. 2. When ready to post, reassign BugA1 to TrackRelease, the release tracking bug. 3. When DocA is released against a version of Fedora, the associated BugA1 is sent back to TrackProgress. It remains in TrackProgress while it is being maintained. 4. At some point, Fedora releases a new version, and DocA is going to be branched for the new version into DocA1. At this point, BugA2 is opened for DocA2, the new version. BugA2 and BugA1 can now work in parallel, each pointing at a specific version of a doc in CVS. 5. BugA1 gets changed from version 'devel' to the specific version of FC it is associated with. BugA2 is set to version 'devel' or a 'testn' if appropriate. 6. When DocA1 moves to unmaintained or is handed-off we close the associated BugA1. Pluses? Minuses? I'll fix this into the XML process doc if it makes sense. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 23 21:08:18 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 23 Aug 2004 14:08:18 -0700 Subject: More docs ideas? In-Reply-To: <1093290239.3627.18.camel@berlin.east.gov> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> Message-ID: <1093295298.17095.30239.camel@erato.phig.org> On Mon, 2004-08-23 at 12:44, Paul W. Frields wrote: > > I think it works as a short tutorial, maybe "Kernel Compilation for > &FC;." It would be good to have on the &FDPDOCS-URL; site because many, > *many* users do not follow fedora-devel-list (including a lot of those > who read fedora-list). If we have a short tutorial there, it will stave > off many repetitive threads on fedora-list and eliminate user > misunderstandings or confusion. I believe it definitely falls into our > charter. Okay, +1, I'm convinced. Wish I had time to write it, too. It wouldn't take too much to put together, if one is familiar with the subject material already. > Agreed for this part. I wish I had the time to do this myself, but I > don't, so is there someone on the list who is interested, before we > Bugzilla this? We can definitely create a tracker bug for this, attach it to the TrackIdeas bu{g,cket}. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Tue Aug 24 17:04:14 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 24 Aug 2004 18:04:14 +0100 Subject: Bug submission? In-Reply-To: <1093290239.3627.18.camel@berlin.east.gov> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> Message-ID: <1093367054.2517.18.camel@homer> On Mon, 2004-08-23 at 20:44, Paul W. Frields wrote: > I think it works as a short tutorial, maybe "Kernel Compilation for > &FC;." It would be good to have on the &FDPDOCS-URL; site I've noted a couple of times that the #included entities are upper case defined, i.e. intended for SGML applications. A bug submission to get them lower cased? Intent: Ease of use. Thoughts? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Tue Aug 24 17:08:27 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 24 Aug 2004 18:08:27 +0100 Subject: FDP docs process - round 2 In-Reply-To: <1093294783.17095.30196.camel@erato.phig.org> References: <1092664199.3459.7055.camel@erato.phig.org> <1093294783.17095.30196.camel@erato.phig.org> Message-ID: <1093367307.2517.23.camel@homer> On Mon, 2004-08-23 at 21:59, Karsten Wade wrote: > I think there's a step/process missing in the middle there. I just > encountered having two active versions of the "same" document and need > another doc-bug for it. I got to thinking about how this could be > handled in the process, and so am proposing a solution, presented as a > *new* lifecycle for a document, DocA: > > 1. Open BugA1 for DocA while you are writing it, assigned to the > in-progress doc tracker bug, TrackProgress. BugA1 is the bug you pass > to editors, QA and release, etc. as defined in the process. > > 2. When ready to post, reassign BugA1 to TrackRelease, the release > tracking bug. Which makes one 'name' align with two items? > > 3. When DocA is released against a version of Fedora, the associated > BugA1 is sent back to TrackProgress. It remains in TrackProgress while > it is being maintained. And its purpose is... Sounds like the sort of 'what if' guessing that occurs? > > 4. At some point, Fedora releases a new version, and DocA is going to be > branched for the new version into DocA1. At this point, BugA2 is opened > for DocA2, the new version. BugA2 and BugA1 can now work in parallel, > each pointing at a specific version of a doc in CVS. Suggest a KISS principle is far more appropriate. If it happens, deal with it. > Pluses? Minuses? I'll fix this into the XML process doc if it makes > sense. Not to me Karsten. Sounds like ISO9000 on steroids. Processes for the sake of it? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Tue Aug 24 17:39:37 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 24 Aug 2004 10:39:37 -0700 Subject: Bug submission? In-Reply-To: <1093367054.2517.18.camel@homer> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> Message-ID: <1093369177.17095.36533.camel@erato.phig.org> On Tue, 2004-08-24 at 10:04, Dave Pawson wrote: > On Mon, 2004-08-23 at 20:44, Paul W. Frields wrote: > > > I think it works as a short tutorial, maybe "Kernel Compilation for > > &FC;." It would be good to have on the &FDPDOCS-URL; site > > I've noted a couple of times that the #included entities are upper > case defined, i.e. intended for SGML applications. > > A bug submission to get them lower cased? > Intent: Ease of use. If UPPER and lower are both compatible, I guess I don't care. Yes, the upper-case usage is a vestige of SGML. Oh, wait. It would require us to fix every single document we've written so far. This is not a decision to take lightly or do on a whim because it seems easier. Can you provide us some additional reasoning? - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Tue Aug 24 17:42:44 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 24 Aug 2004 13:42:44 -0400 Subject: Bug submission? In-Reply-To: <1093367054.2517.18.camel@homer> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> Message-ID: <1093369363.2252.10.camel@berlin.east.gov> On Tue, 2004-08-24 at 13:04, Dave Pawson wrote: > On Mon, 2004-08-23 at 20:44, Paul W. Frields wrote: > > > I think it works as a short tutorial, maybe "Kernel Compilation for > > &FC;." It would be good to have on the &FDPDOCS-URL; site > > I've noted a couple of times that the #included entities are upper > case defined, i.e. intended for SGML applications. > > A bug submission to get them lower cased? > Intent: Ease of use. > > Thoughts? My $0.02: Having them uppercased also makes them more visible to the "naked eye" in other contexts. I dig 'em the way they are, personally. And of course, there's no reason you can't redefine them locally in your docs. -- Paul W. Frields, RHCE From paul at frields.com Tue Aug 24 17:44:35 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 24 Aug 2004 13:44:35 -0400 Subject: Bug submission? In-Reply-To: <1093369177.17095.36533.camel@erato.phig.org> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> <1093369177.17095.36533.camel@erato.phig.org> Message-ID: <1093369475.2252.13.camel@berlin.east.gov> On Tue, 2004-08-24 at 13:39, Karsten Wade wrote: > > > I think it works as a short tutorial, maybe "Kernel Compilation for > > > &FC;." It would be good to have on the &FDPDOCS-URL; site > > > > I've noted a couple of times that the #included entities are upper > > case defined, i.e. intended for SGML applications. > > > > A bug submission to get them lower cased? > > Intent: Ease of use. > > If UPPER and lower are both compatible, I guess I don't care. Yes, the > upper-case usage is a vestige of SGML. > > Oh, wait. It would require us to fix every single document we've > written so far. This is not a decision to take lightly or do on a whim > because it seems easier. > > Can you provide us some additional reasoning? Mr. Flip-Flop here. I suppose we could add lowercase definitions to the included entities file, right? Of course, I came up with this earth-shattering idea after hitting "Send." :-) -- Paul W. Frields, RHCE From davep at dpawson.co.uk Tue Aug 24 17:57:14 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 24 Aug 2004 18:57:14 +0100 Subject: Bug submission? In-Reply-To: <1093369475.2252.13.camel@berlin.east.gov> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> <1093369177.17095.36533.camel@erato.phig.org> <1093369475.2252.13.camel@berlin.east.gov> Message-ID: <1093370233.2517.48.camel@homer> On Tue, 2004-08-24 at 18:44, Paul W. Frields wrote: > Mr. Flip-Flop here. I suppose we could add lowercase definitions to the > included entities file, right? Only if Karsten isn't going to use them in an SGML environment :-) Then its the latest one that is used. XML processors recognise them as different. entity little entity LITTLE would work for SGML though. Is Karsten the only one working with SGML Tammy? Surely not. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Tue Aug 24 18:10:51 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 24 Aug 2004 14:10:51 -0400 Subject: FDP docs process - round 2 In-Reply-To: <1093367307.2517.23.camel@homer> References: <1092664199.3459.7055.camel@erato.phig.org> <1093294783.17095.30196.camel@erato.phig.org> <1093367307.2517.23.camel@homer> Message-ID: <1093371050.2252.38.camel@berlin.east.gov> On Tue, 2004-08-24 at 13:08, Dave Pawson wrote: > On Mon, 2004-08-23 at 21:59, Karsten Wade wrote: > > I think there's a step/process missing in the middle there. I just > > encountered having two active versions of the "same" document and need > > another doc-bug for it. I got to thinking about how this could be > > handled in the process, and so am proposing a solution, presented as a > > *new* lifecycle for a document, DocA: > > > > 1. Open BugA1 for DocA while you are writing it, assigned to the > > in-progress doc tracker bug, TrackProgress. BugA1 is the bug you pass > > to editors, QA and release, etc. as defined in the process. > > > > 2. When ready to post, reassign BugA1 to TrackRelease, the release > > tracking bug. > > Which makes one 'name' align with two items? I'm not sure, but I don't think that's correct. BugA1 is a single bug at this point, say for "mirror-tutorial". While I'm writing it, it's in progress and blocks the Progress tracker bug. Once it's edited and "camera-ready" (for release on &FDPDOCS-URL; along with everything else ready for a release), we remove it from blocking Progress and add it to blocking Release. The blocking essentially serves as a "checklist" for a bunch of other bugs for a variety of purposes, if I've been thinking about it correctly up until now. > > 3. When DocA is released against a version of Fedora, the associated > > BugA1 is sent back to TrackProgress. It remains in TrackProgress while > > it is being maintained. > And its purpose is... > > Sounds like the sort of 'what if' guessing that occurs? Not at all. When my "mirror-tutorial" has been checked against the current release (let's say FC3, and let's also say in October), and a bunch of docs are "released" by FDP onto the site for user reference, we need some way of showing that those docs are now on a checklist for maintenance. It might also be used for determining obsolescence, or any number of other purposes. One point for Karsten to consider: At the point that release happens, would it be more helpful to have, for example, a FC3DocMaintenance tracker bug? Otherwise our "Progress" tracker begins to get a little muddy in my mind. Not that we should set *that* as a limiting factor, mind you. ;-) In other words, does it get confusing what the "Progress" tracker is for at that point, with some documents that might be a little longer in the growth stage? > > 4. At some point, Fedora releases a new version, and DocA is going to be > > branched for the new version into DocA1. At this point, BugA2 is opened > > for DocA2, the new version. BugA2 and BugA1 can now work in parallel, > > each pointing at a specific version of a doc in CVS. Karsten, if I can reply at this point in the thread: To me this is not confusing if the existing bug blocks "FC3DocMaintenance," and a new bug opens for "Progress." Am I reading this right? If I'm hopelessly lost here, I'd appreciate more explanation when you have time, since I am not old hat at Bugzilla usage, other than the odd bug that I've entered and looked in on from time to time. > Suggest a KISS principle is far more appropriate. > If it happens, deal with it. I couldn't disagree more with the second sentence. That's a recipe for disaster in a distributed project like this. As for the first, well, as long as we can have the process clearly written down somewhere in a recipe format, then I don't see how it could get much easier. Contributors *will* have to follow some logical rules in order for this to work, otherwise it's the wild wild west. Remember that not every contributor has to do this stuff, but *someone* has to for the process to work, and in a lot of cases that will be the person who is responsible for maintenance of a document. If the responsibility isn't designated ahead of time, it's very easy for the FDP to become a dumping ground for documentation that becomes as useless or outdated as much of the stuff you find by just doing Google searches. > > Pluses? Minuses? I'll fix this into the XML process doc if it makes > > sense. > > Not to me Karsten. Sounds like ISO9000 on steroids. Processes for the > sake of it? I don't see that, sorry. Personally, I am already finding Bugzilla an indispensable aid as a TODO I sit down to work on this project. That wouldn't be the case if Karsten hadn't delineated some process steps to begin with. I think the new ones sound pretty logical, with the possible exceptions above. (Those may simply be a matter of my not understanding the concept, we'll see.) -- Paul W. Frields, RHCE From paul at frields.com Tue Aug 24 18:12:39 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 24 Aug 2004 14:12:39 -0400 Subject: Bug submission? In-Reply-To: <1093370233.2517.48.camel@homer> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> <1093369177.17095.36533.camel@erato.phig.org> <1093369475.2252.13.camel@berlin.east.gov> <1093370233.2517.48.camel@homer> Message-ID: <1093371159.2252.40.camel@berlin.east.gov> On Tue, 2004-08-24 at 13:57, Dave Pawson wrote: > On Tue, 2004-08-24 at 18:44, Paul W. Frields wrote: > > Mr. Flip-Flop here. I suppose we could add lowercase definitions to the > > included entities file, right? > > Only if Karsten isn't going to use them in an SGML environment :-) > Then its the latest one that is used. > > XML processors recognise them as different. > > > entity little > entity LITTLE would work for SGML though. > > > Is Karsten the only one working with SGML Tammy? Surely not. OK, I didn't know that, thanks for the info. In that case, I definitely vote to leave them alone. -- Paul W. Frields, RHCE From kwade at redhat.com Tue Aug 24 19:09:19 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 24 Aug 2004 12:09:19 -0700 Subject: Bug submission? In-Reply-To: <1093370233.2517.48.camel@homer> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> <1093369177.17095.36533.camel@erato.phig.org> <1093369475.2252.13.camel@berlin.east.gov> <1093370233.2517.48.camel@homer> Message-ID: <1093374558.17095.37198.camel@erato.phig.org> On Tue, 2004-08-24 at 10:57, Dave Pawson wrote: > On Tue, 2004-08-24 at 18:44, Paul W. Frields wrote: > > Mr. Flip-Flop here. I suppose we could add lowercase definitions to the > > included entities file, right? > > Only if Karsten isn't going to use them in an SGML environment :-) > Then its the latest one that is used. > > XML processors recognise them as different. > > > entity little > entity LITTLE would work for SGML though. > > > Is Karsten the only one working with SGML Tammy? Surely not. Irrelevant, actually. We've been authoring inside of Red Hat in SGML for years, but that has nothing to do with Fedora docs project and what we decide to do. Following your KISS, I'm tempted to leave it alone in terms of what has been done already. Perhaps, as you seem to suggest, we can duplicate the entries in lower case and specify that lowercase is recommended. I agree with Paul that they are easier to see, but I said the same thing when I used to capitalize all my HTML tags. ;-) For future proofing, we would be wise to align ourselves with XML usage practices as much as we can. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 24 21:53:18 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 24 Aug 2004 14:53:18 -0700 Subject: FDP docs process - round 2 In-Reply-To: <1093371050.2252.38.camel@berlin.east.gov> References: <1092664199.3459.7055.camel@erato.phig.org> <1093294783.17095.30196.camel@erato.phig.org> <1093367307.2517.23.camel@homer> <1093371050.2252.38.camel@berlin.east.gov> Message-ID: <1093384397.17095.38534.camel@erato.phig.org> On Tue, 2004-08-24 at 11:10, Paul W. Frields wrote: > On Tue, 2004-08-24 at 13:08, Dave Pawson wrote: > > On Mon, 2004-08-23 at 21:59, Karsten Wade wrote: > > > I think there's a step/process missing in the middle there. I just > > > encountered having two active versions of the "same" document and need > > > another doc-bug for it. I got to thinking about how this could be > > > handled in the process, and so am proposing a solution, presented as a > > > *new* lifecycle for a document, DocA: > > > > > > 1. Open BugA1 for DocA while you are writing it, assigned to the > > > in-progress doc tracker bug, TrackProgress. BugA1 is the bug you pass > > > to editors, QA and release, etc. as defined in the process. > > > > > > 2. When ready to post, reassign BugA1 to TrackRelease, the release > > > tracking bug. > > > > Which makes one 'name' align with two items? > > I'm not sure, but I don't think that's correct. BugA1 is a single bug at > this point, say for "mirror-tutorial". While I'm writing it, it's in > progress and blocks the Progress tracker bug. Once it's edited and > "camera-ready" (for release on &FDPDOCS-URL; along with everything else > ready for a release), we remove it from blocking Progress and add it to > blocking Release. The blocking essentially serves as a "checklist" for a > bunch of other bugs for a variety of purposes, if I've been thinking > about it correctly up until now. Yes. You can view a tracker bug's dependency tree[1] and see what is opened, closed, and all sort of states. That tracker bug can then roll-up into higher tracker bugs. Some writers who use bz as a project tool will have a bug for every chapter, which blocks the bug that is for the whole guide; that whole guide bug can block a team production bug, which can then roll up into a QA bug, then a release bug, then closed. It's simply a dependency tree, and the meaning is in how we assign it. [1] https://bugzilla.redhat.com/bugzilla/showdependencytree.cgi?id=129807 > > > > 3. When DocA is released against a version of Fedora, the associated > > > BugA1 is sent back to TrackProgress. It remains in TrackProgress while > > > it is being maintained. > > And its purpose is... > > > > Sounds like the sort of 'what if' guessing that occurs? > > Not at all. When my "mirror-tutorial" has been checked against the > current release (let's say FC3, and let's also say in October), and a > bunch of docs are "released" by FDP onto the site for user reference, we > need some way of showing that those docs are now on a checklist for > maintenance. It might also be used for determining obsolescence, or any > number of other purposes. > > One point for Karsten to consider: At the point that release happens, > would it be more helpful to have, for example, a FC3DocMaintenance > tracker bug? Otherwise our "Progress" tracker begins to get a little > muddy in my mind. Not that we should set *that* as a limiting factor, > mind you. ;-) In other words, does it get confusing what the "Progress" > tracker is for at that point, with some documents that might be a little > longer in the growth stage? That is a good idea, to have a separate maintenance bug. Still, since a bug can block more than one trackers, we might one to have doc tracking bugs block both Progress and Maintenance -if- the doc is in active revision. That might be more rare than I realize ... it's happened to me with the SELinux FAQ for FC2, there were some significant changes to sysvinit that happened in a kernel upgrade, which needed to be reflected in the FAQ. This is more like using the Progress tracker to keep track of a doc that is being added to for errata purposes, etc. It will likely stay in that Progress location for a shorter amount of time. > > > 4. At some point, Fedora releases a new version, and DocA is going to be > > > branched for the new version into DocA1. At this point, BugA2 is opened > > > for DocA2, the new version. BugA2 and BugA1 can now work in parallel, > > > each pointing at a specific version of a doc in CVS. > > Karsten, if I can reply at this point in the thread: To me this is not > confusing if the existing bug blocks "FC3DocMaintenance," and a new bug > opens for "Progress." Am I reading this right? No, that makes sense. :) > > Suggest a KISS principle is far more appropriate. > > If it happens, deal with it. > > I couldn't disagree more with the second sentence. That's a recipe for > disaster in a distributed project like this. As for the first, well, as > long as we can have the process clearly written down somewhere in a > recipe format, then I don't see how it could get much easier. > Contributors *will* have to follow some logical rules in order for this > to work, otherwise it's the wild wild west. > > Remember that not every contributor has to do this stuff, but *someone* > has to for the process to work, and in a lot of cases that will be the > person who is responsible for maintenance of a document. If the > responsibility isn't designated ahead of time, it's very easy for the > FDP to become a dumping ground for documentation that becomes as useless > or outdated as much of the stuff you find by just doing Google searches. > > > > Pluses? Minuses? I'll fix this into the XML process doc if it makes > > > sense. > > > > Not to me Karsten. Sounds like ISO9000 on steroids. Processes for the > > sake of it? > > I don't see that, sorry. Personally, I am already finding Bugzilla an > indispensable aid as a TODO I sit down to work on this project. That > wouldn't be the case if Karsten hadn't delineated some process steps to > begin with. I think the new ones sound pretty logical, with the possible > exceptions above. (Those may simply be a matter of my not understanding > the concept, we'll see.) +1 :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From dataking at cox.net Wed Aug 25 00:36:03 2004 From: dataking at cox.net (D@7@k|N&) Date: Tue, 24 Aug 2004 17:36:03 -0700 Subject: Fundamentals Message-ID: OK..so I have a few questions, that (I know) have probably been answered a thousand times, and the poor posters were flamed continuously for days on end (OK..maybe I'm a member of too many mailing lists ;). Anyhow, I'm curious how you guys work on documentation projects individually. Do you write in your favorite text editor, then pass the subject matter to your editor to parse it into XML? Are all of you so good that you compose in XML? Is there an emacs plugin that I'm missing that allows you to write your content, then adds all of the *basic* XML tags for you? Where does the author start and the editor begin? Do you compose in your favorite editor, then once the content is complete, open it in emacs using the template, and parse it that way? What's the /theoretical/ process, and the /practical/ application of that process? I've skimmed the Documentation Guide, and the Quick Start, and didn't get a whole lot out of it other than I should be either an author, or an editor. Karsten has volunteered to be my editor for this particular project, so I guess that makes me the author. ;) So are there considerations to be made while I'm writing the content? Will those come after the fact? Are they my responsibility or the editors? I apologize for so many questions, but this is my first "official" documentation project, so I want to make sure I get it right. ;) -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 -------------- next part -------------- An HTML attachment was scrubbed... URL: From paul at frields.com Wed Aug 25 02:04:31 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 24 Aug 2004 22:04:31 -0400 Subject: Fundamentals In-Reply-To: References: Message-ID: <1093399471.7559.27.camel@bettie.internal.frields.org> Hi, umm, D at 7@k|N&. (Perhaps you should consider using a real name, I feel really silly typing that!) :-) I'll break out answers below that will hopefully be a little helpful for you. Oh, in the future, could you be so kind as to *not* use HTML in your posts to the list? Case in point, your post comes out on my screen so small I can barely read it. It's considered a "best practice" to use plain text only for e-mail to the list. Sorry for the etiquette detour there, and I apologize to all if Evolution mangles this reply into HTML. On Tue, 2004-08-24 at 20:36, D at 7@k|N& wrote: > OK?.so I have a few questions, that (I know) have probably been > answered a thousand times, and the poor posters were flamed > continuously for days on end (OK?.maybe I?m a member of too many > mailing lists ;). Anyhow, I?m curious how you guys work on > documentation projects individually. Do you write in your favorite > text editor, then pass the subject matter to your editor to parse it > into XML? You can do this if XML is beyond your means. But frankly, if you're comfortable writing HTML or using "styles" in your favorite word processor, Docbook XML is really not any harder. You have to write the tags, true, but there are tools to help. Read on for more.... > Are all of you so good that you compose in XML? I'm a perfect case study for this question. I didn't know *any* DocBook before last year, and I don't know a ton of it now, for that matter. But I know *enough*, and it only took an hour or two to get the hang of it. > Is there an emacs plugin that I?m missing that allows you to write > your content, then adds all of the *basic* XML tags for you? Yes. At a minimum, install psgml, which came with your Fedora distribution. You should already have installed the "Authoring and Publishing" group of tools from your System Settings => Add/Remove Software tool, which is actually system-config-packages. There are other, and many would argue better, tools, such as psgmlx or nxml-mode, which are essentially plugins for Emacs. (Emacs devotees, please don't flame the wording, I'm purposefully simplifying here, in large part for myself too.) They do all the cool work like highlighting your tags, indenting things nicely, and letting you use keyboard shortcuts and auto-completion for tag names. For example, in psgml, you can hit Ctrl+C, "<" to start a tag, then type the first few letters and hit Tab to complete the name, or get a list. Then you hit Enter to insert the tag, and just keep typing. You get used to this VERY fast. I don't even notice doing it anymore. Other tools work similarly. You should read the Documentation Guide, available at the FDP home page at http://fedora.redhat.com/projects/docs/ ... don't skim it, really READ it, and you'll learn a lot. I did. Erm, eventually. :-) > Where does the author start and the editor begin? Reading the archives and Karsten's process document (see https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129993) will give you a better idea how this works. > Do you compose in your favorite editor, then once the content is > complete, open it in emacs using the template, and parse it that way? > What?s the /theoretical/ process, and the /practical/ application of > that process? I just write in Emacs, it's actually easier that way. You can just write big sections with notes and fill them in later as you go. > I?ve skimmed the Documentation Guide, and the Quick Start, and didn?t > get a whole lot out of it other than I should be either an author, or > an editor. See above comment. :-) We really need authors right now, to be honest. It would really suck for everyone to want to be an editor, and have nothing to edit! You can do both for different documents, but in all honesty, I would recommend to any new person coming in that authoring is the way to go right now. Just my $0.02. I have a feeling we will all be doubling up a bit to get things off the ground in the next few months, if we don't want to be embarrassed one day by the fact that FC4 is on the way without (yet again) an installation guide, for example. > Karsten has volunteered to be my editor for this particular project, > so I guess that makes me the author. ;) So are there considerations > to be made while I?m writing the content? Will those come after the > fact? Are they my responsibility or the editors? His process document will tell you a lot about this. > I apologize for so many questions, but this is my first ?official? > documentation project, so I want to make sure I get it right. ;) Asking questions is always the right way to start. > <== dataking's pgp ==> > 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 Shouldn't I know your name before I trust your key? :-) Tee hee, just a thought. Welcome aboard and hope you're excited about the work, there's a lot to go around, it seems! -- Paul W. Frields, RHCE From byte at aeon.com.my Wed Aug 25 01:57:33 2004 From: byte at aeon.com.my (Colin Charles) Date: Wed, 25 Aug 2004 11:57:33 +1000 Subject: FedoraCommunity.org (was:Re: fedora-docs bugs) In-Reply-To: <200408131607.06416.hoyt@cavtel.net> References: <1092318823.18844.155.camel@berlin.east.gov> <1092411986.2449.4.camel@berlin.east.gov> <1092421880.4488.35482.camel@erato.phig.org> <200408131607.06416.hoyt@cavtel.net> Message-ID: <1093399053.12188.330.camel@albus.aeon.com.my> On Sat, 2004-08-14 at 06:07, Hoyt wrote: > If someone hosted a static page with a URL of fedoracommunity.org > gateway-style that provided a list of non-RH community-based resources, > including Google search hints and un-commented links to Fedora-related sites, > that should easily pass muster for mention in the README. No, you are mistaken > Consider it done; that someone will be me. I just registered the domain name > and will be hosting the site by next week on a Fedora server, no less. Why, when the actual plan is to have http://www.fedoraproject.org/ actually be the nice new shiny website? In the meantime, you're better off starting a Wiki page there... -- Colin Charles, byte at aeon.com.my http://www.bytebot.net/ "First they ignore you, then they laugh at you, then they fight you, then you win." -- Mohandas Gandhi From dataking at cox.net Wed Aug 25 03:24:35 2004 From: dataking at cox.net (D@7@k|N&) Date: Tue, 24 Aug 2004 20:24:35 -0700 Subject: Fundamentals In-Reply-To: <1093399471.7559.27.camel@bettie.internal.frields.org> Message-ID: -----Original Message----- From: fedora-docs-list-bounces at redhat.com [mailto:fedora-docs-list-bounces at redhat.com] On Behalf Of Paul W. Frields Sent: Tuesday, August 24, 2004 7:05 PM To: dataking at cox.net; For participants of the docs project Subject: Re: Fundamentals Hi, umm, D at 7@k|N&. (Perhaps you should consider using a real name, I feel really silly typing that!) :-) The name is Charlie. I started with the "handled" address 'cause I wasn't sure how involved (if at all) I would be in this project. Also, if D at 7@k|N& bugs too much, 'dataking' works just as well. ;) I'll break out answers below that will hopefully be a little helpful for you. Thanks. Oh, in the future, could you be so kind as to *not* use HTML in your posts to the list? Case in point, your post comes out on my screen so small I can barely read it. It's considered a "best practice" to use plain text only for e-mail to the list. Sorry for the etiquette detour there, and I apologize to all if Evolution mangles this reply into HTML. Sorry. Nature of the beast. I manage a multiplatform environment at my work, so there are times when I need a similar multiplatform environment at home. Just because of history, WinXP is my primary home environment. On Tue, 2004-08-24 at 20:36, D at 7@k|N& wrote: > OK..so I have a few questions, that (I know) have probably been > answered a thousand times, and the poor posters were flamed > continuously for days on end (OK..maybe I'm a member of too many > mailing lists ;). Anyhow, I'm curious how you guys work on > documentation projects individually. Do you write in your favorite > text editor, then pass the subject matter to your editor to parse it > into XML? You can do this if XML is beyond your means. But frankly, if you're comfortable writing HTML or using "styles" in your favorite word processor, Docbook XML is really not any harder. You have to write the tags, true, but there are tools to help. Read on for more.... Don't have a problem with HTML, but I don't really use styles. I use notepad (or vi) as much or more than Word (or Abiword). Yes. At a minimum, install psgml, which came with your Fedora distribution. Done. I read the guide deeply enough for that. ;) You should read the Documentation Guide, available at the FDP home page at http://fedora.redhat.com/projects/docs/ ... don't skim it, really READ it, and you'll learn a lot. I did. Erm, eventually. :-) Yeah......it might take me a couple times too..... > Where does the author start and the editor begin? Reading the archives and Karsten's process document (see https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129993) will give you a better idea how this works. > Do you compose in your favorite editor, then once the content is > complete, open it in emacs using the template, and parse it that way? > What's the /theoretical/ process, and the /practical/ application of > that process? I just write in Emacs, it's actually easier that way. You can just write big sections with notes and fill them in later as you go. > I've skimmed the Documentation Guide, and the Quick Start, and didn't > get a whole lot out of it other than I should be either an author, or > an editor. See above comment. :-) We really need authors right now, to be honest. I am way more interested in authoring, than in editing. I'm not sure how much I have to contribute, but am definitely willing to contribute what I can. Asking questions is always the right way to start. Thanks. > <== dataking's pgp ==> > 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 Shouldn't I know your name before I trust your key? :-) Like I said...it's Charlie (or dataking if the upper/lower ASCII is a pain), and it's a different PGP key. ;) P.S. I'm CC'ing my linux address so I can see just how badly Outlook mangles these emails. I've received too many *seemingly superficial* complaints not to know. ;) Thanks for all the advice. -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 From mbronkhorst at keppelverolme.nl Wed Aug 25 13:16:15 2004 From: mbronkhorst at keppelverolme.nl (Martijn Bronkhorst) Date: Wed, 25 Aug 2004 15:16:15 +0200 Subject: Corrupted display when booting without external monitor Message-ID: <200408251316.i7PDGF7C009988@mailq.keppelverolme.nl> Dear Mailinglist, I have installed Fedora Core 2 and when I boot, I get my screen all 'torn apart'. Fedora correctly recognized my videocard (ATI mobility 128mb) and I have manually selected my display (Dell 104 x 768 Laptop LCD). The funny thing is, when there is an external monitor connected and you press the FN key to select to output on both displays .. The screen is perfect on the laptop. When I boot without an external monitor connected, the screen is unreadable again. Can you advise me on what to do, where to look ???? Thnx. Martijn Bronkhorst -------------- next part -------------- An HTML attachment was scrubbed... URL: From rahulsundaram at yahoo.co.in Wed Aug 25 14:17:33 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Wed, 25 Aug 2004 07:17:33 -0700 (PDT) Subject: Corrupted display when booting without external monitor In-Reply-To: <200408251316.i7PDGF7C009988@mailq.keppelverolme.nl> Message-ID: <20040825141733.22801.qmail@web8503.mail.in.yahoo.com> --- Martijn Bronkhorst wrote: > Dear Mailinglist, > > > > I have installed Fedora Core 2 and when I boot, I > get my screen all 'torn > apart'. Fedora correctly recognized my videocard > (ATI mobility 128mb) and I > have manually selected my display (Dell 104 x 768 > Laptop LCD). > You are on the wrong list. This mailing list is only meant for fedora document writers and editors. Please ask the question in the fedora users mailing list Thanks regards Rahul Sundaram __________________________________ Do you Yahoo!? New and Improved Yahoo! Mail - Send 10MB messages! http://promotions.yahoo.com/new_mail From davep at dpawson.co.uk Wed Aug 25 17:22:03 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 25 Aug 2004 18:22:03 +0100 Subject: Fundamentals In-Reply-To: References: Message-ID: <1093454523.2518.10.camel@homer> On Wed, 2004-08-25 at 04:24, D at 7@k|N& wrote: > Sorry. Nature of the beast. I manage a multiplatform environment at my > work, so there are times when I need a similar multiplatform environment at > home. Just because of history, WinXP is my primary home environment. Until a few weeks ago, win2k was mine. I still manage to send plain text emails, use emacs on win2k with psgml. It can be done, honest:-) > > You can do this if XML is beyond your means. But frankly, if you're > comfortable writing HTML or using "styles" in your favorite word > processor, Docbook XML is really not any harder. You have to write the > tags, true, but there are tools to help. Read on for more.... > > > Don't have a problem with HTML, but I don't really use styles. I use > notepad (or vi) as much or more than Word (or Abiword). If you are happy with vi, then vim has an xml plugin/extension whatever, that users say is just as good as emacs for xml. > I am way more interested in authoring, than in editing. I'm not sure how > much I have to contribute, but am definitely willing to contribute what I > can. > > > > Asking questions is always the right way to start. > Like I said...it's Charlie (or dataking if the upper/lower ASCII is a pain), > and it's a different PGP key. ;) > > P.S. I'm CC'ing my linux address so I can see just how badly Outlook > mangles these emails. I've received too many *seemingly superficial* > complaints not to know. ;) Hi Charlie. I gave up on Outlook when it managed to screw up/lose my address book. I actually bought Eudora, just to get a plain text email address book. Good luck with the authoring. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From s.ellis at fastmail.co.uk Wed Aug 25 23:04:51 2004 From: s.ellis at fastmail.co.uk (Stuart Ellis) Date: Thu, 26 Aug 2004 00:04:51 +0100 Subject: Self Introduction - Stuart Ellis Message-ID: <1093475091.3733.203069391@webmail.messagingengine.com> Full Name: Stuart Ellis Country, City: UK, Newtown (Powys) Profession: Network Administrator Company: Coleg Powys Goals In Fedora Project: Author documents to help fill the gaps in available resources. Particularly interested in networking and systems administration. Historical Qualifications: Professional admin for about 6 yrs. Started experimenting with Linux at about the same time, since OS/2 didn't look like it had much life left in it. Have been maintaining Linux servers for my current employer for about 3 yrs (usual suspects - Apache, BIND, MySQL etc.). Now provide support on LinuxQuestions forums, mostly on Samba and Red Hat issues. Recently, revised a couple of chapters of the GNOME User Guide for 2.8 - my first go with DocBook. Broad base of understanding, but not an expert in any area. After hanging around LinuxQuestions for a bit, I found that there are a number of problem areas that keep coming up. This may be because there aren't documents which are up to date and specific enough to guide someone through particular tasks. Other issues are that new users aren't aware of the various resources that are available, and that many docs assume a fairly high level of subject knowledge on the part of the reader, more than the average Windows-using enthusiast or technician actually has. So I'm interested in contributing to sets of docs which can be specific, kept up to date and well-advertised so that they can help users who don't yet have the Linux experience to hunt out and interpret the diverse sources around the 'net. -- Stuart Ellis s.ellis at fastmail.co.uk From paul at frields.com Thu Aug 26 00:04:49 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 25 Aug 2004 20:04:49 -0400 Subject: usb-hotplug-tutorial - Help needed Message-ID: <1093478689.9252.21.camel@bettie.internal.frields.org> Cf. Bugzilla #128952. The usb-hotplug-tutorial (formerly updfstab-tutorial) is, I think, ready for some final proofing/editing by a fresh pair of eyes. Dave Pawson helped me quite a bit with some initial technical and editorial issues. Is there anyone out there who can check it out and let me know what you think? The URL's for various flavors of access are listed in Bugzilla until the thing moves into "publish-ready" stage. I am dead-set on getting this out soon, since it's useful for FC2 (and prior) users who are not yet ready to make the big switch to FC3 even after its final release. Thanks all. -- Paul W. Frields, RHCE From redwire at therockmere.com Thu Aug 26 13:58:41 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Thu, 26 Aug 2004 09:58:41 -0400 (EDT) Subject: fedora-docs-list Digest, Vol 6, Issue 30 In-Reply-To: <20040825160007.763DE731E4@hormel.redhat.com> References: <20040825160007.763DE731E4@hormel.redhat.com> Message-ID: <63368.199.224.21.254.1093528721.squirrel@TheRockmere.com> >> If someone hosted a static page with a URL of fedoracommunity.org FYI as of this AM, fedoracommunity.org is dark. But, it does reslove to an active DNS entry. It may just be offline. >> gateway-style that provided a list of non-RH community-based resources, >> including Google search hints and un-commented links to Fedora-related >> sites, >> that should easily pass muster for mention in the README. > > No, you are mistaken > >> Consider it done; that someone will be me. I just registered the domain >> name >> and will be hosting the site by next week on a Fedora server, no less. > > Why, when the actual plan is to have http://www.fedoraproject.org/ > actually be the nice new shiny website? What Plan? fedoraproject.org bounces to http://fedora.linux.duke.edu/ So, why is that site more entitled to be a release point for documentation then any other? OK, I am done with website issues. I apologize if I have antagonized the group with some of my posts. I am only trying to help push for a release of information. Attached is a tutorial that I have been working on for the group. It has basic markup, but I am falling down with the correct syntax for the group and am asking for someone, editor?, to review, revise and critique my first offering. I have compile problems with chp4, my compiler isn't able to handle the -> and ~ char. What do I need to load to get special char. to work. (btw-I have been unable to dl the examples from the CVS) Also, since this is my first project I am trying to keep up ~ Do I open a bugzilla rpt? or What? While I have tried to review and follow the current directions for submissions, I am a little confused. I'll probably be confused until I get one or two submissions under my belt. Thanks, Brad Yum_Tutorial.tar attached -------------- next part -------------- A non-text attachment was scrubbed... Name: Yum_tutorial.tar Type: application/x-tar Size: 11264 bytes Desc: not available URL: From paul at frields.com Thu Aug 26 16:49:32 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 26 Aug 2004 12:49:32 -0400 Subject: fedora-docs-list Digest, Vol 6, Issue 30 In-Reply-To: <63368.199.224.21.254.1093528721.squirrel@TheRockmere.com> References: <20040825160007.763DE731E4@hormel.redhat.com> <63368.199.224.21.254.1093528721.squirrel@TheRockmere.com> Message-ID: <1093538972.4123.70.camel@localhost.localdomain> On Thu, 2004-08-26 at 09:58, redwire at therockmere.com wrote: [...snip...] > Attached is a tutorial that I have been working on for the group. It has > basic markup, but I am falling down with the correct syntax for the group > and am asking for someone, editor?, to review, revise and critique my > first offering. I have compile problems with chp4, my compiler isn't able > to handle the -> and ~ char. What do I need to load to get special char. > to work. > (btw-I have been unable to dl the examples from the CVS) With respect to the last part, how exactly have you been unable to d/l? Please provide details and we can try to help. I just updated this morning from CVS and it worked fine. > Also, since this is my first project I am trying to keep up ~ Do I open a > bugzilla rpt? or What? While I have tried to review and follow the current > directions for submissions, I am a little confused. I'll probably be > confused until I get one or two submissions under my belt. Have you read Karsten's process documents? Those are the most up-to-date guidance on the way it should work. http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en/ HTH. -- Paul W. Frields, RHCE From paul at frields.com Fri Aug 27 01:22:52 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 26 Aug 2004 21:22:52 -0400 Subject: installation guide In-Reply-To: <1092441906.11376.648.camel@localhost.localdomain> References: <1092428328.4488.36007.camel@erato.phig.org> <1092441906.11376.648.camel@localhost.localdomain> Message-ID: <1093569772.15928.13.camel@bettie.internal.frields.org> On Fri, 2004-08-13 at 20:05, Tammy Fox wrote: > On Fri, 2004-08-13 at 16:18, Karsten Wade wrote: > > Today had to tell someone on #fedora-docs that we don't have an > > Installation Guide, and just like many others, had to refer to RHL 9 IG > > and other resources. > > > > Are a couple of people interested in taking on this task? It has some > > tedium to it, but it's not that bad. Once completed, it will need > > regular updating, so it's a good, valuable, and stable long-term > > project. > > > > Anaconda has support for taking screenshots, iirc. A format can be > > borrowed from existing guides, as a starting place. > > > > However ... this is a full guide, which requires more effort than a > > shorter tutorial. Is it even worth it to throw this idea into the > > bucket at this stage? If so, I'll file the bug and etc. This should be > > an early one to be tackled, when we are ready. > > > > Go ahead and open a bug for it since it needs to be done. > > What about creating a TOC for it on the mailing list? Then you or I can > create empty files for it according to the TOC in CVS, and people can > volunteer to write sections that are broken out into files. No one has > to tackle the entire guide, and eventually it will be complete. One > person can even be in charge of just taking screenshots with the method > mentioned in the release notes. The RHEL IGs have been done this way in > th past -- different writers responsible for a set of files in the IG, > and it works great because you don't have to worry about working on the > same files or topics. > > If we plan ahead, we can even make it expandable to multiple platforms. > We did a lot of work to make the same set of files compile for different > arches internally, so we might as well use that knowledge here as well. > I've even written it up already for the internal docs. I could rewrite > it for the Fedora docs without much effort. I meant to reply to this thread but didn't get a chance when it was fresh. Now it is old and smelly, but we still love it just the same. :-) Let's get this one on the road. I would like to put the Style Guide to the side (not the same as on the back burner) while we work on this. The Style Guide is a great thing and necessary, but not as important as having an Installation Guide. I think handing out chapter assignments (or alternately, taking volunteers for chapters) would give everyone an idea of authoring skill levels. It would also mean we could put the process doc to the test, and beyond that, give us good ideas to address in the Style Guide. As an aside, since I don't want it to seem like I am shirking a responsibility, I have been reviewing the GNOME Documentation Style Guidelines[1]. I would suggest for now that everyone who is not an experienced technical writer (and I am including myself in that category) pay attention to Chapters 1-4 in the GDSG. Much of the rest of the manual, although helpful, is more geared toward documentation of graphical interface tools, and is not as applicable in to general docs. Has anyone already started this, beyond the outline available in CVS now? [1] http://developer.gnome.org/documents/style-guide/ -- Paul W. Frields, RHCE From s.ellis at fastmail.co.uk Fri Aug 27 11:04:10 2004 From: s.ellis at fastmail.co.uk (Stuart Ellis) Date: Fri, 27 Aug 2004 12:04:10 +0100 Subject: installation guide Message-ID: <1093604650.29297.203176060@webmail.messagingengine.com> > I meant to reply to this thread but didn't get a chance when it was > fresh. Now it is old and smelly, but we still love it just the same. :-) > Let's get this one on the road. I would like to put the Style Guide to > the side (not the same as on the back burner) while we work on this. The > Style Guide is a great thing and necessary, but not as important as > having an Installation Guide. > I think handing out chapter assignments (or alternately, taking > volunteers for chapters) would give everyone an idea of authoring skill > levels. It would also mean we could put the process doc to the test, and > beyond that, give us good ideas to address in the Style Guide. I was wondering about this - I couldn't find details on the tracking bug or the list archives. I'd be interested in helping, if volunteers are needed. Looking at the TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable systems), but could probably tackle any of the other parts as required. Now away until Monday, can pick up from there. -- Stuart Ellis s.ellis at fastmail.co.uk From tfox at redhat.com Fri Aug 27 17:21:48 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 27 Aug 2004 13:21:48 -0400 Subject: [Fwd: Upgrading from Core1 to Core2] Message-ID: <1093627308.27934.23.camel@localhost.localdomain> I received the below message today. Does anyone have any docs on how to do this? Thanks, Tammy -----Forwarded Message----- Since Core1 is EOL, I would like to upgrade to Core2. I have thousands of core1 devices all over the world. All of which I do not have physical access to. I only have SSH access to these machines, and it seems that there is a severe lack of documentation on the subject of upgrading core1 to core2 remotely over ssh without the use of serial or net booting. Unfortunately, this puts me in quite a predicament, and I would be eternally grateful if you could point me in the right direction. From pnasrat at redhat.com Fri Aug 27 17:23:24 2004 From: pnasrat at redhat.com (Paul Nasrat) Date: Fri, 27 Aug 2004 13:23:24 -0400 Subject: [Fwd: Upgrading from Core1 to Core2] In-Reply-To: <1093627308.27934.23.camel@localhost.localdomain> References: <1093627308.27934.23.camel@localhost.localdomain> Message-ID: <20040827172324.GA31380@devserv.devel.redhat.com> On Fri, Aug 27, 2004 at 01:21:48PM -0400, Tammy Fox wrote: > I received the below message today. Does anyone have any docs on how to > do this? http://linux.duke.edu/~skvidal/misc/fc1-fc2-yum-hints.txt Paul From davep at dpawson.co.uk Fri Aug 27 17:38:54 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 27 Aug 2004 18:38:54 +0100 Subject: [Fwd: Upgrading from Core1 to Core2] In-Reply-To: <20040827172324.GA31380@devserv.devel.redhat.com> References: <1093627308.27934.23.camel@localhost.localdomain> <20040827172324.GA31380@devserv.devel.redhat.com> Message-ID: <1093628333.2516.6.camel@homer> On Fri, 2004-08-27 at 18:23, Paul Nasrat wrote: > On Fri, Aug 27, 2004 at 01:21:48PM -0400, Tammy Fox wrote: > > I received the below message today. Does anyone have any docs on how to > > do this? The only hint I can help with is that with a two week old fc2 burned to CD, I managed to upgrade 1 to 2 with absolute standard, no tweaks follow the hints 'it works' approach. I didn't use net access, but ..... Its a minimal risk? If the guy has that many systems set one up next to his install and run it? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Fri Aug 27 18:13:20 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 27 Aug 2004 11:13:20 -0700 Subject: Self Introduction - Stuart Ellis In-Reply-To: <1093475091.3733.203069391@webmail.messagingengine.com> References: <1093475091.3733.203069391@webmail.messagingengine.com> Message-ID: <1093630400.17095.65459.camel@erato.phig.org> On Wed, 2004-08-25 at 16:04, Stuart Ellis wrote: > Full Name: Stuart Ellis Hi Stuart: Welcome. Your background and interest sound like a perfect fit. Look forward to working with you. - Karsten > Country, City: UK, Newtown (Powys) > Profession: Network Administrator > Company: Coleg Powys > Goals In Fedora Project: Author documents to help fill the gaps in > available resources. Particularly interested in networking and systems > administration. > Historical Qualifications: Professional admin for about 6 yrs. Started > experimenting with Linux at about the same time, since OS/2 didn't look > like it had much life left in it. Have been maintaining Linux servers > for my current employer for about 3 yrs (usual suspects - Apache, BIND, > MySQL etc.). Now provide support on LinuxQuestions forums, mostly on > Samba and Red Hat issues. Recently, revised a couple of chapters of the > GNOME User Guide for 2.8 - my first go with DocBook. Broad base of > understanding, but not an expert in any area. > > After hanging around LinuxQuestions for a bit, I found that there are a > number of problem areas that keep coming up. This may be because there > aren't documents which are up to date and specific enough to guide > someone through particular tasks. Other issues are that new users > aren't aware of the various resources that are available, and that many > docs assume a fairly high level of subject knowledge on the part of the > reader, more than the average Windows-using enthusiast or technician > actually has. So I'm interested in contributing to sets of docs which > can be specific, kept up to date and well-advertised so that they can > help users who don't yet have the Linux experience to hunt out and > interpret the diverse sources around the 'net. > -- > Stuart Ellis s.ellis at fastmail.co.uk -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From redwire at therockmere.com Fri Aug 27 18:55:56 2004 From: redwire at therockmere.com (redwire at therockmere.com) Date: Fri, 27 Aug 2004 14:55:56 -0400 (EDT) Subject: fedora-docs-list Digest, Vol 6, Issue 32 In-Reply-To: <20040827160011.CC66A737C3@hormel.redhat.com> References: <20040827160011.CC66A737C3@hormel.redhat.com> Message-ID: <38621.199.224.21.254.1093632956.squirrel@TheRockmere.com> >> (btw-I have been unable to dl the examples from the CVS) > > With respect to the last part, how exactly have you been unable to d/l? > Please provide details and we can try to help. I just updated this > morning from CVS and it worked fine. Thank you, I will re-trace my steps into CVS and post what errors I'm getting. > Have you read Karsten's process documents? Those are the most up-to-date > guidance on the way it should work. > > http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en/ > Thank you again, I have read the digest of the mailing-list, but this was what I was looking for. Brad From tfox at redhat.com Fri Aug 27 20:19:02 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 27 Aug 2004 16:19:02 -0400 Subject: How to Update tutorial Message-ID: <1093637941.27934.202.camel@localhost.localdomain> Dave Pawson sent me a tutorial on using yum to download Fedora updates a while back, and I finally had time to edit it and get it into CVS. It is in the updates/ directory in CVS. Dave, look over my edits and let me know what you think. I changed a few tags to comply to our standards and made some minor edits like moving the recap list to the end of the Updating Sources section. If they are OK with you, let me know and I'll get it up on the website. I've opened bug #131131 to track this tutorial. Regards, Tammy From tfox at redhat.com Fri Aug 27 20:22:44 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 27 Aug 2004 16:22:44 -0400 Subject: fedora-docs-list Digest, Vol 6, Issue 30 In-Reply-To: <1093538972.4123.70.camel@localhost.localdomain> References: <20040825160007.763DE731E4@hormel.redhat.com> <63368.199.224.21.254.1093528721.squirrel@TheRockmere.com> <1093538972.4123.70.camel@localhost.localdomain> Message-ID: <1093638164.27934.205.camel@localhost.localdomain> On Thu, 2004-08-26 at 12:49, Paul W. Frields wrote: > On Thu, 2004-08-26 at 09:58, redwire at therockmere.com wrote: > [...snip...] > > Attached is a tutorial that I have been working on for the group. It has > > basic markup, but I am falling down with the correct syntax for the group > > and am asking for someone, editor?, to review, revise and critique my > > first offering. I have compile problems with chp4, my compiler isn't able > > to handle the -> and ~ char. What do I need to load to get special char. > > to work. > > (btw-I have been unable to dl the examples from the CVS) > > With respect to the last part, how exactly have you been unable to d/l? > Please provide details and we can try to help. I just updated this > morning from CVS and it worked fine. > > > Also, since this is my first project I am trying to keep up ~ Do I open a > > bugzilla rpt? or What? While I have tried to review and follow the current > > directions for submissions, I am a little confused. I'll probably be > > confused until I get one or two submissions under my belt. > > Have you read Karsten's process documents? Those are the most up-to-date > guidance on the way it should work. > > http://people.redhat.com/kwade/fedora-docs/process-docs/fedora-docs-process-en/ > There is also http://fedora.redhat.com/participate/documentation-quick-start/. Open a Bugzilla report for it (assuming it is not the same as the updates tutorial Dave wrote and I just sent email out about), and I'll assign you an editor. If it is the same as Dave's tutorial, perhaps you can combine them by submitting a patch to his. Regards, Tammy > HTH. > -- > Paul W. Frields, RHCE From tfox at redhat.com Fri Aug 27 20:44:47 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 27 Aug 2004 16:44:47 -0400 Subject: installation guide In-Reply-To: <1093604650.29297.203176060@webmail.messagingengine.com> References: <1093604650.29297.203176060@webmail.messagingengine.com> Message-ID: <1093639487.27934.229.camel@localhost.localdomain> On Fri, 2004-08-27 at 07:04, Stuart Ellis wrote: > > I meant to reply to this thread but didn't get a chance when it was > > fresh. Now it is old and smelly, but we still love it just the same. :-) > > Let's get this one on the road. I would like to put the Style Guide to > > the side (not the same as on the back burner) while we work on this. The > > Style Guide is a great thing and necessary, but not as important as > > having an Installation Guide. > > > I think handing out chapter assignments (or alternately, taking > > volunteers for chapters) would give everyone an idea of authoring skill > > levels. It would also mean we could put the process doc to the test, and > > beyond that, give us good ideas to address in the Style Guide. > > I was wondering about this - I couldn't find details on the tracking bug > or the list archives. > > I'd be interested in helping, if volunteers are needed. Looking at the > TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable > systems), but could probably tackle any of the other parts as required. > > Now away until Monday, can pick up from there. > -- > Stuart Ellis s.ellis at fastmail.co.uk Glad you want to help with this. The first step is to create a ToC. If you want to create one and propose it to this list, that would be a wonderful start. Tammy From tfox at redhat.com Fri Aug 27 20:56:37 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 27 Aug 2004 16:56:37 -0400 Subject: Bug submission? In-Reply-To: <1093369363.2252.10.camel@berlin.east.gov> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> <1093369363.2252.10.camel@berlin.east.gov> Message-ID: <1093640197.27934.244.camel@localhost.localdomain> On Tue, 2004-08-24 at 13:42, Paul W. Frields wrote: > On Tue, 2004-08-24 at 13:04, Dave Pawson wrote: > > On Mon, 2004-08-23 at 20:44, Paul W. Frields wrote: > > > > > I think it works as a short tutorial, maybe "Kernel Compilation for > > > &FC;." It would be good to have on the &FDPDOCS-URL; site > > > > I've noted a couple of times that the #included entities are upper > > case defined, i.e. intended for SGML applications. > > > > A bug submission to get them lower cased? > > Intent: Ease of use. > > > > Thoughts? > > My $0.02: Having them uppercased also makes them more visible to the > "naked eye" in other contexts. I dig 'em the way they are, personally. > And of course, there's no reason you can't redefine them locally in your > docs. > > -- > Paul W. Frields, RHCE FWIW, I also like them uppercase for easy sighting while reading the document. Tammy From tfox at redhat.com Fri Aug 27 20:57:12 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 27 Aug 2004 16:57:12 -0400 Subject: website updates Message-ID: <1093640231.27934.247.camel@localhost.localdomain> Just wanted to make everyone aware of a few website changes: http://fedora.redhat.com/docs/ 1. A link have been added to this page to allow people looking for docs an easier way to submit an idea (bug #130836) 2. The x86_64 Release Notes have been added 3. An updated version of the FC2 SELinux FAQ has been posted From paul at frields.com Fri Aug 27 21:10:35 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 27 Aug 2004 17:10:35 -0400 Subject: installation guide In-Reply-To: <1093639487.27934.229.camel@localhost.localdomain> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> Message-ID: <1093641035.17762.29.camel@bettie.internal.frields.org> On Fri, 2004-08-27 at 16:44, Tammy Fox wrote: > On Fri, 2004-08-27 at 07:04, Stuart Ellis wrote: > > > I meant to reply to this thread but didn't get a chance when it was > > > fresh. Now it is old and smelly, but we still love it just the same. :-) > > > Let's get this one on the road. I would like to put the Style Guide to > > > the side (not the same as on the back burner) while we work on this. The > > > Style Guide is a great thing and necessary, but not as important as > > > having an Installation Guide. > > > > > I think handing out chapter assignments (or alternately, taking > > > volunteers for chapters) would give everyone an idea of authoring skill > > > levels. It would also mean we could put the process doc to the test, and > > > beyond that, give us good ideas to address in the Style Guide. > > > > I was wondering about this - I couldn't find details on the tracking bug > > or the list archives. > > > > I'd be interested in helping, if volunteers are needed. Looking at the > > TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable > > systems), but could probably tackle any of the other parts as required. > > > > Now away until Monday, can pick up from there. > > Glad you want to help with this. The first step is to create a ToC. If > you want to create one and propose it to this list, that would be a > wonderful start. Tammy, I believe there's currently a ToC in CVS, as install-guide/fedora-install-guide-en-outline.txt -- could we use this? -- Paul W. Frields, RHCE From tfox at redhat.com Fri Aug 27 21:17:35 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 27 Aug 2004 17:17:35 -0400 Subject: installation guide In-Reply-To: <1093641035.17762.29.camel@bettie.internal.frields.org> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> Message-ID: <1093641455.27934.249.camel@localhost.localdomain> On Fri, 2004-08-27 at 17:10, Paul W. Frields wrote: > On Fri, 2004-08-27 at 16:44, Tammy Fox wrote: > > On Fri, 2004-08-27 at 07:04, Stuart Ellis wrote: > > > > I meant to reply to this thread but didn't get a chance when it was > > > > fresh. Now it is old and smelly, but we still love it just the same. :-) > > > > Let's get this one on the road. I would like to put the Style Guide to > > > > the side (not the same as on the back burner) while we work on this. The > > > > Style Guide is a great thing and necessary, but not as important as > > > > having an Installation Guide. > > > > > > > I think handing out chapter assignments (or alternately, taking > > > > volunteers for chapters) would give everyone an idea of authoring skill > > > > levels. It would also mean we could put the process doc to the test, and > > > > beyond that, give us good ideas to address in the Style Guide. > > > > > > I was wondering about this - I couldn't find details on the tracking bug > > > or the list archives. > > > > > > I'd be interested in helping, if volunteers are needed. Looking at the > > > TOC I wouldn't be able to test dual-boot or partitioning (no RAIDable > > > systems), but could probably tackle any of the other parts as required. > > > > > > Now away until Monday, can pick up from there. > > > > Glad you want to help with this. The first step is to create a ToC. If > > you want to create one and propose it to this list, that would be a > > wonderful start. > > Tammy, I believe there's currently a ToC in CVS, as > install-guide/fedora-install-guide-en-outline.txt -- could we use this? > -- > Paul W. Frields, RHCE Oh yeah. I wrote that a long time ago and forgot about it. Thank goodness for CVS. ;-) Tammy From kwade at redhat.com Fri Aug 27 22:32:55 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 27 Aug 2004 15:32:55 -0700 Subject: FedoraCommunity.org (was:Re: fedora-docs bugs) In-Reply-To: <1093399053.12188.330.camel@albus.aeon.com.my> References: <1092318823.18844.155.camel@berlin.east.gov> <1092411986.2449.4.camel@berlin.east.gov> <1092421880.4488.35482.camel@erato.phig.org> <200408131607.06416.hoyt@cavtel.net> <1093399053.12188.330.camel@albus.aeon.com.my> Message-ID: <1093645974.17095.67056.camel@erato.phig.org> On Tue, 2004-08-24 at 18:57, Colin Charles wrote: > On Sat, 2004-08-14 at 06:07, Hoyt wrote: > > > If someone hosted a static page with a URL of fedoracommunity.org > > gateway-style that provided a list of non-RH community-based resources, > > including Google search hints and un-commented links to Fedora-related sites, > > that should easily pass muster for mention in the README. > > No, you are mistaken JFYI to the group, the point was resolved after Hoyt wrote the paragraph above, with text from the guy who is a lawyer. :) http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00139.html Should we add that text to a References
in every document that wants to refer to sources of information outside of the guide itself? That References
would include listing other Fedora docs, but would not specify any non-Fedora URL or project name, instead suggesting a Google search. IMO, this is also more useful to our readers -- our docs aren't populated with links liable to get outdated or be difficult to maintain, and readers get access to popular and useful sources of information. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Fri Aug 27 22:33:32 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 27 Aug 2004 18:33:32 -0400 Subject: installation guide In-Reply-To: <1093641455.27934.249.camel@localhost.localdomain> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> <1093641455.27934.249.camel@localhost.localdomain> Message-ID: <1093646012.3341.3.camel@bettie.internal.frields.org> Cf. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129911 I'll volunteer for partitioning, as mentioned in the &BZ; entry above. I would like to suggest several guidelines for screenshots and any other graphics (I think the GDSG may use something similar to these, IIRC): 1. PNG format. Is that too obvious? 2. No wider than 500 pixels. If your graphic is larger than that, use GIMP (Image -> Scale Image) or mogrify to scale the image to no wider than 500 pixels. 3. Graphics should be included as
I think. Can someone else more knowledgeable in guide creation (*cough* Tammy *cough* Karsten *cough*) add to this list? Here's another one I just thought of; the GDSG mentions this as well: 4. Graphics should not be included unless you absolutely *cannot* get along without it. There's no reason to include repetitive screenshots of parts of the interface that are easily explained in a sentence. (Example: anaconda runs several progress bars when it computes package dependencies, writes an install image to the drive, etc.... those don't need to be screenshotted. Wait, is that a real word?) -- Paul W. Frields, RHCE From kwade at redhat.com Fri Aug 27 23:33:12 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 27 Aug 2004 16:33:12 -0700 Subject: installation guide In-Reply-To: <1093646012.3341.3.camel@bettie.internal.frields.org> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> <1093641455.27934.249.camel@localhost.localdomain> <1093646012.3341.3.camel@bettie.internal.frields.org> Message-ID: <1093649591.17095.67458.camel@erato.phig.org> Okay, I'm onboard for the All Hands on Deck for an Installation Guide for FC3. We have until about 20 October to have a release candidate, and this is possible to do if we make the pieces small enough and keep the editors busy. More below ... On Fri, 2004-08-27 at 15:33, Paul W. Frields wrote: > Cf. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129911 Below are some specific points, and I expanded on those suggestions in a patch to the Documentation Guide, as a new 7.3 Taking Screenshots. I'll reply back in a bit with the steps, after I build the DB and snarf them from the HTML page. :) For expediency, I'm prepared to just submit the patch to the Doc Guide, rolling in some other dangling issues I can include. Tammy would see the CVS report and can address any mistakes and expand/modify. > I'll volunteer for partitioning, as mentioned in the &BZ; entry above. I > would like to suggest several guidelines for screenshots and any other > graphics (I think the GDSG may use something similar to these, IIRC): > > 1. PNG format. Is that too obvious? And EPS. > 2. No wider than 500 pixels. If your graphic is larger than that, use > GIMP (Image -> Scale Image) or mogrify to scale the image to no wider > than 500 pixels. That seems reasonable. Make the GUI as small as it can to convey just what you need. 2.1 Use the default Metacity theme to give the guides a consistent look, and also consistent with most user's experience and expectations. 2.2 If you need to crop the image, do that in the GIMP to show just what you need. > 3. Graphics should be included as
I think. http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-figure.html That shows the format. We kept the EPS first because of legacy jadetex issues, no idea if it matters anymore and I'm not tempting fate to find out. ;) > Here's another one I just thought of; the GDSG mentions this as well: > > 4. Graphics should not be included unless you absolutely *cannot* get > along without it. There's no reason to include repetitive screenshots of > parts of the interface that are easily explained in a sentence. > (Example: anaconda runs several progress bars when it computes package > dependencies, writes an install image to the drive, etc.... those don't > need to be screenshotted. Wait, is that a real word?) That seems reasonable. It's nice to have one screenshot to show the whole GUI, if that helps. It's probably better to have too few screenshots than too many. For quality of information, I find blocks (as s) with nice, useful command line output to be better ... :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Sat Aug 28 01:34:28 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 27 Aug 2004 18:34:28 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) Message-ID: <1093656867.17095.68240.camel@erato.phig.org> (note message id intentionally broke to start new thread) On Fri, 2004-08-27 at 16:33, Karsten Wade wrote: > For expediency, I'm prepared to just submit the patch to the Doc Guide, > rolling in some other dangling issues I can include. Tammy would see > the CVS report and can address any mistakes and expand/modify. Darn that cowboy mentality! For those who chomp at the bit, you can see that I am the same myself. The above is a perfect example. Even I get impatient at process, though I recognize we need it more than I need to feel comfortable. 1. I don't own the document, although Tammy said I could do some minor bugfixes and commit them to CVS. What I just wrote is a whole new
not a minor fix, so that requires a new bug for tracking work on the Documentation Guide: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131160 with an attachment of a diff against current CVS and then .... 2. An editor to look it over, which can be the first person who grabs it and confirms what I did, and who can then move it on to block bug # 129722 (ready to publish) for Tammy (in her role as a document owner) to pick up and commit to CVS, then (in the role of website maintainer) update f.r.c/participate/documentation-guide/. To make this easier, I have opted to host this as a DRAFT version at the following URL: http://people.redhat.com/kwade/patches/fedora-docs/documentation-guide-quaid/documentation-guide-en-quaid/taking-screenshots.html The editor will want to a) wordsmith, and b) check the technical details, such as steps and information shown. Also, a check of the DocBook XML is in order. Note thought that I broke rules from the Documentation Guide: 1. I used a meaningful ID for , dropping the location and section specific information. At this point, the most legitimate debate is between "similar-to-title" and "s.similar.to.title", the latter being Norm Walsh's current usage. 2. My tags themselves are not flush left, although the content is. I think that information described on this page: http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html is a legacy SGML problem. My builds show that the following: foo foo foo renders as: foo foo foo Obviously the contents of the are highly sensitive to whitespace issues, and in fact could perhaps be CDATA containers instead to totally make them ignored by the toolchain. Either way, I don't think the tags need to be flush left, nor the the container. I'd like to recommend this for a change in the Documentation Guide, and will file a bugzilla with patch if there is no technical objection. - Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/ -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Sat Aug 28 04:47:38 2004 From: paul at frields.com (Paul W. Frields) Date: Sat, 28 Aug 2004 00:47:38 -0400 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093656867.17095.68240.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> Message-ID: <1093668457.4188.53.camel@bettie.internal.frields.org> On Fri, 2004-08-27 at 21:34, Karsten Wade wrote: > (note message id intentionally broke to start new thread) I probably should have done that, sorry. [...snip...] > 1. I don't own the document, although Tammy said I could do some minor > bugfixes and commit them to CVS. What I just wrote is a whole new >
not a minor fix, so that requires a new bug for tracking work > on the Documentation Guide: > > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131160 > > with an attachment of a diff against current CVS and then .... > > 2. An editor to look it over, which can be the first person who grabs it > and confirms what I did, and who can then move it on to block bug # > 129722 (ready to publish) for Tammy (in her role as a document owner) to > pick up and commit to CVS, then (in the role of website maintainer) > update f.r.c/participate/documentation-guide/. I'll take you up on that, seeing as how I haven't hit the hay quite yet. > To make this easier, I have opted to host this as a DRAFT version at the > following URL: > > http://people.redhat.com/kwade/patches/fedora-docs/documentation-guide-quaid/documentation-guide-en-quaid/taking-screenshots.html > > The editor will want to a) wordsmith, and b) check the technical > details, such as steps and information shown. Also, a check of the > DocBook XML is in order. Honestly, I didn't see much to do with (a). I made a couple of changes which I thought at the time were good ideas. On the other hand, I'm getting sleepy. > Note thought that I broke rules from the Documentation Guide: > > 1. I used a meaningful ID for , dropping the location and section > specific information. At this point, the most legitimate debate is > between "similar-to-title" and "s.similar.to.title", the latter being > Norm Walsh's current usage. I like using meaningful ID's; I have moved to using
tags, with "sn-meaningful-title". Modularity, check. Easy to grab all element-related ID's with a regex, also check. > 2. My tags themselves are not flush left, although the content > is. I think that information described on this page: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html > > is a legacy SGML problem. My builds show that the following: > > > foo > > > foo > > > foo > > > renders as: > > foo > foo > foo > > Obviously the contents of the are highly sensitive to > whitespace issues, and in fact could perhaps be CDATA containers instead > to totally make them ignored by the toolchain. Either way, I don't > think the tags need to be flush left, nor the the > container. I'd like to recommend this for a change in > the Documentation Guide, and will file a bugzilla with patch if there is > no technical objection. I have seen the most problem in the PDF builds, but the HTML builds also seem to do funny stuff with more vertical space if you don't run your first and last text against the opening and closing tags, respectively. In other words, given these two examples: foo bar foo bar The second example renders into a more pleasing vertical context, without a lot of wasted space. The PDF, IIRC, was particularly ugly if you didn't use the second form, but I seem to remember the HTML also was noticeably different. I posted an additive patch to Bugzilla for you to take a look at. I feel a little strange correcting work by someone who does this for a living, when I'm more of a dilettante. Hope the editing sparks something positive. > - Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/ Very good movie! Not that it's necessarily going to be at a Guerilla Drive-In, but if you like "Run Lola Run," you should see Tom Tykwer's film of Krzysztof Kieslowki's "Heaven," if you haven't already. (Sorry for going OT at the end there. Now I'm going TB as well.) -- Paul W. Frields, RHCE (*TB = To Bed) From davep at dpawson.co.uk Sat Aug 28 10:09:00 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 28 Aug 2004 11:09:00 +0100 Subject: How to Update tutorial In-Reply-To: <1093637941.27934.202.camel@localhost.localdomain> References: <1093637941.27934.202.camel@localhost.localdomain> Message-ID: <1093687740.2515.5.camel@homer> On Fri, 2004-08-27 at 21:19, Tammy Fox wrote: If they are OK with you, let me know and I'll > get it up on the website. Fine by me Tammy. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Aug 28 10:14:35 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 28 Aug 2004 11:14:35 +0100 Subject: Bug submission? In-Reply-To: <1093640197.27934.244.camel@localhost.localdomain> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> <1093369363.2252.10.camel@berlin.east.gov> <1093640197.27934.244.camel@localhost.localdomain> Message-ID: <1093688074.2515.11.camel@homer> On Fri, 2004-08-27 at 21:56, Tammy Fox wrote: > > FWIW, I also like them uppercase for easy sighting while reading the > document. Use the coloring capabilies of emacs if you need want them to stand out? (make-face 'sgml-entity-face) (set-face-foreground 'sgml-entity-face "magenta") or whatever. I was just trying to reduce typing a little. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Aug 28 10:21:38 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 28 Aug 2004 11:21:38 +0100 Subject: installation guide In-Reply-To: <1093646012.3341.3.camel@bettie.internal.frields.org> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> <1093641455.27934.249.camel@localhost.localdomain> <1093646012.3341.3.camel@bettie.internal.frields.org> Message-ID: <1093688498.2515.18.camel@homer> On Fri, 2004-08-27 at 23:33, Paul W. Frields wrote: > 1. PNG format. Is that too obvious? No Paul, it needs saying! > 2. No wider than 500 pixels. If your graphic is larger than that, use > GIMP (Image -> Scale Image) or mogrify to scale the image to no wider > than 500 pixels. > 3. Graphics should be included as
I think. With full alternatives to make it work in html.
Block and Inline graphics Two graphics, one as a block, one as an inline.
> > 4. Graphics should not be included unless you absolutely *cannot* get > along without it. There's no reason to include repetitive screenshots of > parts of the interface that are easily explained in a sentence. > (Example: anaconda runs several progress bars when it computes package > dependencies, writes an install image to the drive, etc.... those don't > need to be screenshotted. Wait, is that a real word?) +1 (accessibility) > > -- > Paul W. Frields, RHCE -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Aug 28 10:25:52 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 28 Aug 2004 11:25:52 +0100 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093656867.17095.68240.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> Message-ID: <1093688752.2515.22.camel@homer> On Sat, 2004-08-28 at 02:34, Karsten Wade wrote: > > 2. My tags themselves are not flush left, although the content > is. > My builds show that the following: > > > foo > > > foo > > > foo > > > renders as: > > foo > foo > foo > > Obviously the contents of the are highly sensitive to > whitespace issues, Yes, whitespace is respected within the tags. Since a dtd is in use, the intertag space is non-existant to the parser. > and in fact could perhaps be CDATA containers instead > to totally make them ignored by the toolchain. Either way, I don't > think the tags need to be flush left, nor the the > container. I'd like to recommend this for a change in > the Documentation Guide, and will file a bugzilla with patch if there is > no technical objection. No bug. Just XML :-) Without a schema, you'd have to tell the processor something about whitespace treatment, collapse or preserve. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Aug 28 10:30:08 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 28 Aug 2004 11:30:08 +0100 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093668457.4188.53.camel@bettie.internal.frields.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> Message-ID: <1093689007.2515.27.camel@homer> On Sat, 2004-08-28 at 05:47, Paul W. Frields wrote: > > I have seen the most problem in the PDF builds, but the HTML builds also > seem to do funny stuff with more vertical space if you don't run your > first and last text against the opening and closing tags, > respectively. In other words, given these two examples: > > > > > foo > bar > > > > > foo > bar > > The second example renders into a more pleasing vertical context, > without a lot of wasted space. The PDF, IIRC, was particularly ugly if > you didn't use the second form, but I seem to remember the HTML also was > noticeably different. What processing tools Paul? And why is computeroutput necessary within screen? I'd have thought an either or was more reasonable for the processor to sort out? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Aug 28 10:34:11 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 28 Aug 2004 11:34:11 +0100 Subject: website updates In-Reply-To: <1093640231.27934.247.camel@localhost.localdomain> References: <1093640231.27934.247.camel@localhost.localdomain> Message-ID: <1093689251.2515.29.camel@homer> On Fri, 2004-08-27 at 21:57, Tammy Fox wrote: > Just wanted to make everyone aware of a few website changes: > > http://fedora.redhat.com/docs/ Thank you Tammy. At last the project is visibly alive. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Sat Aug 28 12:25:50 2004 From: paul at frields.com (Paul W. Frields) Date: Sat, 28 Aug 2004 08:25:50 -0400 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093689007.2515.27.camel@homer> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> Message-ID: <1093695950.6210.2.camel@bettie.internal.frields.org> On Sat, 2004-08-28 at 06:30, Dave Pawson wrote: > > I have seen the most problem in the PDF builds, but the HTML builds also > > seem to do funny stuff with more vertical space if you don't run your > > first and last text against the opening and closing tags, > > respectively. In other words, given these two examples: > > > > > > > > > > foo > > bar > > > > > > > > > > foo > > bar > > > > The second example renders into a more pleasing vertical context, > > without a lot of wasted space. The PDF, IIRC, was particularly ugly if > > you didn't use the second form, but I seem to remember the HTML also was > > noticeably different. > > What processing tools Paul? > And why is computeroutput necessary within screen? I'd have thought an > either or was more reasonable for the processor to sort out? I'm using the standard toolset and practices from the Documentation Guide. Maybe that piece should be revisited in the Documentation Guide, which indicates the proper syntax looks like this: cmd -i arg1 Uh-uh, you can't do that. I certainly have no problem doing it some other way... If someone knows that this is wrong or confusing to most (or all?) toolsets, file a bug against the documentation-guide so we can track and fix it. -- Paul W. Frields, RHCE From paul at frields.com Sat Aug 28 12:27:55 2004 From: paul at frields.com (Paul W. Frields) Date: Sat, 28 Aug 2004 08:27:55 -0400 Subject: Bug submission? In-Reply-To: <1093688074.2515.11.camel@homer> References: <1093090472.3424.37.camel@gecko> <1093100909.2792.6.camel@laptop.fenrus.com> <1093108435.3424.98.camel@gecko> <20040821171629.GA15447@devserv.devel.redhat.com> <20040822115606.GB22101@neu.physik.fu-berlin.de> <1093178418.1937.56.camel@localhost.localdomain> <20040822131926.GE22101@neu.physik.fu-berlin.de> <1093181516.2790.17.camel@laptop.fenrus.com> <4128E9E6.7090308@rincon.com> <1093264333.2522.27.camel@berlin.east.gov> <1093283024.17095.29142.camel@erato.phig.org> <1093285425.17095.29377.camel@erato.phig.org> <1093290239.3627.18.camel@berlin.east.gov> <1093367054.2517.18.camel@homer> <1093369363.2252.10.camel@berlin.east.gov> <1093640197.27934.244.camel@localhost.localdomain> <1093688074.2515.11.camel@homer> Message-ID: <1093696075.6210.5.camel@bettie.internal.frields.org> On Sat, 2004-08-28 at 06:14, Dave Pawson wrote: > On Fri, 2004-08-27 at 21:56, Tammy Fox wrote: > > > > FWIW, I also like them uppercase for easy sighting while reading the > > document. > > Use the coloring capabilies of emacs if you need want them to stand out? > > (make-face 'sgml-entity-face) > (set-face-foreground 'sgml-entity-face "magenta") > > or whatever. > > I was just trying to reduce typing a little. Sure, that's understandable. My Emacs/psgml already colors them red using the standard .emacs entries available from the Documentation Guide. But I'm sometimes looking at them in a shell as well. -- Paul W. Frields, RHCE From mjohnson at redhat.com Sun Aug 29 02:33:34 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 28 Aug 2004 22:33:34 -0400 Subject: Style guide In-Reply-To: <1093021205.17095.7768.camel@erato.phig.org> References: <1092953506.25915.8.camel@bettie.internal.frields.org> <1092965662.17095.4056.camel@erato.phig.org> <1093007270.2319.7.camel@berlin.east.gov> <1093021205.17095.7768.camel@erato.phig.org> Message-ID: <4131407E.8000803@redhat.com> Hi All, (Probably should've started a new thread for this...) As I'm working on the Emacs/DocBook Quickstart guide, it occurs to me that that perhaps we should provide some required sections in the beginning of the document that would be intended to address such questions as (realizing that the following are not logically independent): - intended audience - scope of this document - what this document addresses - what this docuemt does not address - goals of this document (a pseudo re-phrasing of the above) - contributors to this document - scope of this document - [....]??? My feeling is that context that the above info provide are very important, in that they allow the reader to quickly assess the scope of the document and, hence, whether it is worth their time to read it. Past experience has shown that the mandatory inclusion of this sort of info a document/tutorial provides valuable info to the reader. My points (and questions), are then: - What, if any, should be the required metadata content for standard fedora docs (which at this point are tutorially structured)? Put another way, should we require some initial sections titled, e.g.: - intended audience - goals of this document (N.B. these are different from the scope as described below), and also provide a basis from which readers can file bug erports. E.g. Bug pointing out how doc doesn't achieve a given goal. - scope of this document (what it does/doesn't addressed in this section. - contributors 'Just thinking out loud here, but honestly do feel strongly that providing a template that requires some of the above-mentioned sections would add much value to docs generated by the fedora docs project. Since this is a rather high-level policy decision, I'm hoping to get feedback on this ASAP, as this sort of policy content would affect all docs written for fedora. FWIW, I'm also a Debian (www.debian.org) developer and have found that clear (& existing) policies regarding the requirement of content of the type I'm advocating is greatly helpful to both authors & readers. In short, it works. Please post your comments relating to my suggestion/proposal to the fediora-docs list. I'm interested in hearing what others think about my ideas to require initial content of this sort. FWIW, the inclusion of this type of document metadata is used by a number of orgnaizations, so I'm not proposing anthing new here. Standard stuff, but can add great value to a document. Thanks, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation Group Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Sun Aug 29 03:06:30 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 28 Aug 2004 23:06:30 -0400 Subject: DocBook/Emacs/psgml Quickstart Guide: update Message-ID: <41314836.5070804@redhat.com> Hi All, I'll re-post here the proposed timeline/outline for the DocBook/Emacs/psgml Quickstart Guide that I put into bugzilla. Thanks to Tammy's helpful poking:), I've now proposed a timeline for the DocBook/Emacs/psgml Quickstart Guide. It's recorded in bugzilla: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130032 But, to get the ideas into y'all's brains asap, I'll post my bugzilla entry here: -------===========================------- > From Tammy Fox : > Mark, can you provide an outline of this or a time frame? Sure. Since I'm doing RedHat work this weekend, I'll do some fedora doc work next week. How about I supply a draft outline (or doc) by Tuesday 8/30, collect bugs/feedback, and supply a pseudo-complete outline by Friday, 9/03. Then, provide a relatively complete document draft by Wednesday, 9/08, for everyone to critique. From there, I would say, give me another week to submit a revised document based on feedback, though I may be able to produce this version sooner. In other words, I submit a usable/postable version by Wednesday, 9/15. I then go on vacation from 9/18 - 9/25. Sound reasonable? (I'm working on it as I type this, FWIW.) -------===========================------- You can also read the bugzilla report yourself: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130032 To stick to this timeline, I'll need some quick turn-around editorial feedback. Hope we can get this out the door on schedule... Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation Group Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From davep at dpawson.co.uk Sun Aug 29 07:07:33 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 29 Aug 2004 08:07:33 +0100 Subject: Style guide In-Reply-To: <4131407E.8000803@redhat.com> References: <1092953506.25915.8.camel@bettie.internal.frields.org> <1092965662.17095.4056.camel@erato.phig.org> <1093007270.2319.7.camel@berlin.east.gov> <1093021205.17095.7768.camel@erato.phig.org> <4131407E.8000803@redhat.com> Message-ID: <1093763253.2518.6.camel@homer> On Sun, 2004-08-29 at 03:33, Mark Johnson wrote: > My points (and questions), are then: > > - What, if any, should be the required metadata content for standard > fedora docs (which at this point are tutorially structured)? Suggest minimally a *info for the top level, perhaps one per separate file (delivered) which would be sect1. This to allow some record of changes with the actual document. For any more, perhaps a better question is who want the metadata, hence what might they want? And I can't think of any 'customers' for metadata. > > Put another way, should we require some initial sections titled, e.g.: > > - intended audience > > - goals of this document (N.B. these are different from the scope as > described below), and also provide a basis from which readers can > file bug erports. E.g. Bug pointing out how doc doesn't achieve a > given goal. Yes, but only a few lines/couple of para's; intention to stop people who are reading the wrong doc? > > - scope of this document (what it does/doesn't addressed in this > section. Ditto above? > FWIW, the inclusion of this type of document metadata is used by a > number of orgnaizations, so I'm not proposing anthing new here. > Standard stuff, but can add great value to a document. Our definitions of metadata are at different levels :-) Audience, goals etc I'd see as part of the document. No matter. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From dataking at cox.net Sun Aug 29 12:16:49 2004 From: dataking at cox.net (D@7@k|N&) Date: Sun, 29 Aug 2004 12:16:49 +0000 Subject: Rough start... Message-ID: <1093781809.4508.14.camel@bach> Hi all. I've been doing some work on the hardening tutorial and I've gotten to the point where I have a few questions. First of all, do I need to do anything to the bugzilla report to show that work is actually being done on this guide? I've tried writing in emacs, and I feel like I'm fighting the program so much that I haven't been able to write any of the actual tutorial. So, I did some work in Kate, and am trying to back port it with the XML tags to make it fit the model. I followed the steps in the Doc Guide for setting up emacs, and I think I got it right, but tag completion, and coloring, etc. doesn't seem to be really intuitive. Anyhow, I've taken a look at the CVS stuff, and thought that the Install Guide my be a good one to use as an example, but that looks like a WIP. So, I took a look at the Doc Guide, and that's a little more complete. The layout of the Doc Guide implies that each chapter should be a separate document. Is this true? Or, if you build one monolithic document, will the Makefile parse all of the info correctly so that the different chapters break out into different pages? Finally, once I get documents complete, what's the best way to submit stuff to my editor? CVS? Bugzilla? Email? What items should be included in the submission? Thanks for hand-holding me right now. Once I get the hang of it, things should be a little easier, and I should be a little more prolific. After looking at the Doc Guide, writing in emacs/XML doesn't seem so daunting, so hopefully that won't be as much of an issue as I continue. Thanks. -Charlie -- -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From dataking at cox.net Sun Aug 29 12:18:43 2004 From: dataking at cox.net (D@7@k|N&) Date: Sun, 29 Aug 2004 12:18:43 +0000 Subject: Rough start... In-Reply-To: <1093781809.4508.14.camel@bach> References: <1093781809.4508.14.camel@bach> Message-ID: <1093781923.4508.17.camel@bach> On Sun, 2004-08-29 at 12:16, D at 7@k|N& wrote: > Hi all. > > I've been doing some work on the hardening tutorial and I've gotten to > the point where I have a few questions. > > First of all, do I need to do anything to the bugzilla report to show > that work is actually being done on this guide? > > I've tried writing in emacs, and I feel like I'm fighting the program so > much that I haven't been able to write any of the actual tutorial. So, > I did some work in Kate, and am trying to back port it with the XML tags > to make it fit the model. I followed the steps in the Doc Guide for > setting up emacs, and I think I got it right, but tag completion, and > coloring, etc. doesn't seem to be really intuitive. > > Anyhow, I've taken a look at the CVS stuff, and thought that the Install > Guide my be a good one to use as an example, but that looks like a WIP. > So, I took a look at the Doc Guide, and that's a little more complete. > The layout of the Doc Guide implies that each chapter should be a > separate document. Is this true? Or, if you build one monolithic > document, will the Makefile parse all of the info correctly so that the > different chapters break out into different pages? > > Finally, once I get documents complete, what's the best way to submit > stuff to my editor? CVS? Bugzilla? Email? What items should be > included in the submission? > > Thanks for hand-holding me right now. Once I get the hang of it, things > should be a little easier, and I should be a little more prolific. > After looking at the Doc Guide, writing in emacs/XML doesn't seem so > daunting, so hopefully that won't be as much of an issue as I continue. > > Thanks. > > -Charlie Oh, one more thing... Is 'make html' (or 'make pdf') the only way to view your progress? How do I need to tweak the Makefile so it will apply to my document? -- -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From paul at frields.com Sun Aug 29 21:30:10 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 29 Aug 2004 17:30:10 -0400 Subject: Rough start... In-Reply-To: <1093781809.4508.14.camel@bach> References: <1093781809.4508.14.camel@bach> Message-ID: <1093815010.5805.23.camel@bettie.internal.frields.org> On Sun, 2004-08-29 at 08:16, D at 7@k|N& wrote: > I've been doing some work on the hardening tutorial and I've gotten to > the point where I have a few questions. > > First of all, do I need to do anything to the bugzilla report to show > that work is actually being done on this guide? You could put your timeline and/or milestones in there for when you expect to have certain things done. See previous threads, and Tammy and Karsten's process documents, for more on that. > I've tried writing in emacs, and I feel like I'm fighting the program so > much that I haven't been able to write any of the actual tutorial. So, > I did some work in Kate, and am trying to back port it with the XML tags > to make it fit the model. I followed the steps in the Doc Guide for > setting up emacs, and I think I got it right, but tag completion, and > coloring, etc. doesn't seem to be really intuitive. I felt the same way when I started. Push through, and try working on something that is *not* your actual document, so you don't feel pressure about "getting things done," and are free to simply try the features out. I think it's probably too much for people to try to memorize the whole chart of Emacs/psgml key bindings in the Doc Guide. Here's what I did to start: 0. Spend a couple days avoiding all editors except Emacs, no matter *what* I was doing, FDP or other work. Spent an hour or so on the Emacs tutorial to learn some basic keystrokes -- only a few of which I've actually memorized, but just enough so that I'm not completely flailing 100% of the time. 1. Pull the .emacs stuff in the Doc Guide into my ~/.emacs file. 2. Download the CVS for fedora-docs, using the steps in the Doc Guide or on the front page of the FDP site. 3. Copy example-tutorial/ folder to foobar/ folder. 4. Open up foobar/example-tutorial-en.xml in Emacs. (A lot of times, I hit Alt+X, type "xml-mode" and hit ENTER to force XML mode, which makes some tag markup work better... do this as optional step 4B. I'm not sure if this is the "right" thing to do, but it stops psgml from acting strangely on tags that self-close, like .) 5. Hit Ctrl+C, Ctrl+P to parse the DTD stuff at the top. Colors should appear shortly thereafter. NOTE: Like you, I don't really feel this is "intuitive," but then, neither is :wq in vi, or hitting Alt+F4 to close a GUI application. They're just things you have to learn. After you use a step enough, it will be second nature to you. (Not being preachy, just matter o' fact. I've learned to accept that each time I learn a new keybinding in Emacs, it takes a few days of use to become habit. I can live with that!) 6. When writing a tag, hit Ctrl+C, < to open the tag, type the beginning of the tag, then TAB to autocomplete. I used this feature to discover a lot of other tags, but I try to stick mainly with the ones in the Doc Guide. If I find a situation not covered, I visit: The ToC there has a list of tags with short summaries of what each is for. That's really helpful! 7. If you have to port in XML written elsewhere (I call that a "last resort," avoidable if you really spend some time with Emacs), make sure you have a DTD section at the top just like the example-tutorial. Parse DTD with Ctrl+C, Ctrl+P, then Ctrl+C Ctrl+Q to resculpt the indentation. This part can get ugly, which is why I prefer to just write in Emacs! > Anyhow, I've taken a look at the CVS stuff, and thought that the Install > Guide my be a good one to use as an example, but that looks like a WIP. > So, I took a look at the Doc Guide, and that's a little more complete. > The layout of the Doc Guide implies that each chapter should be a > separate document. Is this true? Or, if you build one monolithic > document, will the Makefile parse all of the info correctly so that the > different chapters break out into different pages? The only reason to have separate documents is if you are doing a truly long work, and the amount of content requires it. (It means chapters can be assigned separately, for instance.) The Installation Guide's a no-brainer for that; so is the Doc Guide. But for what we do, the FDP suggests that you stick with tutorials that can be completed by one person without too much hassle. If you think your hardening guide is going to be much longer than 6-8 sections of a few pages each, then you might be better off writing an outline and posting it to Bugzilla and the list, to solicit more writers. Our current (and very pressing) need for an Installation Guide seems to say to me that you may want to participate on that as your "initial" project, and then move on to this once you've cut your teeth there. That's just a suggestion, because it seems to me that security and hardening is a somewhat open-ended topic, while installation is somewhat self-limiting, and therefore easier to tackle first. A hardening tutorial (or even a larger Security Guide) is a great idea, I just question the priority. If you write a tutorial as an
as suggested in the Doc Guide, each first-level
will break out into a separate HTML page. Doing the "make html" just takes care of it. You only need to edit the DOCNAME of the document in the Makefile. > Finally, once I get documents complete, what's the best way to submit > stuff to my editor? CVS? Bugzilla? Email? What items should be > included in the submission? The best way to do it IMHO is to submit a tarball of the XML stuff to Bugzilla, e-mail the list (maybe CC the editor), and point to the bug. Or, if you have a private web site, you can use that to serve out the XML source, but make sure the site clearly marks the document as a draft that is not official. Typically, you will want to write your document in a subfolder of the fedora-docs/ folder you downloaded through CVS. For instance, I have a ~/fedora-docs/usb-hotplug-tutorial/ folder, which contains a Makefile and usb-hotplug-tutorial-en.xml, the XML source. Just tarball your document by sitting in the fedora-docs/ folder and: tar czf my-tutorial.tar.gz my-tutorial/ Then any editor can simply pop the tarball out into the fedora-docs/ folder and have it automagically work for building. > Thanks for hand-holding me right now. Once I get the hang of it, things > should be a little easier, and I should be a little more prolific. > After looking at the Doc Guide, writing in emacs/XML doesn't seem so > daunting, so hopefully that won't be as much of an issue as I continue. Believe me, I know JUST where you're standing now, I'm only a few feet away on the other side of the hedge row. I occasionally glimpse Karsten and Dave P., yonder over the hill. Sometimes they throw things. *BONK* -- Paul W. Frields, RHCE From paul at frields.com Sun Aug 29 21:34:08 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 29 Aug 2004 17:34:08 -0400 Subject: Rough start... In-Reply-To: <1093781923.4508.17.camel@bach> References: <1093781809.4508.14.camel@bach> <1093781923.4508.17.camel@bach> Message-ID: <1093815248.5805.28.camel@bettie.internal.frields.org> On Sun, 2004-08-29 at 08:18, D at 7@k|N& wrote: > Oh, one more thing... Is 'make html' (or 'make pdf') the only way to > view your progress? How do I need to tweak the Makefile so it will > apply to my document? Yeah, pretty much. I do this once in a while since the "Validate" function in Emacs/psgml seems roughly worthless from where I'm sitting. I watch the output of xmlto (which is part of the "make" toolchain that runs) to see if my XML validates correctly. Sometimes reading the HTML back in Mozilla is a nice way to make sure the document flows. It can scan differently without all the tags in the way. I'll do a new make every once in a while sometimes to feel like I'm making progress. I built a cron script on my system to feed a nightly HTML build to my web server of all the documents on which I'm working. -- Paul W. Frields, RHCE From dataking at cox.net Sun Aug 29 14:59:24 2004 From: dataking at cox.net ('D@7@k|N&') Date: Sun, 29 Aug 2004 14:59:24 +0000 Subject: Rough start... In-Reply-To: <1093815010.5805.23.camel@bettie.internal.frields.org> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> Message-ID: <1093791564.4508.37.camel@bach> On Sun, 2004-08-29 at 21:30, Paul W. Frields wrote: > On Sun, 2004-08-29 at 08:16, D at 7@k|N& wrote: > > I've been doing some work on the hardening tutorial and I've gotten to > > the point where I have a few questions. > > > > First of all, do I need to do anything to the bugzilla report to show > > that work is actually being done on this guide? > > You could put your timeline and/or milestones in there for when you > expect to have certain things done. See previous threads, and Tammy and > Karsten's process documents, for more on that. Unfortunately, I'm not that organized, so I don't know when I will actually have time to work on this. So, an actual timeline might be tough. This weekend has been a great opportunity to get familiar with the tools, and start getting some content together. > > > I've tried writing in emacs, and I feel like I'm fighting the program so > > much that I haven't been able to write any of the actual tutorial. So, > > I did some work in Kate, and am trying to back port it with the XML tags > > to make it fit the model. I followed the steps in the Doc Guide for > > setting up emacs, and I think I got it right, but tag completion, and > > coloring, etc. doesn't seem to be really intuitive. > > I felt the same way when I started. Push through, and try working on > something that is *not* your actual document, so you don't feel pressure > about "getting things done," and are free to simply try the features > out. I think it's probably too much for people to try to memorize the > whole chart of Emacs/psgml key bindings in the Doc Guide. > > Here's what I did to start: > > 0. Spend a couple days avoiding all editors except Emacs, no matter > *what* I was doing, FDP or other work. Spent an hour or so on the Emacs > tutorial to learn some basic keystrokes -- only a few of which I've > actually memorized, but just enough so that I'm not completely flailing > 100% of the time. > > 1. Pull the .emacs stuff in the Doc Guide into my ~/.emacs file. Did that. > > 2. Download the CVS for fedora-docs, using the steps in the Doc Guide or > on the front page of the FDP site. Did that.... > > 3. Copy example-tutorial/ folder to foobar/ folder. ...yeah... > > 4. Open up foobar/example-tutorial-en.xml in Emacs. > > (A lot of times, I hit Alt+X, type "xml-mode" and hit ENTER to force XML > mode, which makes some tag markup work better... do this as optional > step 4B. I'm not sure if this is the "right" thing to do, but it stops > psgml from acting strangely on tags that self-close, like linkend="sn-some-target"/>.) > > 5. Hit Ctrl+C, Ctrl+P to parse the DTD stuff at the top. Colors should > appear shortly thereafter. > > NOTE: Like you, I don't really feel this is "intuitive," but then, > neither is :wq in vi, or hitting Alt+F4 to close a GUI application. > They're just things you have to learn. After you use a step enough, it > will be second nature to you. (Not being preachy, just matter o' fact. No worries. Alt+F4 happens to not be that elusive for me; I've been hit with enough adware/popups on my windows box that it's familiar. > I've learned to accept that each time I learn a new keybinding in Emacs, > it takes a few days of use to become habit. I can live with that!) > > 6. When writing a tag, hit Ctrl+C, < to open the tag, type the beginning > of the tag, then TAB to autocomplete. I used this feature to discover a > lot of other tags, but I try to stick mainly with the ones in the Doc > Guide. If I find a situation not covered, I visit: > > The ToC there has a list of tags with short summaries of what each is > for. That's really helpful! > > 7. If you have to port in XML written elsewhere (I call that a "last > resort," avoidable if you really spend some time with Emacs), make sure > you have a DTD section at the top just like the example-tutorial. Parse > DTD with Ctrl+C, Ctrl+P, then Ctrl+C Ctrl+Q to resculpt the indentation. > This part can get ugly, which is why I prefer to just write in Emacs! Well, that was the thing. The XML in general was killing me, and I wanted to get some basic content put together. SO I just wrote out the content in kate, and then went back and added the XML tags, modeled after the doc-guide. > > > Anyhow, I've taken a look at the CVS stuff, and thought that the Install > > Guide my be a good one to use as an example, but that looks like a WIP. > > So, I took a look at the Doc Guide, and that's a little more complete. > > The layout of the Doc Guide implies that each chapter should be a > > separate document. Is this true? Or, if you build one monolithic > > document, will the Makefile parse all of the info correctly so that the > > different chapters break out into different pages? > > The only reason to have separate documents is if you are doing a truly > long work, and the amount of content requires it. (It means chapters can > be assigned separately, for instance.) The Installation Guide's a > no-brainer for that; so is the Doc Guide. So, this should more or less be one monolithic document. > But for what we do, the FDP > suggests that you stick with tutorials that can be completed by one > person without too much hassle. If you think your hardening guide is > going to be much longer than 6-8 sections of a few pages each, then you > might be better off writing an outline and posting it to Bugzilla and > the list, to solicit more writers. > Verbosity, and scope of content was never an issue for me. I used to handwrite write 1500 word, open book, essays in an hour (in class) when I was in high school ( a loooong time ago ;). I think that a document of the magnitude you describe would be no problem for one person if the content is driving the document. > Our current (and very pressing) need for an Installation Guide seems to > say to me that you may want to participate on that as your "initial" > project, and then move on to this once you've cut your teeth there. How do I do that? How do I know what needs to be done, so that I'm not duplicating work? > That's just a suggestion, because it seems to me that security and > hardening is a somewhat open-ended topic, while installation is somewhat > self-limiting, and therefore easier to tackle first. A hardening > tutorial (or even a larger Security Guide) is a great idea, I just > question the priority. True. However, being a security engineer, I tend to place a great deal of value on security and it's implementation. > > If you write a tutorial as an
as suggested in the Doc Guide, > each first-level
will break out into a separate HTML page. > Doing the "make html" just takes care of it. You only need to edit the > DOCNAME of the document in the Makefile. Finally figured that out, once I got things in order and was able to get the 'make html' work. > > > Finally, once I get documents complete, what's the best way to submit > > stuff to my editor? CVS? Bugzilla? Email? What items should be > > included in the submission? > > The best way to do it IMHO is to submit a tarball of the XML stuff to > Bugzilla, e-mail the list (maybe CC the editor), and point to the bug. > Or, if you have a private web site, you can use that to serve out the > XML source, but make sure the site clearly marks the document as a draft > that is not official. > > Typically, you will want to write your document in a subfolder of the > fedora-docs/ folder you downloaded through CVS. For instance, I have a > ~/fedora-docs/usb-hotplug-tutorial/ folder, which contains a Makefile > and usb-hotplug-tutorial-en.xml, the XML source. Just tarball your > document by sitting in the fedora-docs/ folder and: > > tar czf my-tutorial.tar.gz my-tutorial/ > > Then any editor can simply pop the tarball out into the fedora-docs/ > folder and have it automagically work for building. > > > Thanks for hand-holding me right now. Once I get the hang of it, things > > should be a little easier, and I should be a little more prolific. > > After looking at the Doc Guide, writing in emacs/XML doesn't seem so > > daunting, so hopefully that won't be as much of an issue as I continue. > > Believe me, I know JUST where you're standing now, I'm only a few feet > away on the other side of the hedge row. I occasionally glimpse Karsten > and Dave P., yonder over the hill. Sometimes they throw things. *BONK* I'll post my outline to the bug, and maybe people will have some suggestions on sections to add. My focus for this doc, has been to use Fedora "native" utilities to accomplish the task at hand (securing your system). Introducing third party tools would increase the scope of the document, and may require additional authors, but I doubt it. ;) I already feel like I'm getting used to the tags, and having written HTML for almost 7 years, I should be able to slip right into it. Thanks again for the tips and the list's patience. ;) -- -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From dataking at cox.net Sun Aug 29 15:01:56 2004 From: dataking at cox.net ('D@7@k|N&') Date: Sun, 29 Aug 2004 15:01:56 +0000 Subject: Rough start... In-Reply-To: <1093815248.5805.28.camel@bettie.internal.frields.org> References: <1093781809.4508.14.camel@bach> <1093781923.4508.17.camel@bach> <1093815248.5805.28.camel@bettie.internal.frields.org> Message-ID: <1093791716.4508.40.camel@bach> On Sun, 2004-08-29 at 21:34, Paul W. Frields wrote: > On Sun, 2004-08-29 at 08:18, D at 7@k|N& wrote: > > Oh, one more thing... Is 'make html' (or 'make pdf') the only way to > > view your progress? How do I need to tweak the Makefile so it will > > apply to my document? > > Yeah, pretty much. I do this once in a while since the "Validate" > function in Emacs/psgml seems roughly worthless from where I'm sitting. > I watch the output of xmlto (which is part of the "make" toolchain that > runs) to see if my XML validates correctly. > > Sometimes reading the HTML back in Mozilla is a nice way to make sure > the document flows. It can scan differently without all the tags in the > way. I'll do a new make every once in a while sometimes to feel like I'm > making progress. > > I built a cron script on my system to feed a nightly HTML build to my > web server of all the documents on which I'm working. > > -- > Paul W. Frields, RHCE Cool. I find that I need immediate feedback when working on something like this. So, I've been running 'make html' to be able to view the document (as it progresses) in my browser. Just didn't know if there was a better (faster/easier) way. -- -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From paul at frields.com Sun Aug 29 23:55:47 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 29 Aug 2004 19:55:47 -0400 Subject: Rough start... In-Reply-To: <1093791564.4508.37.camel@bach> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> Message-ID: <1093823747.14439.21.camel@bettie.internal.frields.org> On Sun, 2004-08-29 at 10:59, 'D at 7@k|N&' wrote: > Unfortunately, I'm not that organized, so I don't know when I will > actually have time to work on this. So, an actual timeline might be > tough. This weekend has been a great opportunity to get familiar with > the tools, and start getting some content together. Once you're more familiar with the tools, like anything else, projecting how long it takes to get things done gets easier. Sounds like you're on your way. [...snip...] > > 6. When writing a tag, hit Ctrl+C, < to open the tag, type the beginning > > of the tag, then TAB to autocomplete. I used this feature to discover a > > lot of other tags, but I try to stick mainly with the ones in the Doc > > Guide. If I find a situation not covered, I visit: > > > > The ToC there has a list of tags with short summaries of what each is > > for. That's really helpful! > > > > 7. If you have to port in XML written elsewhere (I call that a "last > > resort," avoidable if you really spend some time with Emacs), make sure > > you have a DTD section at the top just like the example-tutorial. Parse > > DTD with Ctrl+C, Ctrl+P, then Ctrl+C Ctrl+Q to resculpt the indentation. > > This part can get ugly, which is why I prefer to just write in Emacs! > > Well, that was the thing. The XML in general was killing me, and I > wanted to get some basic content put together. SO I just wrote out the > content in kate, and then went back and added the XML tags, modeled > after the doc-guide. There's nothing wrong with that approach, but once you learn the Emacs stuff you probably won't bother. At least that's been my experience. [...snip...] > > The only reason to have separate documents is if you are doing a truly > > long work, and the amount of content requires it. (It means chapters can > > be assigned separately, for instance.) The Installation Guide's a > > no-brainer for that; so is the Doc Guide. > > So, this should more or less be one monolithic document. Right. One of my current docs, mirror-tutorial, will probably end up around 2000 lines. > > But for what we do, the FDP > > suggests that you stick with tutorials that can be completed by one > > person without too much hassle. If you think your hardening guide is > > going to be much longer than 6-8 sections of a few pages each, then you > > might be better off writing an outline and posting it to Bugzilla and > > the list, to solicit more writers. > > > > Verbosity, and scope of content was never an issue for me. I used to > handwrite write 1500 word, open book, essays in an hour (in class) when > I was in high school ( a loooong time ago ;). I think that a document > of the magnitude you describe would be no problem for one person if the > content is driving the document. *nod* The great thing about using DocBook is that your content always drives, and you don't have to worry about presentation. I've been working by making an outline using just sections and titles, and filling them in as I go. If I think of something along the way, I just make a comment note , rearrange sections as needed, and so forth. > > Our current (and very pressing) need for an Installation Guide seems to > > say to me that you may want to participate on that as your "initial" > > project, and then move on to this once you've cut your teeth there. > > How do I do that? How do I know what needs to be done, so that I'm not > duplicating work? Glad you asked. Did you know that you can see a list of all open issues for fedora-docs, as bugs in Bugzilla? Here's what I use for a query.[1] http://bugzilla.redhat.com/bugzilla/query.cgi?query_format=&short_desc_type=allwordssubstr&short_desc=&product=Fedora%20Core&component=fedora-docs&component_text=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&long_desc_type=allwordssubstr&bug_file_loc_type=allwordssubstr Bug 129911, it turns out, is the Installation Guide bug. Read that bug; drop a line to the list and a comment in that Bugzilla bug about what you're interested in doing. > > That's just a suggestion, because it seems to me that security and > > hardening is a somewhat open-ended topic, while installation is somewhat > > self-limiting, and therefore easier to tackle first. A hardening > > tutorial (or even a larger Security Guide) is a great idea, I just > > question the priority. > > True. However, being a security engineer, I tend to place a great deal > of value on security and it's implementation. Absolutely. I should have been more clear: Although security is *very* important, producing a Security Guide is *less* important than an Installation guide right now. [...snip...] > > > Finally, once I get documents complete, what's the best way to submit > > > stuff to my editor? CVS? Bugzilla? Email? What items should be > > > included in the submission? > > > > The best way to do it IMHO is to submit a tarball of the XML stuff to > > Bugzilla, e-mail the list (maybe CC the editor), and point to the bug. > > Or, if you have a private web site, you can use that to serve out the > > XML source, but make sure the site clearly marks the document as a draft > > that is not official. > > > > Typically, you will want to write your document in a subfolder of the > > fedora-docs/ folder you downloaded through CVS. For instance, I have a > > ~/fedora-docs/usb-hotplug-tutorial/ folder, which contains a Makefile > > and usb-hotplug-tutorial-en.xml, the XML source. Just tarball your > > document by sitting in the fedora-docs/ folder and: > > > > tar czf my-tutorial.tar.gz my-tutorial/ > > > > Then any editor can simply pop the tarball out into the fedora-docs/ > > folder and have it automagically work for building. > > > > > Thanks for hand-holding me right now. Once I get the hang of it, things > > > should be a little easier, and I should be a little more prolific. > > > After looking at the Doc Guide, writing in emacs/XML doesn't seem so > > > daunting, so hopefully that won't be as much of an issue as I continue. > > > > Believe me, I know JUST where you're standing now, I'm only a few feet > > away on the other side of the hedge row. I occasionally glimpse Karsten > > and Dave P., yonder over the hill. Sometimes they throw things. *BONK* > > I'll post my outline to the bug, and maybe people will have some > suggestions on sections to add. My focus for this doc, has been to use > Fedora "native" utilities to accomplish the task at hand (securing your > system). Introducing third party tools would increase the scope of the > document, and may require additional authors, but I doubt it. ;) This is a fine idea. And I would say, FWIW, that your focus on using the utilities in the distribution is *absolutely* the right way to go for official FDP docs. There are way too many sites that solve problems in Fedora Core by downloading a third-party utility, rather than using some of the existing tools. In many cases, it's hard to tell whether that's because the third-party tool is actually better, or if the author simply doesn't know how to use what's already available. As the "official" documentation site we should aim for helping people understand all the goodies that come right out of the box. > I already feel like I'm getting used to the tags, and having written > HTML for almost 7 years, I should be able to slip right into it. > > Thanks again for the tips and the list's patience. ;) Thanks for your time and dedication -- that's on behalf of everyone, I'm sure. The project is what we make of it, no more, no less! :-) -- Paul W. Frields, RHCE From mjohnson at redhat.com Mon Aug 30 00:10:41 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sun, 29 Aug 2004 20:10:41 -0400 Subject: Rough start... In-Reply-To: <1093791564.4508.37.camel@bach> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> Message-ID: <41327081.7010408@redhat.com> 'D at 7@k|N&' wrote: >>1. Pull the .emacs stuff in the Doc Guide into my ~/.emacs file. Another user-friendly alternative would be to use my 'psgmlx' package, which not only does all the SGML/XML editing setup for you, it also provides the capability to tag content or add/change attributes by right-clicking the mouse in various places in your document. It also provides a number of color themes specifically for editing SGML/XML documents, all of which are accessible from the 'SGML' menu when in sgml-mode or xml-mode. To use/install it, all you need to do is to expand the tarball, run the 'test' script, put a couple snippets in your .emacs, choose a default color-theme, and you're up and running. BTW, specific installation instructions are provided in a popup emacs window when you run the 'test' script. You can download & read more about psgmlx at the home page: http://dulug.duke.edu/~mark/psgmlx/ If you do choose to go this route, you should either start a new .emacs file (rename your old one), and add the snippets to it, or else place the psgmlx stuff *after* the stuff you've put in from the Docs Guide. Either way, don't forget to byte compile the new .emacs. OTOH, if you're happy with your setup, don't change it. HTH. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation Group Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From dataking at cox.net Sun Aug 29 18:27:08 2004 From: dataking at cox.net ('D@7@k|N&') Date: Sun, 29 Aug 2004 18:27:08 +0000 Subject: Possibly stupid question... Message-ID: <1093804027.4508.49.camel@bach> Since I have been working on the hardening tute, I've been doing so with the Docs Guide open, so I have an immediate reference for the tags that I should be using. I noticed something, that other people may have noticed, but I don't really understand the point of. The , , , , , and several other tags, all seem to just make the text bold. Is there a reason that these aren't more defined? (Something really could would be to id the guimenu buttons, and have the tag insert the graphic for that button, etc.) Without the more differentiating characteristics, what is the point of using different tags? -Charlie -- -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From dasho at ma-isp.com Mon Aug 30 10:47:15 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Mon, 30 Aug 2004 12:47:15 +0200 Subject: Fwd: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server Message-ID: <200408301247.15581.dasho@ma-isp.com> -------------- next part -------------- An embedded message was scrubbed... From: bugzilla at redhat.com Subject: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server Date: Mon, 30 Aug 2004 06:33:14 -0400 Size: 2711 URL: From paul at frields.com Mon Aug 30 11:25:44 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 30 Aug 2004 07:25:44 -0400 Subject: Possibly stupid question... In-Reply-To: <1093804027.4508.49.camel@bach> References: <1093804027.4508.49.camel@bach> Message-ID: <1093865144.2401.7.camel@berlin.east.gov> On Sun, 2004-08-29 at 14:27, 'D at 7@k|N&' wrote: > Since I have been working on the hardening tute, I've been doing so with > the Docs Guide open, so I have an immediate reference for the tags that > I should be using. I noticed something, that other people may have > noticed, but I don't really understand the point of. The > , , , , > , and several other tags, all seem to just make the text > bold. Is there a reason that these aren't more defined? (Something > really could would be to id the guimenu buttons, and have the tag insert > the graphic for that button, etc.) Without the more differentiating > characteristics, what is the point of using different tags? The same as the point of any markup language... if a new stylesheet (XSLT?) is developed, you don't have to go back and re-markup all those tags to take advantage of it. Inserting "graphics" for buttons would mean that you have to have a graphic for any button that might come up, and if they change, well, that would be a full-time job just to keep someone on updating them. In a rendering environment where you could (for instance) simply surround a selected group of characters with a gray frame with a black border, the result would look like a key, no? I think this is possible with Web browsers that support HTML 4.0 (i.e. most everything nowadays). I'm not sure what the impact is on text browsing people provided you use a transformation like that; likely minimal. Using an actual graphics character, though, would likely screw those folks up. Always think accessibility! I know for a fact there are several visually-impaired and/or blind persons on some of the fedora lists who are very vocal about problems they have with some a11y features. -- Paul W. Frields, RHCE From rahulsundaram at yahoo.co.in Mon Aug 30 11:07:16 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Mon, 30 Aug 2004 04:07:16 -0700 (PDT) Subject: Fwd: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server In-Reply-To: <200408301247.15581.dasho@ma-isp.com> Message-ID: <20040830110716.37477.qmail@web8507.mail.in.yahoo.com> --- Dashamir Hoxha wrote: > Looks like it has been filled and assigned appropriately. You might want to call it a howto instead of a manual. that seems to the more appropriate terminology but wait for feedback from the other fedora doc editors and volunteers regards Rahul Sundaram __________________________________ Do you Yahoo!? Yahoo! Mail Address AutoComplete - You start. We finish. http://promotions.yahoo.com/new_mail From paul at frields.com Mon Aug 30 11:32:45 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 30 Aug 2004 07:32:45 -0400 Subject: Fwd: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server In-Reply-To: <200408301247.15581.dasho@ma-isp.com> References: <200408301247.15581.dasho@ma-isp.com> Message-ID: <1093865564.2401.11.camel@berlin.east.gov> On Mon, 2004-08-30 at 06:47, Dashamir Hoxha wrote: > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131233 > > Summary: Tutorial About Installing a Simple Gateway Server > Product: Fedora Core > Version: devel > Platform: All > URL: http://www.soft.inima.al/docs/ [...snip...] It looks like it could be a tutorial to me, like the summary says. The only problem I had is that I couldn't download the DocBook/XML or any other format from the sidebar. Can you either upload a copy to the bug, or fix the Web server appropriately? -- Paul W. Frields, RHCE From dasho at ma-isp.com Mon Aug 30 15:02:21 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Mon, 30 Aug 2004 17:02:21 +0200 Subject: Fwd: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server In-Reply-To: <1093865564.2401.11.camel@berlin.east.gov> References: <200408301247.15581.dasho@ma-isp.com> <1093865564.2401.11.camel@berlin.east.gov> Message-ID: <200408301702.21409.dasho@ma-isp.com> I have already fixed the web server, and you can also download it from: http://www.soft.inima.al/docs/content/downloads/ > only problem I had is that I couldn't download the DocBook/XML or any > other format from the sidebar. Can you either upload a copy to the bug, > or fix the Web server appropriately? Dashamir From s.ellis at fastmail.co.uk Mon Aug 30 19:53:31 2004 From: s.ellis at fastmail.co.uk (Stuart Ellis) Date: Mon, 30 Aug 2004 20:53:31 +0100 Subject: FedoraCommunity.org (was:Re: fedora-docs bugs) In-Reply-To: <1093645974.17095.67056.camel@erato.phig.org> References: <1092318823.18844.155.camel@berlin.east.gov> <1092411986.2449.4.camel@berlin.east.gov> <1092421880.4488.35482.camel@erato.phig.org> <200408131607.06416.hoyt@cavtel.net> <1093399053.12188.330.camel@albus.aeon.com.my> <1093645974.17095.67056.camel@erato.phig.org> Message-ID: <1093895611.14175.15.camel@hampton.eln.lan> On Fri, 2004-08-27 at 23:32, Karsten Wade wrote: > Should we add that text to a References
in every document that > wants to refer to sources of information outside of the guide itself? > > That References
would include listing other Fedora docs, but > would not specify any non-Fedora URL or project name, instead suggesting > a Google search. > > IMO, this is also more useful to our readers -- our docs aren't > populated with links liable to get outdated or be difficult to > maintain, and readers get access to popular and useful sources of > information. > I think that this is a very good idea. I suspect that most documents/tutorials can potentially have links to third-party sites, but keeping the URLs up to date on a large set could be near impossible even with a checking script to flag broken links. A bibliography style References section would probably offer enough keywords for Google with no maintenance. And Google cache offers some insurance against referenced docs just disappearing... From s.ellis at fastmail.co.uk Mon Aug 30 20:20:46 2004 From: s.ellis at fastmail.co.uk (Stuart Ellis) Date: Mon, 30 Aug 2004 21:20:46 +0100 Subject: installation guide In-Reply-To: <1093649591.17095.67458.camel@erato.phig.org> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> <1093641455.27934.249.camel@localhost.localdomain> <1093646012.3341.3.camel@bettie.internal.frields.org> <1093649591.17095.67458.camel@erato.phig.org> Message-ID: <1093897246.14175.25.camel@hampton.eln.lan> On Sat, 2004-08-28 at 00:33, Karsten Wade wrote: > Okay, I'm onboard for the All Hands on Deck for an Installation Guide > for FC3. > > We have until about 20 October to have a release candidate, and this is > possible to do if we make the pieces small enough and keep the editors > busy. Is there any existing material we can use as a basis, or just guidance on how a Fedora doc should be ? One of the nice things about working on GNOME docs is that between the Style Guide and the existing documentation the "house style" is very clearly defined, so that it was easy to write to the format. If nothing else is more appropriate, would the Release Notes be a good base-line in this respect ? From kwade at redhat.com Mon Aug 30 21:07:11 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 14:07:11 -0700 Subject: installation guide In-Reply-To: <1093897246.14175.25.camel@hampton.eln.lan> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> <1093641455.27934.249.camel@localhost.localdomain> <1093646012.3341.3.camel@bettie.internal.frields.org> <1093649591.17095.67458.camel@erato.phig.org> <1093897246.14175.25.camel@hampton.eln.lan> Message-ID: <1093900030.17095.92658.camel@erato.phig.org> On Mon, 2004-08-30 at 13:20, Stuart Ellis wrote: > On Sat, 2004-08-28 at 00:33, Karsten Wade wrote: > > Okay, I'm onboard for the All Hands on Deck for an Installation Guide > > for FC3. > > > > We have until about 20 October to have a release candidate, and this is > > possible to do if we make the pieces small enough and keep the editors > > busy. > > Is there any existing material we can use as a basis, or just guidance > on how a Fedora doc should be ? > > One of the nice things about working on GNOME docs is that between the > Style Guide and the existing documentation the "house style" is very > clearly defined, so that it was easy to write to the format. If nothing > else is more appropriate, would the Release Notes be a good base-line in > this respect ? In the interest of speed, I think we're trying to make this up as we go on. To get docs out in time for FC3, we'll need to take an iterative approach: 1) Work with what we have. 2) Get caught by snags, resolve, propose the solution to the list. 3) With just a few +1s or -1s we resolve the matter and write it to the process/templates/Doc Guide/wherever that piece belongs. 4) Include the new style decisions, fix everything we have to match that, and move on. 5) Back to 1). Still, we can take the next few days to hammer out more items, but much longer than that and we will be behind the curve. I propose: 1) We make a short list of reference sites/materials. 2) When in doubt, refer to the list. 3) If two or more reference sites are contradictory, bring it to the mailing list. 4) Try to capture the definite items we want in our Style Guidelines - required sections, styles, etc. - as we go along So far we can reference: * Fedora Documentation Guide * GNOME Style Guide -- Paul had a recommended list of chapters * Red Hat documentation -- redhat.com/docs * Elements of Style -- free edition available - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 30 21:15:33 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 14:15:33 -0700 Subject: common opening sections (was Re: Style guide) Message-ID: <1093900532.17095.92724.camel@erato.phig.org> I think the below sounds reasonable and correct. With this kind of stuff, it's just so automatic for me to include it, and I haven't really sat down to analyze a tutorial structure to break it out more clearly. I definitely think we need these common sections. On Sat, 2004-08-28 at 19:33, Mark Johnson wrote: > As I'm working on the Emacs/DocBook Quickstart guide, it occurs to > me that that perhaps we should provide some required sections in the > beginning of the document that would be intended to address such > questions as (realizing that the following are not logically > independent): Since it sounds as if you are writing a set of these yourself, how about if you complete your version and submit it as a draft for a common, single
containing file. That will be kept in fedora-docs/common. When we see your version in action, we can then make any tweaks/suggestions, and then make it part of any document. Few specific thoughts at this point: > - intended audience > - scope of this document > - what this document addresses > - what this docuemt does not address > - goals of this document (a pseudo re-phrasing of the above) > - contributors to this document > - scope of this document > - [....]??? That's pretty much it; just a sentence or two each, so this is about one paragraph right at the start. > My feeling is that context that the above info provide are very > important, in that they allow the reader to quickly assess the scope > of the document and, hence, whether it is worth their time to read > it. Past experience has shown that the mandatory inclusion of this > sort of info a document/tutorial provides valuable info to the reader. Agreed > My points (and questions), are then: > > - What, if any, should be the required metadata content for standard > fedora docs (which at this point are tutorially structured)? >From Dave's response, I'm not sure I know what kind of metadata you are talking about. Is this part of the DocBook structure? > Put another way, should we require some initial sections titled, e.g.: > > - intended audience > > - goals of this document (N.B. these are different from the scope as > described below), and also provide a basis from which readers can > file bug erports. E.g. Bug pointing out how doc doesn't achieve a > given goal. > > - scope of this document (what it does/doesn't addressed in this > section. > > - contributors Having a contributors
(as part of the single, common file) would be a good way to handle long lists of contributors. Otherwise, I would recommend hacking the stylesheet so we didn't have a full page of authors as the standard DB stylesheets does for the . Another section we might consider is a document conventions section [1]. Is this appropriate/necessary/useful for tutorial sized documents? It's probably also unnecessary for right now, but something we could develop. FWIW, I'm intere [1] E.g. http://www.redhat.com/docs/manuals/enterprise/RHEL-3-Manual/x8664-multi-install-guide/ch-intro.html#S1-INTRO-CONVENTIONS - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 30 21:36:39 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 14:36:39 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093668457.4188.53.camel@bettie.internal.frields.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> Message-ID: <1093901799.17095.92860.camel@erato.phig.org> On Fri, 2004-08-27 at 21:47, Paul W. Frields wrote: > On Fri, 2004-08-27 at 21:34, Karsten Wade wrote: > > Note thought that I broke rules from the Documentation Guide: > > > > 1. I used a meaningful ID for , dropping the location and section > > specific information. At this point, the most legitimate debate is > > between "similar-to-title" and "s.similar.to.title", the latter being > > Norm Walsh's current usage. > > I like using meaningful ID's; I have moved to using
tags, with > "sn-meaningful-title". Modularity, check. Easy to grab all > element-related ID's with a regex, also check. Okay, so the proposals for new ID generation rules are: 1. "similar-to-title" 2. "s.similar.to.title" 3. "sn-similar-to-title" I combined "meaningful" and "similar to" under the idea that an ID should closely match the title and have the same meaning as title, but not necessarily be the same length as the title (which could be very long). > I have seen the most problem in the PDF builds, but the HTML builds also > seem to do funny stuff with more vertical space if you don't run your > first and last text against the opening and closing tags, > respectively. In other words, given these two examples: > > > > > foo > bar > > > > > foo > bar > > The second example renders into a more pleasing vertical context, > without a lot of wasted space. The PDF, IIRC, was particularly ugly if > you didn't use the second form, but I seem to remember the HTML also was > noticeably different. I can't get anything to build PDF right now to test this, but in HTML I see the same thing as output, so am not sure of the advantage of the different way you suggest it. I do notice that doing sgml-fill-paragraph will make them line up like: foo bar Then introducing the line break gets the functionality you mention. Ultimately, I think we will want to drop the redundant and use a CDATA container instead. In that case, _all_ whitespace will be considered for certain. All content will need to use the left margin of the XML as starting point for indention. > I posted an additive patch to Bugzilla for you to take a look at. I feel > a little strange correcting work by someone who does this for a living, > when I'm more of a dilettante. Hope the editing sparks something > positive. I'll look today. > > - Karsten, off to see Run Lola Run at http://www.thespoon.com/drivein/ > > Very good movie! Not that it's necessarily going to be at a Guerilla > Drive-In, but if you like "Run Lola Run," you should see Tom Tykwer's > film of Krzysztof Kieslowki's "Heaven," if you haven't already. (Sorry > for going OT at the end there. Now I'm going TB as well.) I'll suggest it; I've seen RLR before, it was a cool experience. I may throw up some paras about it on blogs.redhat.com/people. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 30 21:40:10 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 14:40:10 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093695950.6210.2.camel@bettie.internal.frields.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> Message-ID: <1093902009.17095.92882.camel@erato.phig.org> On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote: > On Sat, 2004-08-28 at 06:30, Dave Pawson wrote: > > What processing tools Paul? > > And why is computeroutput necessary within screen? I'd have thought an > > either or was more reasonable for the processor to sort out? I am advocating: Same for blocks. This material, in the Fedora Doc Guide, is historical practice that we can (and should) revise. > I'm using the standard toolset and practices from the Documentation > Guide. Maybe that piece should be revisited in the Documentation Guide, > which indicates the proper syntax looks like this: > > cmd -i arg1 > Uh-uh, you can't do that. That's not what I see on this page: http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 30 21:45:22 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 14:45:22 -0700 Subject: Rough start... In-Reply-To: <1093791716.4508.40.camel@bach> References: <1093781809.4508.14.camel@bach> <1093781923.4508.17.camel@bach> <1093815248.5805.28.camel@bettie.internal.frields.org> <1093791716.4508.40.camel@bach> Message-ID: <1093902321.17095.92924.camel@erato.phig.org> On Sun, 2004-08-29 at 08:01, 'D at 7@k|N&' wrote: > Cool. I find that I need immediate feedback when working on something > like this. So, I've been running 'make html' to be able to view the > document (as it progresses) in my browser. Just didn't know if there > was a better (faster/easier) way. This method works, too, giving you just plain HTML without our custom styling: xmlto html-nochunks file.xml or if you want it with chunks, I recommend a sup-directory: xmlto -o directory/ file.xml I do this when working with a really big document and don't want custom, lengthy pieces such as the index building done. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 30 22:06:16 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 15:06:16 -0700 Subject: Rough start... In-Reply-To: <1093791564.4508.37.camel@bach> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> Message-ID: <1093903576.17095.93068.camel@erato.phig.org> On Sun, 2004-08-29 at 07:59, 'D at 7@k|N&' wrote: You are a perfect candidate for PSMLX: http://dulug.duke.edu/~mark/psgmlx/ It's designed to help newbies to Emacs _and_ DocBook. Mark is working on a short tutorial around PSGMLX, so you can wait for that if you want, but installing and trying it out is easy. Helpful points: * More colors to help you out. * Automatically parses the DTD when you load the XML file. * Right-click will show you menus of tags that are available at that exact location. Then you can use all of the PSGML keybindings you don't know yet, but will learn to love. > On Sun, 2004-08-29 at 21:30, Paul W. Frields wrote: > > On Sun, 2004-08-29 at 08:16, D at 7@k|N& wrote: > Unfortunately, I'm not that organized, so I don't know when I will > actually have time to work on this. So, an actual timeline might be > tough. This weekend has been a great opportunity to get familiar with > the tools, and start getting some content together. A strawman milestone schedule will work, but don't feel that is required. You could also attach your XML in various (broken) stages, or other updates and questions. For questions, make sure the proper people are on the cc: (such as an assigned editor, who you don't have yet). > Well, that was the thing. The XML in general was killing me, and I > wanted to get some basic content put together. SO I just wrote out the > content in kate, and then went back and added the XML tags, modeled > after the doc-guide. I sometimes write in plain text and then add tags. That's a very legitimate way to work. > > The only reason to have separate documents is if you are doing a truly > > long work, and the amount of content requires it. (It means chapters can > > be assigned separately, for instance.) The Installation Guide's a > > no-brainer for that; so is the Doc Guide. > > So, this should more or less be one monolithic document. It can be, but if you want to break out your sections into separate files because they are getting long, you can do this with any section you want separate: 1. Define this at the top of your main (parent) XML file: Then where you want the section(s) to appear, you put: &SECTION-FOO; Of course, you need to respect the nesting rules and call those sections only where they are allowed. > Verbosity, and scope of content was never an issue for me. I used to > handwrite write 1500 word, open book, essays in an hour (in class) when > I was in high school ( a loooong time ago ;). I think that a document > of the magnitude you describe would be no problem for one person if the > content is driving the document. To quickly revisit the reasoning I still support tutorials over long guides: My job at Red Hat is to write and maintain two guides of about 100 pages each (when printed to HTML). They'll likely grow in time. But that is the core of my entire job. 40+ hours per week, every week, every month, all year, to keep track the technology as it progresses, how it interacts with our solutions, and write about them. Unless your employer is going to pay you to spend about 1/2 of your time on writing and maintaining a Fedora Security Guide, I think you're going to find it's much more time than you are willing or able to volunteer. Remember, writing is much more than just flowing words onto paper. :) Now, for larger guides, I really like the idea of the modular approach. It's like other parts of open source development, giving us all something that is within our available time to write and maintain, which comes together in the end to make something synergistic. > > Our current (and very pressing) need for an Installation Guide seems to > > say to me that you may want to participate on that as your "initial" > > project, and then move on to this once you've cut your teeth there. > > How do I do that? How do I know what needs to be done, so that I'm not > duplicating work? Good question. :) We need to work on that early this week, deciding which sections to have in the ToC, and then assigning them. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 30 22:10:52 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 15:10:52 -0700 Subject: Rough start... In-Reply-To: <41327081.7010408@redhat.com> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> <41327081.7010408@redhat.com> Message-ID: <1093903852.17095.93095.camel@erato.phig.org> On Sun, 2004-08-29 at 17:10, Mark Johnson wrote: > Either way, don't forget to byte compile the new .emacs. Always something new for me to learn ... Was this a step in the PSGMLX setup? I hadn't heard about the value of byte-compiling in Emacs (until I just google'd about it). Can you give us the shortcut method and reasoning? thx - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Mon Aug 30 22:11:21 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 30 Aug 2004 18:11:21 -0400 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093902009.17095.92882.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> Message-ID: <1093903881.3666.1.camel@bettie.internal.frields.org> On Mon, 2004-08-30 at 17:40, Karsten Wade wrote: > On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote: > > On Sat, 2004-08-28 at 06:30, Dave Pawson wrote: > > > What processing tools Paul? > > > And why is computeroutput necessary within screen? I'd have thought an > > > either or was more reasonable for the processor to sort out? > > I am advocating: > > > foo { > bar () > } > ]]> > > > Same for blocks. > > This material, in the Fedora Doc Guide, is historical practice that we > can (and should) revise. > > > I'm using the standard toolset and practices from the Documentation > > Guide. Maybe that piece should be revisited in the Documentation Guide, > > which indicates the proper syntax looks like this: > > > > cmd -i arg1 > > Uh-uh, you can't do that. > > That's not what I see on this page: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html You're right. I think I changed this in my usage because the extra linefeeds were causing the PDF rendering to use WAY too much vertical space. Would a bug report for that go against xmlto, then? And how does your recommendation fare for those purposes? -- Paul W. Frields, RHCE From kwade at redhat.com Mon Aug 30 22:22:41 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 15:22:41 -0700 Subject: Possibly stupid question... In-Reply-To: <1093804027.4508.49.camel@bach> References: <1093804027.4508.49.camel@bach> Message-ID: <1093904560.17095.93180.camel@erato.phig.org> On Sun, 2004-08-29 at 11:27, 'D at 7@k|N&' wrote: > Since I have been working on the hardening tute, I've been doing so with > the Docs Guide open, so I have an immediate reference for the tags that > I should be using. I noticed something, that other people may have > noticed, but I don't really understand the point of. The > , , , , > , and several other tags, all seem to just make the text > bold. Is there a reason that these aren't more defined? (Something > really could would be to id the guimenu buttons, and have the tag insert > the graphic for that button, etc.) Without the more differentiating > characteristics, what is the point of using different tags? /me is kind-of repeating what Paul said, but ... The styling (bold, etc.) is in the stylesheets, and has no meaning to us on the markup side. The markup should be contextual, only. We never do things so that they "look" a certain way in one of the many ways to render a document. This lets us focus on the content and not the formatting, and the separation of the layers lets us have more global control. We want all tags to now make a button-like appearance using CSS in HTML, but not PDF, we can do that in the XSL and the CSS. The button-effect was done in Red Hat manuals in the past, and we could do that if it was worth it. Here's an example to illustrate the value of proper content tagging and not worrying about the presentation: You are writing a tutorial for using GTK+ to create some onscreen widgets. It includes blocks with lots of sample code, some blocks with commands for installing packages and tweaking configuration files, and several textual descriptions of a GUI, talking about the s, s, and s. One of your readers is very visually impaired. She has to use two huge monitors set at 640x480 with large fonts and contrasting colors, and has both a regular and Braille keyboard, and a Braille printer for output. If your content was marked up with enough proper detail, an XSLT could be used to get the XML ready for a custom low-vision reading system that would: * Take the blocks and send them intact to the reader's monitor and Braille output printer (both configured to receive STDOUT); this lets her see them on screen and confirm what she reads with Braille output. * Take the elements and display them in a properly nested fashion to STDOUT, similar to the way they give us File -> Edit -> Foo, that could be a visually descending tree done in a very big font. * Take the and tags and send that content straight to the console and Braille keyboard (STDIN), while teeing it to STDOUT for confirmation via monitor and Braille printer. Does that help? - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Mon Aug 30 22:25:11 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 15:25:11 -0700 Subject: Fwd: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server In-Reply-To: <20040830110716.37477.qmail@web8507.mail.in.yahoo.com> References: <20040830110716.37477.qmail@web8507.mail.in.yahoo.com> Message-ID: <1093904709.17095.93195.camel@erato.phig.org> On Mon, 2004-08-30 at 04:07, Rahul Sundaram wrote: > --- Dashamir Hoxha wrote: > > > > > Looks like it has been filled and assigned > appropriately. You might want to call it a howto > instead of a manual. that seems to the more > appropriate terminology but wait for feedback from the > other fedora doc editors and volunteers +1 We've been using "tutorial" and "how to"; a "guide" or "manual" implies something longer, and so far we are only doing the Doc Guide and Installation Guide as full length manuals/guides. Other terms might be acceptable, as long as they convey the short, concise nature of FDP tutorials. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 31 01:21:53 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 18:21:53 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093903881.3666.1.camel@bettie.internal.frields.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093903881.3666.1.camel@bettie.internal.frields.org> Message-ID: <1093915311.17095.94448.camel@erato.phig.org> On Mon, 2004-08-30 at 15:11, Paul W. Frields wrote: > On Mon, 2004-08-30 at 17:40, Karsten Wade wrote: > > That's not what I see on this page: > > > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html > > You're right. I think I changed this in my usage because the extra > linefeeds were causing the PDF rendering to use WAY too much vertical > space. Would a bug report for that go against xmlto, then? And how does > your recommendation fare for those purposes? Hey, you're doing great if you can even get a PDF. :) I must be doing something in the SGML way that xmlto doesn't like. It sounds like starting with a bug to xmlto would be a good idea; I created a sample XML document that shows all the variations; the source and PDF output can be attached to the bug report: http://people.redhat.com/kwade/fedora-docs/process-docs/xmlto-whitespace-test.pdf I pasted the TXT output below this message, for discussion FWIW, this PDF builds for me, so my non-PDF building docs must have an error of some kind in the XML. I do know that we will need to keep our content on separate lines than the tags. This is a sanity checking device. If you have a code or configuration file: foo { bar { some.call () } } and the first and lines of that are flush with tags, e.g.: foo { bar { some.call () } } it is hard to tell if the code indenting is correct, which matters in many contexts. This simple example is easy to fix, but complex examples are much harder, as I have personally experienced many times. ## begin sample output xmlto test of whitespace usage Karsten Wade Copyright ? 2004 Red Hat, Inc. _________________________________________________________ Table of Contents xmlto test xmlto test Here are some self-referential examples: Example 1. Stacked Tags - Source foo { bar { some.call () } } Example 2. Stacked Tags - Output foo { bar { some.call () } } Example 3. Stacked and Broke - Source foo { bar { some.call () } } Example 4. Stacked and Broke - Output foo { bar { some.call () } } Example 5. All Flush Left - Source foo { bar { some.call () } } Example 6. All Flush Left - Output foo { bar { some.call () } } Example 7. Only Content Flush Left - Source foo { bar { some.call () } } Example 8. Only Content Flush Left - Output foo { bar { some.call () } } ## end sample output -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From dataking at cox.net Mon Aug 30 18:24:57 2004 From: dataking at cox.net ('D@7@k|N&') Date: Mon, 30 Aug 2004 18:24:57 +0000 Subject: Hardening Tutorial Outline added to bug 129957 Message-ID: <1093890296.4508.58.camel@bach> Attaching outline for review by the group (to bug, not here). Group: This is the direction I'm heading. I'm thinking that I might need to add a few more things, but this should be a good start. I think that kernel compilation should be somewhere in there, but considering the recent (ongoing) discussion of magnitude (guide vs. tutorial) on the lists, I'll leave it here for now. Thoughts, suggestions, additions, critique....all are welcome. I'll be posting the Intro and Chapter 1 xml docs, as soon as I have them available (which should be soon). https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129957 -- -- -=D at 7@k|N&=- <== dataking's pgp ==> 9287 3334 03E4 965E 0D2D F7CA A6E7 407C 1558 A263 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From tfox at redhat.com Tue Aug 31 01:30:17 2004 From: tfox at redhat.com (Tammy Fox) Date: Mon, 30 Aug 2004 21:30:17 -0400 Subject: How to Update tutorial In-Reply-To: <1093687740.2515.5.camel@homer> References: <1093637941.27934.202.camel@localhost.localdomain> <1093687740.2515.5.camel@homer> Message-ID: <1093915817.27934.698.camel@localhost.localdomain> On Sat, 2004-08-28 at 06:09, Dave Pawson wrote: > On Fri, 2004-08-27 at 21:19, Tammy Fox wrote: If they are OK with you, > let me know and I'll > > get it up on the website. > > Fine by me Tammy. > > Great. I'm reviewing Paul's patch now, and we'll get it up as soon as possible. Tammy From kwade at redhat.com Tue Aug 31 01:36:54 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 30 Aug 2004 18:36:54 -0700 Subject: Hardening Tutorial Outline added to bug 129957 In-Reply-To: <1093890296.4508.58.camel@bach> References: <1093890296.4508.58.camel@bach> Message-ID: <1093916214.17095.94540.camel@erato.phig.org> On Mon, 2004-08-30 at 11:24, 'D at 7@k|N&' wrote: > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129957 Here is my reply, for the lazy and appreciative (like me!): [snip] With all the changes to the kernel packaging (-source, -sourcecode, .src.rpm), there is a proposal for a kernel compilation tutorial. Bug # 130754 is tracking this. I think a section on hardening the kernel could fit into that guide. If you are interested in either working on or contributing a kernel hardening section for bug # 130754 Kernel Compilation Tutorial, please attach yourself or content to that doc. :) As for the outline, it looks really good. The only thing I see obviously missing are the "common" sections we've just been discussing over the weekend. Since they don't exist yet, you aren't responsible for them not being in your outline :), just keep in mind that we are defining those and they will need a slot. At the moment this would add: Introduction - add in include scope and !scope, audience and !audience C. Document Conventions (might be the right place) VI. References Looks very ## 30 -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From tfox at redhat.com Tue Aug 31 01:41:01 2004 From: tfox at redhat.com (Tammy Fox) Date: Mon, 30 Aug 2004 21:41:01 -0400 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093902009.17095.92882.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> Message-ID: <1093916461.27934.702.camel@localhost.localdomain> On Mon, 2004-08-30 at 17:40, Karsten Wade wrote: > On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote: > > On Sat, 2004-08-28 at 06:30, Dave Pawson wrote: > > > What processing tools Paul? > > > And why is computeroutput necessary within screen? I'd have thought an > > > either or was more reasonable for the processor to sort out? > > I am advocating: > > > foo { > bar () > } > ]]> > > > Same for blocks. > > This material, in the Fedora Doc Guide, is historical practice that we > can (and should) revise. > There are 2 reasons why the style guide says to include computeroutput or userinput tags inside screen tags: 1. Technically, the content is computeroutput or userinput and should be marked accordingly to make it more correct 2. Marking them as computeroutput and userinput allows the text to be styled using CSS for the HTML version. Tammy > > I'm using the standard toolset and practices from the Documentation > > Guide. Maybe that piece should be revisited in the Documentation Guide, > > which indicates the proper syntax looks like this: > > > > cmd -i arg1 > > Uh-uh, you can't do that. > > That's not what I see on this page: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html > > - Karsten > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From tfox at redhat.com Tue Aug 31 01:52:07 2004 From: tfox at redhat.com (Tammy Fox) Date: Mon, 30 Aug 2004 21:52:07 -0400 Subject: installation guide In-Reply-To: <1093649591.17095.67458.camel@erato.phig.org> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> <1093641455.27934.249.camel@localhost.localdomain> <1093646012.3341.3.camel@bettie.internal.frields.org> <1093649591.17095.67458.camel@erato.phig.org> Message-ID: <1093917127.27934.711.camel@localhost.localdomain> On Fri, 2004-08-27 at 19:33, Karsten Wade wrote: > Okay, I'm onboard for the All Hands on Deck for an Installation Guide > for FC3. > > We have until about 20 October to have a release candidate, and this is > possible to do if we make the pieces small enough and keep the editors > busy. > > More below ... > > On Fri, 2004-08-27 at 15:33, Paul W. Frields wrote: > > Cf. http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=129911 > > Below are some specific points, and I expanded on those suggestions in a > patch to the Documentation Guide, as a new 7.3 Taking Screenshots. I'll > reply back in a bit with the steps, after I build the DB and snarf them > from the HTML page. :) > > For expediency, I'm prepared to just submit the patch to the Doc Guide, > rolling in some other dangling issues I can include. Tammy would see > the CVS report and can address any mistakes and expand/modify. > > > I'll volunteer for partitioning, as mentioned in the &BZ; entry above. I > > would like to suggest several guidelines for screenshots and any other > > graphics (I think the GDSG may use something similar to these, IIRC): > > > > 1. PNG format. Is that too obvious? > > And EPS. > > > 2. No wider than 500 pixels. If your graphic is larger than that, use > > GIMP (Image -> Scale Image) or mogrify to scale the image to no wider > > than 500 pixels. > > That seems reasonable. Make the GUI as small as it can to convey just > what you need. > > 2.1 Use the default Metacity theme to give the guides a consistent look, > and also consistent with most user's experience and expectations. > > 2.2 If you need to crop the image, do that in the GIMP to show just what > you need. > > > 3. Graphics should be included as
I think. > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-figure.html > > That shows the format. We kept the EPS first because of legacy jadetex > issues, no idea if it matters anymore and I'm not tempting fate to find > out. ;) > > > Here's another one I just thought of; the GDSG mentions this as well: > > > > 4. Graphics should not be included unless you absolutely *cannot* get > > along without it. There's no reason to include repetitive screenshots of > > parts of the interface that are easily explained in a sentence. > > (Example: anaconda runs several progress bars when it computes package > > dependencies, writes an install image to the drive, etc.... those don't > > need to be screenshotted. Wait, is that a real word?) > I agree as long as we also keep the following in mind (from what I have learned working on the Red Hat IGs for 4 years and attending a usability study where newbies were given the IG and asked to install RHL for the first time): 1. Many people use the IG as a reference. When they get stuck, they refer to the Installation Guide and try to find help from that point forward. If this is the case, having a screenshot to match the one they are stuck on helps tremendously. 2. For people following the IG sequentially from the first screen forward, having a screenshot that looks like the one they are on helps confirm that they are proceeding correctly and makes them feel confident that they are performing the installation correctly. 3. Users find it useful to see sample data entered into the sample screenshot even if it is listed in the text. Some people just learn better visually. > That seems reasonable. It's nice to have one screenshot to show the > whole GUI, if that helps. It's probably better to have too few > screenshots than too many. > That being said, whoever is taking the screenshots should take them all and a few extra just in case we decide it is actually needed later. This will keep the size and sample data entered consistent throughout the screenshots. Tammy > For quality of information, I find blocks (as s) with > nice, useful command line output to be better ... :) > > - Karsten > -- > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From tfox at redhat.com Tue Aug 31 01:54:36 2004 From: tfox at redhat.com (Tammy Fox) Date: Mon, 30 Aug 2004 21:54:36 -0400 Subject: DocBook/Emacs/psgml Quickstart Guide: update In-Reply-To: <41314836.5070804@redhat.com> References: <41314836.5070804@redhat.com> Message-ID: <1093917276.27934.714.camel@localhost.localdomain> On Sat, 2004-08-28 at 23:06, Mark Johnson wrote: > Hi All, > > I'll re-post here the proposed timeline/outline for the > DocBook/Emacs/psgml Quickstart Guide that I put into bugzilla. > > Thanks to Tammy's helpful poking:), I've now proposed a timeline for > the DocBook/Emacs/psgml Quickstart Guide. It's recorded in bugzilla: > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130032 > > But, to get the ideas into y'all's brains asap, I'll post my > bugzilla entry here: > > -------===========================------- > > From Tammy Fox : > > Mark, can you provide an outline of this or a time frame? > > Sure. > > Since I'm doing RedHat work this weekend, I'll do some fedora doc > work next week. > > How about I supply a draft outline (or doc) by Tuesday 8/30, collect > bugs/feedback, and supply a pseudo-complete outline by Friday, 9/03. > Tuesday is the 31st. Since today is almost over, I'll assume you meant the 31st. > Then, provide a relatively complete document draft by Wednesday, > 9/08, for everyone to critique. > > From there, I would say, give me another week to submit a revised > document based on feedback, though I may be able to produce this > version sooner. In other words, I submit a usable/postable version > by Wednesday, 9/15. > > I then go on vacation from 9/18 - 9/25. > > Sound reasonable? (I'm working on it as I type this, FWIW.) > Sounds reasonable to me. Thanks for working on this one! Tammy > -------===========================------- > > You can also read the bugzilla report yourself: > > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130032 > > To stick to this timeline, I'll need some quick turn-around > editorial feedback. Hope we can get this out the door on schedule... > > Cheers, > Mark > -- > ---------------------------------------------------------- > Mark Johnson > OS Product Documentation Group > Engineering, Red Hat, Inc. > Tel: 919.754.4151 Fax: 919.754.3708 > GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 -- Tammy Fox Executive Editor International Publications From mjohnson at redhat.com Tue Aug 31 02:13:39 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Mon, 30 Aug 2004 22:13:39 -0400 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093901799.17095.92860.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093901799.17095.92860.camel@erato.phig.org> Message-ID: <4133DED3.8000202@redhat.com> Karsten Wade wrote: > > Okay, so the proposals for new ID generation rules are: > > 1. "similar-to-title" > 2. "s.similar.to.title" > 3. "sn-similar-to-title" I vote for 1 (b). s.similar-to-title as it provides a different separator to distinguish structural info from semantic, content-related info. >>I have seen the most problem in the PDF builds, but the HTML builds also >>seem to do funny stuff with more vertical space if you don't run your >>first and last text against the opening and closing tags, >>respectively. In other words, given these two examples: >> >> >> >> >>foo >>bar >> >> >> >> >>foo >>bar >> >>The second example renders into a more pleasing vertical context, >>without a lot of wasted space. The PDF, IIRC, was particularly ugly if >>you didn't use the second form, but I seem to remember the HTML also was >>noticeably different. > > > I can't get anything to build PDF right now to test this, but in HTML I > see the same thing as output, so am not sure of the advantage of the > different way you suggest it. > > I do notice that doing sgml-fill-paragraph will make them line up like: > > foo bar > > Then introducing the line break gets the functionality you mention. > > Ultimately, I think we will want to drop the redundant > and use a CDATA container instead. In that case, _all_ whitespace will > be considered for certain. All content will need to use the left margin > of the XML as starting point for indention. FWIW, I've switched over to with no ill effects (yet). Example: ]]> There are those times when having the capability of just dumping your content into a CDATA section can really simplify the markup. OTOH, if the HTML/CSS styling issue Tammy brings up presents problems, then I'd support using . FWIW, the combo doesn't seem to add anymore semantic info due to overlap in meaning between the two elements. My $0.02, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation Group Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Tue Aug 31 02:32:33 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Mon, 30 Aug 2004 22:32:33 -0400 Subject: common opening sections (was Re: Style guide) In-Reply-To: <1093900532.17095.92724.camel@erato.phig.org> References: <1093900532.17095.92724.camel@erato.phig.org> Message-ID: <4133E341.9050808@redhat.com> Karsten Wade wrote: > > Since it sounds as if you are writing a set of these yourself, how about > if you complete your version and submit it as a draft for a common, > single
containing file. That will be kept in > fedora-docs/common. When we see your version in action, we can then > make any tweaks/suggestions, and then make it part of any document. Sounds like a reasonable plan. I'll also take a look at a bunch of my favorite O'Reilly books & pocket references to see that they have for these types of sections in their intro sections/chapters. > > Few specific thoughts at this point: > > >>- intended audience >>- scope of this document >>- what this document addresses >>- what this docuemt does not address >>- goals of this document (a pseudo re-phrasing of the above) >>- contributors to this document >>- [....]??? > > > That's pretty much it; just a sentence or two each, so this is about one > paragraph right at the start. > > > >>My feeling is that context that the above info provide are very >>important, in that they allow the reader to quickly assess the scope >>of the document and, hence, whether it is worth their time to read >>it. Past experience has shown that the mandatory inclusion of this >>sort of info a document/tutorial provides valuable info to the reader. > > > Agreed > > >>My points (and questions), are then: >> >>- What, if any, should be the required metadata content for standard >> fedora docs (which at this point are tutorially structured)? > > >>From Dave's response, I'm not sure I know what kind of metadata you are > talking about. Is this part of the DocBook structure? I confess to using the term metadata a bit loosely. The above statement simply asks which of the above suggested subsections would make sense to include in the introductory
. The subsections do, indeed, provide document metadata (=data about the document), but if someone wants to start a semantic argument about the meaning of metadata, I'll forfeit and stay out of it. More pressing matters await:) > > >>Put another way, should we require some initial sections titled, e.g.: >> >>- intended audience >> >>- goals of this document (N.B. these are different from the scope as >> described below), and also provide a basis from which readers can >> file bug erports. E.g. Bug pointing out how doc doesn't achieve a >> given goal. >> >>- scope of this document (what it does/doesn't addressed in this >> section. >> >>- contributors > > Having a contributors
(as part of the single, common file) > would be a good way to handle long lists of contributors. Otherwise, I > would recommend hacking the stylesheet so we didn't have a full page of > authors as the standard DB stylesheets does for the . This is definitely a policy issue, the chief ramification being that with you don't get to thank ^X\@/farb34 for searching for foobar archives for valuable data. You just can't do any sort of natural, narrative-like acknowledgements in the authorgroup construct. > Another section we might consider is a document conventions section > [1]. Is this appropriate/necessary/useful for tutorial sized > documents? It's probably also unnecessary for right now, but something > we could develop. IMO, not needed at this point, but easily added later as an external entity to the introductory secion. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation Group Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 From mjohnson at redhat.com Tue Aug 31 02:50:18 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Mon, 30 Aug 2004 22:50:18 -0400 Subject: Rough start... (emacs byte-compiling) In-Reply-To: <1093903852.17095.93095.camel@erato.phig.org> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> <41327081.7010408@redhat.com> <1093903852.17095.93095.camel@erato.phig.org> Message-ID: <4133E76A.4050805@redhat.com> Karsten Wade wrote: > On Sun, 2004-08-29 at 17:10, Mark Johnson wrote: > >>Either way, don't forget to byte compile the new .emacs. > > Always something new for me to learn ... Actually, when you fire up emacs, it reads .emacs.elc, the byte-compiled version of your .emacs file (I think), so re-compiling the file after making changes is essential. > Was this a step in the PSGMLX setup? Probably forgot to mention it, but PSGMLX does automagically byte compiles any of its *own* files if you edit them, so you don't need to worry about compiling any changes you make to the default PSGMLX configuration. > I hadn't heard about the value of > byte-compiling in Emacs (until I just google'd about it). > > Can you give us the shortcut method and reasoning? The reasoning is that the code will execute faster because it's partially compiled. The shortcut method is to use the menus (when in elisp mode): Emacs-Lisp -> Byte-compile This File Of course, 'M-x byte-compile-file' also does the trick. There are other byte-compiling options that may make more sense for a given context. See the attached screenshot 'emacs-byte-compiling.png' for a visual of the menu-based usage. HTH Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation Group Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 -------------- next part -------------- A non-text attachment was scrubbed... Name: emacs-byte-compiling.png Type: image/png Size: 19187 bytes Desc: not available URL: From dasho at ma-isp.com Tue Aug 31 07:51:56 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Tue, 31 Aug 2004 09:51:56 +0200 Subject: Fwd: [Bug 131233] New: Tutorial About Installing a Simple Gateway Server In-Reply-To: <1093904709.17095.93195.camel@erato.phig.org> References: <20040830110716.37477.qmail@web8507.mail.in.yahoo.com> <1093904709.17095.93195.camel@erato.phig.org> Message-ID: <200408310951.56758.dasho@ma-isp.com> On Tuesday 31 August 2004 12:25 am, Karsten Wade wrote: > We've been using "tutorial" and "how to"; a "guide" or "manual" implies > something longer I also agree that 'manual' is not the right term. I am in favor of 'tutorial', although 'how to' is not bad. Dashamir From paul at frields.com Tue Aug 31 12:52:40 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 31 Aug 2004 08:52:40 -0400 Subject: Rough start... (emacs byte-compiling) In-Reply-To: <4133E76A.4050805@redhat.com> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> <41327081.7010408@redhat.com> <1093903852.17095.93095.camel@erato.phig.org> <4133E76A.4050805@redhat.com> Message-ID: <1093956760.5064.5.camel@berlin.east.gov> On Mon, 2004-08-30 at 22:50, Mark Johnson wrote: > > I hadn't heard about the value of > > byte-compiling in Emacs (until I just google'd about it). > > > > Can you give us the shortcut method and reasoning? > > The reasoning is that the code will execute faster because it's > partially compiled. > > The shortcut method is to use the menus (when in elisp mode): > Emacs-Lisp -> Byte-compile This File > > Of course, 'M-x byte-compile-file' also does the trick. > > There are other byte-compiling options that may make more sense for > a given context. See the attached screenshot > 'emacs-byte-compiling.png' for a visual of the menu-based usage. Well, I'll be darned. It really is faster loading! Is it just my imagination, or did fontifying the XML (I think that's what it's called when I do C-C C-P to parse the DTD, right?) get faster also? -- Paul W. Frields, RHCE From tfox at redhat.com Tue Aug 31 16:46:50 2004 From: tfox at redhat.com (Tammy Fox) Date: Tue, 31 Aug 2004 12:46:50 -0400 Subject: screenshot instructions Message-ID: <1093970810.27934.774.camel@localhost.localdomain> The instructions for taking screenshots has been posted: http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html Thanks to Karsten Wade for writing it and Paul W. Friends for editing! Tammy From davep at dpawson.co.uk Tue Aug 31 16:57:56 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 17:57:56 +0100 Subject: Possibly stupid question... In-Reply-To: <1093804027.4508.49.camel@bach> References: <1093804027.4508.49.camel@bach> Message-ID: <1093971476.2517.28.camel@homer> On Sun, 2004-08-29 at 19:27, 'D at 7@k|N&' wrote: > Since I have been working on the hardening tute, I've been doing so with > the Docs Guide open, so I have an immediate reference for the tags that > I should be using. I noticed something, that other people may have > noticed, but I don't really understand the point of. The > , , , , > , and several other tags, all seem to just make the text > bold. Is there a reason that these aren't more defined? http://www.docbook.org/tdg/en/html/docbook.html I have an icon on my desktop that links to a disk based version of this. the toc provides a full list of tags and hence the meaning of each. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Tue Aug 31 17:05:17 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:05:17 +0100 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093902009.17095.92882.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> Message-ID: <1093971917.2517.32.camel@homer> On Mon, 2004-08-30 at 22:40, Karsten Wade wrote: > > I am advocating: > > > foo { > bar () > } > ]]> > > > Same for blocks. Which is identical to < blah blah, I.e. Just a processor frig. In the example you've shown they are identical, with / without CDATA wrapper, since there is nothing needing escaping. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Tue Aug 31 17:07:41 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:07:41 +0100 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093903881.3666.1.camel@bettie.internal.frields.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093903881.3666.1.camel@bettie.internal.frields.org> Message-ID: <1093972061.2517.35.camel@homer> On Mon, 2004-08-30 at 23:11, Paul W. Frields wrote: > You're right. I think I changed this in my usage because the extra > linefeeds were causing the PDF rendering to use WAY too much vertical > space. If the xml-pdf processor is fop, check out the known bug list; Whitespace expectation in the xslt stylsheets are a long way ahead of fop, which is catching up quite markedly. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Tue Aug 31 17:09:08 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 10:09:08 -0700 Subject: installation guide In-Reply-To: <1093917127.27934.711.camel@localhost.localdomain> References: <1093604650.29297.203176060@webmail.messagingengine.com> <1093639487.27934.229.camel@localhost.localdomain> <1093641035.17762.29.camel@bettie.internal.frields.org> <1093641455.27934.249.camel@localhost.localdomain> <1093646012.3341.3.camel@bettie.internal.frields.org> <1093649591.17095.67458.camel@erato.phig.org> <1093917127.27934.711.camel@localhost.localdomain> Message-ID: <1093972148.17095.100112.camel@erato.phig.org> On Mon, 2004-08-30 at 18:52, Tammy Fox wrote: > On Fri, 2004-08-27 at 19:33, Karsten Wade wrote: > > > > > Here's another one I just thought of; the GDSG mentions this as well: > > > > > > 4. Graphics should not be included unless you absolutely *cannot* get > > > along without it. There's no reason to include repetitive screenshots of > > > parts of the interface that are easily explained in a sentence. > > > (Example: anaconda runs several progress bars when it computes package > > > dependencies, writes an install image to the drive, etc.... those don't > > > need to be screenshotted. Wait, is that a real word?) > > > > I agree as long as we also keep the following in mind (from what I have > learned working on the Red Hat IGs for 4 years and attending a usability > study where newbies were given the IG and asked to install RHL for the > first time): This makes sense. The IG is a special creature -- the screens are sequential and don't have a bunch of pop-ups or menus to get lost in. For the IG, having at least one screenshot for each Anaconda page makes sense. I think this "fewer screenshots is better" rule applies mainly to regular GUI applications. There is a style of how-to that has a screenshot for each piece of the GUI -- here's the drop down menu, here's the sub-menu, here's selecting the sub-menu, here's the window that comes up, here's the box checked, here's another box checked, etc. > 1. Many people use the IG as a reference. When they get stuck, they > refer to the Installation Guide and try to find help from that point > forward. If this is the case, having a screenshot to match the one they > are stuck on helps tremendously. > > 2. For people following the IG sequentially from the first screen > forward, having a screenshot that looks like the one they are on helps > confirm that they are proceeding correctly and makes them feel confident > that they are performing the installation correctly. > > 3. Users find it useful to see sample data entered into the sample > screenshot even if it is listed in the text. Some people just learn > better visually. > > > That seems reasonable. It's nice to have one screenshot to show the > > whole GUI, if that helps. It's probably better to have too few > > screenshots than too many. > > > > That being said, whoever is taking the screenshots should take them all > and a few extra just in case we decide it is actually needed later. This > will keep the size and sample data entered consistent throughout the > screenshots. Wise suggestion. -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 31 17:12:44 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 10:12:44 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093971917.2517.32.camel@homer> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093971917.2517.32.camel@homer> Message-ID: <1093972363.17095.100140.camel@erato.phig.org> On Tue, 2004-08-31 at 10:05, Dave Pawson wrote: > On Mon, 2004-08-30 at 22:40, Karsten Wade wrote: > > > > > I am advocating: > > > > > > > foo { > > bar () > > } > > ]]> > > > > > > Same for blocks. > > Which is identical to > > < blah blah, > > > I.e. Just a processor frig. > > In the example you've shown they are identical, > with / without CDATA wrapper, since there is nothing > needing escaping. Don't let the example rule the usage. Anyone who has had to convert many lines of XML, HTML, or other languages to use entities such as < and > knows what a pain it is to maintain. You can't tell from the source what you are looking at. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Tue Aug 31 17:16:58 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:16:58 +0100 Subject: Possibly stupid question... In-Reply-To: <1093904560.17095.93180.camel@erato.phig.org> References: <1093804027.4508.49.camel@bach> <1093904560.17095.93180.camel@erato.phig.org> Message-ID: <1093972618.2517.45.camel@homer> On Mon, 2004-08-30 at 23:22, Karsten Wade wrote: > Here's an example to illustrate the value of proper content tagging and > not worrying about the presentation: > One of your readers is very visually impaired. She has to use two huge > monitors set at 640x480 with large fonts and contrasting colors, and has > both a regular and Braille keyboard, and a Braille printer for output. Braille keyboard normally ~= soft braille display, a beast that sits under the keyboard, with 40 or 80 character single line display. > > If your content was marked up with enough proper detail, an XSLT could > be used to get the XML ready for a custom low-vision reading system that > would: > > * Take the blocks and send them intact to the reader's > monitor and Braille output printer (both configured to receive STDOUT); > this lets her see them on screen and confirm what she reads with Braille > output. As it does with any html, wrapping only the content which is not marked as preserve space. The problem with big magnification is that panning is usually mandatory, since (worst case I've seen) fewer than 20 chars are visible on the screen at once? Special stylesheets won't help in cases like that. > > * Take the elements and display them in a properly nested > fashion to STDOUT, similar to the way they give us File -> Edit -> Foo, > that could be a visually descending tree done in a very big font. Except that a person whose reading media is tactile is restricted to tty class of output? I.e. line at a time, hence they need to keep any 'visual' structure in their heads whilst reading. > > * Take the and tags and send that content > straight to the console and Braille keyboard (STDIN), while teeing it to > STDOUT for confirmation via monitor and Braille printer. I've never seen software or devices which split output like that Karsten. Assistive technology on Linux is quite good at accessing html output. And if current trends are maintained, the combination of braille output and low vision tools is a waste of time. The number of people learning braille is diminishing. regards, also, david.pawson at rnib.org.uk http://www.rnib.org.uk -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Tue Aug 31 17:24:04 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 31 Aug 2004 13:24:04 -0400 Subject: screenshot instructions In-Reply-To: <1093970810.27934.774.camel@localhost.localdomain> References: <1093970810.27934.774.camel@localhost.localdomain> Message-ID: <1093973043.2950.0.camel@berlin.east.gov> On Tue, 2004-08-31 at 12:46, Tammy Fox wrote: > The instructions for taking screenshots has been posted: > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html > > Thanks to Karsten Wade for writing it and Paul W. Friends for editing! Not to be too picky, seeing as how you gave me an acknowledgement and all :-), but could you fix the spelling of my last name? Thanks! s/Friends/Frields/g -- Paul W. Frields, RHCE From davep at dpawson.co.uk Tue Aug 31 17:27:51 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:27:51 +0100 Subject: common opening sections (was Re: Style guide) In-Reply-To: <4133E341.9050808@redhat.com> References: <1093900532.17095.92724.camel@erato.phig.org> <4133E341.9050808@redhat.com> Message-ID: <1093973271.2517.52.camel@homer> On Tue, 2004-08-31 at 03:32, Mark Johnson wrote: > >>From Dave's response, I'm not sure I know what kind of metadata you are > > talking about. Is this part of the DocBook structure? Yes, sorry. docbook too has metadata, which isn't too regular (Due to be updated in 5.0 and regularised). E.g.
contains metadata. > > I confess to using the term metadata a bit loosely. > > The above statement simply asks which of the above suggested > subsections would make sense to include in the introductory >
. I sort of gathered something along those lines was taking place :-) > The subsections do, indeed, provide document metadata > (=data about the document), but if someone wants to start a semantic > argument about the meaning of metadata, No way :-) > > > Having a contributors
(as part of the single, common file) > > would be a good way to handle long lists of contributors. Docbook does allow for that in its markup. http://www.docbook.org/tdg/en/html/authorgroup.html > Otherwise, I > > would recommend hacking the stylesheet so we didn't have a full page of > > authors as the standard DB stylesheets does for the . Customising it? +1 Probably not required for other than multiple author docs. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Tue Aug 31 17:30:29 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:30:29 +0100 Subject: Rough start... (emacs byte-compiling) In-Reply-To: <1093956760.5064.5.camel@berlin.east.gov> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> <41327081.7010408@redhat.com> <1093903852.17095.93095.camel@erato.phig.org> <4133E76A.4050805@redhat.com> <1093956760.5064.5.camel@berlin.east.gov> Message-ID: <1093973428.2517.55.camel@homer> On Tue, 2004-08-31 at 13:52, Paul W. Frields wrote: > > Of course, 'M-x byte-compile-file' also does the trick. > > > > There are other byte-compiling options that may make more sense for > > a given context. See the attached screenshot > > 'emacs-byte-compiling.png' for a visual of the menu-based usage. > > Well, I'll be darned. It really is faster loading! The other trick, once documents become large, is to 'compile' the dtd producing xyz.ced, which psgml then uses, and it 'reads' the dtd so much quicker. Probably not noticable until the file size is significant; but well worth doing. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From tfox at redhat.com Tue Aug 31 17:32:51 2004 From: tfox at redhat.com (Tammy Fox) Date: Tue, 31 Aug 2004 13:32:51 -0400 Subject: screenshot instructions In-Reply-To: <1093973043.2950.0.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <1093973043.2950.0.camel@berlin.east.gov> Message-ID: <1093973571.27934.776.camel@localhost.localdomain> On Tue, 2004-08-31 at 13:24, Paul W. Frields wrote: > On Tue, 2004-08-31 at 12:46, Tammy Fox wrote: > > The instructions for taking screenshots has been posted: > > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html > > > > Thanks to Karsten Wade for writing it and Paul W. Friends for editing! > > Not to be too picky, seeing as how you gave me an acknowledgement and > all :-), but could you fix the spelling of my last name? Thanks! > s/Friends/Frields/g > Sure. Sorry about that! > -- > Paul W. Frields, RHCE From kwade at redhat.com Tue Aug 31 17:33:07 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 10:33:07 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093916461.27934.702.camel@localhost.localdomain> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093916461.27934.702.camel@localhost.localdomain> Message-ID: <1093973587.17095.100282.camel@erato.phig.org> On Mon, 2004-08-30 at 18:41, Tammy Fox wrote: > On Mon, 2004-08-30 at 17:40, Karsten Wade wrote: > > On Sat, 2004-08-28 at 05:25, Paul W. Frields wrote: > > > On Sat, 2004-08-28 at 06:30, Dave Pawson wrote: > > > > What processing tools Paul? > > > > And why is computeroutput necessary within screen? I'd have thought an > > > > either or was more reasonable for the processor to sort out? > > > > I am advocating: > > > > > > > foo { > > bar () > > } > > ]]> > > > > > > Same for blocks. > > > > This material, in the Fedora Doc Guide, is historical practice that we > > can (and should) revise. > > > > There are 2 reasons why the style guide says to include computeroutput > or userinput tags inside screen tags: > > 1. Technically, the content is computeroutput or userinput and should be > marked accordingly to make it more correct > 2. Marking them as computeroutput and userinput allows the text to be > styled using CSS for the HTML version. We've moved into very fine lines of distinction here. In many situations, I'm not even sure I want any styling for the contents of _some_ of my and blocks (esp. ). It should be unstyled fixed-width fonts, no bold, no extra fancy characters, no matter if it's utf-8 or iso-whatever. However, Tammy's poing in 1) above is important -- perhaps the only thing that _should_ be in a block is STDIN () or STDOUT (). If that is the case, then we wouldn't use CDATA blocks for . FWIW, putting CDATA in e.g. does not validate, but it does build PDF and HTML. It seems that my examples using foo {} is actually incorrect; that should be a block which should probably always use CDATA. Sounds like I might be reversing myself! How about this: * We modify current usage rules to show a couple of acceptable styles and which ones are likely to break or cause problems. Specify that the point is not XML styling but quality of output -- if your code gets the desired output of no extra vertical or horizontal whitespace in PDF or HTML, then it's fine. * has or within it to be semantically correct. * always uses a CDATA section to preserve every detail from processing (XSL and CSS included). - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Tue Aug 31 17:37:59 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:37:59 +0100 Subject: screenshot instructions In-Reply-To: <1093970810.27934.774.camel@localhost.localdomain> References: <1093970810.27934.774.camel@localhost.localdomain> Message-ID: <1093973879.2517.63.camel@homer> On Tue, 2004-08-31 at 17:46, Tammy Fox wrote: > The instructions for taking screenshots has been posted: > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html Thanks or that you two. One less reason to stick with M$ :-) Snagit is one of my 'must haves'. Comment: obviously, a photographic image of a scene can convey more than 1000 words can. Fine... unless your eyesight is shot to ... How about obviously, for sighted users, a photographic image of a scene can convey more than 1000 words can. One more, it may be obvious to most, but how about stating how to capture a text output? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Tue Aug 31 17:40:56 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:40:56 +0100 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093972363.17095.100140.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093971917.2517.32.camel@homer> <1093972363.17095.100140.camel@erato.phig.org> Message-ID: <1093974056.2517.67.camel@homer> On Tue, 2004-08-31 at 18:12, Karsten Wade wrote: > Don't let the example rule the usage. My point was they are identical. There is no advantage one to the other. > Anyone who has had to convert many lines of XML, HTML, or other > languages to use entities such as < and > knows what a pain it is > to maintain. You can't tell from the source what you are looking at. Which is why I a) process heavy markup externally. 1. replace & 2. replace < b) use emacs colouring to 'see' the content. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Tue Aug 31 17:42:27 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 10:42:27 -0700 Subject: Possibly stupid question... In-Reply-To: <1093972618.2517.45.camel@homer> References: <1093804027.4508.49.camel@bach> <1093904560.17095.93180.camel@erato.phig.org> <1093972618.2517.45.camel@homer> Message-ID: <1093974147.17095.100340.camel@erato.phig.org> On Tue, 2004-08-31 at 10:16, Dave Pawson wrote: Dave: Thanks for the corrections to my example. I had mainly made that up from the top of my head, which is why it doesn't exist anywhere yet. :) We illustrated the point well, though -- properly marked up content can be used in many different ways, and it is important to use tags correctly. We need to envision our document output being styled in many different ways and languages. One of the powers of DocBook is that it gives you a single-source that can be made into many forms of highly accessible output. - Karsten > On Mon, 2004-08-30 at 23:22, Karsten Wade wrote: > > > Here's an example to illustrate the value of proper content tagging and > > not worrying about the presentation: > > > One of your readers is very visually impaired. She has to use two huge > > monitors set at 640x480 with large fonts and contrasting colors, and has > > both a regular and Braille keyboard, and a Braille printer for output. > Braille keyboard normally ~= soft braille display, > a beast that sits under the keyboard, with 40 or 80 character single > line display. > > > > > If your content was marked up with enough proper detail, an XSLT could > > be used to get the XML ready for a custom low-vision reading system that > > would: > > > > * Take the blocks and send them intact to the reader's > > monitor and Braille output printer (both configured to receive STDOUT); > > this lets her see them on screen and confirm what she reads with Braille > > output. > > As it does with any html, wrapping only the content which is not marked > as preserve space. > The problem with big magnification is that panning is usually > mandatory, since (worst case I've seen) fewer than 20 chars are > visible on the screen at once? > Special stylesheets won't help in cases like that. > > > > > > * Take the elements and display them in a properly nested > > fashion to STDOUT, similar to the way they give us File -> Edit -> Foo, > > that could be a visually descending tree done in a very big font. > > Except that a person whose reading media is tactile is restricted to > tty class of output? I.e. line at a time, hence they need to > keep any 'visual' structure in their heads whilst reading. > > > > > > > * Take the and tags and send that content > > straight to the console and Braille keyboard (STDIN), while teeing it to > > STDOUT for confirmation via monitor and Braille printer. > > I've never seen software or devices which split output like that > Karsten. Assistive technology on Linux is quite good at accessing > html output. > > And if current trends are maintained, the combination of braille output > and low vision tools is a waste of time. > The number of people learning braille is diminishing. > > regards, > also, > david.pawson at rnib.org.uk > http://www.rnib.org.uk > > > -- > Regards DaveP. > XSLT&Docbook FAQ > http://www.dpawson.co.uk/xsl -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From davep at dpawson.co.uk Tue Aug 31 17:48:25 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 31 Aug 2004 18:48:25 +0100 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093973587.17095.100282.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093916461.27934.702.camel@localhost.localdomain> <1093973587.17095.100282.camel@erato.phig.org> Message-ID: <1093974504.2517.75.camel@homer> On Tue, 2004-08-31 at 18:33, Karsten Wade wrote: > In many situations, I'm not even sure I want any styling for the > contents of _some_ of my and blocks (esp. > ). It should be unstyled fixed-width fonts, no bold, no > extra fancy characters, no matter if it's utf-8 or iso-whatever. Which is a pretty good definition of a style IMHO. > If that is the case, then we wouldn't use CDATA blocks for . > FWIW, putting CDATA in e.g. does not validate, but it > does build PDF and HTML. Its not a validity issue. Simply well-formedness. > * We modify current usage rules to show a couple of acceptable styles > and which ones are likely to break or cause problems. Specify that the > point is not XML styling but quality of output -- if your code gets the > desired output of no extra vertical or horizontal whitespace in PDF or > HTML, then it's fine. -1. I'd have thought the project needs valid XML instances. > > * has or within it to be > semantically correct. Why isn't screen 'right' for the contents of the screen? Or if you are talking about a programs output, or a user input, then use computeroutput or userinput. > > * always uses a CDATA section to preserve every detail > from processing (XSL and CSS included). But thats the point of stylesheets Karsten, to apply style. http://www.w3.org/TR/2004/REC-xml-20040204/#sec-cdata-sect An example of a CDATA section, in which "" and "" are recognized as character data, not markup: Hello, world!]]> That's all CDATA sections do. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Tue Aug 31 17:53:06 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 10:53:06 -0700 Subject: screenshot instructions In-Reply-To: <1093973879.2517.63.camel@homer> References: <1093970810.27934.774.camel@localhost.localdomain> <1093973879.2517.63.camel@homer> Message-ID: <1093974785.17095.100415.camel@erato.phig.org> On Tue, 2004-08-31 at 10:37, Dave Pawson wrote: > On Tue, 2004-08-31 at 17:46, Tammy Fox wrote: > > The instructions for taking screenshots has been posted: > > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html > > > Thanks or that you two. > One less reason to stick with M$ :-) Snagit is one of my 'must haves'. > > Comment: > obviously, a photographic image of a scene can convey more than 1000 > words can. > > Fine... unless your eyesight is shot to ... > How about > obviously, for sighted users, a photographic image of a scene can convey > more than 1000 words can. Ah, yes, thank you. I felt sort of funny when I wrote that, like there was something wrong with the assumption, and that is it. I wonder if there is a way to get Anaconda to dump all of it's raw curses screens for us to use in blocks? A PNG screenshot of the text install would be, uh ... lame ... but it would be a hassle to create the TUI screens manually ... I'll check with Jeremy to see if this is possible. One person on #fedora-devel suggested doing the install in a virtual machine, then we can use the mouse to grab the text. > One more, it may be obvious to most, > but how about stating how to capture a text output? In Red Hat guides, we have a section that gets included in some guides (such as the Installation Guide) that talks about how to use the mouse, how to copy-paste, etc. I think that such information is already a given for Fedora writers; I would save it for an entry-level Fedora tutorial. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 31 18:12:15 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 11:12:15 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093974504.2517.75.camel@homer> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093916461.27934.702.camel@localhost.localdomain> <1093973587.17095.100282.camel@erato.phig.org> <1093974504.2517.75.camel@homer> Message-ID: <1093975935.17095.100546.camel@erato.phig.org> On Tue, 2004-08-31 at 10:48, Dave Pawson wrote: > On Tue, 2004-08-31 at 18:33, Karsten Wade wrote: > > > In many situations, I'm not even sure I want any styling for the > > contents of _some_ of my and blocks (esp. > > ). It should be unstyled fixed-width fonts, no bold, no > > extra fancy characters, no matter if it's utf-8 or iso-whatever. > > Which is a pretty good definition of a style IMHO. Ha! You caught me there. You can tell by my flip-flopping and half-thought-through opinions that I'm not quite sure what is the best thing to do, which usually means it's time to pick something that works and move on. > > If that is the case, then we wouldn't use CDATA blocks for . > > FWIW, putting CDATA in e.g. does not validate, but it > > does build PDF and HTML. > > Its not a validity issue. Simply well-formedness. Odd, I did C-c C-v and got some validation errors, which, uh, aren't occurring now. *shrug* > > * We modify current usage rules to show a couple of acceptable styles > > and which ones are likely to break or cause problems. Specify that the > > point is not XML styling but quality of output -- if your code gets the > > desired output of no extra vertical or horizontal whitespace in PDF or > > HTML, then it's fine. > > -1. > I'd have thought the project needs valid XML instances. Which instances are valid and which are not? I only meant, valid XML usage. Is there only one "right way"? If so, then I guess this whole discussion is no longer moot! > > * has or within it to be > > semantically correct. > > Why isn't screen 'right' for the contents of the screen? > Or if you are talking about a programs output, or a user input, > then use computeroutput or userinput. I would reckon that the usage came about this way from wanting to mark all user input as and all screen output as , whether it is inline in a or blocked in a . The idea would be, it should be marked as <...input/> or <...output/> in all instances. However, those tags cannot stand alone the way can. must be used to get the desired styling output. Just putting tags around the <...put/> tags would not be the same thing, semantically or stylistically. I'm guessing as to that reasoning; Ed or Tammy would be better to answer that. That reasoning makes some amount of sense to me. > > * always uses a CDATA section to preserve every detail > > from processing (XSL and CSS included). > > But thats the point of stylesheets Karsten, to apply style. > > http://www.w3.org/TR/2004/REC-xml-20040204/#sec-cdata-sect > > > An example of a CDATA section, in which "" and "" > are recognized as character data, not markup: > > Hello, world!]]> > > > That's all CDATA sections do. Okay, I concede that I'm getting myself into a confused corner. For maintainability and ease of handing off documents to others for editing and writing, I find using CDATA inside to be invaluable. Perhaps we don't make this a hard requirement, just fix the stylesheets so content output looks the same regardless of CDATA usage (it may already do that), and leave it up to the author. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Tue Aug 31 18:15:14 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 31 Aug 2004 14:15:14 -0400 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093915311.17095.94448.camel@erato.phig.org> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093903881.3666.1.camel@bettie.internal.frields.org> <1093915311.17095.94448.camel@erato.phig.org> Message-ID: <1093976114.2950.15.camel@berlin.east.gov> On Mon, 2004-08-30 at 21:21, Karsten Wade wrote: > I do know that we will need to keep our content on separate lines than > the tags. This is a sanity checking device. If you have a code or > configuration file: > > foo { > bar { > some.call () > } > } > > and the first and lines of that are flush with tags, e.g.: > > foo { > bar { > some.call () > } > } > > it is hard to tell if the code indenting is correct, which matters in > many contexts. This simple example is easy to fix, but complex examples > are much harder, as I have personally experienced many times. Agreed. I didn't like having to stack tags one bit from a readability standpoint, but I figured the end justified the means (i.e. readable output). If this part of xmlto (or something else) needs fixing, it would be great if someone could identify what's broken. With regard to your test ([...snipped...]), I think that examples 1-2 prove my point. Example 2 shows a rendering with the least amount of extra vertical whitespace surrounding the actual code snippet. That's what I was seeing as well, and why I started stacking tags. If wiser heads think that I am putting the cart before the horse there, I'm happy to comply. Just means I can read it easier while editing, anyway! :-) -- Paul W. Frields, RHCE From kwade at redhat.com Tue Aug 31 18:17:51 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 11:17:51 -0700 Subject: screenshot instructions In-Reply-To: <1093974785.17095.100415.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <1093973879.2517.63.camel@homer> <1093974785.17095.100415.camel@erato.phig.org> Message-ID: <1093976271.17095.100589.camel@erato.phig.org> On Tue, 2004-08-31 at 10:53, Karsten Wade wrote: > I wonder if there is a way to get Anaconda to dump all of it's raw > curses screens for us to use in blocks? A PNG screenshot of > the text install would be, uh ... lame ... but it would be a hassle to > create the TUI screens manually ... > > I'll check with Jeremy to see if this is possible. One person on > #fedora-devel suggested doing the install in a virtual machine, then we > can use the mouse to grab the text. Just discussed this with Jeremy, here are the points. * Telnet install is broken, until it gets fixed, we can't use that to get text screen captures of installation. * VMWare, unfortunately, is the best virtual machine to install with in order to get text grabs. Others such as UML require work to make happen. * Even if a version of the Installation Guide had text-based shots of the installation screen, we would still not be able to easily capture the contents of scrolling or drop-down menus, etc. I'm thinking that we should push this discussion off until FC4 Installation Guide, at the earliest. It would be a good but tough project to make an a11y version of the IG. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Tue Aug 31 18:20:22 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 31 Aug 2004 14:20:22 -0400 Subject: Rough start... (emacs byte-compiling) In-Reply-To: <1093973428.2517.55.camel@homer> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> <41327081.7010408@redhat.com> <1093903852.17095.93095.camel@erato.phig.org> <4133E76A.4050805@redhat.com> <1093956760.5064.5.camel@berlin.east.gov> <1093973428.2517.55.camel@homer> Message-ID: <1093976422.2950.24.camel@berlin.east.gov> On Tue, 2004-08-31 at 13:30, Dave Pawson wrote: > > > Of course, 'M-x byte-compile-file' also does the trick. > > > > > > There are other byte-compiling options that may make more sense for > > > a given context. See the attached screenshot > > > 'emacs-byte-compiling.png' for a visual of the menu-based usage. > > > > Well, I'll be darned. It really is faster loading! > > The other trick, once documents become large, is to > 'compile' the dtd producing xyz.ced, which psgml then > uses, and it 'reads' the dtd so much quicker. > Probably not noticable until the file size is significant; > but well worth doing. Ah, now *that* I've done before. Since my markup of Strunk's book was in separate chapter files, that step was invaluable. -- Paul W. Frields, RHCE From kwade at redhat.com Tue Aug 31 18:20:42 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 11:20:42 -0700 Subject: taking screenshots - new section for Documentation Guide (was installation guide) In-Reply-To: <1093976114.2950.15.camel@berlin.east.gov> References: <1093656867.17095.68240.camel@erato.phig.org> <1093668457.4188.53.camel@bettie.internal.frields.org> <1093689007.2515.27.camel@homer> <1093695950.6210.2.camel@bettie.internal.frields.org> <1093902009.17095.92882.camel@erato.phig.org> <1093903881.3666.1.camel@bettie.internal.frields.org> <1093915311.17095.94448.camel@erato.phig.org> <1093976114.2950.15.camel@berlin.east.gov> Message-ID: <1093976442.17095.100611.camel@erato.phig.org> On Tue, 2004-08-31 at 11:15, Paul W. Frields wrote: > Agreed. I didn't like having to stack tags one bit from a readability > standpoint, but I figured the end justified the means (i.e. readable > output). If this part of xmlto (or something else) needs fixing, it > would be great if someone could identify what's broken. > > With regard to your test ([...snipped...]), I think that examples 1-2 > prove my point. Example 2 shows a rendering with the least amount of > extra vertical whitespace surrounding the actual code snippet. That's > what I was seeing as well, and why I started stacking tags. It looks like it is just a function of the whitespace. The new line following the tag is interpreted and inserted into the output. I think it's a visual thing we shouldn't worry about; it doesn't make the output an harder to read with the extra line, but it makes the XML lots easier to read and maintain. - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From kwade at redhat.com Tue Aug 31 18:24:11 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 11:24:11 -0700 Subject: Rough start... (emacs byte-compiling) In-Reply-To: <1093976422.2950.24.camel@berlin.east.gov> References: <1093781809.4508.14.camel@bach> <1093815010.5805.23.camel@bettie.internal.frields.org> <1093791564.4508.37.camel@bach> <41327081.7010408@redhat.com> <1093903852.17095.93095.camel@erato.phig.org> <4133E76A.4050805@redhat.com> <1093956760.5064.5.camel@berlin.east.gov> <1093973428.2517.55.camel@homer> <1093976422.2950.24.camel@berlin.east.gov> Message-ID: <1093976650.17095.100634.camel@erato.phig.org> On Tue, 2004-08-31 at 11:20, Paul W. Frields wrote: > On Tue, 2004-08-31 at 13:30, Dave Pawson wrote: > > > Well, I'll be darned. It really is faster loading! > > > > The other trick, once documents become large, is to > > 'compile' the dtd producing xyz.ced, which psgml then > > uses, and it 'reads' the dtd so much quicker. > > Probably not noticable until the file size is significant; > > but well worth doing. > > Ah, now *that* I've done before. Since my markup of Strunk's book was in > separate chapter files, that step was invaluable. That's SOP for internal Red Hat guides, which are many multiple chapters. So much so that one developer I worked with on a doc got so tired of doing M-x sgml-load-dtd each time that he wrote this bit for our .emacs files; it assigns C-c d to the task of loading a .ced file (from the $PWD only): ;; Vadim Nasardinov's wrote this to save some ;; keystrokes when loading DTDs; this presumes the existence of only ;; one .ced file. (defun rh-sgml-load-dtd () "Load the .ced file from the current directory." (interactive) (let* ((files (directory-files "." nil "\\.ced$")) (ced-file (car files))) (if (or (not ced-file) (cdr files)) (error (format "Expected one .ced file, but found: %S" files)) (progn (message (format "Loading the DTD from %s..." ced-file)) (sgml-load-dtd (car files)))))) (add-hook 'sgml-mode-hook (lambda () (local-set-key "\C-cd" 'rh-sgml-load-dtd))) -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Tue Aug 31 18:25:22 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 31 Aug 2004 14:25:22 -0400 Subject: screenshot instructions In-Reply-To: <1093976271.17095.100589.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <1093973879.2517.63.camel@homer> <1093974785.17095.100415.camel@erato.phig.org> <1093976271.17095.100589.camel@erato.phig.org> Message-ID: <1093976722.2950.33.camel@berlin.east.gov> On Tue, 2004-08-31 at 14:17, Karsten Wade wrote: > * VMWare, unfortunately, is the best virtual machine to install with in > order to get text grabs. Others such as UML require work to make > happen. FWIW, I have a license for VMWare (we use it constantly at work) and would be happy to assist whoever writes that section. If no one volunteers for it I will take it up; just want to clear a couple things off my plate before I fill it up again. -- Paul W. Frields, RHCE From kwade at redhat.com Tue Aug 31 18:40:05 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 31 Aug 2004 11:40:05 -0700 Subject: screenshot instructions In-Reply-To: <1093976722.2950.33.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <1093973879.2517.63.camel@homer> <1093974785.17095.100415.camel@erato.phig.org> <1093976271.17095.100589.camel@erato.phig.org> <1093976722.2950.33.camel@berlin.east.gov> Message-ID: <1093977605.17095.100733.camel@erato.phig.org> On Tue, 2004-08-31 at 11:25, Paul W. Frields wrote: > On Tue, 2004-08-31 at 14:17, Karsten Wade wrote: > > * VMWare, unfortunately, is the best virtual machine to install with in > > order to get text grabs. Others such as UML require work to make > > happen. > > FWIW, I have a license for VMWare (we use it constantly at work) and > would be happy to assist whoever writes that section. If no one > volunteers for it I will take it up; just want to clear a couple things > off my plate before I fill it up again. Yeah, I was thinking of making it an RFE for the IG in the FC4 timeframe. Graphic installation screenshots will cover most our users for the IG for FC3. :) - Karsten -- Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 From paul at frields.com Tue Aug 31 19:49:19 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 31 Aug 2004 15:49:19 -0400 Subject: mirror-tutorial 0.2 Message-ID: <1093981759.3670.7.camel@berlin.east.gov> The updated version, hopefully ready for editorial, is available at Bugzilla #130125. Major issues: 1. I need someone to contribute sections on apt. I don't use it, only up2date with the yum backend. Note that the tutorial is purposely *not* designed to be a tutorial for how to use yum and apt. The only reason they are mentioned is in the context of providing a backend for up2date on both the server and the client side. As it stands, the tutorial fulfills its mission, but it does not cover the apt part, only yum. 2. There is a technical question in there about using a directory containing ISO loopback mount points (disc1/, disc2/, etc.) via NFS for system-config-packages. Anyone know the answer? 3. For those only willing to browse the results, the nightly HTML build will be available tomorrow at . I need an editor; anyone willing to bear the pain? -- Paul W. Frields, RHCE From forrestx.taylor at intel.com Tue Aug 31 20:01:57 2004 From: forrestx.taylor at intel.com (Taylor, ForrestX) Date: Tue, 31 Aug 2004 13:01:57 -0700 Subject: mirror-tutorial 0.2 In-Reply-To: <1093981759.3670.7.camel@berlin.east.gov> References: <1093981759.3670.7.camel@berlin.east.gov> Message-ID: <1093982517.23048.40.camel@bad.jf.intel.com> On Tue, 2004-08-31 at 12:49, Paul W. Frields wrote: > 2. There is a technical question in there about using a directory > containing ISO loopback mount points (disc1/, disc2/, etc.) via NFS for > system-config-packages. Anyone know the answer? You don't need to mount them. Just put the isos in a directory, and use linux nfsiso:test-machine:/path/to/isos Forrest P.S. I've use apt a few times--what kind of information are you interested in? From forrestx.taylor at intel.com Tue Aug 31 20:04:55 2004 From: forrestx.taylor at intel.com (Taylor, ForrestX) Date: Tue, 31 Aug 2004 13:04:55 -0700 Subject: mirror-tutorial 0.2 In-Reply-To: <1093981759.3670.7.camel@berlin.east.gov> References: <1093981759.3670.7.camel@berlin.east.gov> Message-ID: <1093982695.23048.43.camel@bad.jf.intel.com> On Tue, 2004-08-31 at 12:49, Paul W. Frields wrote: > The updated version, hopefully ready for editorial, is available at > Bugzilla #130125. Major issues: > > 1. I need someone to contribute sections on apt. I don't use it, only > up2date with the yum backend. Note that the tutorial is purposely *not* > designed to be a tutorial for how to use yum and apt. The only reason > they are mentioned is in the context of providing a backend for up2date > on both the server and the client side. As it stands, the tutorial > fulfills its mission, but it does not cover the apt part, only yum. Oops, I just looked at your doc to see what you were talking about. Apt does exactly the same thing as yum. You could just copy/paste the information about yum into the apt section. It even has the same drawback as you mention for yum. Forrest From forrestx.taylor at intel.com Tue Aug 31 20:15:28 2004 From: forrestx.taylor at intel.com (Taylor, ForrestX) Date: Tue, 31 Aug 2004 13:15:28 -0700 Subject: mirror-tutorial 0.2 In-Reply-To: <1093982695.23048.43.camel@bad.jf.intel.com> References: <1093981759.3670.7.camel@berlin.east.gov> <1093982695.23048.43.camel@bad.jf.intel.com> Message-ID: <1093983327.23048.46.camel@bad.jf.intel.com> On Tue, 2004-08-31 at 13:04, Taylor, ForrestX wrote: > On Tue, 2004-08-31 at 12:49, Paul W. Frields wrote: > > The updated version, hopefully ready for editorial, is available at > > Bugzilla #130125. Major issues: > > > > 1. I need someone to contribute sections on apt. I don't use it, only > > up2date with the yum backend. Note that the tutorial is purposely *not* > > designed to be a tutorial for how to use yum and apt. The only reason > > they are mentioned is in the context of providing a backend for up2date > > on both the server and the client side. As it stands, the tutorial > > fulfills its mission, but it does not cover the apt part, only yum. > > Oops, I just looked at your doc to see what you were talking about. Apt > does exactly the same thing as yum. You could just copy/paste the > information about yum into the apt section. It even has the same > drawback as you mention for yum. And to create a repository, you need to run: genbasedir --flat --bloat --bz2only \ --topdir=/top_level/dir sub_dir1 subdir2 subdir3 ... Forrest From paul at frields.com Tue Aug 31 21:58:09 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 31 Aug 2004 17:58:09 -0400 Subject: mirror-tutorial 0.2 In-Reply-To: <1093983327.23048.46.camel@bad.jf.intel.com> References: <1093981759.3670.7.camel@berlin.east.gov> <1093982695.23048.43.camel@bad.jf.intel.com> <1093983327.23048.46.camel@bad.jf.intel.com> Message-ID: <1093989489.11446.20.camel@bettie.internal.frields.org> On Tue, 2004-08-31 at 16:15, Taylor, ForrestX wrote: > And to create a repository, you need to run: > > genbasedir --flat --bloat --bz2only \ > --topdir=/top_level/dir sub_dir1 subdir2 subdir3 ... I was about to generate a reply to you regarding syntax questions, when I noticed that apt is not included in &FC;. Didn't someone say that for tutorials we should stick with purely &FED; software to avoid "third-party utility" bloat in the docs? If not, let me throw that issue on the table. (*bump* Soup spills everywhere.) Sorry if this seems like backpedaling. I honestly didn't even think of it until just now, when I decided to try installing apt to test your suggestions. Now that I find it's not included, I am a little hesitant -- OK, to be truthful, more than a little -- to put it in the documentation. I don't have any axe to grind either way; I just never got around to using apt. Comments from anyone? -- Paul W. Frields, RHCE From mjohnson at redhat.com Tue Aug 31 23:16:46 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Tue, 31 Aug 2004 19:16:46 -0400 Subject: DocBook/Emacs/psgml Quickstart Guide: update In-Reply-To: <1093917276.27934.714.camel@localhost.localdomain> References: <41314836.5070804@redhat.com> <1093917276.27934.714.camel@localhost.localdomain> Message-ID: <413506DE.8070006@redhat.com> Tammy Fox wrote: > On Sat, 2004-08-28 at 23:06, Mark Johnson wrote: > >>Hi All, >> >>I'll re-post here the proposed timeline/outline for the >>DocBook/Emacs/psgml Quickstart Guide that I put into bugzilla. >> >>I've now proposed a timeline for >>the DocBook/Emacs/psgml Quickstart Guide. It's recorded in bugzilla: >>https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130032 >> >> >> -------===========================------- >> > From Tammy Fox : >> > Mark, can you provide an outline of this or a time frame? >> >>How about I supply a draft outline (or doc) by Tuesday 8/31, Done. I've hacked out a draft outline. Please take a look & file bugs/comments or whatever form of feedback you prefer. The html version is here: http://people.redhat.com/mjohnson/docs/fedora/docbook-emacs-quickstart The source document is here: http://people.redhat.com/mjohnson/docs/fedora/docbook-emacs-quickstart-tutorial.xml Look forward to any comments and/or suggestions. You should probably focus on the outline, since there's almost no content:) >>collect bugs/feedback, and supply a pseudo-complete outline by >>Friday, 9/03. Next outline version to be released Friday. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation Group Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242