From dasho at ma-isp.com Wed Sep 1 07:09:15 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Wed, 1 Sep 2004 09:09:15 +0200 Subject: screenshot instructions In-Reply-To: <1093970810.27934.774.camel@localhost.localdomain> References: <1093970810.27934.774.camel@localhost.localdomain> Message-ID: <200409010909.15295.dasho@ma-isp.com> On Tuesday 31 August 2004 06:46 pm, Tammy Fox wrote: > The instructions for taking screenshots has been posted: > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.htm > Omit the username and machine information, and separate > what the user types from sample command output. Also, > in screen tags, what the user types should be in userinput tags, > and what the user is shown as output should be in computeroutput > tags. I would suggest something like this: * Everything inside a tag is assumed by default as computeroutput, unless otherwise stated. * The prompt should be denoted like this: bash# or bash$ (depending on whether it is the root or any user). * Commands are placed inside a element. * The text inputed by the users, other that commands, e.g. in interactive programs, is placed inside a element. What do you think? Does it become too complicated? Dashamir From kwade at redhat.com Wed Sep 1 10:58:45 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 01 Sep 2004 03:58:45 -0700 Subject: screenshot instructions In-Reply-To: <200409010909.15295.dasho@ma-isp.com> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> Message-ID: <1094036325.24040.4485.camel@erato.phig.org> On Wed, 2004-09-01 at 00:09, Dashamir Hoxha wrote: > On Tuesday 31 August 2004 06:46 pm, Tammy Fox wrote: > > The instructions for taking screenshots has been posted: > > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.htm > > > Omit the username and machine information, and separate > > what the user types from sample command output. Also, > > in screen tags, what the user types should be in userinput tags, > > and what the user is shown as output should be in computeroutput > > tags. > > I would suggest something like this: > > * Everything inside a tag is assumed by default as > computeroutput, unless otherwise stated. Do you mean by "assumed by default as computeroutput" to mean, whenever you use a block, you will be surrounding a block unless otherwise stated? This is how it stands right now, aiui. > * The prompt should be denoted like this: bash# > or bash$ (depending on whether it is the root > or any user). The current usage is to not include a prompt. Refer to the Note at the bottom of this page: http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-prompt.html Personally, I agree with this from an aesthetic viewpoint. Unless the point is to display the prompt for discussion, it is long and clutters the view, confusing the reader with a big block of text that may not even describe what they are looking at. The document convention we use of having long blocks of input and output in tags is sufficient to clue-in the reader that this is input or output. > * Commands are placed inside a element. It seems redundant to put a tag inside of a tag ... yes, it's technically allowed, and yes, I think we should mark up all text to a fine degree so it is useful for the most types of output, but there is a point where it is ridiculous. Both of these are correct, but the second one is just so much easier to manage: com.redhat.BigObject.ObjectGrabber.grab() com.redhat.BigObject.ObjectGrabber.grab() > * The text inputed by the users, other that commands, e.g. in > interactive programs, is placed inside a element. > > What do you think? Does it become too complicated? I would drop the addition of and , which essentially leaves us at the same place. :( And we need to settle the matter of indenting tags. Tough consensus to reach, apparently. So much of this is up to style and represents various levels of "correct". - 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 Wed Sep 1 11:50:27 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 01 Sep 2004 07:50:27 -0400 Subject: screenshot instructions In-Reply-To: <1094036325.24040.4485.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> Message-ID: <1094039427.2297.12.camel@berlin.east.gov> On Wed, 2004-09-01 at 06:58, Karsten Wade wrote: > > I would suggest something like this: > > > > * Everything inside a tag is assumed by default as > > computeroutput, unless otherwise stated. > > Do you mean by "assumed by default as computeroutput" to mean, whenever > you use a block, you will be surrounding a > block unless otherwise stated? > > This is how it stands right now, aiui. > > > * The prompt should be denoted like this: bash# > > or bash$ (depending on whether it is the root > > or any user). > > The current usage is to not include a prompt. Refer to the Note at the > bottom of this page: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-prompt.html > > Personally, I agree with this from an aesthetic viewpoint. > > Unless the point is to display the prompt for discussion, it is long and > clutters the view, confusing the reader with a big block of text that > may not even describe what they are looking at. > > The document convention we use of having long blocks of input and output > in tags is sufficient to clue-in the reader that this is input > or output. > > > * Commands are placed inside a element. > > It seems redundant to put a tag inside of a tag > ... yes, it's technically allowed, and yes, I think we should mark up > all text to a fine degree so it is useful for the most types of output, > but there is a point where it is ridiculous. My vote is that: - should be used for any interaction with the computer, be it input or output. - should be used inside for what a user is expected to type. No prompt should be shown. - should be used inside for what the user views, whether it is a response to a command or the contents of a file. - No additional , or other tags inside <*put> other than , where it applies and would aid comprehension or the text demands it. - The optimal way of differentiating from is to separate the sections in which they appear with narrative text. Tammy used an example of this in another thread, so the code would look like this. Note that I'm using what I think was Karsten's latest recommendation for formatting in , i.e. nest the tags instead of stacking, and flush left the actual content only. Run foobar with the following syntax: foobar -v -f myfile You should see the following output: Finished processing, run time 0.035s This seems flexible enough to me -- easy to write, easy to edit, easy to read and maintain. I think the Documentation Guide itself, in Section 6.22, advocates using a lot of nested tags, more than I think are useful (see Note at bottom of page): http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html Once we get some consensus here, we should &BZ; the results to make Sec. 6.22 agree with our decisions (including indentation). By the way, I think the sections on and should have a to Sec. 6.22 as well to indicate that people don't really need to use them in normal contexts. -- Paul W. Frields, RHCE From dasho at ma-isp.com Wed Sep 1 12:20:09 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Wed, 1 Sep 2004 14:20:09 +0200 Subject: screenshot instructions In-Reply-To: <1094036325.24040.4485.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> Message-ID: <200409011420.09336.dasho@ma-isp.com> On Wednesday 01 September 2004 12:58 pm, Karsten Wade wrote: > > * Everything inside a tag is assumed by default as > > computeroutput, unless otherwise stated. > > Do you mean by "assumed by default as computeroutput" to mean, whenever > you use a block, you will be surrounding a > block unless otherwise stated? No, I mean that everything that is not tagged is assumed to be computer output. So, there should be no tag inside a tag. > > * The prompt should be denoted like this: bash# > > or bash$ (depending on whether it is the root > > or any user). > > The current usage is to not include a prompt. Refer to the Note at the > bottom of this page: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-prompt >.html > > Personally, I agree with this from an aesthetic viewpoint. > > Unless the point is to display the prompt for discussion, it is long and > clutters the view, confusing the reader with a big block of text that > may not even describe what they are looking at. I think that a prompt like 'bash$' or 'bash#' is not confusing and it is even helpful. E.g. it makes clear immediatly that what follows is a command and whether this command needs to be executed as root or not. > It seems redundant to put a tag inside of a tag No, I don't mean inside a tag, but without it (instead of it). A command is actually userinput, but the tag describes it better (more specificly) than . > Tough consensus to reach, apparently. So much of this is up to style > and represents various levels of "correct". If a consensus cannot be reached, then I think that it should not be included in the guide, or should be included like a suggestion, not like a rule that everybody has to follow. Dashamir From paul at frields.com Wed Sep 1 13:45:57 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 01 Sep 2004 09:45:57 -0400 Subject: screenshot instructions In-Reply-To: <200409011420.09336.dasho@ma-isp.com> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <200409011420.09336.dasho@ma-isp.com> Message-ID: <1094046356.2297.115.camel@berlin.east.gov> On Wed, 2004-09-01 at 08:20, Dashamir Hoxha wrote: > On Wednesday 01 September 2004 12:58 pm, Karsten Wade wrote: > > > * Everything inside a tag is assumed by default as > > > computeroutput, unless otherwise stated. > > > > Do you mean by "assumed by default as computeroutput" to mean, whenever > > you use a block, you will be surrounding a > > block unless otherwise stated? > > No, I mean that everything that is not tagged is assumed to be computer > output. So, there should be no tag inside a tag. I ran into a situation while writing the mirror-tutorial where being able to differentiate from inside a tag would have come in handy. I didn't mention this in my last e-mail because I thought it muddied the waters. In a configuration file, frequently a tutorial will ask a user to modify part of a configuration file, while giving some existing lines, or parts thereof, for context. It seems to me that being able to delineate one from the other is a good thing, to wit: # The following line should be changed. MyVariable = NewValue MyVariableContext = default It's possible to use and outside of , for example in . I like being able to search for to quickly find my example screens that are set off from the text in the HTML version that I'm reading. I think eliminating is a bad thing, and the transforms we're using make stuff very readable from a human interface perspective. > > > * The prompt should be denoted like this: bash# > > > or bash$ (depending on whether it is the root > > > or any user). > > > > The current usage is to not include a prompt. Refer to the Note at the > > bottom of this page: > > > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-prompt > >.html > > > > Personally, I agree with this from an aesthetic viewpoint. > > > > Unless the point is to display the prompt for discussion, it is long and > > clutters the view, confusing the reader with a big block of text that > > may not even describe what they are looking at. > > I think that a prompt like 'bash$' or 'bash#' is not confusing and it is even > helpful. E.g. it makes clear immediatly that what follows is a command > and whether this command needs to be executed as root or not. The narrative should make this clear. Doing otherwise is lazy writing, IMHO. > > It seems redundant to put a tag inside of a tag > > No, I don't mean inside a tag, but without it (instead of it). > A command is actually userinput, but the tag describes it > better (more specificly) than . > > Tough consensus to reach, apparently. So much of this is up to style > > and represents various levels of "correct". > > If a consensus cannot be reached, then I think that it should not be > included in the guide, or should be included like a suggestion, not > like a rule that everybody has to follow. Without having the rules in the Guide to begin with, I wouldn't have been able to understand how to get started as an author. Remember that rules don't just cause people to do everything the same way (although that's very useful); they also make it easier for beginners to understand how to do things acceptably. Or the editor fixes it the way they like, perhaps? "Suggestions" that are made in place of what should be a rule simply encourage discontinuity and chaos. This means the process from writing to posting at &FDPDOCS-URL; will get longer, which is not something to aim for when &FC; has such a short release cycle. Experts can always deviate according to taste. -- Paul W. Frields, RHCE From dasho at ma-isp.com Wed Sep 1 14:10:26 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Wed, 1 Sep 2004 16:10:26 +0200 Subject: screenshot instructions In-Reply-To: <1094046356.2297.115.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <200409011420.09336.dasho@ma-isp.com> <1094046356.2297.115.camel@berlin.east.gov> Message-ID: <200409011610.26352.dasho@ma-isp.com> On Wednesday 01 September 2004 03:45 pm, Paul W. Frields wrote: > > > # The following line should be changed. > MyVariable = NewValue > MyVariableContext = default > > What I suggested is this: # The following line should be changed. MyVariable = NewValue MyVariableContext = default I don't see anything wrong with your version. Do you see anything wrong with my version? If not, why the usage of should be enforced by a rule? Actually, for configuration files (and for anything that can be edited) I would prefer something like this: # The following line should be changed. MyVariable = NewValue MyVariableContext = default Dashamir From paul at frields.com Wed Sep 1 15:07:20 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 01 Sep 2004 11:07:20 -0400 Subject: screenshot instructions In-Reply-To: <200409011610.26352.dasho@ma-isp.com> References: <1093970810.27934.774.camel@localhost.localdomain> <200409011420.09336.dasho@ma-isp.com> <1094046356.2297.115.camel@berlin.east.gov> <200409011610.26352.dasho@ma-isp.com> Message-ID: <1094051239.2297.159.camel@berlin.east.gov> On Wed, 2004-09-01 at 10:10, Dashamir Hoxha wrote: > On Wednesday 01 September 2004 03:45 pm, Paul W. Frields wrote: > > > > > > # The following line should be changed. > > MyVariable = NewValue > > MyVariableContext = default > > > > > > What I suggested is this: > > # The following line should be changed. > MyVariable = NewValue > MyVariableContext = default > > > I don't see anything wrong with your version. > Do you see anything wrong with my version? > If not, why the usage of > should be enforced by a rule? Nothing wrong with it, I just think using <*put> throughout is more descriptive. "On the screen, the computer outputs XXX." > Actually, for configuration files (and for anything > that can be edited) I would prefer something like this: > > # The following line should be changed. > MyVariable = NewValue > MyVariableContext = default > I could agree with the part here, but I think in the interest of consistency and sensibility, use instead of if that's something the user is expected to enter. Again, I think these are minor points and are probably just better left for an editor to simply fix as required or desired, provided the sense and context are unaffected by a change. -- Paul W. Frields, RHCE From kwade at redhat.com Wed Sep 1 15:27:54 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 01 Sep 2004 08:27:54 -0700 Subject: screenshot instructions In-Reply-To: <200409011420.09336.dasho@ma-isp.com> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <200409011420.09336.dasho@ma-isp.com> Message-ID: <1094052473.24040.6104.camel@erato.phig.org> On Wed, 2004-09-01 at 05:20, Dashamir Hoxha wrote: > If a consensus cannot be reached, then I think that it should not be > included in the guide, or should be included like a suggestion, not > like a rule that everybody has to follow. Just like in other parts of the Fedora project, coding style and consistency with the rest of the project is important. In documentation, absolute consistency can be more important than determining and following a "right way". I'd rather have a document make a mistake consistently, than make three different mistakes about the sake thing. Worse is doing the same thing three different ways! Part of what makes a professional documentation set like the Red Hat (Enterprise) Linux docs so useful for the reader is this consistency. Without it, we might as well be a bunch of random HOWTOS and tutorials. Sloppy consistency is similar to sloppy instructions. If you write instructions that are almost but not quite what the reader sees, they will doubt the instructions because they don't match what is seen on the screen. In the screenshot instructions, Paul and I went to pains to make sure that what we describe on the screen for the GIMP is exactly what you see. Such accuracy and consistency inspires confidence. - 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 Wed Sep 1 15:29:06 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 01 Sep 2004 08:29:06 -0700 Subject: screenshot instructions In-Reply-To: <1094051239.2297.159.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <200409011420.09336.dasho@ma-isp.com> <1094046356.2297.115.camel@berlin.east.gov> <200409011610.26352.dasho@ma-isp.com> <1094051239.2297.159.camel@berlin.east.gov> Message-ID: <1094052546.24040.6113.camel@erato.phig.org> On Wed, 2004-09-01 at 08:07, Paul W. Frields wrote: > On Wed, 2004-09-01 at 10:10, Dashamir Hoxha wrote: > > > > # The following line should be changed. > > MyVariable = NewValue > > MyVariableContext = default > > > > I could agree with the part here, but I think in the > interest of consistency and sensibility, use instead of > if that's something the user is expected to enter. Again, I > think these are minor points and are probably just better left for an > editor to simply fix as required or desired, provided the sense and > context are unaffected by a change. For config files, we should use and . is only for listing source code. - 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 dasho at ma-isp.com Wed Sep 1 16:33:46 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Wed, 1 Sep 2004 18:33:46 +0200 Subject: screenshot instructions In-Reply-To: <1094052473.24040.6104.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409011420.09336.dasho@ma-isp.com> <1094052473.24040.6104.camel@erato.phig.org> Message-ID: <200409011833.46666.dasho@ma-isp.com> On Wednesday 01 September 2004 05:27 pm, Karsten Wade wrote: > In documentation, absolute consistency can be more important than > determining and following a "right way". I'd rather have a document > make a mistake consistently, than make three different mistakes about > the sake thing. Worse is doing the same thing three different ways! I have to agree, but I don't like to give up my editing styles. I will see the possibility of converting automatically my way of editing to the consistent way (using a script or an XSLT stylesheet), so that whenever I modify the document it can be converted instantly to the consistent way. If I fail, then I may need an editor to do the conversion. By the way, do you have any tool to check that a document follows the rules of the guide? I think that it can be done by customizing the DocBook DTD to a subset of it, and then using a validating parser. I don't know yet how to do this, but I don't think it should be very difficult. What is the deadline for making ready my tutorial (converting it to the required style) so that I can plan for meeting it? Dashamir From davep at dpawson.co.uk Wed Sep 1 16:49:29 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 01 Sep 2004 17:49:29 +0100 Subject: screenshot instructions In-Reply-To: <1094036325.24040.4485.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> Message-ID: <1094057369.2541.8.camel@homer> >From docbook tdg. computeroutput: Inline markup. screen. A block level element This element is displayed ?verbatim?; whitespace and linebreaks within this element are significant. userinput: Note that UserInput is not a verbatim environment, but an inline. Does that help explain some of the oddities? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Wed Sep 1 16:52:10 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 01 Sep 2004 17:52:10 +0100 Subject: screenshot instructions In-Reply-To: <1094039427.2297.12.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094039427.2297.12.camel@berlin.east.gov> Message-ID: <1094057530.2541.12.camel@homer> On Wed, 2004-09-01 at 12:50, Paul W. Frields wrote: > My vote is that: > > - should be used for any interaction with the computer, be it > input or output. > > - should be used inside for what a user is expected > to type. No prompt should be shown. Valid markup, don't expect to see any presentational difference. > > - should be used inside for what the user > views, whether it is a response to a command or the contents of a file. Ditto above. > > - No additional , or other tags inside <*put> other > than , where it applies and would aid comprehension or the > text demands it. Nested inlines really are a waste of effort IMHO. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From forrestx.taylor at intel.com Wed Sep 1 17:22:42 2004 From: forrestx.taylor at intel.com (Taylor, ForrestX) Date: Wed, 01 Sep 2004 10:22:42 -0700 Subject: mirror-tutorial 0.2 In-Reply-To: <1093989489.11446.20.camel@bettie.internal.frields.org> References: <1093981759.3670.7.camel@berlin.east.gov> <1093982695.23048.43.camel@bad.jf.intel.com> <1093983327.23048.46.camel@bad.jf.intel.com> <1093989489.11446.20.camel@bettie.internal.frields.org> Message-ID: <1094059361.27718.31.camel@bad.jf.intel.com> On Tue, 2004-08-31 at 14:58, Paul W. Frields wrote: > 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? I'd tend to agree with you. If it is not included in FC, why bother? A quick google can pick up that syntax, so let's devote our resources to included programs. Forrest From hoyt at cavtel.net Wed Sep 1 18:58:46 2004 From: hoyt at cavtel.net (Hoyt) Date: Wed, 1 Sep 2004 14:58:46 -0400 Subject: mirror-tutorial 0.2 In-Reply-To: <1094059361.27718.31.camel@bad.jf.intel.com> References: <1093981759.3670.7.camel@berlin.east.gov> <1093989489.11446.20.camel@bettie.internal.frields.org> <1094059361.27718.31.camel@bad.jf.intel.com> Message-ID: <200409011458.46255.hoyt@cavtel.net> On Wednesday 01 September 2004 01:22 pm, Taylor, ForrestX wrote: > I'd tend to agree with you. ?If it is not included in FC, why bother? ?A > quick google can pick up that syntax, so let's devote our resources to > included programs. FedoraNews.com would seems to be the appropriate place to document apt. Hoyt From paul at frields.com Wed Sep 1 21:02:36 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 01 Sep 2004 17:02:36 -0400 Subject: mirror-tutorial 0.2 In-Reply-To: <200409011458.46255.hoyt@cavtel.net> References: <1093981759.3670.7.camel@berlin.east.gov> <1093989489.11446.20.camel@bettie.internal.frields.org> <1094059361.27718.31.camel@bad.jf.intel.com> <200409011458.46255.hoyt@cavtel.net> Message-ID: <1094072556.19292.0.camel@bettie.internal.frields.org> On Wed, 2004-09-01 at 14:58, Hoyt wrote: > On Wednesday 01 September 2004 01:22 pm, Taylor, ForrestX wrote: > > I'd tend to agree with you. If it is not included in FC, why bother? A > > quick google can pick up that syntax, so let's devote our resources to > > included programs. > > FedoraNews.com would seems to be the appropriate place to document apt. Agreed. I'll adapt my mirror-tutorial appropriately. -- Paul W. Frields, RHCE From kwade at redhat.com Wed Sep 1 22:29:44 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 01 Sep 2004 15:29:44 -0700 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094057369.2541.8.camel@homer> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> Message-ID: <1094077784.24040.8801.camel@erato.phig.org> On Wed, 2004-09-01 at 09:49, Dave Pawson wrote: > >From docbook tdg. > > computeroutput: Inline markup. > > screen. A block level element > This element is displayed ?verbatim?; whitespace and linebreaks within > this element are significant. > > userinput: > Note that UserInput is not a verbatim environment, but an inline. > > Does that help explain some of the oddities? Yay! A reference that trumps and settles the matter ... smooth move, Dave. Wish you had brought up that point earlier ... ... I'd forgotten about those distinctions. My feeling about DocBook usage is, follow what Norm says in "DocBook: The Definitive Guide". That represents the best practices from all over. Only break those rules for very good reasons. When Dashamir suggested we might as well write our own DTD, that was a warning bell. We definitely do not want to stray from the DocBook DTD and usage. We have enough to maintain and worry about. The rules in our own Doc Guide (&DOCG;) are then changed to: * is all by itself without or or , although you can use semantically appropriate tags inside such as . * and are *inline* containers, meaning they are properly used in the flow of content inside of a . I also forgot about ... going to have to experiment with that one. :) - 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 dima_1 at netvision.net.il Thu Sep 2 18:04:11 2004 From: dima_1 at netvision.net.il (Dima Lenderman) Date: Thu, 02 Sep 2004 20:04:11 +0200 Subject: redhat.com mailing list memberships reminder References: Message-ID: <008f01c49117$4fae39f0$0701a8c0@dimahome> Hi. I have only one problem. I unsubsribed 100 time but still continue to get messages fro the fedora mailing list. Please, unsubscribe me. ----- Original Message ----- From: To: Sent: Wednesday, September 01, 2004 11:17 AM Subject: redhat.com mailing list memberships reminder > This is a reminder, sent out once a month, about your redhat.com > mailing list memberships. It includes your subscription info and how > to use it to change it or unsubscribe from a list. > > You can visit the URLs to change your membership status or > configuration, including unsubscribing, setting digest-style delivery > or disabling delivery altogether (e.g., for a vacation), and so on. > > In addition to the URL interfaces, you can also use email to make such > changes. For more info, send a message to the '-request' address of > the list (for example, mailman-request at redhat.com) containing just the > word 'help' in the message body, and an email message will be sent to > you with instructions. > > If you have questions, problems, comments, etc, send them to > mailman-owner at redhat.com. Thanks! > > Passwords for dima_1 at netvision.net.il: > > List Password // URL > ---- -------- > fedora-docs-list at redhat.com strider > http://www.redhat.com/mailman/options/fedora-docs-list/dima_1%40netvision.ne t.il From davep at dpawson.co.uk Thu Sep 2 17:35:40 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 02 Sep 2004 18:35:40 +0100 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094077784.24040.8801.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> Message-ID: <1094146540.2520.22.camel@homer> On Wed, 2004-09-01 at 23:29, Karsten Wade wrote: > I also forgot about ... going to have to experiment with > that one. :) And don't forget 'programlisting' and literallayout; both have their uses, but the definitive guide has always been my guide. I have its icon on my desktop and a copy on my hard disk, in case I'm caught without a connection (sad or what) -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Thu Sep 2 20:24:49 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 02 Sep 2004 13:24:49 -0700 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094146540.2520.22.camel@homer> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> Message-ID: <1094156688.24040.18000.camel@erato.phig.org> On Thu, 2004-09-02 at 10:35, Dave Pawson wrote: > On Wed, 2004-09-01 at 23:29, Karsten Wade wrote: > > > I also forgot about ... going to have to experiment with > > that one. :) > > And don't forget 'programlisting' and literallayout; > both have their uses, but the definitive guide has always been my guide. > I have its icon on my desktop and a copy on my hard disk, in case > I'm caught without a connection (sad or what) Ha! I keep a local copy as well, wouldn't hop a plane without it. An addendum to this conversation, and then I think I'll have to submit a patch for the Doc Guide based on this thread. It is *allowed* to use inline tags inside a block, and it's usage should not necessarily be discouraged. For general purposes, it's enough to put content into without further markup. It meets minimum correctness and accessibility, and provides a rich experience for all the media we can publish to currently. What I just noticed during all this experimentation is that it is best to keep the inline tags, well, inline: foo That keeps extra whitespace from creeping in. The example in our Documentation Guide[1] has newlines that create whitespace. Was that done to make the gray box look better? I don't think it's necessary, tight boxes look fine. If the box needs expanding, best to solve it in the stylesheet. - Karsten [1] http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html -- 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 Sep 2 20:45:56 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 02 Sep 2004 16:45:56 -0400 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094156688.24040.18000.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> <1094156688.24040.18000.camel@erato.phig.org> Message-ID: <1094157956.4353.86.camel@berlin.east.gov> On Thu, 2004-09-02 at 16:24, Karsten Wade wrote: > On Thu, 2004-09-02 at 10:35, Dave Pawson wrote: > > On Wed, 2004-09-01 at 23:29, Karsten Wade wrote: > > > > > I also forgot about ... going to have to experiment with > > > that one. :) > > > > And don't forget 'programlisting' and literallayout; > > both have their uses, but the definitive guide has always been my guide. > > I have its icon on my desktop and a copy on my hard disk, in case > > I'm caught without a connection (sad or what) > > Ha! I keep a local copy as well, wouldn't hop a plane without it. > > An addendum to this conversation, and then I think I'll have to submit a > patch for the Doc Guide based on this thread. > > It is *allowed* to use inline tags inside a block, and it's > usage should not necessarily be discouraged. For general purposes, it's > enough to put content into without further markup. It meets > minimum correctness and accessibility, and provides a rich experience > for all the media we can publish to currently. > > What I just noticed during all this experimentation is that it is best > to keep the inline tags, well, inline: > > > foo > > > That keeps extra whitespace from creeping in. The example in our > Documentation Guide[1] has newlines that create whitespace. Was that > done to make the gray box look better? I don't think it's necessary, > tight boxes look fine. If the box needs expanding, best to solve it in > the stylesheet. I think I've posted a bug with a patch to fix the issues. Comments appreciated as always. See: Karsten, I have a not quite-OT question. Are your cool little footnotes just a manual habit, or are they automatically generated? They're super-helpful, and I'm feeling covetous. :-) -- Paul W. Frields, RHCE From paul at frields.com Thu Sep 2 22:03:38 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 02 Sep 2004 18:03:38 -0400 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094157956.4353.86.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> <1094156688.24040.18000.camel@erato.phig.org> <1094157956.4353.86.camel@berlin.east.gov> Message-ID: <1094162618.5436.2.camel@berlin.east.gov> On Thu, 2004-09-02 at 16:45, Paul W. Frields wrote: > I think I've posted a bug with a patch to fix the issues. Comments > appreciated as always. See: Good lord, this from someone trying to be an editor? Am I really that wishy-washy? :-) What I meant, of course, was "I've posted a bug with a patch that I believe fixes the issues." Thank goodness quitting time is around the corner and there's a pint waiting there. Cheers! -- Paul W. Frields, RHCE From pnasrat at redhat.com Thu Sep 2 22:38:30 2004 From: pnasrat at redhat.com (Paul Nasrat) Date: Thu, 2 Sep 2004 18:38:30 -0400 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: <20040902223829.GG16511@devserv.devel.redhat.com> On Tue, Aug 31, 2004 at 03:49:19PM -0400, Paul W. Frields wrote: > The updated version, hopefully ready for editorial, is available at > Bugzilla #130125. Major issues: Note all changes for fc3 and yum as we'll be using createrepo (now in rawhide) for the metadata based repo. End goal is yum/apt/up2date support for the metadata. It's in yum 2.1.x as in rawhide, up2date also has had support written (may not be enabled) unsure of apt status. Paul From tfox at redhat.com Fri Sep 3 15:55:29 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 03 Sep 2004 11:55:29 -0400 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094156688.24040.18000.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> <1094156688.24040.18000.camel@erato.phig.org> Message-ID: <1094226928.4225.0.camel@jadefox.rdu.redhat.com> On Thu, 2004-09-02 at 16:24, Karsten Wade wrote: > On Thu, 2004-09-02 at 10:35, Dave Pawson wrote: > > On Wed, 2004-09-01 at 23:29, Karsten Wade wrote: > > > > > I also forgot about ... going to have to experiment with > > > that one. :) > > > > And don't forget 'programlisting' and literallayout; > > both have their uses, but the definitive guide has always been my guide. > > I have its icon on my desktop and a copy on my hard disk, in case > > I'm caught without a connection (sad or what) > > Ha! I keep a local copy as well, wouldn't hop a plane without it. > > An addendum to this conversation, and then I think I'll have to submit a > patch for the Doc Guide based on this thread. > > It is *allowed* to use inline tags inside a block, and it's > usage should not necessarily be discouraged. For general purposes, it's > enough to put content into without further markup. It meets > minimum correctness and accessibility, and provides a rich experience > for all the media we can publish to currently. > > What I just noticed during all this experimentation is that it is best > to keep the inline tags, well, inline: > > > foo > > > That keeps extra whitespace from creeping in. The example in our > Documentation Guide[1] has newlines that create whitespace. Was that > done to make the gray box look better? I don't think it's necessary, > tight boxes look fine. If the box needs expanding, best to solve it in > the stylesheet. > No. It was intended to make the code easier to read. But, if it is adding whitespace, we should obviously omit it. Tammy > - Karsten > > [1] > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-screen.html > > -- > 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 Sep 3 15:57:19 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 03 Sep 2004 11:57:19 -0400 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094162618.5436.2.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> <1094156688.24040.18000.camel@erato.phig.org> <1094157956.4353.86.camel@berlin.east.gov> <1094162618.5436.2.camel@berlin.east.gov> Message-ID: <1094227038.4225.2.camel@jadefox.rdu.redhat.com> On Thu, 2004-09-02 at 18:03, Paul W. Frields wrote: > On Thu, 2004-09-02 at 16:45, Paul W. Frields wrote: > > I think I've posted a bug with a patch to fix the issues. Comments > > appreciated as always. See: > > Good lord, this from someone trying to be an editor? Am I really that > wishy-washy? :-) What I meant, of course, was "I've posted a bug with a > patch that I believe fixes the issues." Thank goodness quitting time is > around the corner and there's a pint waiting there. Cheers! > > -- > Paul W. Frields, RHCE > Thanks Paul! I'll get it applied and up on the website this weekend. BTW, I added you to the official editors list on the project page in case you haven't noticed. ;-) Tammy From tfox at redhat.com Fri Sep 3 16:07:34 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 03 Sep 2004 12:07:34 -0400 Subject: screenshot instructions In-Reply-To: <1094051239.2297.159.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <200409011420.09336.dasho@ma-isp.com> <1094046356.2297.115.camel@berlin.east.gov> <200409011610.26352.dasho@ma-isp.com> <1094051239.2297.159.camel@berlin.east.gov> Message-ID: <1094227654.4225.12.camel@jadefox.rdu.redhat.com> On Wed, 2004-09-01 at 11:07, Paul W. Frields wrote: > On Wed, 2004-09-01 at 10:10, Dashamir Hoxha wrote: > > On Wednesday 01 September 2004 03:45 pm, Paul W. Frields wrote: > > > > > > > > > # The following line should be changed. > > > MyVariable = NewValue > > > MyVariableContext = default > > > > > > > > > > What I suggested is this: > > > > # The following line should be changed. > > MyVariable = NewValue > > MyVariableContext = default > > > > > > I don't see anything wrong with your version. > > Do you see anything wrong with my version? > > If not, why the usage of > > should be enforced by a rule? > > Nothing wrong with it, I just think using <*put> throughout is more > descriptive. "On the screen, the computer outputs XXX." > I agree with this as well. Using the computeroutput tags is more descriptive. It also allows us to make it stand out even more in the HTML versions by changing the font. > > Actually, for configuration files (and for anything > > that can be edited) I would prefer something like this: > > > > # The following line should be changed. > > MyVariable = NewValue > > MyVariableContext = default > > > > I could agree with the part here, but I think in the > interest of consistency and sensibility, use instead of > if that's something the user is expected to enter. Again, I > think these are minor points and are probably just better left for an > editor to simply fix as required or desired, provided the sense and > context are unaffected by a change. > I use for *exact* text the user must type and for text that should be changed to the appropriate value for the user. IMO, tags should be used in your example instead of . Tammy > -- > Paul W. Frields, RHCE > From kwade at redhat.com Fri Sep 3 18:04:28 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 03 Sep 2004 11:04:28 -0700 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094226928.4225.0.camel@jadefox.rdu.redhat.com> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> <1094156688.24040.18000.camel@erato.phig.org> <1094226928.4225.0.camel@jadefox.rdu.redhat.com> Message-ID: <1094234667.24040.26985.camel@erato.phig.org> On Fri, 2004-09-03 at 08:55, Tammy Fox wrote: > On Thu, 2004-09-02 at 16:24, Karsten Wade wrote: > > That keeps extra whitespace from creeping in. The example in our > > Documentation Guide[1] has newlines that create whitespace. Was that > > done to make the gray box look better? I don't think it's necessary, > > tight boxes look fine. If the box needs expanding, best to solve it in > > the stylesheet. > No. It was intended to make the code easier to read. But, if it is > adding whitespace, we should obviously omit it. It's not as obvious when the gray box is surrounding the text. The stylesheet in the fedora-docs/ module don't use the gray box, so the extra whitespace is much more obvious. - 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 Sep 3 18:59:39 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 03 Sep 2004 11:59:39 -0700 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094157956.4353.86.camel@berlin.east.gov> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> <1094156688.24040.18000.camel@erato.phig.org> <1094157956.4353.86.camel@berlin.east.gov> Message-ID: <1094237978.24040.27369.camel@erato.phig.org> On Thu, 2004-09-02 at 13:45, Paul W. Frields wrote: > Karsten, I have a not quite-OT question. Are your cool little footnotes > just a manual habit, or are they automatically generated? They're > super-helpful, and I'm feeling covetous. :-) Entirely manual habit I picked up from others because I liked the way it provides context, reference, and support for the text, while putting the URLs out of the way. I prefer plain text except for the poor hyperlinking. ;-) - 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 tuxxer at cox.net Sat Sep 4 13:04:27 2004 From: tuxxer at cox.net (tuxxer) Date: Sat, 04 Sep 2004 13:04:27 +0000 Subject: Hardening Doc Preview Message-ID: <1094303066.16202.9.camel@bach> Hey guys. I'm posting a draft version of what I've got so far of the hardening doc in my own web-space. It's not much, but it will be updated rather randomly, as I get chances to work on it. There isn't a "draft" statement on it at the moment (other than the title), but I'm working on that, and it will be there shortly. Link: http://members.cox.net/tuxxer/ I'll be posting the XML to the bug, once I've finished chapter 1. Please feel free to comment, critique, shred, etc. -Charlie -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 tuxxer at cox.net Sat Sep 4 13:27:55 2004 From: tuxxer at cox.net (tuxxer) Date: Sat, 04 Sep 2004 13:27:55 +0000 Subject: Hardening Doc Preview In-Reply-To: <1094303066.16202.9.camel@bach> References: <1094303066.16202.9.camel@bach> Message-ID: <1094304475.16202.14.camel@bach> On Sat, 2004-09-04 at 13:04, tuxxer wrote: > Hey guys. > > I'm posting a draft version of what I've got so far of the hardening doc > in my own web-space. It's not much, but it will be updated rather > randomly, as I get chances to work on it. There isn't a "draft" > statement on it at the moment (other than the title), but I'm working on > that, and it will be there shortly. > On that note, is there a way to insert a "default disclaimer" stating that it's a draft? I've tried creating an called 'DRAFTNOTICE', but `make html` fails everytime I add it. Included below it the text for the DRAFTNOTICE... > > Link: http://members.cox.net/tuxxer/ > > I'll be posting the XML to the bug, once I've finished chapter 1. > > Please feel free to comment, critique, shred, etc. > > -Charlie DRAFTNOTICE TEXT: Draft Notice: This version of this document is not yet affiliated with the Fedora Docs Project. It is a draft, and may be submitted to the project for review/approval at a later date. Until that time, that document will be receiving constant updates, and may change frequently. -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 mjohnson at redhat.com Sat Sep 4 20:51:39 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 04 Sep 2004 16:51:39 -0400 Subject: Hardening Doc Preview In-Reply-To: <1094304475.16202.14.camel@bach> References: <1094303066.16202.9.camel@bach> <1094304475.16202.14.camel@bach> Message-ID: <413A2ADB.1090906@redhat.com> tuxxer wrote: > On Sat, 2004-09-04 at 13:04, tuxxer wrote: > >>Hey guys. >> >>I'm posting a draft version of what I've got so far of the hardening doc >>in my own web-space. It's not much, but it will be updated rather >>randomly, as I get chances to work on it. There isn't a "draft" >>statement on it at the moment (other than the title), but I'm working on >>that, and it will be there shortly. >> > > > On that note, is there a way to insert a "default disclaimer" stating > that it's a draft? You can do it at the stylesheet level by setting the xsl parameter "draft.mode" to "yes", your doc will then get a watermark background on every page that looks like this: http://docbook.sourceforge.net/release/images/draft.png But it doesn't sound like this is what you want to do. 'Just thought I'd let you know there are other options... Cheers, Mark > I've tried creating an called > 'DRAFTNOTICE', but `make html` fails everytime I add it. > > Included below it the text for the DRAFTNOTICE... > > >>Link: http://members.cox.net/tuxxer/ >> >>I'll be posting the XML to the bug, once I've finished chapter 1. >> >>Please feel free to comment, critique, shred, etc. >> >>-Charlie > > > DRAFTNOTICE TEXT: > > > > > Draft Notice: > This version of this document is not yet affiliated with the > Fedora Docs > Project. It is a draft, and may be submitted to the project for > review/approval at a later date. Until that time, that document will > be > receiving constant updates, and may change frequently. > > > -- ---------------------------------------------------------- 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 paul at frields.com Sat Sep 4 21:37:47 2004 From: paul at frields.com (Paul W. Frields) Date: Sat, 04 Sep 2004 17:37:47 -0400 Subject: Hardening Doc Preview In-Reply-To: <1094303066.16202.9.camel@bach> References: <1094303066.16202.9.camel@bach> Message-ID: <1094333867.14895.66.camel@bettie.internal.frields.org> On Sat, 2004-09-04 at 09:04, tuxxer wrote: > Hey guys. > > I'm posting a draft version of what I've got so far of the hardening doc > in my own web-space. It's not much, but it will be updated rather > randomly, as I get chances to work on it. There isn't a "draft" > statement on it at the moment (other than the title), but I'm working on > that, and it will be there shortly. > > > Link: http://members.cox.net/tuxxer/ > > I'll be posting the XML to the bug, once I've finished chapter 1. > > Please feel free to comment, critique, shred, etc. It's good to see you're blazing ahead! I will try and fix up an XML patch for you that will make these points, but I am committing some of them to the list in the hopes they will help others who are lurking and/or working on documents of their own. I will readily admit to being guilty of these same problems from time to time, and I'm marking the suggestions below accordingly. I try to catch the problems before they leave my repo, but as Karsten will testify, that doesn't always happen! I am going to add these issues to my Style TODO as well. 1. Don't overuse "most of," "typically," "usually," "many." These water down your instructions and make the tutorial sound wishy-washy, as if you're trying to CYA. A document the length of a typical tutorial can't possibly cover every single case, and shouldn't try. Your tips should adequately cover a stock installation of Fedora Core, in the present version. Don't state this beyond the context of your document's goal(s); the fact that it's going to be an official Fedora Doc makes this the case. (Guilty) 2. Don't use first person at all: "I," "me," "my," "mine," "we," "our," "ours." Also do not use "his or her," "his/her," "he or she," "s/he." Reformulate your sentence to eliminate it. 3. Use ispell (or whatever spelling checker you have available) before you post a new version. That simply saves the editor a little time. :-) (Guilty) 4. Use active voice. "Issue this command," not "The XXX command needs to be run." The tutorial tells the user how to do something, and should give instructions clearly and concisely. (GUILTY!) 5. Don't use abbreviations like FC2 or FC. Instead, use the entity &FC; (which inserts the words "Fedora Core" thanks to our entities) with or without &FCVER; (the version number). Put a space between &FC; and &FCVER; like this: &FC; &FCVER; provides firewall capabilities... 6. This is a matter of content: Don't cover updates (up2date or yum) in a tutorial about system hardening, beyond stating the user should pull system updates. Direct the reader to other resources. If every tutorial author does this, the aggregate wasted time will be substantial. There may not be an "official" update-tutorial to link to right now, but that's fine. Simply leave a place marker; there's a tutorial on the way for that subject. When it shows up, add a to it in your document. (*** NOTE: I think this brings up an interesting side point, which is that the yum/up2date tutorial currently in process [1] needs some editorial lovin'. Once that's done, any author can point to the finished document at the &FDPDOCS-URL; site. That's what this tutorial should do. ***) 7. Leave out statements like "One of the most important things to do is to mind your P's and Q's." If it's important, the reader expects it to be in your tutorial. The converse is also true: if it's in your tutorial, the reader expects it is important, especially if you use a whole section for it. Merely state, "Mind your P's and Q's." Then elaborate as required. If the whole section concerns how to mind one's P's and Q's, you may be able to leave this sentence out entirely. (Guilty) 8. When you direct readers, use correct words for the actions they should take. Users do not "go to" the Main Menu -> Foobar. They either click on Main Menu and then click on Foobar, or from the Main Menu they select Foobar. (I would argue the latter is better, because some people don't use a mouse even in the GUI. I actually avoid it depending on what I'm doing at the time.) 9. Avoid punctuation in your titles for sections or admonitions -- except for commas where demanded. ("Important!:", "Note:".) Instead, just use the title itself ("Important"). It is helpful (and encouraged) to use a title that says something about the admonition comment, such as "Stop services." This is a minor style point, but your editor will likely fix it if you don't. 10. Avoid contractions when possible. They can be confusing to readers for whom English is not a first language. (Guilty) 11. Avoid slashes "/" in titles or in your prose (except in or other appropriate context, of course). Use "and" or "or." That's a long list, but not too difficult to learn for your writing. I think these are all minor criticisms, and hope you'll take them in the constructive spirit in which they're offered. Also, visit the following URL's and bring your document in line with their recommendations. Following these guidelines will make your document stronger and more professional looking: http://www.redhat.com/archives/fedora-docs-list/2004-August/msg00307.html http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html There are others in the archives but I didn't have time to track them all down. They will certainly be collected for the style portion of the Docs Guide as soon as I have time to do that. I'm hoping to start this weekend. = = = = = [1] update-tutorial: https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131131 -- Paul W. Frields, RHCE (greedily appropriating Karsten's footnotes) From tuxxer at cox.net Sat Sep 4 16:12:23 2004 From: tuxxer at cox.net (tuxxer) Date: Sat, 04 Sep 2004 16:12:23 +0000 Subject: Hardening Doc Preview In-Reply-To: <413A2ADB.1090906@redhat.com> References: <1094303066.16202.9.camel@bach> <1094304475.16202.14.camel@bach> <413A2ADB.1090906@redhat.com> Message-ID: <1094314343.16202.17.camel@bach> On Sat, 2004-09-04 at 20:51, Mark Johnson wrote: > tuxxer wrote: > > On Sat, 2004-09-04 at 13:04, tuxxer wrote: > > > >>Hey guys. > >> > >>I'm posting a draft version of what I've got so far of the hardening doc > >>in my own web-space. It's not much, but it will be updated rather > >>randomly, as I get chances to work on it. There isn't a "draft" > >>statement on it at the moment (other than the title), but I'm working on > >>that, and it will be there shortly. > >> > > > > > > On that note, is there a way to insert a "default disclaimer" stating > > that it's a draft? > > You can do it at the stylesheet level by setting the xsl parameter > "draft.mode" to "yes", your doc will then get a watermark background > on every page that looks like this: > > http://docbook.sourceforge.net/release/images/draft.png > > But it doesn't sound like this is what you want to do. I'm always open to other options, and this certainly get's the point across, which is the main objective. Where do I set that config item? (what file, etc.) > > 'Just thought I'd let you know there are other options... > > Cheers, > Mark > > > I've tried creating an called > > 'DRAFTNOTICE', but `make html` fails everytime I add it. > > > > Included below it the text for the DRAFTNOTICE... > > > > > >>Link: http://members.cox.net/tuxxer/ > >> > >>I'll be posting the XML to the bug, once I've finished chapter 1. > >> > >>Please feel free to comment, critique, shred, etc. > >> > >>-Charlie > > > > > > DRAFTNOTICE TEXT: > > > > > > > > > > Draft Notice: > > This version of this document is not yet affiliated with the > > Fedora Docs > > Project. It is a draft, and may be submitted to the project for > > review/approval at a later date. Until that time, that document will > > be > > receiving constant updates, and may change frequently. > > > > > > -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 tuxxer at cox.net Sat Sep 4 22:36:49 2004 From: tuxxer at cox.net (tuxxer) Date: Sat, 04 Sep 2004 22:36:49 +0000 Subject: Hardening Doc Preview In-Reply-To: <1094333867.14895.66.camel@bettie.internal.frields.org> References: <1094303066.16202.9.camel@bach> <1094333867.14895.66.camel@bettie.internal.frields.org> Message-ID: <1094337408.16202.58.camel@bach> On Sat, 2004-09-04 at 21:37, Paul W. Frields wrote: > On Sat, 2004-09-04 at 09:04, tuxxer wrote: > > Hey guys. > > > > 1. Don't overuse "most of," "typically," "usually," "many." These water > down your instructions and make the tutorial sound wishy-washy, as if > you're trying to CYA. A document the length of a typical tutorial can't > possibly cover every single case, and shouldn't try. Your tips should > adequately cover a stock installation of Fedora Core, in the present > version. Don't state this beyond the context of your document's goal(s); > the fact that it's going to be an official Fedora Doc makes this the > case. (Guilty) I think that it just implies that the author is aware, that his way isn't the only way. But that's also a matter of perspective, and nuance. > 2. Don't use first person at all: "I," "me," "my," "mine," "we," "our," > "ours." Also do not use "his or her," "his/her," "he or she," "s/he." > Reformulate your sentence to eliminate it. > Generally a good practice. > 3. Use ispell (or whatever spelling checker you have available) before > you post a new version. That simply saves the editor a little time. :-) > (Guilty) > Never used any of the linux spell-checking utilities before. Guess now's as good of a time as any to learn. ;) > 4. Use active voice. "Issue this command," not "The XXX command needs to > be run." The tutorial tells the user how to do something, and should > give instructions clearly and concisely. (GUILTY!) > > 5. Don't use abbreviations like FC2 or FC. Instead, use the entity &FC; > (which inserts the words "Fedora Core" thanks to our entities) with or > without &FCVER; (the version number). Put a space between &FC; and > &FCVER; like this: > > &FC; &FCVER; provides firewall capabilities... Cool....wasn't sure if those were "standard" entities, or ones that you had customized in. > > 6. This is a matter of content: Don't cover updates (up2date or yum) in > a tutorial about system hardening, beyond stating the user should pull > system updates. Direct the reader to other resources. If every tutorial > author does this, the aggregate wasted time will be substantial. There > may not be an "official" update-tutorial to link to right now, but > that's fine. Simply leave a place marker; there's a tutorial on the way > for that subject. When it shows up, add a to it in your > document. > > (*** NOTE: I think this brings up an interesting side point, which is > that the yum/up2date tutorial currently in process [1] needs some > editorial lovin'. Once that's done, any author can point to the finished > document at the &FDPDOCS-URL; site. That's what this tutorial should do. > ***) Understood and agreed. However, I think that there is some value in glossing over certain procedures (or re-presenting them) which might otherwise be covered elsewhere, and thus referenced in your document. Continuously referencing other material makes the document discontinuous, and sometimes difficult to read. Overuse can even render your document useless to the "average" user. You end up with a document like: How to harden: Accomplish this task described in this other document: http://foo.doc.com/first_ref/ Then accomplish the task described in this other document: http://foo.doc.com/second_ref/ Then accomplish the task described in this other document: http://foo.doc.com/third_ref/ Then accomplish the task described in this other document: http://foo.doc.com/fouth_ref/ etc., etc. ad nauseum..... You're not really providing the reader with a tutorial, just a list of links that they probably could have found on some Joe Schmoe's website hosted out of his garage. ;) Now if the document could be included (as an entity???), so that work isn't duplicated, but your document actually contains the same instructions, that might have value. Then the reader is presented with all of the information needed in one, concise location, that flows from the beginning of the process to the end. Sure, there might be some duplication of data within the document project as a whole (100,000 ft. view), but that duplication is only in the presentation of the data, not the development or storage of the data. From the reader's perspective, I would think that this approach would be orders of magnitude more valuable, than having a document that had a bunch of links for every other section. If I wanted a list of links I would just use Google (which is usually the case anyway). I also think that the FDP should be the defacto standard in documentation for the distribution, and thus, the most complete, most readable, and most informative. In other words, why would I read (and follow) the FPD's document for a particular project, if charliesfedoradocs.com has a document that has everything I need in one single place? (Rhetorical question. ;) > 7. Leave out statements like "One of the most important things to do is > to mind your P's and Q's." If it's important, the reader expects it to > be in your tutorial. The converse is also true: if it's in your > tutorial, the reader expects it is important, especially if you use a > whole section for it. Merely state, "Mind your P's and Q's." Then > elaborate as required. If the whole section concerns how to mind one's > P's and Q's, you may be able to leave this sentence out entirely. > (Guilty) OK, so how do you say ... "This section is important. However, THIS section is REALLY important." ?? For example, while it IS important to update your system, I've actually been in situations where NOT being updated has been a good thing. Certain vulnerabilities are found to work in certain versions of certain applications, but earlier versions (and sometimes later ones) may not necessarily be vulnerable. So how would I emphasize that updating is important, but it's MORE important that the user close off other vectors of attack (network penetration, file system vulnerabilities, unmanaged users, etc.)? > > 8. When you direct readers, use correct words for the actions they > should take. Users do not "go to" the Main Menu -> Foobar. They either > click on Main Menu and then click on Foobar, or from the Main Menu they > select Foobar. (I would argue the latter is better, because some people > don't use a mouse even in the GUI. I actually avoid it depending on what > I'm doing at the time.) I think this is a matter of semantics, and could just be a matter of "learning the lingo". > > 9. Avoid punctuation in your titles for sections or admonitions -- > except for commas where demanded. ("Important!:", "Note:".) Instead, > just use the title itself ("Important"). It is helpful (and encouraged) > to use a title that says something about the admonition comment, such as > "Stop services." This is a minor style point, but your editor will > likely fix it if you don't. Again, a matter of nuance.... "Important!" reads as a lot more important to me than "Important". > > 10. Avoid contractions when possible. They can be confusing to readers > for whom English is not a first language. (Guilty) Generally a good practice. I am from the southeast, so it tends to come a little too naturally sometimes. ;) > > 11. Avoid slashes "/" in titles or in your prose (except in > or other appropriate context, of course). Use "and" or "or." > > That's a long list, but not too difficult to learn for your writing. I > think these are all minor criticisms, and hope you'll take them in the > constructive spirit in which they're offered. And all very valid points. I was going to say in my initial post (but finally decided against it) that I have a hard shell for criticism, since this is my first attempt at any sort of official documentation, and really any technical writing, as well. I've written PLENTY of SOPs, but the ones I write have to be designed for Joe-Blow-I-Can't-Even-Spell-Linux types. They are also maintained with a very limited audience scope, so I guess I'm allowed certain "freedoms" (read: I'm the only one writing anything, so standardization is pretty much what I say it is at this point [for MY environment ;) ]). > > = = = = = > [1] update-tutorial: > https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=131131 > > -- > Paul W. Frields, RHCE (greedily appropriating Karsten's footnotes) -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 tuxxer at cox.net Sat Sep 4 23:34:48 2004 From: tuxxer at cox.net (tuxxer) Date: Sat, 04 Sep 2004 23:34:48 +0000 Subject: Emacs error Message-ID: <1094340887.16202.61.camel@bach> Whenever I run `C-c C-p` to parse the DTD, I get "External entity CHAPTER not found". Can any one explain why? And perhaps suggest a fix? -Charlie -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 kwade at redhat.com Sun Sep 5 07:57:11 2004 From: kwade at redhat.com (Karsten Wade) Date: Sun, 05 Sep 2004 00:57:11 -0700 Subject: Emacs error In-Reply-To: <1094340887.16202.61.camel@bach> References: <1094340887.16202.61.camel@bach> Message-ID: <1094371031.24040.42709.camel@erato.phig.org> On Sat, 2004-09-04 at 16:34, tuxxer wrote: > Whenever I run `C-c C-p` to parse the DTD, I get "External entity > CHAPTER not found". Can any one explain why? And perhaps suggest a > fix? This happens when you are parsing the DTD for an individual in a single file; since there is no DOCTYPE header, Emacs isn't sure how to parse the file. This is where the saved parsed file comes in handy: http://fedora.redhat.com/participate/documentation-guide/s1-emacs-cedfile.html http://fedora.redhat.com/participate/documentation-guide/s1-emacs-loadced.html Once you've loaded the .ced file, the XML will parse and validate. You may experience a difference in indenting levels or other things when the XML is properly parsed. - 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 Sun Sep 5 09:46:11 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 05 Sep 2004 10:46:11 +0100 Subject: Hardening Doc Preview In-Reply-To: <1094303066.16202.9.camel@bach> References: <1094303066.16202.9.camel@bach> Message-ID: <1094377571.2545.25.camel@homer> On Sat, 2004-09-04 at 14:04, tuxxer wrote: > Hey guys. > > I'm posting a draft version of what I've got so far of the hardening doc > in my own web-space. It's not much, but it will be updated rather > randomly, as I get chances to work on it. There isn't a "draft" > statement on it at the moment (other than the title), but I'm working on > that, and it will be there shortly. > > > Link: http://members.cox.net/tuxxer/ Hi Charlie http://members.cox.net/tuxxer/s1-chapter1-services.html 1. General. I was surprised to find that 'hardening' meant setting up the ssystem to repel 'attacks'. Be nice to see something like a comparison with a Windows (Norton setup) and this, perhaps to get a perspective for a windows user? 2. On the above url, No idea what half those services do. How about a one line description of each? 1.4.2 you use the term 'service control'. No idea what it is. Who is the audience for this document? If newbies included, please tell us! Overall. I'm a 'new to fc2' user, and its looking potentially very useful. Please finish it :-) -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sun Sep 5 10:33:21 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 05 Sep 2004 11:33:21 +0100 Subject: Hardening Doc Preview In-Reply-To: <1094337408.16202.58.camel@bach> References: <1094303066.16202.9.camel@bach> <1094333867.14895.66.camel@bettie.internal.frields.org> <1094337408.16202.58.camel@bach> Message-ID: <1094380401.2545.68.camel@homer> On Sat, 2004-09-04 at 23:36, Charlie wrote: > Now if the document could be included (as an entity???), so that work > isn't duplicated, but your document actually contains the same > instructions, that might have value. Nice idea. Exploring it a bit further... You said you wanted draft mode.. A customising stylesheet might look like Lets say in your source document you had a pi then add to the stylesheet as shown, That (untested) should pull in the yum stuff, xml version, starting at a specific sect1 tag. Next question, are the xml files available without a cvs pull? I dont' think they are. The basics are there though. Equally, an entity in the XML would do it, but not in such a selective way. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sun Sep 5 10:37:44 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 05 Sep 2004 11:37:44 +0100 Subject: Emacs error In-Reply-To: <1094340887.16202.61.camel@bach> References: <1094340887.16202.61.camel@bach> Message-ID: <1094380663.2545.73.camel@homer> On Sun, 2004-09-05 at 00:34, tuxxer wrote: > Whenever I run `C-c C-p` to parse the DTD, I get "External entity > CHAPTER not found". Can any one explain why? And perhaps suggest a > fix? Yes, either as Karsten says, or the emacs way; Add That tells psgml that the file root.xml holds the 'chapter' element that this file is a part of? See the psgml doco for details, but basically this just links this file with the parent that has the doctype declaration. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sun Sep 5 11:03:29 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 05 Sep 2004 12:03:29 +0100 Subject: Docbook quick reference card Message-ID: <1094382209.2545.75.camel@homer> http://sources.redhat.com/ml/docbook-apps/2003-q2/msg00834.html Quick summary of the major docbook elements. May be of help? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From rahulsundaram at yahoo.co.in Sun Sep 5 13:07:34 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Sun, 5 Sep 2004 06:07:34 -0700 (PDT) Subject: documentation process Message-ID: <20040905130734.55875.qmail@web8507.mail.in.yahoo.com> Hi I have been in the LDP list for sometime and the review process there is something like this * Author submits the document link to the discussion list * Peer review is done by volunteers in the list * If the document is generally agreed upon to be included the author would then update the document according to peer reviews * The document would be assigned to editors who would then do a language review as well as a technical review( need not be the same person). * It is included in LDP and goes through a yearly review to make sure its relevant and kept updated. * If not the document author is contacted off list and gently advised to make appropriate updates * If the authors cannot maintain the document it is moved to the unmaintained list or someone else takes over the maintainance or even completely removed where it is deemed necessary(gross inaccuracies or such- ex: kernel howto) The author as well as reviewers howto has more details. Fedora docs project should probably adopt something similar if its not done already regards Rahul Sundaram _______________________________ Do you Yahoo!? Win 1 of 4,000 free domain names from Yahoo! Enter now. http://promotions.yahoo.com/goldrush From paul at frields.com Sun Sep 5 15:24:19 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 05 Sep 2004 11:24:19 -0400 Subject: Docbook quick reference card In-Reply-To: <1094382209.2545.75.camel@homer> References: <1094382209.2545.75.camel@homer> Message-ID: <1094397859.22071.94.camel@bettie.internal.frields.org> On Sun, 2004-09-05 at 07:03, Dave Pawson wrote: > http://sources.redhat.com/ml/docbook-apps/2003-q2/msg00834.html > > Quick summary of the major docbook elements. > May be of help? I tried the link, but twistedcranium.com doesn't resolve via DNS, so I couldn't get to the PDF. Anyone else have any luck? -- Paul W. Frields, RHCE From paul at frields.com Sun Sep 5 15:21:13 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 05 Sep 2004 11:21:13 -0400 Subject: Hardening Doc Preview In-Reply-To: <1094337408.16202.58.camel@bach> References: <1094303066.16202.9.camel@bach> <1094333867.14895.66.camel@bettie.internal.frields.org> <1094337408.16202.58.camel@bach> Message-ID: <1094397673.22071.92.camel@bettie.internal.frields.org> On Sat, 2004-09-04 at 18:36, tuxxer wrote: > > 1. Don't overuse "most of," "typically," "usually," "many." These water > > down your instructions and make the tutorial sound wishy-washy, as if > > you're trying to CYA. A document the length of a typical tutorial can't > > possibly cover every single case, and shouldn't try. Your tips should > > adequately cover a stock installation of Fedora Core, in the present > > version. Don't state this beyond the context of your document's goal(s); > > the fact that it's going to be an official Fedora Doc makes this the > > case. (Guilty) > > I think that it just implies that the author is aware, that his way > isn't the only way. But that's also a matter of perspective, and > nuance. You can include a single sentence in the introduction addressing this point, if you feel it's necessary. We are offering our documents as the "official" word on Fedora, so while they can't completely address every possible configuration or edge case, they should be reasonably complete. If you feel your tutorial doesn't cover enough cases to be authoritative, you should either research the issue some more, or solicit the opinions of other knowledgeable parties. When I was working on my usb-hotplug-tutorial, a helpful third party pointed out that I had left out a couple major technical issues that really needed to be addressed. I reworked the tutorial to take advantage of existing advice from a pretty authoritative source. [...snip...] > > 6. This is a matter of content: Don't cover updates (up2date or yum) in > > a tutorial about system hardening, beyond stating the user should pull > > system updates. Direct the reader to other resources. If every tutorial > > author does this, the aggregate wasted time will be substantial. There > > may not be an "official" update-tutorial to link to right now, but > > that's fine. Simply leave a place marker; there's a tutorial on the way > > for that subject. When it shows up, add a to it in your > > document. > > > > (*** NOTE: I think this brings up an interesting side point, which is > > that the yum/up2date tutorial currently in process [1] needs some > > editorial lovin'. Once that's done, any author can point to the finished > > document at the &FDPDOCS-URL; site. That's what this tutorial should do. > > ***) > > Understood and agreed. However, I think that there is some value in > glossing over certain procedures (or re-presenting them) which might > otherwise be covered elsewhere, and thus referenced in your document. > Continuously referencing other material makes the document > discontinuous, and sometimes difficult to read. Overuse can even render > your document useless to the "average" user. You end up with a document > like: > > How to harden: > > Accomplish this task described in this other document: > > http://foo.doc.com/first_ref/ > > Then accomplish the task described in this other document: > > http://foo.doc.com/second_ref/ > [...snip...] > etc., etc. ad nauseum..... > > You're not really providing the reader with a tutorial, just a list of > links that they probably could have found on some Joe Schmoe's website > hosted out of his garage. ;) A tutorial should be *reasonably* self-contained, so I would hope this wouldn't happen. Otherwise the writer should revisit the scope. > Now if the document could be included (as an entity???), so that work > isn't duplicated, but your document actually contains the same > instructions, that might have value. This is an interesting idea, and certainly the idea of updating the system seems universal enough to warrant such a treatment. A paragraph or even just a couple sentences, with one or two command lines ("up2date -u" and/or "yum update"), is sufficient to cover this topic. If we can find a concise way of covering this issue, we could duplicate it for other tutorials that need the same material. How does that sound? [...snip...] > > 7. Leave out statements like "One of the most important things to do is > > to mind your P's and Q's." If it's important, the reader expects it to > > be in your tutorial. The converse is also true: if it's in your > > tutorial, the reader expects it is important, especially if you use a > > whole section for it. Merely state, "Mind your P's and Q's." Then > > elaborate as required. If the whole section concerns how to mind one's > > P's and Q's, you may be able to leave this sentence out entirely. > > (Guilty) > > OK, so how do you say ... "This section is important. However, THIS > section is REALLY important." ?? For example, while it IS important to > update your system, I've actually been in situations where NOT being > updated has been a good thing. Certain vulnerabilities are found to > work in certain versions of certain applications, but earlier versions > (and sometimes later ones) may not necessarily be vulnerable. So how > would I emphasize that updating is important, but it's MORE important > that the user close off other vectors of attack (network penetration, > file system vulnerabilities, unmanaged users, etc.)? In many cases, "This is important," the concept, becomes "It is important to," the execution. The writer slides into passive voice without meaning to. (Guilty again, here.) I'm not advocating stating explicitly, "This section is important." Use an admonition to carry the sense of gravity. Here's an incomplete example of a good way to execute this intent, IMHO: Note the admonition carries the weight of how important this section is. We don't need to hit the reader over the head, because the admonition does it for us. Any reader who doesn't get the sense of importance from that admonition, and the use of an emphasized "must" in the previous paragraph, is simply not reading! :-) > > 8. When you direct readers, use correct words for the actions they > > should take. Users do not "go to" the Main Menu -> Foobar. They either > > click on Main Menu and then click on Foobar, or from the Main Menu they > > select Foobar. (I would argue the latter is better, because some people > > don't use a mouse even in the GUI. I actually avoid it depending on what > > I'm doing at the time.) > > I think this is a matter of semantics, and could just be a matter of > "learning the lingo". It's a matter of style, which should be consistent across tutorials, but yes, you're absolutely right. As you write more, read more of what's already produced, and try to match your style to the accepted standards, I suspect the usage will become second nature to you. > > 9. Avoid punctuation in your titles for sections or admonitions -- > > except for commas where demanded. ("Important!:", "Note:".) Instead, > > just use the title itself ("Important"). It is helpful (and encouraged) > > to use a title that says something about the admonition comment, such as > > "Stop services." This is a minor style point, but your editor will > > likely fix it if you don't. > > Again, a matter of nuance.... "Important!" reads as a lot more > important to me than "Important". This is also part of the style. Right now there's no "style chapter" in the Documentation Guide to tell you what's OK and what's not, so my advice here is not really criticism. It's more an attempt to give you a "heads up" of the issues that will be addressed in the style chapter. Writing that chapter is my responsibility, and I hope to have a first draft in a week or two. Nuance *is* important in professional technical writing, as anyone who does it for a living will tell you. It's part of what separates polished looking official documentation from the majority of what's available by Googling. > > 10. Avoid contractions when possible. They can be confusing to readers > > for whom English is not a first language. (Guilty) > > Generally a good practice. I am from the southeast, so it tends to come > a little too naturally sometimes. ;) I'm from Virginia, so I resemble that remark too! :-) [...snip...] > And all very valid points. I was going to say in my initial post (but > finally decided against it) that I have a hard shell for criticism, > since this is my first attempt at any sort of official documentation, > and really any technical writing, as well. I've written PLENTY of SOPs, > but the ones I write have to be designed for > Joe-Blow-I-Can't-Even-Spell-Linux types. They are also maintained with > a very limited audience scope, so I guess I'm allowed certain > "freedoms" (read: I'm the only one writing anything, so > standardization is pretty much what I say it is at this point [for MY > environment ;) ]). And that's all understandable. I've written in the past for my employer, but it was for similar purposes. I'm learning a lot from some of the pros who are here on this list, such as Mark, Tammy, and Karsten. For instance, when I wrote the advice in my last post, I was making a very conscious effort to write in an active voice. I didn't write "You probably don't want to do XYZ." Instead, I wrote "Avoid XYZ." The style in which I'm learning to write our documentation is carrying over into my writing on the list, to some extent. Unfortunately, it now takes me longer to write a list reply since I correct myself often! :-) I was particularly attentive to style here, partly because Karsten had just edited one of my documents. He provided a lot of advice on fitting my writing to a professionally acceptable style. I tend to drift when I "get on a roll," so to speak, and he picked up on that and didn't bother editing the whole document. It made more sense for him to do part of it, showing me what was wrong, and then leaving it up to me to fix the rest of it. I was also attentive to the style because my responsibility for the style chapter is starting to loom. I'm using examples from the tutorials I see, and write myself, for that purpose. In any case, there's *nothing wrong* with writing a first draft in which you don't worry about any of this. The previous advice just gives you an idea of how to revisit your document -- i.e. how to edit yourself on the second pass, which every writer should learn to do. The more self-editing you can do, the easier it will be for an editor to get your tutorial through the process later. And all other considerations aside, it's great that you are producing material. I hope other writers with your enthusiasm come out to help as well! -- Paul W. Frields, RHCE From paul at frields.com Sun Sep 5 15:29:24 2004 From: paul at frields.com (Paul W. Frields) Date: Sun, 05 Sep 2004 11:29:24 -0400 Subject: documentation process In-Reply-To: <20040905130734.55875.qmail@web8507.mail.in.yahoo.com> References: <20040905130734.55875.qmail@web8507.mail.in.yahoo.com> Message-ID: <1094398164.22071.100.camel@bettie.internal.frields.org> On Sun, 2004-09-05 at 09:07, Rahul Sundaram wrote: > I have been in the LDP list for sometime and the > review process there is something like this > > * Author submits the document link to the discussion > list > * Peer review is done by volunteers in the list > * If the document is generally agreed upon to be > included the author would then update the document > according to peer reviews > * The document would be assigned to editors who would > then do a language review as well as a technical > review( need not be the same person). > * It is included in LDP and goes through a yearly > review to make sure its relevant and kept updated. > * If not the document author is contacted off list and > gently advised to make appropriate updates > * If the authors cannot maintain the document it is > moved to the unmaintained list or someone else takes > over the maintainance or even completely removed where > it is deemed necessary(gross inaccuracies or such- ex: > kernel howto) > > The author as well as reviewers howto has more > details. Fedora docs project should probably adopt > something similar if its not done already Have you reviewed the process documents that Tammy and Karsten prepared? http://fedora.redhat.com/participate/documentation-quick-start/ http://people.redhat.com/kwade/fedora-docs/process-docs/ These documents address some of these concerns; Perhaps you can patch the XML on the latter to include a little bit more on maintenance. -- Paul W. Frields, RHCE From tuxxer at cox.net Sun Sep 5 22:08:46 2004 From: tuxxer at cox.net (tuxxer) Date: Sun, 05 Sep 2004 22:08:46 +0000 Subject: Emacs error In-Reply-To: <1094371031.24040.42709.camel@erato.phig.org> References: <1094340887.16202.61.camel@bach> <1094371031.24040.42709.camel@erato.phig.org> Message-ID: <1094422125.16202.63.camel@bach> On Sun, 2004-09-05 at 07:57, Karsten Wade wrote: > On Sat, 2004-09-04 at 16:34, tuxxer wrote: > > Whenever I run `C-c C-p` to parse the DTD, I get "External entity > > CHAPTER not found". Can any one explain why? And perhaps suggest a > > fix? > > This happens when you are parsing the DTD for an individual in > a single file; since there is no DOCTYPE header, Emacs isn't sure how to > parse the file. > > This is where the saved parsed file comes in handy: > > http://fedora.redhat.com/participate/documentation-guide/s1-emacs-cedfile.html > http://fedora.redhat.com/participate/documentation-guide/s1-emacs-loadced.html > > Once you've loaded the .ced file, the XML will parse and validate. You > may experience a difference in indenting levels or other things when the > XML is properly parsed. I've done that. But my .ced file is called hardfen-parent.ced. Do I need a .ced file for each individual XML file? -charlie -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 tuxxer at cox.net Sun Sep 5 23:56:30 2004 From: tuxxer at cox.net (tuxxer) Date: Sun, 05 Sep 2004 23:56:30 +0000 Subject: Hardening Doc Preview In-Reply-To: <1094380401.2545.68.camel@homer> References: <1094303066.16202.9.camel@bach> <1094333867.14895.66.camel@bettie.internal.frields.org> <1094337408.16202.58.camel@bach> <1094380401.2545.68.camel@homer> Message-ID: <1094428590.16202.73.camel@bach> On Sun, 2004-09-05 at 10:33, Dave Pawson wrote: > On Sat, 2004-09-04 at 23:36, Charlie wrote: > > > Now if the document could be included (as an entity???), so that work > > isn't duplicated, but your document actually contains the same > > instructions, that might have value. > > Nice idea. > > Exploring it a bit further... > > You said you wanted draft mode.. > A customising stylesheet might look like > > > > version="1.0"> > > > > > > > > > select="document('http://fedora-docsURL/yumFDC/xxx.xml')//sect1[@id='start']"/> > > > > > > Lets say in your source document you had a pi > > > then add to the stylesheet as shown, > > That (untested) should pull in the yum stuff, xml version, starting at > a specific sect1 tag. > > > Next question, are the xml files available without a cvs pull? > I dont' think they are. > > The basics are there though. > > Equally, an entity in the XML would do it, but not in such a selective > way. > > > It would also depend on how the author of the particular document that you were referencing authored the doc. I tend to think in a more modular way, so writing different files for different chapters (or sections), just makes more sense to me. To digress for an example, I know that PHP and JSP both support "includes" which can be retrieved from another file. If the document were written in a more modular format, the referenced document could be "included" in another doc. I would suspect that XML would have this same functionality. There could also be an argument for a "detailed" doc, and a "summary" doc. The summary doc would be a smaller doc, which would go over the steps of a particular process, but not in the same detail (obviously) as the "detailed" doc. Also, something to consider, if I can cover updating your system with up2date or yum, in 2 sections (one for GUI and one for command line), does it really require a doc of it's own? Now I could see writing one [for yum], explaining all of the different functionalities of the tool, but not just for the simple purpose of updating your system. Just my $.02. -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 tuxxer at cox.net Mon Sep 6 00:09:58 2004 From: tuxxer at cox.net (tuxxer) Date: Mon, 06 Sep 2004 00:09:58 +0000 Subject: Hardening Doc Preview In-Reply-To: <1094377571.2545.25.camel@homer> References: <1094303066.16202.9.camel@bach> <1094377571.2545.25.camel@homer> Message-ID: <1094429398.16202.81.camel@bach> On Sun, 2004-09-05 at 09:46, Dave Pawson wrote: > On Sat, 2004-09-04 at 14:04, tuxxer wrote: > > Hey guys. > > > > I'm posting a draft version of what I've got so far of the hardening doc > > in my own web-space. It's not much, but it will be updated rather > > randomly, as I get chances to work on it. There isn't a "draft" > > statement on it at the moment (other than the title), but I'm working on > > that, and it will be there shortly. > > > > > > Link: http://members.cox.net/tuxxer/ > > Hi Charlie > http://members.cox.net/tuxxer/s1-chapter1-services.html > > 1. General. I was surprised to find that 'hardening' meant setting up > the ssystem to repel 'attacks'. What else would it be? > Be nice to see something like a comparison with a Windows (Norton > setup) and this, perhaps to get a perspective for a windows user? > How would this compare? Maybe something for a Windows to linux migrator, but because of the inherent differences of the OS's, the processes won't be the same. What do you mean by a "Norton" setup? > 2. On the above url, > No idea what half those services do. How about a one line description > of each? Done. > 1.4.2 you use the term 'service control'. No idea what it is. > Who is the audience for this document? If newbies included, please > tell us! Working on that part. > > Overall. > I'm a 'new to fc2' user, and its looking potentially very useful. > > Please finish it :-) > -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 Mon Sep 6 12:42:15 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 06 Sep 2004 08:42:15 -0400 Subject: Emacs error In-Reply-To: <1094422125.16202.63.camel@bach> References: <1094340887.16202.61.camel@bach> <1094371031.24040.42709.camel@erato.phig.org> <1094422125.16202.63.camel@bach> Message-ID: <1094474535.6518.2.camel@bettie.internal.frields.org> On Sun, 2004-09-05 at 18:08, tuxxer wrote: > On Sun, 2004-09-05 at 07:57, Karsten Wade wrote: > > On Sat, 2004-09-04 at 16:34, tuxxer wrote: > > > Whenever I run `C-c C-p` to parse the DTD, I get "External entity > > > CHAPTER not found". Can any one explain why? And perhaps suggest a > > > fix? > > > > This happens when you are parsing the DTD for an individual in > > a single file; since there is no DOCTYPE header, Emacs isn't sure how to > > parse the file. > > > > This is where the saved parsed file comes in handy: > > > > http://fedora.redhat.com/participate/documentation-guide/s1-emacs-cedfile.html > > http://fedora.redhat.com/participate/documentation-guide/s1-emacs-loadced.html > > > > Once you've loaded the .ced file, the XML will parse and validate. You > > may experience a difference in indenting levels or other things when the > > XML is properly parsed. > > I've done that. But my .ced file is called hardfen-parent.ced. Do I > need a .ced file for each individual XML file? You only need one for the parent file (the one with the actual declaration at the top). A copy of the Documentation Guide comes with the CVS pull. Look at that one for an example. There's only a single .ced file for the parent. The component (chapter) files are all declared as entities in the parent. When you edit one of them, you load the .ced file, and off you go. -- Paul W. Frields, RHCE From kwade at redhat.com Mon Sep 6 15:52:55 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 06 Sep 2004 08:52:55 -0700 Subject: Emacs error In-Reply-To: <1094380663.2545.73.camel@homer> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> Message-ID: <1094485975.24040.55919.camel@erato.phig.org> On Sun, 2004-09-05 at 03:37, Dave Pawson wrote: > On Sun, 2004-09-05 at 00:34, tuxxer wrote: > > Whenever I run `C-c C-p` to parse the DTD, I get "External entity > > CHAPTER not found". Can any one explain why? And perhaps suggest a > > fix? > > > Yes, either as Karsten says, > or the emacs way; Please don't do as Dave says, unless he can truly fix this problem. If you use a Local Variable instead of a .ced file, the indenting is off by two; the core element for the file is indented flush left. When using a .ced file, the indenting for the or
starts two from the left-flush. I assume Dave would then run the file through an XSLT before doing XML diffs[1]. That seems like a lot of steps to me. If you use a Local Variable, and the rest of the project is using .ced files, then doing a diff on your file with an editor is going to be impossible. I've run these experiments numerous times, but if someone can point out the error in my method to let us use Local Variable, I am more than happy to use this easier method. Otherwise, we must stick with the project practice or change the practice across all documents for editorial consistency. - Karsten [1] BTW, I've always only ever been talking about XML diffs, *not* diffs of the rendered file. > Add > > > > > That tells psgml that the file root.xml holds the 'chapter' element > that this file is a part of? > > See the psgml doco for details, > but basically this just links this file with the parent > that has the doctype declaration. -- 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 Sep 6 16:15:45 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 06 Sep 2004 17:15:45 +0100 Subject: Emacs error In-Reply-To: <1094485975.24040.55919.camel@erato.phig.org> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> Message-ID: <1094487345.2518.30.camel@homer> On Mon, 2004-09-06 at 16:52, Karsten Wade wrote: > > Yes, either as Karsten says, > > or the emacs way; > > Please don't do as Dave says, unless he can truly fix this problem. Its not a problem Karsten. Its the way psgml is supposed to work? > > If you use a Local Variable instead of a .ced file, the indenting is off > by two; so address that problem? Unrelated to finding the schema? > I assume Dave would then run the file through an XSLT before doing XML > diffs[1]. That seems like a lot of steps to me. No. I keep saying (OK once :-) that plain text diffs on xml are ... not right. > > If you use a Local Variable, and the rest of the project is using .ced > files, then doing a diff on your file with an editor is going to be > impossible. Thats a project weakness. Nothing to do with schema location. > > I've run these experiments numerous times, but if someone can point out > the error in my method to let us use Local Variable, I am more than > happy to use this easier method. The error is using the wrong tools. I edit pretty large xml files in emacs quite a lot. I also use nxml-mode with xml-mode and believe me hacking that 4 liner to the bottom of the file is the easier option. If you are bothered by the indents, fix the elisp for sgml-mode, or ask on psmgl-list for Lennart to do it! -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Mon Sep 6 16:10:58 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 06 Sep 2004 17:10:58 +0100 Subject: Hardening Doc Preview In-Reply-To: <1094429398.16202.81.camel@bach> References: <1094303066.16202.9.camel@bach> <1094377571.2545.25.camel@homer> <1094429398.16202.81.camel@bach> Message-ID: <1094487058.2518.24.camel@homer> On Mon, 2004-09-06 at 01:09, tuxxer wrote: > > 1. General. I was surprised to find that 'hardening' meant setting up > > the ssystem to repel 'attacks'. > > What else would it be? Windows, windows firewall software etc, doesn't call it 'hardening'. Norton Firewall. I really am at a loss to explain that Nortons product and yours are going in the same direction... but have quite different names. I'm just trying to suggest that your docs might tell the reader early on that 'this does what Norton firewall does in Windows'. It may not be as simple as that, but the end game is the same? Can anyone else help me? > > > Be nice to see something like a comparison with a Windows (Norton > > setup) and this, perhaps to get a perspective for a windows user? > > > > How would this compare? Maybe something for a Windows to linux > migrator, but because of the inherent differences of the OS's, the > processes won't be the same. What do you mean by a "Norton" setup? Wizard type approach? Select one from two Install basic or 'get complicated' I.e. an option for the idiot/non-aware user? I'm taking the part of the windows user finding this funny Linux beast on my screen!!!! -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Mon Sep 6 17:45:32 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 06 Sep 2004 10:45:32 -0700 Subject: Emacs error In-Reply-To: <1094487345.2518.30.camel@homer> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> <1094487345.2518.30.camel@homer> Message-ID: <1094492732.24040.56716.camel@erato.phig.org> On Mon, 2004-09-06 at 09:15, Dave Pawson wrote: > On Mon, 2004-09-06 at 16:52, Karsten Wade wrote: > > > > Yes, either as Karsten says, > > > or the emacs way; > > > > Please don't do as Dave says, unless he can truly fix this problem. > Its not a problem Karsten. Its the way psgml is supposed to work? Something can work as it's supposed to and still be a problem. :) For example, we have two different indenting behaviors depending on which method we choose to get a file to parse. That is a problem. It doesn't matter if they methods are, in themselves, working correctly. :) > > > > > If you use a Local Variable instead of a .ced file, the indenting is off > > by two; > so address that problem? Unrelated to finding the schema? > > > I assume Dave would then run the file through an XSLT before doing XML > > diffs[1]. That seems like a lot of steps to me. > No. I keep saying (OK once :-) that plain text diffs on xml are > ... not right. Oh, good, we're in agreement. > > If you use a Local Variable, and the rest of the project is using .ced > > files, then doing a diff on your file with an editor is going to be > > impossible. > Thats a project weakness. Nothing to do with schema location. Okay ... but the solution to a project weakness is not to suggest that people just start doing things a different way. We're having enough challenges managing things as they are. > > I've run these experiments numerous times, but if someone can point out > > the error in my method to let us use Local Variable, I am more than > > happy to use this easier method. > > The error is using the wrong tools. What is the wrong tool? Using a .ced file built from a parent XML file to parse a child XML file? > I edit pretty large xml files in emacs quite a lot. > I also use nxml-mode with xml-mode and believe me > hacking that 4 liner to the bottom of the file > is the easier option. Then perhaps we should abandon the .ced files and use Local Variable instead? Wouldn't get any objections from me! > If you are bothered by the indents, I'm not bothered by them until I have to reconcile two authors/editors who are using different methods. The difference between a random bunch of documents stored together and an organized, quality document project is a) consistent methodology, and b) sticking to a) until everyone agrees to change the method. My request is, if you have an idea of how to do something better than our current methodology, please *suggest* it as a new solution, and we'll get a quick consensus and move forward. Telling new users to just do something different from what is laid out in our project guide is confusing for the user and detrimental to the project. - 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 Sep 6 18:46:37 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 06 Sep 2004 11:46:37 -0700 Subject: documentation process In-Reply-To: <20040905130734.55875.qmail@web8507.mail.in.yahoo.com> References: <20040905130734.55875.qmail@web8507.mail.in.yahoo.com> Message-ID: <1094496396.24040.57179.camel@erato.phig.org> On Sun, 2004-09-05 at 06:07, Rahul Sundaram wrote: > Hi > > I have been in the LDP list for sometime and the > review process there is something like this > > * Author submits the document link to the discussion > list > * Peer review is done by volunteers in the list > * If the document is generally agreed upon to be > included the author would then update the document > according to peer reviews > * The document would be assigned to editors who would > then do a language review as well as a technical > review( need not be the same person). > * It is included in LDP and goes through a yearly > review to make sure its relevant and kept updated. > * If not the document author is contacted off list and > gently advised to make appropriate updates > * If the authors cannot maintain the document it is > moved to the unmaintained list or someone else takes > over the maintainance or even completely removed where > it is deemed necessary(gross inaccuracies or such- ex: > kernel howto) Thanks for the benchmarking information. It's nice to see that we are following good practices. I think the current FDP process (that Paul provided links to) is relatively similar to this, with one important exception. By having a formalized editing process tied into the Fedora release schedule, we keep a much tighter control on the quality and aging of documents. In Fedora, a year is too long to wait, and a gentle nudge is not sufficient. We need authors who are committed to maintaining their documents and are prepared to do a proper hand-off to a new maintainer or proper closure of the document, should the original author decide to no longer maintain it.[1] We definitely do not want documents thrown over the transom.[2] Another benefit to having a tighter author/editor connection is that the documents can be honed to nearly perfect accuracy for Fedora. TLDP are working in a more generic realm; it's difficult for them to ensure total technical accuracy, and documents need to be written to cover multiple distros. Their documents are generally very useful, but not often specifically useful to each person's unique case. For FDP, we can and should be 100% accurate when it comes to describing Fedora in our documentation. We can do this because the authors, editors, and users are all on the same version of the same distro. FWIW, the methodology you describe is appropriate for TLDP. Their scope is much wider; changes to generic Linux happen over a longer period of time, where Fedora docs needs to closely track Fedora versions. Our process is at least three times faster. - Karsten New experiment in putting my lengthy asides ... well, aside: [1] Yes, I know we'll have abandoned documents; we'll deal with that, that's inevitable. Even at a company, people leave and you can't replace them in time, a document may go a cycle without significant maintenance. We must strive from the beginning to not invite documents that will languish and die. [2] For those who don't know this one, writers in the earlier part of the twentieth century would sometimes throw their completed manuscript into the open transom over a locked door, hoping that when a publisher/editor (literally) stumbled over it the next morning, it might be a step closer to being published. The difference between a publishing house that will print anything that comes in "over the transom" and one that only prints work properly submitted and approved is what I am alluding to in this metaphor. -- 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 Sep 6 19:03:07 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 06 Sep 2004 12:03:07 -0700 Subject: Hardening Doc Preview In-Reply-To: <1094304475.16202.14.camel@bach> References: <1094303066.16202.9.camel@bach> <1094304475.16202.14.camel@bach> Message-ID: <1094497387.24040.57315.camel@erato.phig.org> On Sat, 2004-09-04 at 06:27, tuxxer wrote: > On that note, is there a way to insert a "default disclaimer" stating > that it's a draft? I've tried creating an called > 'DRAFTNOTICE', but `make html` fails everytime I add it. > > Included below it the text for the DRAFTNOTICE... Hey, that's a nice idea. I like that. Inclusion of a draft notice like this is a good must-have, and Mark's watermark is a good nice-have. I am definitely going to use the watermark for whenever I am concerned that a reader will think looks_nice == completed_document. :) > DRAFTNOTICE TEXT: > > > > > Draft Notice: > This version of this document is not yet affiliated with the > Fedora Docs > Project. It is a draft, and may be submitted to the project for > review/approval at a later date. Until that time, that document will > be > receiving constant updates, and may change frequently. > > +1 on the text and format. Not sure what the trouble is; your idea should work. You can call in any arbitrary bit of legal XML that is kept in a separate file. * Put the block into a separate file draftnotice.xml and put it in fedora-docs/common (where we can all use it, thank you) * Put an entity in common/fedora-entities-en.xml. Note that the format is different when you are calling in a file: * In your XML, you will have to put in the &DRAFTNOTICE; where it is legal XML, i.e., inside of a
. If you do that, and it works, please do the following to get your idea into regular usage: 1. 'cd fedora-docs/common' 2. 'cvs diff -du fedora-entities-en.xml | tee /tmp/fedora-entities-en-tuxxer.patch' (or some such name) 3. If that doesn't work (probably because of a cvs environment variable), try the following: 3.1. Before you edit the file, 'cp fedora-entities-en.xml fedora-entities-en.xml.original' 3.2. Edit the file, then do 'diff -u fedora-entities-en.xml.original fedora-entities-en.xml | tee /tmp/fedora-entities-en-tuxxer.patch' 4. File a bug against fedora-docs, set the severity to Enhancement (this is a Request For Enhancement aka RFE); put the details into the bug report, make an attachment of the new XML file (draftnotice.xml) and the patch. Hmmm ... maybe I should snarf the above description and submit it as a patch to the Documentation Guide for "How to submit your idea for a change to Fedora Docs Project." ;-) - 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 Mon Sep 6 19:38:58 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Mon, 06 Sep 2004 15:38:58 -0400 Subject: Emacs error In-Reply-To: <1094487345.2518.30.camel@homer> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> <1094487345.2518.30.camel@homer> Message-ID: <413CBCD2.7060708@redhat.com> Dave Pawson wrote: > > The error is using the wrong tools. > I edit pretty large xml files in emacs quite a lot. > I also use nxml-mode with xml-mode and believe me > hacking that 4 liner to the bottom of the file > is the easier option. I've gotta side with Dave on this one. The emacs 'Local Variables' approach allows you to open up any of the 'child' docs and immediately start editing in DTD-aware mode. (Emacs then automatically loads the top-level parent file.) Also, as soon as you change the internal subset of the DTD, by, e.g. , adding a new entity, you *must* recompile the DTD because the DTD itself has been changed. Regarding the indenting issue: I've heard this is a problem for translation, but one should be still be able to produce reasonable diffs w/ some work around. Or someone could test the GPL tool 'xmldiff'[1], to see if it cares about indentation. FWIW, I use a slightly different form of the local varable statement than Dave; mine specifies three quantities: - top-level-parent-document - top-level-element-in-parent-doc - top-level-element-in-this-doc e.g., for a chapter file, I'd have this at the end: My $0.02, Mark [1] http://www.logilab.org/projects/xmldiff/ > If you are bothered by the indents, > fix the elisp for sgml-mode, > or ask on psmgl-list for Lennart to do it! > > -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 Mon Sep 6 19:45:23 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 06 Sep 2004 20:45:23 +0100 Subject: Emacs error In-Reply-To: <1094492732.24040.56716.camel@erato.phig.org> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> <1094487345.2518.30.camel@homer> <1094492732.24040.56716.camel@erato.phig.org> Message-ID: <1094499923.2518.44.camel@homer> On Mon, 2004-09-06 at 18:45, Karsten Wade wrote: > > > I've run these experiments numerous times, but if someone can point out > > > the error in my method to let us use Local Variable, I am more than > > > happy to use this easier method. > > > > The error is using the wrong tools. > > What is the wrong tool? Using a .ced file built from a parent XML file > to parse a child XML file? .ced file is the right tool, for faster access to a compiled dtd for a specific file. .ced is not always the right way to get hold of the dtd for a suite of files e.g. if n files make up an article. In that case, the psgml comment is (IMHO) the right way to do it. Especially since splitting up the file makes psgml parsing sufficiently fast. IMHO its using a line based comparison or diff tool to find out what the changes are in an XML file, when xml is largely 'don't care' about white space. > > > I edit pretty large xml files in emacs quite a lot. > > I also use nxml-mode with xml-mode and believe me > > hacking that 4 liner to the bottom of the file > > is the easier option. > > Then perhaps we should abandon the .ced files and use Local Variable > instead? Wouldn't get any objections from me! Not my view. Use when appropriate? > > > If you are bothered by the indents, > > I'm not bothered by them until I have to reconcile two authors/editors > who are using different methods. > > The difference between a random bunch of documents stored together and > an organized, quality document project is a) consistent methodology, and > b) sticking to a) until everyone agrees to change the method. > > My request is, if you have an idea of how to do something better than > our current methodology, please *suggest* it as a new solution, I've recently looked at two XML based diff engines. Neither seem appropriate for this projects use. the sourceforge one has possibilities though, > and > we'll get a quick consensus and move forward. Telling new users to just > do something different from what is laid out in our project guide is > confusing for the user and detrimental to the project. I don't tell people anything. Just saying what I use, and have done for 7 years. YMMV. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Mon Sep 6 23:47:16 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 06 Sep 2004 16:47:16 -0700 Subject: Emacs error In-Reply-To: <413CBCD2.7060708@redhat.com> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> <1094487345.2518.30.camel@homer> <413CBCD2.7060708@redhat.com> Message-ID: <1094514436.24040.59317.camel@erato.phig.org> On Mon, 2004-09-06 at 12:38, Mark Johnson wrote: > Regarding the indenting issue: I've heard this is a problem for > translation, but one should be still be able to produce reasonable > diffs w/ some work around. Or someone could test the GPL tool > 'xmldiff'[1], to see if it cares about indentation. > [1] http://www.logilab.org/projects/xmldiff/ Sounds like a fine approach to me. Here is where we stand: * Until we learn otherwise, we need to practice a given set of rules (outlined in the Doc Guide) to keep editing and translating feasible. These rules include whitespace (and indenting) practices. * Those who are interested should a) research XML diff tools, and b) bring this up with the translation team (fedora-i18n-list) to find out what they want to and are able to do. I just joined that list, and am prepared to discuss toolchains. So, while I'm all for Local Variables and letting people indent and use whitespace as they wish, until we *know* that our documents can be internationalized with available tools, we must stick with what works, regardless of our personal preferences. - 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 Sep 6 23:54:34 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 06 Sep 2004 16:54:34 -0700 Subject: Emacs error In-Reply-To: <1094499923.2518.44.camel@homer> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> <1094487345.2518.30.camel@homer> <1094492732.24040.56716.camel@erato.phig.org> <1094499923.2518.44.camel@homer> Message-ID: <1094514873.24040.59382.camel@erato.phig.org> On Mon, 2004-09-06 at 12:45, Dave Pawson wrote: > On Mon, 2004-09-06 at 18:45, Karsten Wade wrote: > > Then perhaps we should abandon the .ced files and use Local Variable > > instead? Wouldn't get any objections from me! > > Not my view. Use when appropriate? We need to be consistent until we have proof that we can change our practices. Surely you can understand this? > I don't tell people anything. > Just saying what I use, and have done for 7 years. > YMMV. It's great that you bring your experience to bear in solving problems here. Your help is really important. But if your suggestion is to try something that is not inline with our practices, it's detrimental to the goals of the project. The Documentation Guide clearly says to follow one practice, and you suggest a different one. Because of the authority your voice lends, you influence a new writer down a path that diverges from the project. The writer and the project suffer now, or down the road. Having and following good practices is what it takes to make Fedora docs the best resource for Fedora users, as opposed to a collection of random and semi-maintained documents. - 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 Sep 7 02:17:55 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 06 Sep 2004 22:17:55 -0400 Subject: mirror-tutorial, etc. Message-ID: <1094523475.3252.6.camel@bettie.internal.frields.org> Version 0.22 is reasonably complete except for one open technical question, noted by a comment in the DocBook XML source. I need an editor for this document. Find the bug at: http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=130125 Hope everyone had a nice weekend. I should have the usb-hotplug-tutorial ready tomorrow, and a first shot at the style guide by the end of the week. -- Paul W. Frields, RHCE From rahulsundaram at yahoo.co.in Tue Sep 7 10:44:38 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Tue, 7 Sep 2004 03:44:38 -0700 (PDT) Subject: documentation process In-Reply-To: <1094496396.24040.57179.camel@erato.phig.org> Message-ID: <20040907104438.7895.qmail@web8506.mail.in.yahoo.com> > Another benefit to having a tighter author/editor > connection is that the > documents can be honed to nearly perfect accuracy > for Fedora. TLDP are > working in a more generic realm; it's difficult for > them to ensure total > technical accuracy, and documents need to be written > to cover multiple > distros. Their documents are generally very useful, > but not often > specifically useful to each person's unique case. I am not sure this will remain true over time. Fedora is a fast moving distro and things change over time. what might be true in fc1 might be entirely irrelevant to fc5 or something like that. how are we planning to deal with this. would these documents be made version specific? > > New experiment in putting my lengthy asides ... > well, aside: > > [1] Yes, I know we'll have abandoned documents; > we'll deal with that, > that's inevitable. Yes. you probably need to add some kind of process to deal with unmaintained docs. > [2] For those who don't know this one, writers in > the earlier part of > the twentieth century would sometimes throw their > completed manuscript > into the open transom over a locked door, hoping > that when a > publisher/editor (literally) stumbled over it the > next morning, it might > be a step closer to being published. The difference > between a > publishing house that will print anything that comes > in "over the > transom" and one that only prints work properly > submitted and approved > is what I am alluding to in this metaphor. > > -- very interesting but you should probably choose metaphors that make sense without a lengthy explanation. :-) regards Rahul Sundaram _______________________________ Do you Yahoo!? Win 1 of 4,000 free domain names from Yahoo! Enter now. http://promotions.yahoo.com/goldrush From davep at dpawson.co.uk Tue Sep 7 17:14:59 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 07 Sep 2004 18:14:59 +0100 Subject: Emacs error In-Reply-To: <1094514436.24040.59317.camel@erato.phig.org> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> <1094487345.2518.30.camel@homer> <413CBCD2.7060708@redhat.com> <1094514436.24040.59317.camel@erato.phig.org> Message-ID: <1094576287.2519.28.camel@homer> On Tue, 2004-09-07 at 00:47, Karsten Wade wrote: > > * Until we learn otherwise, we need to practice a given set of rules > (outlined in the Doc Guide) to keep editing and translating feasible. > These rules include whitespace (and indenting) practices. I'm asking you to question why its important, outside the requirements of specific docbook elements (those which respect ws in presentation). > > * Those who are interested should a) research XML diff tools, and b) > bring this up with the translation team (fedora-i18n-list) to find out > what they want to and are able to do. I just joined that list, and am > prepared to discuss toolchains. > > So, while I'm all for Local Variables and letting people indent and use > whitespace as they wish, until we *know* that our documents can be > internationalized with available tools, we must stick with what works, > regardless of our personal preferences. How will indentation impact i18N (even in the tiniest way) Karsten? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From tfox at redhat.com Tue Sep 7 18:51:04 2004 From: tfox at redhat.com (Tammy Fox) Date: Tue, 07 Sep 2004 14:51:04 -0400 Subject: final decision (?!?) on et al (was Re: screenshot instructions) In-Reply-To: <1094234667.24040.26985.camel@erato.phig.org> References: <1093970810.27934.774.camel@localhost.localdomain> <200409010909.15295.dasho@ma-isp.com> <1094036325.24040.4485.camel@erato.phig.org> <1094057369.2541.8.camel@homer> <1094077784.24040.8801.camel@erato.phig.org> <1094146540.2520.22.camel@homer> <1094156688.24040.18000.camel@erato.phig.org> <1094226928.4225.0.camel@jadefox.rdu.redhat.com> <1094234667.24040.26985.camel@erato.phig.org> Message-ID: <1094583063.4232.78.camel@jadefox.rdu.redhat.com> On Fri, 2004-09-03 at 14:04, Karsten Wade wrote: > On Fri, 2004-09-03 at 08:55, Tammy Fox wrote: > > On Thu, 2004-09-02 at 16:24, Karsten Wade wrote: > > > > That keeps extra whitespace from creeping in. The example in our > > > Documentation Guide[1] has newlines that create whitespace. Was that > > > done to make the gray box look better? I don't think it's necessary, > > > tight boxes look fine. If the box needs expanding, best to solve it in > > > the stylesheet. > > > No. It was intended to make the code easier to read. But, if it is > > adding whitespace, we should obviously omit it. > > It's not as obvious when the gray box is surrounding the text. The > stylesheet in the fedora-docs/ module don't use the gray box, so the > extra whitespace is much more obvious. > A bug was filed pointing out this inconsistency, so I added to the CSS used in the CVS as well. cvs up and let me know if you don't see the gray box after that. Tammy > - 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 Sep 7 18:56:31 2004 From: tfox at redhat.com (Tammy Fox) Date: Tue, 07 Sep 2004 14:56:31 -0400 Subject: Hardening Doc Preview In-Reply-To: <1094497387.24040.57315.camel@erato.phig.org> References: <1094303066.16202.9.camel@bach> <1094304475.16202.14.camel@bach> <1094497387.24040.57315.camel@erato.phig.org> Message-ID: <1094583390.4232.80.camel@jadefox.rdu.redhat.com> On Mon, 2004-09-06 at 15:03, Karsten Wade wrote: > On Sat, 2004-09-04 at 06:27, tuxxer wrote: > > > On that note, is there a way to insert a "default disclaimer" stating > > that it's a draft? I've tried creating an called > > 'DRAFTNOTICE', but `make html` fails everytime I add it. > > > > Included below it the text for the DRAFTNOTICE... > > Hey, that's a nice idea. I like that. Inclusion of a draft notice like > this is a good must-have, and Mark's watermark is a good nice-have. I > am definitely going to use the watermark for whenever I am concerned > that a reader will think looks_nice == completed_document. :) > > > > DRAFTNOTICE TEXT: > > > > > > > > > > Draft Notice: > > This version of this document is not yet affiliated with the > > Fedora Docs > > Project. It is a draft, and may be submitted to the project for > > review/approval at a later date. Until that time, that document will > > be > > receiving constant updates, and may change frequently. > > > > > > +1 on the text and format. > > Not sure what the trouble is; your idea should work. You can call in > any arbitrary bit of legal XML that is kept in a separate file. > > * Put the block into a separate file draftnotice.xml and put it > in fedora-docs/common (where we can all use it, thank you) > > * Put an entity in common/fedora-entities-en.xml. Note that the format > is different when you are calling in a file: > > > > * In your XML, you will have to put in the &DRAFTNOTICE; where it is > legal XML, i.e., inside of a
. > > If you do that, and it works, please do the following to get your idea > into regular usage: > > 1. 'cd fedora-docs/common' > 2. 'cvs diff -du fedora-entities-en.xml | tee > /tmp/fedora-entities-en-tuxxer.patch' (or some such name) > 3. If that doesn't work (probably because of a cvs environment > variable), try the following: > 3.1. Before you edit the file, 'cp fedora-entities-en.xml > fedora-entities-en.xml.original' > 3.2. Edit the file, then do 'diff -u fedora-entities-en.xml.original > fedora-entities-en.xml | tee /tmp/fedora-entities-en-tuxxer.patch' > 4. File a bug against fedora-docs, set the severity to Enhancement (this > is a Request For Enhancement aka RFE); put the details into the bug > report, make an attachment of the new XML file (draftnotice.xml) and the > patch. > > Hmmm ... maybe I should snarf the above description and submit it as a > patch to the Documentation Guide for "How to submit your idea for a > change to Fedora Docs Project." > > ;-) > Great idea. > - 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 Sep 7 20:11:54 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 07 Sep 2004 13:11:54 -0700 Subject: Emacs error In-Reply-To: <1094576287.2519.28.camel@homer> References: <1094340887.16202.61.camel@bach> <1094380663.2545.73.camel@homer> <1094485975.24040.55919.camel@erato.phig.org> <1094487345.2518.30.camel@homer> <413CBCD2.7060708@redhat.com> <1094514436.24040.59317.camel@erato.phig.org> <1094576287.2519.28.camel@homer> Message-ID: <1094587914.3014.2221.camel@erato.phig.org> On Tue, 2004-09-07 at 10:14, Dave Pawson wrote: > How will indentation impact i18N (even in the tiniest way) Karsten? As has been mentioned previously, the legacy translation toolchain uses line based diffs. A translator uses the diff to determine what has changed since the last translation, reducing workload greatly. We don't know what will break down the path from our changing existing practices. Wouldn't the responsible thing be to find out *first* before changing them? Anyone interested in perusing the f-i18n-list archives, please post your research with links. Otherwise, we'll just have to ask what their plans are. - 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 s.ellis at fastmail.co.uk Tue Sep 7 21:08:56 2004 From: s.ellis at fastmail.co.uk (Stuart Ellis) Date: Tue, 07 Sep 2004 22:08:56 +0100 Subject: installation guide Message-ID: <1094591336.4518.72.camel@hampton.eln.lan> I've started to write a draft of the "Starting the Installation Program" to see how it goes, and hit the first point requiring a screenshot. How should "needs screenshot" be marked ? Should I put in a screenshot (which can be discarded later), or just put a placeholder ? From paul at frields.com Tue Sep 7 23:45:40 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 07 Sep 2004 19:45:40 -0400 Subject: installation guide In-Reply-To: <1094591336.4518.72.camel@hampton.eln.lan> References: <1094591336.4518.72.camel@hampton.eln.lan> Message-ID: <1094600740.11653.8.camel@bettie.internal.frields.org> On Tue, 2004-09-07 at 17:08, Stuart Ellis wrote: > I've started to write a draft of the "Starting the Installation Program" > to see how it goes, and hit the first point requiring a screenshot. > > How should "needs screenshot" be marked ? Should I put in a screenshot > (which can be discarded later), or just put a placeholder ? I would put in a comment that looks something like this: Sorry about the funky indentation there, but hopefully you get my meaning. Remember that there is a difference between a "screen" and a "dialog." Make sure the FIXME comment is exacting enough so someone can contribute a screenshot without any guesswork about what you meant. I think most people, whether working on code or documents, would agree that having a string like "FIXME" in a problem area allows anyone to quickly find it again. Load into editor, search for "FIXME," and now you have an easy checklist! :-) -- Paul W. Frields, RHCE From davep at dpawson.co.uk Wed Sep 8 10:14:00 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 08 Sep 2004 11:14:00 +0100 Subject: installation guide In-Reply-To: <1094600740.11653.8.camel@bettie.internal.frields.org> References: <1094591336.4518.72.camel@hampton.eln.lan> <1094600740.11653.8.camel@bettie.internal.frields.org> Message-ID: <1094638440.2535.7.camel@homer> On Wed, 2004-09-08 at 00:45, Paul W. Frields wrote: > On Tue, 2004-09-07 at 17:08, Stuart Ellis wrote: > > I've started to write a draft of the "Starting the Installation Program" > > to see how it goes, and hit the first point requiring a screenshot. > > > > How should "needs screenshot" be marked ? Should I put in a screenshot > > (which can be discarded later), or just put a placeholder ? Why not put in a screenshot markup, whatever you are going to use, then find a suitable image. Then as you obtain the correct images, simply change the default for the right one? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Wed Sep 8 13:46:37 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 08 Sep 2004 09:46:37 -0400 Subject: installation guide In-Reply-To: <1094638440.2535.7.camel@homer> References: <1094591336.4518.72.camel@hampton.eln.lan> <1094600740.11653.8.camel@bettie.internal.frields.org> <1094638440.2535.7.camel@homer> Message-ID: <1094651196.19003.1.camel@bettie.internal.frields.org> On Wed, 2004-09-08 at 06:14, Dave Pawson wrote: > On Wed, 2004-09-08 at 00:45, Paul W. Frields wrote: > > On Tue, 2004-09-07 at 17:08, Stuart Ellis wrote: > > > I've started to write a draft of the "Starting the Installation Program" > > > to see how it goes, and hit the first point requiring a screenshot. > > > > > > How should "needs screenshot" be marked ? Should I put in a screenshot > > > (which can be discarded later), or just put a placeholder ? > > Why not put in a screenshot markup, whatever you are going to use, > then find a suitable image. > > Then as you obtain the correct images, simply change the > default for the right one? True, you could just use The GIMP to make a 500x375 light gray rectangle, and put a big "SCREENSHOT OF..." message in it. On the other hand, that needlessly bloats the tarball, although I suspect if you kept to a solid color rectangle and a solid color text, the graphic should compress to a pretty minimal size. -- Paul W. Frields, RHCE From mjohnson at redhat.com Wed Sep 8 14:04:35 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Wed, 08 Sep 2004 10:04:35 -0400 Subject: installation guide In-Reply-To: <1094600740.11653.8.camel@bettie.internal.frields.org> References: <1094591336.4518.72.camel@hampton.eln.lan> <1094600740.11653.8.camel@bettie.internal.frields.org> Message-ID: <413F1173.7050204@redhat.com> Paul W. Frields wrote: > On Tue, 2004-09-07 at 17:08, Stuart Ellis wrote: > >>I've started to write a draft of the "Starting the Installation Program" >>to see how it goes, and hit the first point requiring a screenshot. >> >>How should "needs screenshot" be marked ? Should I put in a screenshot >>(which can be discarded later), or just put a placeholder ? > > > I would put in a comment that looks something like this: > > When I've got a section that needs fixing, I use a FIXME: screenshot needed, showing anaconda screen for choosing mouse. construct (although the role isn't really needed). Then I add the following snippet to the CSS stylesheet (we're talking about HTML output, right?) .remark { color: #0000FF; font-weight: bold; } which generates a bold, blue statement, as e.g., can be seen here: http://debian-xml-sgml.alioth.debian.org/xml-policy/xml-caching-resources.html And I believe s need to be wrapped in a s. Semantically, remark is recommended specifically for (you guessed it) remarks in draft documents, so at least there's some consistency. As it says in DocBook: The Defintive Guide: remark ? A remark (or comment) intended for presentation in a draft manuscript I have similar stylesheet snippets for DSSSL print output, but not for XSL print output (yet:). Of course, you can choose any color you wish. Yet another option for FIXMEs... HTH. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 pnasrat at redhat.com Wed Sep 8 15:09:25 2004 From: pnasrat at redhat.com (Paul Nasrat) Date: Wed, 8 Sep 2004 11:09:25 -0400 Subject: installation guide In-Reply-To: <1094591336.4518.72.camel@hampton.eln.lan> References: <1094591336.4518.72.camel@hampton.eln.lan> Message-ID: <20040908150923.GD19333@devserv.devel.redhat.com> On Tue, Sep 07, 2004 at 10:08:56PM +0100, Stuart Ellis wrote: > I've started to write a draft of the "Starting the Installation Program" > to see how it goes, and hit the first point requiring a screenshot. > > How should "needs screenshot" be marked ? Should I put in a screenshot > (which can be discarded later), or just put a placeholder ? ks.cfg with autostep --autoscreenshot will help you out here IIRC Paul From tfox at redhat.com Wed Sep 8 20:20:16 2004 From: tfox at redhat.com (Tammy Fox) Date: Wed, 08 Sep 2004 16:20:16 -0400 Subject: Docbook quick reference card In-Reply-To: <1094397859.22071.94.camel@bettie.internal.frields.org> References: <1094382209.2545.75.camel@homer> <1094397859.22071.94.camel@bettie.internal.frields.org> Message-ID: <1094674816.6176.91.camel@jadefox.rdu.redhat.com> On Sun, 2004-09-05 at 11:24, Paul W. Frields wrote: > On Sun, 2004-09-05 at 07:03, Dave Pawson wrote: > > http://sources.redhat.com/ml/docbook-apps/2003-q2/msg00834.html > > > > Quick summary of the major docbook elements. > > May be of help? > > I tried the link, but twistedcranium.com doesn't resolve via DNS, so I > couldn't get to the PDF. Anyone else have any luck? > > -- > Paul W. Frields, RHCE > Nope. I can't get to it either. If someone knows the correct link, I'd be glad to add it to the Docs Guide as another reference. Tammy From s.ellis at fastmail.co.uk Wed Sep 8 20:28:36 2004 From: s.ellis at fastmail.co.uk (Stuart Ellis) Date: Wed, 08 Sep 2004 21:28:36 +0100 Subject: installation guide Message-ID: <1094675316.4516.57.camel@hampton.eln.lan> Thanks to all for the tips. The wording of my original question was probably too vague. I could either put in FIXMEs (this is what I actually meant by placeholders) for the designated screenshotter, or try to do the screenshots as I go. It would definitely be best if one person does all of the screenshots, especially since what I know about the Gimp at the moment probably wouldn't fill the 500x375 rectangle, but I'm not sure if we have a screenshotter to do the work. I've seen custom FIXME tags cause odd-looking results in the output from a Docbook, so it's useful to know that FIXMEs should be written with . From jwheelock at ucsd.edu Wed Sep 8 23:17:55 2004 From: jwheelock at ucsd.edu (John Wheelock) Date: Wed, 8 Sep 2004 16:17:55 -0700 Subject: does mkbootdisk work in Fedora Core 2? Message-ID: I have created a bootdisk for Kernel 2.6.8-1.521, but am unable to use it. After rebooting I get the error message "Could not find kernel image: linux" boot: (flashing curser) I'm sure I have successfully rebooted from a floppy in earlier versions. Any ideas? JOHN WHEELOCK MCSE CCNA CCA University of California at San Diego Computer Resource Specialist II 619-543-8080, ext. 238 jwheelock at ucsd.edu "Give a man a fish he eats for a day. Teach a man to fish he eats forever." -------------- next part -------------- An HTML attachment was scrubbed... URL: From kwade at redhat.com Thu Sep 9 04:19:33 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 08 Sep 2004 21:19:33 -0700 Subject: installation guide In-Reply-To: <1094675316.4516.57.camel@hampton.eln.lan> References: <1094675316.4516.57.camel@hampton.eln.lan> Message-ID: <1094703572.3014.10688.camel@erato.phig.org> On Wed, 2004-09-08 at 13:28, Stuart Ellis wrote: > Thanks to all for the tips. > > The wording of my original question was probably too vague. I could > either put in FIXMEs (this is what I actually meant by placeholders) for > the designated screenshotter, or try to do the screenshots as I go. Probably a good idea to assume that one person will do all the screenshots in one pass. These should be done with a later test version of FC3 (test2 or test3). To fill the space, perhaps a verbal description of the screen, noting anything that is different from how it appears by default, i.e., what you would want changed for a screenshot. One nice idea about setting a standard is the person who does the screenshots can grep all the XML for "FIXME" or "SCREENSHOT". I'd suggest putting in blank blocks along with a , but I'm not sure you can do that without breaking the build. > It would definitely be best if one person does all of the screenshots, > especially since what I know about the Gimp at the moment probably > wouldn't fill the 500x375 rectangle, but I'm not sure if we have a > screenshotter to do the work. Not yet, but we will. That job will need to be done either at the end of Sep. or the first week of October. - Karsten > I've seen custom FIXME tags cause odd-looking results in the output from > a Docbook, so it's useful to know that FIXMEs should be written with > . > -- 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 pengunix at yahoo.com Thu Sep 9 07:21:11 2004 From: pengunix at yahoo.com (Necati Keles) Date: Thu, 9 Sep 2004 00:21:11 -0700 (PDT) Subject: does mkbootdisk work in Fedora Core 2? In-Reply-To: Message-ID: <20040909072111.61486.qmail@web60605.mail.yahoo.com> Try to boot via first installation CD or boot CD. when the boot prompt appears, type "linux rescue" . --- John Wheelock wrote: > I have created a bootdisk for Kernel 2.6.8-1.521, > but am unable to use > it. > > > > After rebooting I get the error message > > > > "Could not find kernel image: linux" > > boot: (flashing curser) > > > > I'm sure I have successfully rebooted from a floppy > in earlier versions. > Any ideas? > > > > JOHN WHEELOCK > > MCSE CCNA CCA > > University of California at San Diego > > Computer Resource Specialist II > > 619-543-8080, ext. 238 > > jwheelock at ucsd.edu > > > > "Give a man a fish he eats for a day. Teach a man > to fish he eats > forever." > > > > > -- > fedora-docs-list mailing list > fedora-docs-list at redhat.com > To unsubscribe: > http://www.redhat.com/mailman/listinfo/fedora-docs-list > __________________________________ Do you Yahoo!? New and Improved Yahoo! Mail - 100MB free storage! http://promotions.yahoo.com/new_mail From s.ellis at fastmail.co.uk Thu Sep 9 12:48:35 2004 From: s.ellis at fastmail.co.uk (Stuart Ellis) Date: Thu, 09 Sep 2004 13:48:35 +0100 Subject: Installation Guide Message-ID: <1094734115.6711.204015049@webmail.messagingengine.com> On Wed, 08 Sep 2004 21:19:33 -0700, "Karsten Wade" said: > Probably a good idea to assume that one person will do all the > screenshots in one pass. These should be done with a later test version > of FC3 (test2 or test3). > > To fill the space, perhaps a verbal description of the screen, noting > anything that is different from how it appears by default, i.e., what > you would want changed for a screenshot. > > One nice idea about setting a standard is the person who does the > screenshots can grep all the XML for "FIXME" or "SCREENSHOT". > > I'd suggest putting in blank blocks along with a > , but I'm not sure you can do that without breaking the build. > I think that I'll probably use this format: SCREENSHOT - (name of screen and window), (description of requirement) LINK - (name of unwritten section) TECHQUERY - (description of technical detail that needs to checked) > > It would definitely be best if one person does all of the screenshots, > > especially since what I know about the Gimp at the moment probably > > wouldn't fill the 500x375 rectangle, but I'm not sure if we have a > > screenshotter to do the work. > > Not yet, but we will. That job will need to be done either at the end > of Sep. or the first week of October. OK. I'll press on with the text. -- Stuart Ellis s.ellis at fastmail.co.uk From mjohnson at redhat.com Thu Sep 9 17:28:32 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Thu, 09 Sep 2004 13:28:32 -0400 Subject: new DocBook packages... Message-ID: <414092C0.1060403@redhat.com> Hi All, I've built a Simplified DocBook package (aka docbook-simple) and a DocBook Slides package (docbook-slides). They're available here: http://people.redhat.com/mjohnson/packages/RPMS/ I'm wondering if the docbook-simple package might be useful as part of the standard fedora-docs toolkit?? Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 binhpublicmail at yahoo.com.au Fri Sep 10 00:27:22 2004 From: binhpublicmail at yahoo.com.au (=?iso-8859-1?q?Binh=20Nguyen?=) Date: Fri, 10 Sep 2004 10:27:22 +1000 (EST) Subject: Linux Dictionary Contribution Message-ID: <20040910002722.70227.qmail@web52408.mail.yahoo.com> Dear all, My name is Binh Nguyen. I would like to contribute the 'Linux Dictionary', (http://www.tldp.org/LDP/Linux-Dictionary/html/index.html) to the Fedora Documentation project. I'm also willing to contribute the 'Linux Dictionary' to the Fedora Documentation Wiki provided that you maintain the original front cover and provide a hyperlink to it. ie. Everything from, http://www.tldp.org/LDP/Linux-Dictionary/html/index.html Regards, Binh Nguyen. Find local movie times and trailers on Yahoo! Movies. http://au.movies.yahoo.com From kwade at redhat.com Sat Sep 11 07:04:53 2004 From: kwade at redhat.com (Karsten Wade) Date: Sat, 11 Sep 2004 00:04:53 -0700 Subject: Linux Dictionary Contribution In-Reply-To: <20040910002722.70227.qmail@web52408.mail.yahoo.com> References: <20040910002722.70227.qmail@web52408.mail.yahoo.com> Message-ID: <1094886293.3014.24847.camel@erato.phig.org> On Thu, 2004-09-09 at 17:27, Binh Nguyen wrote: > Dear all, > > My name is Binh Nguyen. I would like to contribute the > 'Linux Dictionary', > (http://www.tldp.org/LDP/Linux-Dictionary/html/index.html) > to the Fedora Documentation project. This is an amazing undertaking. Thank you very much for your contribution. Looking on the TLDP site, I couldn't find the XML source. I was going to look at it to help in estimating what it will take you to modify the guide to fit the Fedora docs project (FDP) requirements. Have you filled out a feature enhancement report (via bugzilla.redhat.com)? An overview of the submission process is at: http://fedora.redhat.com/participate/documentation-quick-start/ You should be able to continue to have a single-source XML for the Linux Dictionary, with a Makefile that uses the FDP toolchain. > I'm also willing to contribute the 'Linux Dictionary' > to the Fedora Documentation Wiki > provided that you maintain the original front > cover and provide a hyperlink to it. ie. Everything > from, > http://www.tldp.org/LDP/Linux-Dictionary/html/index.html FDP doesn't maintain a Wiki, as far as I know. As a side note, I see a dict database available as well. Have you contacted dict.org to see if they'd like to include the Linux Dictionary in their downloads? AIUI, Rik is always looking for good free dictionaries. - 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 binhpublicmail at yahoo.com.au Sat Sep 11 10:01:01 2004 From: binhpublicmail at yahoo.com.au (=?iso-8859-1?q?Binh=20Nguyen?=) Date: Sat, 11 Sep 2004 20:01:01 +1000 (EST) Subject: Linux Dictionary Contribution In-Reply-To: <1094886293.3014.24847.camel@erato.phig.org> Message-ID: <20040911100101.56902.qmail@web52405.mail.yahoo.com> > > My name is Binh Nguyen. I would like to contribute > the > > 'Linux Dictionary', > > > (http://www.tldp.org/LDP/Linux-Dictionary/html/index.html) > > to the Fedora Documentation project. > > This is an amazing undertaking. Thank you very much > for your > contribution. > > Looking on the TLDP site, I couldn't find the XML > source. I was going > to look at it to help in estimating what it will > take you to modify the > guide to fit the Fedora docs project (FDP) > requirements. http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/Linux-Dictionary/ Heehee.... The XML is automatically generated using bash scripts :) Altering it to suit the FDP shouldn't be too difficult. I've created deb, rpm, slack, tarball and lsb packages a few days ago. I've only tested the deb package. That seems to work ok. Not too sure about the rest though since they were also auto-generated via 'alien'. > Have you filled out a feature enhancement report > (via > bugzilla.redhat.com)? An overview of the submission > process is at: > > http://fedora.redhat.com/participate/documentation-quick-start/ I'll read up on this. Thankyou. > You should be able to continue to have a > single-source XML for the Linux > Dictionary, with a Makefile that uses the FDP > toolchain. Brill.... > As a side note, I see a dict database available as > well. Have you > contacted dict.org to see if they'd like to include > the Linux Dictionary > in their downloads? AIUI, Rik is always looking for > good free > dictionaries. > > - Karsten Binh. Find local movie times and trailers on Yahoo! Movies. http://au.movies.yahoo.com From rahulsundaram at yahoo.co.in Sat Sep 11 10:54:43 2004 From: rahulsundaram at yahoo.co.in (Rahul Sundaram) Date: Sat, 11 Sep 2004 03:54:43 -0700 (PDT) Subject: Linux Dictionary Contribution In-Reply-To: <1094886293.3014.24847.camel@erato.phig.org> Message-ID: <20040911105443.90680.qmail@web8503.mail.in.yahoo.com> --- Karsten Wade wrote: > On Thu, 2004-09-09 at 17:27, Binh Nguyen wrote: > > Dear all, > > > > My name is Binh Nguyen. I would like to contribute > the > > 'Linux Dictionary', > > > (http://www.tldp.org/LDP/Linux-Dictionary/html/index.html) > > to the Fedora Documentation project. > Hi I am curious at to why you would want a particular document replicated in FDP as well as LDP. Can you kindly explain the reasoning behind this regards Rahul Sundaram _______________________________ Do you Yahoo!? Shop for Back-to-School deals on Yahoo! Shopping. http://shopping.yahoo.com/backtoschool From binhpublicmail at yahoo.com.au Sat Sep 11 13:02:50 2004 From: binhpublicmail at yahoo.com.au (=?iso-8859-1?q?Binh=20Nguyen?=) Date: Sat, 11 Sep 2004 23:02:50 +1000 (EST) Subject: Linux Dictionary Contribution In-Reply-To: <20040911105443.90680.qmail@web8503.mail.in.yahoo.com> Message-ID: <20040911130250.91523.qmail@web52410.mail.yahoo.com> --- Rahul Sundaram wrote: > > --- Karsten Wade wrote: > > > On Thu, 2004-09-09 at 17:27, Binh Nguyen wrote: > > > Dear all, > > > > > > My name is Binh Nguyen. I would like to > contribute > > the > > > 'Linux Dictionary', > > > > > > (http://www.tldp.org/LDP/Linux-Dictionary/html/index.html) > > > to the Fedora Documentation project. > > > > > Hi > > I am curious at to why you would want a particular > document replicated in FDP as well as LDP. Can you > kindly explain the reasoning behind this > > regards > Rahul Sundaram Main reason is because I'd prefer not to see work duplicated and I've seen what their 'Jargon Buster' and Wiki is like. I'd just like to give it a bit of a kickstart. Also, I'm seriously thinking about letting go of the 'Linux Dictionary' since its become *way* too big for me to handle. I need help!!!! Binh. Find local movie times and trailers on Yahoo! Movies. http://au.movies.yahoo.com From paul at frields.com Sat Sep 11 13:12:04 2004 From: paul at frields.com (Paul W. Frields) Date: Sat, 11 Sep 2004 09:12:04 -0400 Subject: Linux Dictionary Contribution In-Reply-To: <20040911130250.91523.qmail@web52410.mail.yahoo.com> References: <20040911130250.91523.qmail@web52410.mail.yahoo.com> Message-ID: <1094908324.13976.3.camel@bettie.internal.frields.org> > > > > My name is Binh Nguyen. I would like to > > contribute > > > the > > > > 'Linux Dictionary', > (http://www.tldp.org/LDP/Linux-Dictionary/html/index.html) > > > > to the Fedora Documentation project. > > > > > I am curious at to why you would want a particular > > document replicated in FDP as well as LDP. Can you > > kindly explain the reasoning behind this > Main reason is because I'd prefer not to see work > duplicated and I've seen what their 'Jargon Buster' > and > Wiki is like. I'd just like to give it a bit of a > kickstart. Also, I'm seriously thinking about letting > go of the 'Linux Dictionary' since its become *way* > too big for me to handle. I need help!!!! I think it's a great document, and shows a lot of work you've put into it. I'm sure if there's anything non-repetitive in the Jargon Buster, we could merge them. Please keep in mind, though, that the GNU FDL doesn't allow you to place additional restrictions over and above the license itself on your work. But the license also requires that your name stay attached as the primary author, so you don't need to have any fear that you'll lose credit for the amazing amount of effort you've put into it! Thanks for your generosity; I'm sure everyone appreciates it! We'll look forward to adapting it for the FDP. Make sure you get that Bugzilla entry in, as Karsten said, at the earliest opportunity. -- Paul W. Frields, RHCE From tuxxer at cox.net Sun Sep 12 16:36:58 2004 From: tuxxer at cox.net (tuxxer) Date: Sun, 12 Sep 2004 16:36:58 +0000 Subject: Hardening Doc Preview In-Reply-To: <1094497387.24040.57315.camel@erato.phig.org> References: <1094303066.16202.9.camel@bach> <1094304475.16202.14.camel@bach> <1094497387.24040.57315.camel@erato.phig.org> Message-ID: <1095007018.16202.129.camel@bach> On Mon, 2004-09-06 at 19:03, Karsten Wade wrote: > On Sat, 2004-09-04 at 06:27, tuxxer wrote: > > > On that note, is there a way to insert a "default disclaimer" stating > > that it's a draft? I've tried creating an called > > 'DRAFTNOTICE', but `make html` fails everytime I add it. > > > > Included below it the text for the DRAFTNOTICE... > > Hey, that's a nice idea. I like that. Inclusion of a draft notice like > this is a good must-have, and Mark's watermark is a good nice-have. I > am definitely going to use the watermark for whenever I am concerned > that a reader will think looks_nice == completed_document. :) > > > > DRAFTNOTICE TEXT: > > > > > > > > > > Draft Notice: > > This version of this document is not yet affiliated with the > > Fedora Docs > > Project. It is a draft, and may be submitted to the project for > > review/approval at a later date. Until that time, that document will > > be > > receiving constant updates, and may change frequently. > > > > > > +1 on the text and format. > > Not sure what the trouble is; your idea should work. You can call in > any arbitrary bit of legal XML that is kept in a separate file. > > * Put the block into a separate file draftnotice.xml and put it > in fedora-docs/common (where we can all use it, thank you) > > * Put an entity in common/fedora-entities-en.xml. Note that the format > is different when you are calling in a file: > > > > * In your XML, you will have to put in the &DRAFTNOTICE; where it is > legal XML, i.e., inside of a
. > OK, I did all of the above. This is what I get when I 'make html': make html xmlto: input does not validate (status 1) /home/charlie/fedora-docs/fedora-docs/hardening/harden-intro-en.xml:6: parser error : Entity 'DRAFTNOTICE' not defined &DRAFTNOTICE; ^ /home/charlie/fedora-docs/fedora-docs/hardening/harden-intro-en.xml:18: parser error : chunk is not well balanced ^ /home/charlie/fedora-docs/fedora-docs/hardening/fedora-hardening-guide-en.xml:38: parser error : chunk is not well balanced &INTRODUCTION; ^ make: *** [html] Error 1 > If you do that, and it works, please do the following to get your idea > into regular usage: > > 1. 'cd fedora-docs/common' > 2. 'cvs diff -du fedora-entities-en.xml | tee > /tmp/fedora-entities-en-tuxxer.patch' (or some such name) > 3. If that doesn't work (probably because of a cvs environment > variable), try the following: > 3.1. Before you edit the file, 'cp fedora-entities-en.xml > fedora-entities-en.xml.original' > 3.2. Edit the file, then do 'diff -u fedora-entities-en.xml.original > fedora-entities-en.xml | tee /tmp/fedora-entities-en-tuxxer.patch' > 4. File a bug against fedora-docs, set the severity to Enhancement (this > is a Request For Enhancement aka RFE); put the details into the bug > report, make an attachment of the new XML file (draftnotice.xml) and the > patch. > > Hmmm ... maybe I should snarf the above description and submit it as a > patch to the Documentation Guide for "How to submit your idea for a > change to Fedora Docs Project." > > ;-) > > - Karsten Do I need to "reload" the doc somehow to get it to recognize the &DRAFTNOTICE; entity? -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 tuxxer at cox.net Sun Sep 12 17:00:27 2004 From: tuxxer at cox.net (tuxxer) Date: Sun, 12 Sep 2004 17:00:27 +0000 Subject: Hardening Doc Preview In-Reply-To: <1095007018.16202.129.camel@bach> References: <1094303066.16202.9.camel@bach> <1094304475.16202.14.camel@bach> <1094497387.24040.57315.camel@erato.phig.org> <1095007018.16202.129.camel@bach> Message-ID: <1095008426.16202.132.camel@bach> On Sun, 2004-09-12 at 16:36, tuxxer wrote: << ... SNIP ... >> > > > > OK, I did all of the above. This is what I get when I 'make html': > > make html > xmlto: input does not validate (status 1) > /home/charlie/fedora-docs/fedora-docs/hardening/harden-intro-en.xml:6: > parser error : Entity 'DRAFTNOTICE' not defined > &DRAFTNOTICE; > ^ > /home/charlie/fedora-docs/fedora-docs/hardening/harden-intro-en.xml:18: > parser error : chunk is not well balanced > > ^ > /home/charlie/fedora-docs/fedora-docs/hardening/fedora-hardening-guide-en.xml:38: parser error : chunk is not well balanced > &INTRODUCTION; > ^ > make: *** [html] Error 1 > Nevermind. It turned out to be a typo. Proceedig boldy... ;) << ... SNIP ... >> > > Do I need to "reload" the doc somehow to get it to recognize the > &DRAFTNOTICE; entity? -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 tuxxer at cox.net Sun Sep 12 18:21:00 2004 From: tuxxer at cox.net (tuxxer) Date: Sun, 12 Sep 2004 18:21:00 +0000 Subject: Hardening Doc Preview In-Reply-To: <1094497387.24040.57315.camel@erato.phig.org> References: <1094303066.16202.9.camel@bach> <1094304475.16202.14.camel@bach> <1094497387.24040.57315.camel@erato.phig.org> Message-ID: <1095013260.16202.137.camel@bach> On Mon, 2004-09-06 at 19:03, Karsten Wade wrote: > +1 on the text and format. > > Not sure what the trouble is; your idea should work. You can call in > any arbitrary bit of legal XML that is kept in a separate file. > > * Put the block into a separate file draftnotice.xml and put it > in fedora-docs/common (where we can all use it, thank you) > > * Put an entity in common/fedora-entities-en.xml. Note that the format > is different when you are calling in a file: > > > > * In your XML, you will have to put in the &DRAFTNOTICE; where it is > legal XML, i.e., inside of a
. > > If you do that, and it works, please do the following to get your idea > into regular usage: > > 1. 'cd fedora-docs/common' > 2. 'cvs diff -du fedora-entities-en.xml | tee > /tmp/fedora-entities-en-tuxxer.patch' (or some such name) > 3. If that doesn't work (probably because of a cvs environment > variable), try the following: > 3.1. Before you edit the file, 'cp fedora-entities-en.xml > fedora-entities-en.xml.original' > 3.2. Edit the file, then do 'diff -u fedora-entities-en.xml.original > fedora-entities-en.xml | tee /tmp/fedora-entities-en-tuxxer.patch' > 4. File a bug against fedora-docs, set the severity to Enhancement (this > is a Request For Enhancement aka RFE); put the details into the bug > report, make an attachment of the new XML file (draftnotice.xml) and the > patch. > > Hmmm ... maybe I should snarf the above description and submit it as a > patch to the Documentation Guide for "How to submit your idea for a > change to Fedora Docs Project." > > ;-) > > - Karsten Created bug #132415 with mentioned attachments (patch and draftnotice.xml). Preview is available at http://members.cox.net/tuxxer/index.html. Set it to block bug #129784 (hope that's the right procedure). Enjoy! -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 Mon Sep 13 02:32:49 2004 From: tfox at redhat.com (Tammy Fox) Date: Sun, 12 Sep 2004 22:32:49 -0400 Subject: website and CVS changes Message-ID: <1095042768.11357.319.camel@localhost.localdomain> I have closed the following bugs to add patches to CVS and to add content to the website: 130051: &DOCG; entity added to fedora-entities-en.xml 131131: Keeping Up to Date tutorial posted to http://fedora.redhat.com/docs/updates/ 131647 and 131775: Updates to Docs Guide Regards, Tammy From davep at dpawson.co.uk Mon Sep 13 16:22:39 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 13 Sep 2004 17:22:39 +0100 Subject: website and CVS changes In-Reply-To: <1095042768.11357.319.camel@localhost.localdomain> References: <1095042768.11357.319.camel@localhost.localdomain> Message-ID: <1095092558.2700.10.camel@homer> On Mon, 2004-09-13 at 03:32, Tammy Fox wrote: > I have closed the following bugs to add patches to CVS and to add > content to the website: > > 130051: &DOCG; entity added to fedora-entities-en.xml How to retrieve it please Tammy? (and could such a note be added to the Fedora docs documentation somewhere, since its needed if an author wants to preview?) -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Mon Sep 13 16:23:37 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 13 Sep 2004 12:23:37 -0400 Subject: website and CVS changes In-Reply-To: <1095092558.2700.10.camel@homer> References: <1095042768.11357.319.camel@localhost.localdomain> <1095092558.2700.10.camel@homer> Message-ID: <1095092617.19314.4.camel@berlin.east.gov> On Mon, 2004-09-13 at 12:22, Dave Pawson wrote: > On Mon, 2004-09-13 at 03:32, Tammy Fox wrote: > > I have closed the following bugs to add patches to CVS and to add > > content to the website: > > > > 130051: &DOCG; entity added to fedora-entities-en.xml > > How to retrieve it please Tammy? > (and could such a note be added to the Fedora docs documentation > somewhere, since its needed if an author wants to preview?) Retrieve it along with the fedora-docs CVS materials, in the manner shown on the Docs Project front page, and in the Docs Guide. In other words, do a "cvs co", or if you're CVS-savvy, "cvs up". If you type the three command lines shown on the Docs Project page verbatim, everything will work. You should be located in the parent directory of your fedora-docs/ folder when you run the commands, if you want to update your existing code base. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Mon Sep 13 17:49:38 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 13 Sep 2004 18:49:38 +0100 Subject: website and CVS changes In-Reply-To: <1095092617.19314.4.camel@berlin.east.gov> References: <1095042768.11357.319.camel@localhost.localdomain> <1095092558.2700.10.camel@homer> <1095092617.19314.4.camel@berlin.east.gov> Message-ID: <1095097778.2700.33.camel@homer> On Mon, 2004-09-13 at 17:23, Paul W. Frields wrote: > > Retrieve it along with the fedora-docs CVS materials, Done that, along with legalnotice. rxp tells me [dpawson at homer links]$ myrxp links-en.xml Error: Undefined entity BOOKID in entity "LEGALNOTICE" at line 27 char 13 of file:///home/dpawson/common/legalnotice-en.xml in unnamed entity at line 56 char 18 of file:///home/dpawson/fedora-docs/links/links-en.xml &bookid; in legalnotice is missing in fedora-entities-en.xml ? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Mon Sep 13 17:56:01 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 13 Sep 2004 13:56:01 -0400 Subject: website and CVS changes In-Reply-To: <1095097778.2700.33.camel@homer> References: <1095042768.11357.319.camel@localhost.localdomain> <1095092558.2700.10.camel@homer> <1095092617.19314.4.camel@berlin.east.gov> <1095097778.2700.33.camel@homer> Message-ID: <1095098160.19314.15.camel@berlin.east.gov> On Mon, 2004-09-13 at 13:49, Dave Pawson wrote: > On Mon, 2004-09-13 at 17:23, Paul W. Frields wrote: > > > > > Retrieve it along with the fedora-docs CVS materials, > > Done that, along with legalnotice. > > rxp tells me > [dpawson at homer links]$ myrxp links-en.xml Error: Undefined entity BOOKID > in entity "LEGALNOTICE" at line 27 char 13 of > file:///home/dpawson/common/legalnotice-en.xml > in unnamed entity at line 56 char 18 of > file:///home/dpawson/fedora-docs/links/links-en.xml > > &bookid; in legalnotice is missing in fedora-entities-en.xml ? I think BOOKID is to be defined in your top-level tutorial file, as in the example-tutorial-en.xml file. -- Paul W. Frields, RHCE From paul at frields.com Mon Sep 13 17:57:27 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 13 Sep 2004 13:57:27 -0400 Subject: website and CVS changes In-Reply-To: <1095098160.19314.15.camel@berlin.east.gov> References: <1095042768.11357.319.camel@localhost.localdomain> <1095092558.2700.10.camel@homer> <1095092617.19314.4.camel@berlin.east.gov> <1095097778.2700.33.camel@homer> <1095098160.19314.15.camel@berlin.east.gov> Message-ID: <1095098247.19314.17.camel@berlin.east.gov> On Mon, 2004-09-13 at 13:56, Paul W. Frields wrote: > I think BOOKID is to be defined in your top-level tutorial file, as in > the example-tutorial-en.xml file. I should have also mentioned BOOKID needs to come before LEGALNOTICE, since LEGALNOTICE references it. See the example. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Mon Sep 13 18:13:12 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 13 Sep 2004 19:13:12 +0100 Subject: website and CVS changes In-Reply-To: <1095098160.19314.15.camel@berlin.east.gov> References: <1095042768.11357.319.camel@localhost.localdomain> <1095092558.2700.10.camel@homer> <1095092617.19314.4.camel@berlin.east.gov> <1095097778.2700.33.camel@homer> <1095098160.19314.15.camel@berlin.east.gov> Message-ID: <1095099191.2700.45.camel@homer> On Mon, 2004-09-13 at 18:56, Paul W. Frields wrote: > I think BOOKID is to be defined in your top-level tutorial file, as in > the example-tutorial-en.xml file. OK, Pawson retires hurt. RTFM was the cruder response Paul. +2 to Frields :-) Thanks again Paul. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Wed Sep 15 10:54:11 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 15 Sep 2004 03:54:11 -0700 Subject: Installation Guide In-Reply-To: <1094734115.6711.204015049@webmail.messagingengine.com> References: <1094734115.6711.204015049@webmail.messagingengine.com> Message-ID: <1095245650.3014.60292.camel@erato.phig.org> On Thu, 2004-09-09 at 05:48, Stuart Ellis wrote: > I think that I'll probably use this format: > > SCREENSHOT - (name of screen and window), > (description of requirement) > > LINK - (name of unwritten > section) > > TECHQUERY - (description of technical detail > that needs to checked) ^ +1 I like these, they seem good and sufficient for now. - 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 Wed Sep 15 11:05:15 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 15 Sep 2004 04:05:15 -0700 Subject: version control on website Message-ID: <1095246314.3014.60338.camel@erato.phig.org> How are we going to organize different versions of documents on the website? Option 1. By FC version, then document. f.r.c/docs -> FC2 -> Tutorial 1 -> Tutorial 2 ... -> FC3 -> Tutorial 1 -> Tutorial 2 ... Option 2. By document, then FC version. f.r.c/docs -> Tutorial 1 -> FC2 -> FC3 -> Tutorial 2 -> FC2 -> FC3 ... Option 3. Other ideas? -- 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 Wed Sep 15 12:39:19 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 15 Sep 2004 08:39:19 -0400 Subject: version control on website In-Reply-To: <1095246314.3014.60338.camel@erato.phig.org> References: <1095246314.3014.60338.camel@erato.phig.org> Message-ID: <1095251959.2322.9.camel@berlin.east.gov> On Wed, 2004-09-15 at 07:05, Karsten Wade wrote: > How are we going to organize different versions of documents on the > website? > > Option 1. By FC version, then document. > > f.r.c/docs > -> FC2 > -> Tutorial 1 > -> Tutorial 2 > ... > -> FC3 > -> Tutorial 1 > -> Tutorial 2 > ... > > Option 2. By document, then FC version. > > f.r.c/docs > -> Tutorial 1 > -> FC2 > -> FC3 > -> Tutorial 2 > -> FC2 > -> FC3 > ... > > Option 3. Other ideas? I don't see why we can't have both... Two links, "Index by Core release," then organized alphabetically within each release number, and "Index by Subject," organized by release number within each tutorial. Am I missing something? Also, it might not be a bad idea for the editorial folks to, on publication of a new tutorial, make a list of one or more questions answered by the tutorial. Those questions should be organized into a kind of FAQ, or quasi-FAQ (QFAQ?), which a reader uses to follow a link to the appropriate tutorial in the "Index by Subject," e.g.: How do I configure update notifications? How do I keep my system updated? How do I update my system? What is up2date? What is yum? These are all questions that would link to the update-tutorial. This list would get pretty long, but the page should be searchable simply by using the Web browser "search" function. I don't see a need to design a complicated Web interface (search engine, indexing, etc.) for this purpose. What do you think? -- Paul W. Frields, RHCE From davep at dpawson.co.uk Wed Sep 15 15:43:42 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 15 Sep 2004 16:43:42 +0100 Subject: version control on website In-Reply-To: <1095251959.2322.9.camel@berlin.east.gov> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> Message-ID: <1095263022.2515.14.camel@homer> On Wed, 2004-09-15 at 13:39, Paul W. Frields wrote: > > Option 3. Other ideas? > > I don't see why we can't have both... Two links, "Index by Core > release," then organized alphabetically within each release number, and > "Index by Subject," organized by release number within each tutorial. Am > I missing something? Is the information available to sort by such criteria Paul? If so then yes. > > Also, it might not be a bad idea for the editorial folks to, on > publication of a new tutorial, make a list of one or more questions > answered by the tutorial. Those questions should be organized into a > kind of FAQ, or quasi-FAQ (QFAQ?), which a reader uses to follow a link > to the appropriate tutorial Speaking from fairly bitter experience. I've been criticised for 'answering the wrong question' or bad categorising, for 6 years now. Bottom line, we can't please all of the people all of the time. People seem to come at information from n different directions. Its really hard without something like a topic map to provide the differing schemas that will meet the varying needs of users. Great idea, and a list of xrefs would answer some of the questions. No problem using docbook to mark it up... The logic for it, the groupings etc, I'll leave to the group, I gave up trying to outguess people some time ago. My best solution is to use a google search of a list of pages. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From mjohnson at redhat.com Wed Sep 15 16:07:44 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Wed, 15 Sep 2004 12:07:44 -0400 Subject: Installation Guide In-Reply-To: <1095245650.3014.60292.camel@erato.phig.org> References: <1094734115.6711.204015049@webmail.messagingengine.com> <1095245650.3014.60292.camel@erato.phig.org> Message-ID: <414868D0.40602@redhat.com> Karsten Wade wrote: > On Thu, 2004-09-09 at 05:48, Stuart Ellis wrote: > > >>I think that I'll probably use this format: >> >>SCREENSHOT - (name of screen and window), >>(description of requirement) >> >>LINK - (name of unwritten >>section) >> >>TECHQUERY - (description of technical detail >>that needs to checked) > > ^ > +1 > > I like these, they seem good and sufficient for now. Karsten's statement seems sufficient to me. For now, anyway:) Mark > > - Karsten -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 tfox at redhat.com Wed Sep 15 20:28:50 2004 From: tfox at redhat.com (Tammy Fox) Date: Wed, 15 Sep 2004 16:28:50 -0400 Subject: version control on website In-Reply-To: <1095251959.2322.9.camel@berlin.east.gov> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> Message-ID: <1095280130.6130.25.camel@jadefox.rdu.redhat.com> On Wed, 2004-09-15 at 08:39, Paul W. Frields wrote: > On Wed, 2004-09-15 at 07:05, Karsten Wade wrote: > > How are we going to organize different versions of documents on the > > website? > > > > Option 1. By FC version, then document. > > > > f.r.c/docs > > -> FC2 > > -> Tutorial 1 > > -> Tutorial 2 > > ... > > -> FC3 > > -> Tutorial 1 > > -> Tutorial 2 > > ... > > > > Option 2. By document, then FC version. > > > > f.r.c/docs > > -> Tutorial 1 > > -> FC2 > > -> FC3 > > -> Tutorial 2 > > -> FC2 > > -> FC3 > > ... > > > > Option 3. Other ideas? > > I don't see why we can't have both... Two links, "Index by Core > release," then organized alphabetically within each release number, and > "Index by Subject," organized by release number within each tutorial. Am > I missing something? > We could do both on the Docs page, but we still need a way to organize the left navigation bar under the Docs category. Currently, all docs are listed there because there aren't that many, but it is going to get too long very soon. Sorting by version in the nav seems reasonable to me. If a tutorial is applicable to more than one version, we can list it more than once. We also need a directory structure for the URLs as well. For example, we now have docs/selinux-faq-fc2/ but it would be better to have docs/fc2/selinux-faq/ docs/fc3/selinux-faq/, which is how redhat.com/docs/ is organized. Tammy > Also, it might not be a bad idea for the editorial folks to, on > publication of a new tutorial, make a list of one or more questions > answered by the tutorial. Those questions should be organized into a > kind of FAQ, or quasi-FAQ (QFAQ?), which a reader uses to follow a link > to the appropriate tutorial in the "Index by Subject," e.g.: > > How do I configure update notifications? > How do I keep my system updated? > How do I update my system? > What is up2date? > What is yum? > > These are all questions that would link to the update-tutorial. This > list would get pretty long, but the page should be searchable simply by > using the Web browser "search" function. I don't see a need to design a > complicated Web interface (search engine, indexing, etc.) for this > purpose. What do you think? > > -- > Paul W. Frields, RHCE > From tfox at redhat.com Wed Sep 15 20:52:56 2004 From: tfox at redhat.com (Tammy Fox) Date: Wed, 15 Sep 2004 16:52:56 -0400 Subject: draft notice text Message-ID: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> I was about to add the common draft notice file from bug #132415, but I wanted to discuss the wording of the notice a bit more. (This was discussed on the Hardening Doc Preview thread, but I am starting a new one with a more appropriate subject.) The text proposed for the note is as follows: Draft Notice This version of this document is not yet affiliated with the Fedora Docs Project. It is a draft, and may be submitted to the project for review/approval at a later date. Until that time, that document will be receiving constant updates, and may change frequently. Saying that it isn't affliliated with the Fedora Docs Project might be misleading. It is being worked on for the project, but it isn't final yet. Also, it would be nice to tell readers how to help with the document if they are reading it. So, how about the following: DRAFT This is a draft version of the document. It is subject to change at any time and may not have been tested for technical accuracy yet. If you find any errors, please report them via Bugzilla in bug &BUG-NUM;. Then, in the parent file, the entity &BUG-NUM; would a link to the Bugzilla entry for that document. Thoughts? Tammy From borgan at redhat.com Wed Sep 15 21:12:19 2004 From: borgan at redhat.com (Brock Organ) Date: Wed, 15 Sep 2004 17:12:19 -0400 Subject: draft notice text In-Reply-To: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> Message-ID: <1095282739.3483.4.camel@borgan.devel.redhat.com> On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > I was about to add the common draft notice file from bug #132415, but I > wanted to discuss the wording of the notice a bit more. (This was > discussed on the Hardening Doc Preview thread, but I am starting a new > one with a more appropriate subject.) > > Thoughts? sounds good to me ... Regards, Brock From mjohnson at redhat.com Wed Sep 15 21:38:15 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Wed, 15 Sep 2004 17:38:15 -0400 Subject: draft notice text In-Reply-To: <1095282739.3483.4.camel@borgan.devel.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> Message-ID: <4148B647.9030305@redhat.com> Brock Organ wrote: > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > >>I was about to add the common draft notice file from bug #132415, but I >>wanted to discuss the wording of the notice a bit more. (This was >>discussed on the Hardening Doc Preview thread, but I am starting a new >>one with a more appropriate subject.) >> > > >>Thoughts? > > > sounds good to me ... Me, too. A nice improvement:) > Then, in the parent file, the entity &BUG-NUM; would a link to the > Bugzilla entry for that document. We may not want the &BUG-NUM; entity to show the full URL if it's one of those horrendously long, page-wrapping bugzilla URLs. If that's indeed the case, we may want the entity to contain a complete ulink element with link text that is literally the bugzilla bug number. ('just thinking out loud here...) Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 paul at frields.com Wed Sep 15 22:07:40 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 15 Sep 2004 18:07:40 -0400 Subject: version control on website In-Reply-To: <1095263022.2515.14.camel@homer> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> <1095263022.2515.14.camel@homer> Message-ID: <1095286060.4433.3.camel@bettie.internal.frields.org> On Wed, 2004-09-15 at 11:43, Dave Pawson wrote: > On Wed, 2004-09-15 at 13:39, Paul W. Frields wrote: > > > > Option 3. Other ideas? > > > > I don't see why we can't have both... Two links, "Index by Core > > release," then organized alphabetically within each release number, and > > "Index by Subject," organized by release number within each tutorial. Am > > I missing something? > Is the information available to sort by such criteria Paul? > If so then yes. I was once again using the wrong words for the right idea, sorry. I should have said "Index by Title," and *not* "Index by Subject." One would hope the name of the tutorial is in fact the subject, but perhaps it might be misleading otherwise. -- Paul W. Frields, RHCE From paul at frields.com Wed Sep 15 22:12:25 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 15 Sep 2004 18:12:25 -0400 Subject: version control on website In-Reply-To: <1095280130.6130.25.camel@jadefox.rdu.redhat.com> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> <1095280130.6130.25.camel@jadefox.rdu.redhat.com> Message-ID: <1095286345.4433.10.camel@bettie.internal.frields.org> On Wed, 2004-09-15 at 16:28, Tammy Fox wrote: > On Wed, 2004-09-15 at 08:39, Paul W. Frields wrote: > > On Wed, 2004-09-15 at 07:05, Karsten Wade wrote: > > > How are we going to organize different versions of documents on the > > > website? > > > > > > Option 1. By FC version, then document. > > > > > > f.r.c/docs > > > -> FC2 > > > -> Tutorial 1 > > > -> Tutorial 2 > > > ... > > > -> FC3 > > > -> Tutorial 1 > > > -> Tutorial 2 > > > ... > > > > > > Option 2. By document, then FC version. > > > > > > f.r.c/docs > > > -> Tutorial 1 > > > -> FC2 > > > -> FC3 > > > -> Tutorial 2 > > > -> FC2 > > > -> FC3 > > > ... > > > > > > Option 3. Other ideas? > > > > I don't see why we can't have both... Two links, "Index by Core > > release," then organized alphabetically within each release number, and > > "Index by Subject," organized by release number within each tutorial. Am > > I missing something? > > > > We could do both on the Docs page, but we still need a way to organize > the left navigation bar under the Docs category. Currently, all docs are > listed there because there aren't that many, but it is going to get too > long very soon. Sorting by version in the nav seems reasonable to me. If > a tutorial is applicable to more than one version, we can list it more > than once. We also need a directory structure for the URLs as well. For > example, we now have docs/selinux-faq-fc2/ but it would be better to > have docs/fc2/selinux-faq/ docs/fc3/selinux-faq/, which is how > redhat.com/docs/ is organized. I see your point, Tammy, but my feeling would be to opt for only two (or three) subheadings under the current "Docs" nav bar entry: Docs by Title by FC Release [FAQ]* *This would be that extra structure I mentioned; not really a FAQ, but an organization of questions that would link to the Title index. With the very aggressive release schedule of Fedora Core, it wouldn't be long before the nav bar became very crowded (FC2 through FC6, anyone?). The Docs Project doesn't currently have a policy for when we won't publish documentation anymore for a release, and I'm not sure we should have one. There may be people as comfortable staying with certain releases as they were staying with, say, Red Hat Linux 7.3. I would try and leave the nav bar as generic as possible while still being useful. I'm sure there are problems with this idea, so I welcome the inevitable holes to be shot through it! :-) -- Paul W. Frields, RHCE From paul at frields.com Wed Sep 15 22:19:15 2004 From: paul at frields.com (Paul W. Frields) Date: Wed, 15 Sep 2004 18:19:15 -0400 Subject: draft notice text In-Reply-To: <4148B647.9030305@redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> Message-ID: <1095286755.4433.17.camel@bettie.internal.frields.org> On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > Brock Organ wrote: > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > > >>I was about to add the common draft notice file from bug #132415, but I > >>wanted to discuss the wording of the notice a bit more. (This was > >>discussed on the Hardening Doc Preview thread, but I am starting a new > >>one with a more appropriate subject.) > >> > >>Thoughts? > > > > > > sounds good to me ... > > Me, too. A nice improvement:) I also like this! > > Then, in the parent file, the entity &BUG-NUM; would a link to the > > Bugzilla entry for that document. > > We may not want the &BUG-NUM; entity to show the full URL if it's > one of those horrendously long, page-wrapping bugzilla URLs. If > that's indeed the case, we may want the entity to contain a complete > ulink element with link text that is literally the bugzilla bug > number. ('just thinking out loud here...) The URL always works in my experience (for non-restricted bugs of course). If the writer uses too long a URL, the editor can fix it without a problem. Or for that matter, I suppose we could have a common entity: And in the writer's doc: But maybe that's just too much work? Not sure. -- Paul W. Frields, RHCE From sarahs at redhat.com Thu Sep 16 04:40:08 2004 From: sarahs at redhat.com (Sarah Wang) Date: Thu, 16 Sep 2004 14:40:08 +1000 Subject: How to add screenshots in XML? Message-ID: <1095309608.2120.56.camel@sarah.brisbane.redhat.com> I read through the documentation guide but didn't find any tags for embedding screenshots in xml files. Where can I find that information? Thanks, Sarah From kwade at redhat.com Thu Sep 16 06:08:19 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 15 Sep 2004 23:08:19 -0700 Subject: How to add screenshots in XML? In-Reply-To: <1095309608.2120.56.camel@sarah.brisbane.redhat.com> References: <1095309608.2120.56.camel@sarah.brisbane.redhat.com> Message-ID: <1095314899.3014.63752.camel@erato.phig.org> On Wed, 2004-09-15 at 21:40, Sarah Wang wrote: > I read through the documentation guide but didn't find any tags for > embedding screenshots in xml files. Where can I find that information? This is a recent section: http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html However, the actual XML tags you need are defined at: http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-figure.html hth - 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 sarahs at redhat.com Thu Sep 16 06:14:14 2004 From: sarahs at redhat.com (Sarah Wang) Date: Thu, 16 Sep 2004 16:14:14 +1000 Subject: How to add screenshots in XML? In-Reply-To: <1095314899.3014.63752.camel@erato.phig.org> References: <1095309608.2120.56.camel@sarah.brisbane.redhat.com> <1095314899.3014.63752.camel@erato.phig.org> Message-ID: <1095315254.2120.59.camel@sarah.brisbane.redhat.com> Thanks a lot! can't figure out how i missed those... On Thu, 2004-09-16 at 16:08, Karsten Wade wrote: > On Wed, 2004-09-15 at 21:40, Sarah Wang wrote: > > I read through the documentation guide but didn't find any tags for > > embedding screenshots in xml files. Where can I find that information? > > This is a recent section: > > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html > > However, the actual XML tags you need are defined at: > > http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-figure.html > > hth - Karsten From tuxxer at cox.net Wed Sep 15 23:34:21 2004 From: tuxxer at cox.net (tuxxer) Date: Wed, 15 Sep 2004 23:34:21 +0000 Subject: draft notice text In-Reply-To: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> Message-ID: <1095291261.16202.194.camel@bach> On Wed, 2004-09-15 at 20:52, Tammy Fox wrote: > I was about to add the common draft notice file from bug #132415, but I > wanted to discuss the wording of the notice a bit more. (This was > discussed on the Hardening Doc Preview thread, but I am starting a new > one with a more appropriate subject.) > > The text proposed for the note is as follows: > > > Draft Notice > This version of this document is not yet affiliated with the Fedora Docs > Project. It is a draft, and may be submitted to the project for > review/approval at a later date. Until that time, that document will > be receiving constant updates, and may change frequently. > > > > Saying that it isn't affliliated with the Fedora Docs Project might be > misleading. It is being worked on for the project, but it isn't final > yet. Also, it would be nice to tell readers how to help with the > document if they are reading it. So, how about the following: > > > DRAFT > > This is a draft version of the document. It is subject to change > at any time and may not have been tested for technical accuracy > yet. If you find any errors, please report them via Bugzilla in bug > &BUG-NUM;. > > > > Then, in the parent file, the entity &BUG-NUM; would a link to the > Bugzilla entry for that document. > > Thoughts? > > Tammy I like the idea of the bugzilla reference. However, (in defense of my original draft [no pun intended]) IMHO a document isn't part of the FDP unless it's been committed to CVS (or is hosted or referenced by RedHat or Fedora). Would I be wrong in making this assumption? Nor is it in any way affiliated (other than by the author's "loyalty") with the project if it is hosted somewhere *other* than a RedHat/Fedora "official" site. Just from the little bit that I've seen since I've been here, this is not the general practice, nor is this functionality even available (I'm hosting my hardening "preview" on my own webspace [well.....my ISPs, but you get the idea]). I guess the point that I'm making here is this: A document is not part of the official documentation until it is fully "culled into the fold" of the FDP, e.g. accepted by the community and committed to CVS and/or hosted by RedHat/Fedora. How about a blend of the two approaches: Draft Notice This document is a draft. It is being developed for and/or by the $FDP; community and is intended to be submitted as official documentation. It is subject to change at any time and may not have been tested for technical accuracy. If you find any errors, please report them via Bugzilla in bug &BUG-NUM;. This closely resembles Tammy's proposal, but still implies that it has not been "blessed" by the community and, while it is still in draft form, is owned by the author (and not yet part of the official documentation). I don't mean to go off of the deep-end here. But (unless I missed something in the process) only those that are employed by RedHat are bound by any type of intellectual property rights (maybe not even then). So unless "volunteers" are going to be given certain "rights and privileges" (i.e. devel-cvs access, "preview" webspace, etc.), there's no obligation on the part of the author to develop and/or submit the document to/with the project. I don't mean to be antagonistic, I DO want to contribute to the community. But I guess the point I am ultimately making is, my words are my words, until I say (or it is mutually agreed upon) that they are NOT just *my* words. The statement above (my proposed ammendment) implies, and/or states that it is not yet part of the official documentation, yet states intent, and therefore should be less misleading than the original text. I believe that also gives the community (and editors, and RedHat) a lot more "say-so" in the final presentation of that document. Otherwise, why even put any emphasis on the Project's "methods"? Why not write a document (in whatever format) and submit it? Just my 2 ...... ok, maybe .... 3 cents. ;) -Charlie -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 kwade at redhat.com Thu Sep 16 08:06:04 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 16 Sep 2004 01:06:04 -0700 Subject: draft notice text In-Reply-To: <1095291261.16202.194.camel@bach> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095291261.16202.194.camel@bach> Message-ID: <1095321963.3014.64224.camel@erato.phig.org> On Wed, 2004-09-15 at 16:34, tuxxer wrote: > > Thoughts? > > > > Tammy > > I like the idea of the bugzilla reference. However, (in defense of my > original draft [no pun intended]) IMHO a document isn't part of the FDP > unless it's been committed to CVS (or is hosted or referenced by RedHat > or Fedora). I think the idea is that, yes, eventually, many authors will work on their documents directly in CVS. Think of the situation as being akin to a piece of software being made available during a test cycle. It is expected to be broken, but it's still part of Fedora. > How about a blend of the two approaches: Since both situations are likely to occur, why not offer both s as either/or options? I'd say that we could leave the wording entirely up to the author, but that would be presuming too much from writers. Still, if someone changed the wording in their doc for whatever reason, I don't think anyone would think it's a big deal. - 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 Sep 16 08:17:46 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 16 Sep 2004 01:17:46 -0700 Subject: version control on website In-Reply-To: <1095286345.4433.10.camel@bettie.internal.frields.org> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> <1095280130.6130.25.camel@jadefox.rdu.redhat.com> <1095286345.4433.10.camel@bettie.internal.frields.org> Message-ID: <1095322666.3014.64278.camel@erato.phig.org> On Wed, 2004-09-15 at 15:12, Paul W. Frields wrote: > I see your point, Tammy, but my feeling would be to opt for only two (or > three) subheadings under the current "Docs" nav bar entry: > > Docs > by Title > by FC Release > [FAQ]* > > *This would be that extra structure I mentioned; not really a FAQ, but > an organization of questions that would link to the Title index. I.e., "by Title" expands to have a list of all documents by title in alpha order, and "by FC Release" expands to a short list of release numbers, which then expand to a set of document titles that are just part of that release? One immediate problem I see is a maintenance nightmare. As much as we would like to have a CMS, this is currently a manual process. We need to focus on a simple structure that works, and let Google do the indexing for us. :) > With the very aggressive release schedule of Fedora Core, it wouldn't be > long before the nav bar became very crowded (FC2 through FC6, anyone?). > The Docs Project doesn't currently have a policy for when we won't > publish documentation anymore for a release, and I'm not sure we should > have one. There may be people as comfortable staying with certain > releases as they were staying with, say, Red Hat Linux 7.3. I would try > and leave the nav bar as generic as possible while still being useful. It seems reasonable to hand-off maintenance on version-specific docs to the Fedora Legacy project, when the matching version of FC is handed-off. An author could choose to continue to work on the document, but it is now under the aegis of the Legacy group, who are presumably just following the examples and rules we have set. Just like supporting the software, we have to draw the line on how far back this project is going to support documents. We don't have the resources to support a version of FC for several years. Tying the lifecycle of our documents into the entire distro lifecycle seems like a good idea. Just my personal pennies, - 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 Sep 16 08:29:00 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 16 Sep 2004 01:29:00 -0700 Subject: draft notice text In-Reply-To: <1095286755.4433.17.camel@bettie.internal.frields.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> Message-ID: <1095323339.3014.64328.camel@erato.phig.org> On Wed, 2004-09-15 at 15:19, Paul W. Frields wrote: > On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > > Brock Organ wrote: > > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > > > > >>I was about to add the common draft notice file from bug #132415, but I > > >>wanted to discuss the wording of the notice a bit more. (This was > > >>discussed on the Hardening Doc Preview thread, but I am starting a new > > >>one with a more appropriate subject.) > > >> > > >>Thoughts? > > > > > > > > > sounds good to me ... > > > > Me, too. A nice improvement:) > > I also like this! +1 for a complete consensus :) > The URL > always works in my experience (for non-restricted bugs of course). If > the writer uses too long a URL, the editor can fix it without a problem. > > Or for that matter, I suppose we could have a common entity: > > "http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id="> > > And in the writer's doc: > > Strike SYSTEM from that usage. > > But maybe that's just too much work? Not sure. Seems simpler to go with a locally defined entity that is the bug #. FWIW, this works: http://bugzilla.redhat.com/XXXXXX I think Mark is thinking of a pre-filled bug report such as the one that I use for the SELinux FAQ. For getting proper feedback, it is invaluable -- it prefills the product, version, and component, sets the blocker bug and assigned to, suggests a useful title-style, should have the latest version number embedded already, and has specific suggestions for filling out a bug report unique to this project. However, it looks like this: https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora%20Core&op_sys=Linux&version=fc3test2&component=fedora-docs&component_text=&rep_platform=All&priority=normal&bug_severity=normal&bug_status=NEW&assigned_to=kwade%40redhat.com&cc=&estimated_time=0.0&bug_file_loc=http%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselinux-faq-en%2F&short_desc=SELinux%20FAQ%20-%20%5Bsummarize%20FAQ%20change%20or%20addition%5D&comment=Description%20of%20change%2FFAQ%20addition.%20%20If%20a%20change%2C%20include%20the%20original%0D%0Atext%20first%2C%20then%20the%20changed%20text%3A%0D%0A%0D%0A%0D%0A%0D%0AVersion-Release%20of%20FAQ%20%28found%20on%0D%0Ahttp%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselinux-faq-en%2Fln-legalnotice.html%29%3A%0D%0A%0D%0A%20for%20example%3A%20selinux-faq-1.3%20%282004-09-15-T04%3A20-0800%29%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A&keywords=&dependson=&blocked=118757%20%20&maketemplate=Remember%20values%20as%20bookmarkable%20templ! ate&form_name=enter_bug I use a with descriptive link text. :) How about: 1. If it is just a link to the bug report, then: usage: 2. If it is a Really Long URL, then following the same solution to define the entity, but usage is: pre-filled bug report NOTE - if you use a long URL that includes '&' characters, you _must_ change them to & in the XML so that they process into the correct characters when rendered. - 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 Sep 16 08:39:50 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 16 Sep 2004 01:39:50 -0700 Subject: draft notice text In-Reply-To: <1095323339.3014.64328.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> Message-ID: <1095323989.3014.64368.camel@erato.phig.org> On Thu, 2004-09-16 at 01:29, Karsten Wade wrote: > 2. If it is a Really Long URL, then following the same solution to > define the entity, but usage is: > > pre-filled bug report > > NOTE - if you use a long URL that includes '&' characters, you _must_ > change them to & in the XML so that they process into the correct > characters when rendered. Oops ... looks like there are plenty of special characters that have other meaning in the ENTITY space, such as %. I tried to do option 2., and the build broke on the %. I had to change 97 % to % ... and it worked. - 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 Sep 16 13:55:15 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 16 Sep 2004 09:55:15 -0400 Subject: draft notice text In-Reply-To: <1095323989.3014.64368.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> Message-ID: <1095342914.2361.3.camel@berlin.east.gov> On Thu, 2004-09-16 at 04:39, Karsten Wade wrote: > > 2. If it is a Really Long URL, then following the same solution to > > define the entity, but usage is: > > > > pre-filled bug report > > > > NOTE - if you use a long URL that includes '&' characters, you _must_ > > change them to & in the XML so that they process into the correct > > characters when rendered. > > Oops ... looks like there are plenty of special characters that have > other meaning in the ENTITY space, such as %. I tried to do option 2., > and the build broke on the %. > > I had to change 97 % to % ... and it worked. I agree with the approach, and with the usage. One question: for Very Long URLs, should the actual URL appear somewhere like a ? Normally we use the URL as the content body as well as the "url" parameter for . I like the idea that people will be able to read the document online and immediately register problems if they have any. Customer service at its finest! -- Paul W. Frields, RHCE From paul at frields.com Thu Sep 16 14:08:57 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 16 Sep 2004 10:08:57 -0400 Subject: version control on website In-Reply-To: <1095322666.3014.64278.camel@erato.phig.org> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> <1095280130.6130.25.camel@jadefox.rdu.redhat.com> <1095286345.4433.10.camel@bettie.internal.frields.org> <1095322666.3014.64278.camel@erato.phig.org> Message-ID: <1095343737.2361.18.camel@berlin.east.gov> On Thu, 2004-09-16 at 04:17, Karsten Wade wrote: > On Wed, 2004-09-15 at 15:12, Paul W. Frields wrote: > > > I see your point, Tammy, but my feeling would be to opt for only two (or > > three) subheadings under the current "Docs" nav bar entry: > > > > Docs > > by Title > > by FC Release > > [FAQ]* > > > > *This would be that extra structure I mentioned; not really a FAQ, but > > an organization of questions that would link to the Title index. > > I.e., "by Title" expands to have a list of all documents by title in > alpha order, and "by FC Release" expands to a short list of release > numbers, which then expand to a set of document titles that are just > part of that release? Yes, exactly, although by "expand" I am guessing you mean when one clicks "By Title" in the nav bar, the body of the HTML page fills with the content. I certainly wouldn't want all that in the nav bar too. I'm not sure I made that clear. > One immediate problem I see is a maintenance nightmare. As much as we > would like to have a CMS, this is currently a manual process. We need > to focus on a simple structure that works, and let Google do the > indexing for us. :) Ah. If Tammy has to change three or four pages manually, plus the nav bar source, every time a document is posted, that would indeed be prohibitive. I wasn't sure of the internal process. If she had scripts doing it for her, now.... :-) Would you say that a simple listing by alphabetical title should be enough -- in other words, not much different from the current page? > > With the very aggressive release schedule of Fedora Core, it wouldn't be > > long before the nav bar became very crowded (FC2 through FC6, anyone?). > > The Docs Project doesn't currently have a policy for when we won't > > publish documentation anymore for a release, and I'm not sure we should > > have one. There may be people as comfortable staying with certain > > releases as they were staying with, say, Red Hat Linux 7.3. I would try > > and leave the nav bar as generic as possible while still being useful. > > It seems reasonable to hand-off maintenance on version-specific docs to > the Fedora Legacy project, when the matching version of FC is > handed-off. > > An author could choose to continue to work on the document, but it is > now under the aegis of the Legacy group, who are presumably just > following the examples and rules we have set. > > Just like supporting the software, we have to draw the line on how far > back this project is going to support documents. We don't have the > resources to support a version of FC for several years. Tying the > lifecycle of our documents into the entire distro lifecycle seems like a > good idea. OK, I can live with this as well. I figured that having old versions on the shelf somewhere would be a good idea. If we obsolete our documents at roughly the same rate as other handoffs to the FLP, then we should at least have a link on &FDPDOCS-URL; that points to their document repository. It probably bears mentioning, with absolutely no ill will or offense intended, that the FLP is currently undergoing some pain trying to recruit and maintain participation. I'm sure that's no different than many other projects, and I hope they get everything sorted out satisfactorily. We might want to be prepared for the small chance that FLP is not prepared to handle maintaining any such repository. The task of storage won't be overwhelming in that case, but the task of maintenance will, of necessity, likely drop off the scope. -- Paul W. Frields, RHCE From mjohnson at redhat.com Thu Sep 16 15:44:18 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Thu, 16 Sep 2004 11:44:18 -0400 Subject: version control on website In-Reply-To: <1095322666.3014.64278.camel@erato.phig.org> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> <1095280130.6130.25.camel@jadefox.rdu.redhat.com> <1095286345.4433.10.camel@bettie.internal.frields.org> <1095322666.3014.64278.camel@erato.phig.org> Message-ID: <4149B4D2.4060209@redhat.com> Karsten Wade wrote: > On Wed, 2004-09-15 at 15:12, Paul W. Frields wrote: > > >>I see your point, Tammy, but my feeling would be to opt for only two (or >>three) subheadings under the current "Docs" nav bar entry: >> >> Docs >> by Title >> by FC Release >> [FAQ]* >> >>*This would be that extra structure I mentioned; not really a FAQ, but >>an organization of questions that would link to the Title index. > > > I.e., "by Title" expands to have a list of all documents by title in > alpha order, and "by FC Release" expands to a short list of release > numbers, which then expand to a set of document titles that are just > part of that release? > > One immediate problem I see is a maintenance nightmare. As much as we > would like to have a CMS, this is currently a manual process. FWIW, if you built the site with the DocBook Website DTD & stylesheets, the expanding ToC/navbar gets generated automatically. (I wrote the dbwebsite code for that turns/expands the icons.) And the really nice thing is that the source content of the site is - you guessed it - XML:) Doubt that the resources exist presently for a site rebuild based on the DocBook Website package, but it may be worth investigating for the long term. Sites built from this package are ubiquitous. (Dave Pawson's is a case in point, though he uses a horizontal ToC/navbar:) A good example of the kind of navbar/ToC expansion you're talking about is at http://docbook.org. Click on the 'schema' link on the navbar to see how the ToC expands and the icons flip to provide some visual cues as to the present navigational context. It wouldn't be too difficult to reproduce the current Fedora site look-n-feel by customizing the website stylesheets, if someone had the time & energy to do it. Maintaining a website by hand-coding HTML is a painful process, but 'sounds like it's the best we've got for now. My $0.02, Mark > We need > to focus on a simple structure that works, and let Google do the > indexing for us. :) -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 Thu Sep 16 16:28:23 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 16 Sep 2004 17:28:23 +0100 Subject: version control on website In-Reply-To: <1095286345.4433.10.camel@bettie.internal.frields.org> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> <1095280130.6130.25.camel@jadefox.rdu.redhat.com> <1095286345.4433.10.camel@bettie.internal.frields.org> Message-ID: <1095352102.2516.9.camel@homer> On Wed, 2004-09-15 at 23:12, Paul W. Frields wrote: > I see your point, Tammy, but my feeling would be to opt for only two (or > three) subheadings under the current "Docs" nav bar entry: > > Docs > by Title > by FC Release > [FAQ]* > > *This would be that extra structure I mentioned; not really a FAQ, but > an organization of questions that would link to the Title index. > > With the very aggressive release schedule of Fedora Core, it wouldn't be > long before the nav bar became very crowded (FC2 through FC6, anyone?). > The Docs Project doesn't currently have a policy for when we won't > publish documentation anymore for a release, and I'm not sure we should > have one. There may be people as comfortable staying with certain > releases as they were staying with, say, Red Hat Linux 7.3. I would try > and leave the nav bar as generic as possible while still being useful. > > I'm sure there are problems with this idea, so I welcome the inevitable > holes to be shot through it! :-) It struck me that Tammy was getting hung up on the left hand nav bar. The fact that it has navigability issues for accessibility isn't the only reason to question it. A plain html list or other structure wouldn't hurt too much, and would provide the options. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Thu Sep 16 16:28:15 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 16 Sep 2004 09:28:15 -0700 Subject: draft notice text In-Reply-To: <1095342914.2361.3.camel@berlin.east.gov> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> Message-ID: <1095352094.3014.65780.camel@erato.phig.org> On Thu, 2004-09-16 at 06:55, Paul W. Frields wrote: > I agree with the approach, and with the usage. One question: for Very > Long URLs, should the actual URL appear somewhere like a ? > Normally we use the URL as the content body as well as the "url" > parameter for . Ideally, you wouldn't have to do this. When rendered to HTML, a should make a hyperlink, and when rendered to print (PDF), a footnote should be generated instead (and it should wrap properly, too.) However, the PDF part has been broken in SGML in our internal toolchain for some time, which is what prompted the practice in the Doc Guide. Is this still broken in the FDP toolchain? I don't have a working PDF build at the moment (again) to test ... - 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 Sep 16 16:32:32 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 16 Sep 2004 09:32:32 -0700 Subject: version control on website In-Reply-To: <1095352102.2516.9.camel@homer> References: <1095246314.3014.60338.camel@erato.phig.org> <1095251959.2322.9.camel@berlin.east.gov> <1095280130.6130.25.camel@jadefox.rdu.redhat.com> <1095286345.4433.10.camel@bettie.internal.frields.org> <1095352102.2516.9.camel@homer> Message-ID: <1095352352.3014.65796.camel@erato.phig.org> On Thu, 2004-09-16 at 09:28, Dave Pawson wrote: > It struck me that Tammy was getting hung up on the left hand nav bar. > The fact that it has navigability issues for accessibility isn't the > only > reason to question it. > > A plain html list or other structure wouldn't hurt too much, > and would provide the options. Oh, I thought that the nav bar was fairly accessible, being a construct of CSS. When I've seen the page rendered without any stylesheet, the links cascade in a manner you could move through with a tab. Also, I thought the order within the HTML was roughly standardized to make it usable for a11y and handheld devices? Thanks for the clarification, btw, a11y is an area I need more edumacation in. - 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 Sep 16 18:22:38 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 16 Sep 2004 14:22:38 -0400 Subject: draft notice text In-Reply-To: <1095352094.3014.65780.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095352094.3014.65780.camel@erato.phig.org> Message-ID: <1095358958.3730.0.camel@berlin.east.gov> On Thu, 2004-09-16 at 12:28, Karsten Wade wrote: > On Thu, 2004-09-16 at 06:55, Paul W. Frields wrote: > > > I agree with the approach, and with the usage. One question: for Very > > Long URLs, should the actual URL appear somewhere like a ? > > Normally we use the URL as the content body as well as the "url" > > parameter for . > > Ideally, you wouldn't have to do this. When rendered to HTML, a > should make a hyperlink, and when rendered to print (PDF), a > footnote should be generated instead (and it should wrap properly, too.) That's what I was looking for, thanks. > However, the PDF part has been broken in SGML in our internal toolchain > for some time, which is what prompted the practice in the Doc Guide. > > Is this still broken in the FDP toolchain? I don't have a working PDF > build at the moment (again) to test ... I'll test and let you know. My PDF builds work fine, albeit to A4 paper size. -- Paul W. Frields, RHCE From tfox at redhat.com Fri Sep 17 15:15:47 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 11:15:47 -0400 Subject: draft notice text In-Reply-To: <4148B647.9030305@redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> Message-ID: <1095434146.6112.9.camel@jadefox.rdu.redhat.com> On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > Brock Organ wrote: > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > > >>I was about to add the common draft notice file from bug #132415, but I > >>wanted to discuss the wording of the notice a bit more. (This was > >>discussed on the Hardening Doc Preview thread, but I am starting a new > >>one with a more appropriate subject.) > >> > > > > > >>Thoughts? > > > > > > sounds good to me ... > > Me, too. A nice improvement:) > > > Then, in the parent file, the entity &BUG-NUM; would a link to the > > Bugzilla entry for that document. > > We may not want the &BUG-NUM; entity to show the full URL if it's > one of those horrendously long, page-wrapping bugzilla URLs. If > that's indeed the case, we may want the entity to contain a complete > ulink element with link text that is literally the bugzilla bug > number. ('just thinking out loud here...) > > Cheers, > Mark > > Sorry. That is what I was thinking but just didn't articulate properly. The HTML version would have a link, but the text itself would just have the bug number such as: If you find any errors, please report them via Bugzilla in bug #11111. Tammy > -- > ---------------------------------------------------------- > Mark Johnson > OS Product Documentation > 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 tfox at redhat.com Fri Sep 17 15:21:20 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 11:21:20 -0400 Subject: draft notice text In-Reply-To: <1095352094.3014.65780.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095352094.3014.65780.camel@erato.phig.org> Message-ID: <1095434479.6112.13.camel@jadefox.rdu.redhat.com> On Thu, 2004-09-16 at 12:28, Karsten Wade wrote: > On Thu, 2004-09-16 at 06:55, Paul W. Frields wrote: > > > I agree with the approach, and with the usage. One question: for Very > > Long URLs, should the actual URL appear somewhere like a ? > > Normally we use the URL as the content body as well as the "url" > > parameter for . > > Ideally, you wouldn't have to do this. When rendered to HTML, a > should make a hyperlink, and when rendered to print (PDF), a > footnote should be generated instead (and it should wrap properly, too.) > > However, the PDF part has been broken in SGML in our internal toolchain > for some time, which is what prompted the practice in the Doc Guide. > What part is broken? The footnote for URLs? I turned that off on purpose in our stylesheets for our internal SGML because we decided that we preferred the URL inline or inside screen tags if it might line wrap. Tammy > Is this still broken in the FDP toolchain? I don't have a working PDF > build at the moment (again) to test ... > > - 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 Sep 17 15:23:57 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 11:23:57 -0400 Subject: draft notice text In-Reply-To: <1095342914.2361.3.camel@berlin.east.gov> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> Message-ID: <1095434637.6112.17.camel@jadefox.rdu.redhat.com> On Thu, 2004-09-16 at 09:55, Paul W. Frields wrote: > On Thu, 2004-09-16 at 04:39, Karsten Wade wrote: > > > 2. If it is a Really Long URL, then following the same solution to > > > define the entity, but usage is: > > > > > > pre-filled bug report > > > > > > NOTE - if you use a long URL that includes '&' characters, you _must_ > > > change them to & in the XML so that they process into the correct > > > characters when rendered. > > > > Oops ... looks like there are plenty of special characters that have > > other meaning in the ENTITY space, such as %. I tried to do option 2., > > and the build broke on the %. > > > > I had to change 97 % to % ... and it worked. > > I agree with the approach, and with the usage. One question: for Very > Long URLs, should the actual URL appear somewhere like a ? > Normally we use the URL as the content body as well as the "url" > parameter for . > > I like the idea that people will be able to read the document online and > immediately register problems if they have any. Customer service at its > finest! > > -- > Paul W. Frields, RHCE > For docs created for RHEL, etc. we decided that the URL should be part of the text since when the decision was made we printed the docs. So, our rule was, if the URL is short, it should be inline text. If it is long and might line wrap, include it in screen tags so it is always rendered on its own line. Tammy From paul at frields.com Fri Sep 17 15:32:25 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 17 Sep 2004 11:32:25 -0400 Subject: draft notice text In-Reply-To: <1095434637.6112.17.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> Message-ID: <1095435145.4419.6.camel@berlin.east.gov> On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > For docs created for RHEL, etc. we decided that the URL should be part > of the text since when the decision was made we printed the docs. So, > our rule was, if the URL is short, it should be inline text. If it is > long and might line wrap, include it in screen tags so it is always > rendered on its own line. Would you say that the suggested usage is OK, since it is doubtful these manuals will be printed commercially? I would expect users *might* print them locally for reference, but most reading will be done online, I suspect, whether off a local hard disk (installed from a fedora-docs[1] RPM package) or the Internet. If we can turn the footnote function back on for Fedora, that would be great IMHO. Also, I have another minor suggestion (I think for the stylesheets) which I will post to the list and bugzilla momentarily. = = = = = [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} -- Paul W. Frields, RHCE From paul at frields.com Fri Sep 17 15:39:28 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 17 Sep 2004 11:39:28 -0400 Subject: Stylesheet for Message-ID: <1095435568.4419.14.camel@berlin.east.gov> I would like to see sections take on a different rendered style, somewhat like the sections. I think the right way to do this is with an outlined box, but without changing the shade (BG color). That should keep an distinct from a . I hope this doesn't sound trivial in the face of other work; I was actually doing substantial FDP work when the subject came up. As I was showing my wife a section of text I had written, which included several s, she commented that the HTML rendering was confusing because the content itself does not significantly differ from the surrounding content. On top of that, the caption appears below the content. We agreed that the caption is nice to have under the content for a professional appearance, but only if the example is in some way separated from the rest of the text. I thought introducing yet another color of shading was excessive. We already have blue for admonitions and gray for . Red sets the
headers apart. I think simply outlining the area and increasing the margin slightly would do the trick. I will Bugzilla a RFE for this change to css/fedora.css shortly, but I thought I would solicit a few comments before I commit the bug. -- Paul W. Frields, RHCE From tfox at redhat.com Fri Sep 17 16:17:05 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 12:17:05 -0400 Subject: draft notice text In-Reply-To: <1095323339.3014.64328.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> Message-ID: <1095437825.6112.70.camel@jadefox.rdu.redhat.com> On Thu, 2004-09-16 at 04:29, Karsten Wade wrote: > On Wed, 2004-09-15 at 15:19, Paul W. Frields wrote: > > On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > > > Brock Organ wrote: > > > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > > > > > > >>I was about to add the common draft notice file from bug #132415, but I > > > >>wanted to discuss the wording of the notice a bit more. (This was > > > >>discussed on the Hardening Doc Preview thread, but I am starting a new > > > >>one with a more appropriate subject.) > > > >> > > > >>Thoughts? > > > > > > > > > > > > sounds good to me ... > > > > > > Me, too. A nice improvement:) > > > > I also like this! > > +1 for a complete consensus :) Then let it be so. I've added this to CVS and closed out the bug. Thanks for the feedback. Tammy > > > The URL > > always works in my experience (for non-restricted bugs of course). If > > the writer uses too long a URL, the editor can fix it without a problem. > > > > Or for that matter, I suppose we could have a common entity: > > > > > "http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id="> > > > > And in the writer's doc: > > > > > > Strike SYSTEM from that usage. > > > > > But maybe that's just too much work? Not sure. > > Seems simpler to go with a locally defined entity that is the bug #. > > FWIW, this works: http://bugzilla.redhat.com/XXXXXX > > I think Mark is thinking of a pre-filled bug report such as the one that > I use for the SELinux FAQ. For getting proper feedback, it is > invaluable -- it prefills the product, version, and component, sets the > blocker bug and assigned to, suggests a useful title-style, should have > the latest version number embedded already, and has specific suggestions > for filling out a bug report unique to this project. However, it looks > like this: > > https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora%20Core&op_sys=Linux&version=fc3test2&component=fedora-docs&component_text=&rep_platform=All&priority=normal&bug_severity=normal&bug_status=NEW&assigned_to=kwade%40redhat.com&cc=&estimated_time=0.0&bug_file_loc=http%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselinux-faq-en%2F&short_desc=SELinux%20FAQ%20-%20%5Bsummarize%20FAQ%20change%20or%20addition%5D&comment=Description%20of%20change%2FFAQ%20addition.%20%20If%20a%20change%2C%20include%20the%20original%0D%0Atext%20first%2C%20then%20the%20changed%20text%3A%0D%0A%0D%0A%0D%0A%0D%0AVersion-Release%20of%20FAQ%20%28found%20on%0D%0Ahttp%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselinux-faq-en%2Fln-legalnotice.html%29%3A%0D%0A%0D%0A%20for%20example%3A%20selinux-faq-1.3%20%282004-09-15-T04%3A20-0800%29%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A&keywords=&dependson=&blocked=118757%20%20&maketemplate=Remember%20values%20as%20bookmarkable%20tem! pl! > ate&form_name=enter_bug > > I use a with descriptive link text. :) > > How about: > > 1. If it is just a link to the bug report, then: > > > > usage: > > > > 2. If it is a Really Long URL, then following the same solution to > define the entity, but usage is: > > pre-filled bug report > > NOTE - if you use a long URL that includes '&' characters, you _must_ > change them to & in the XML so that they process into the correct > characters when rendered. > > - 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 Sep 17 16:20:35 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 12:20:35 -0400 Subject: Stylesheet for In-Reply-To: <1095435568.4419.14.camel@berlin.east.gov> References: <1095435568.4419.14.camel@berlin.east.gov> Message-ID: <1095438035.6112.73.camel@jadefox.rdu.redhat.com> On Fri, 2004-09-17 at 11:39, Paul W. Frields wrote: > I would like to see sections take on a different rendered > style, somewhat like the sections. I think the right way to do > this is with an outlined box, but without changing the shade (BG color). > That should keep an distinct from a . > > I hope this doesn't sound trivial in the face of other work; I was > actually doing substantial FDP work when the subject came up. As I was > showing my wife a section of text I had written, which included several > s, she commented that the HTML rendering was confusing because > the content itself does not significantly differ from the > surrounding content. On top of that, the caption appears below > the content. > > We agreed that the caption is nice to have under the content for a > professional appearance, but only if the example is in some way > separated from the rest of the text. I thought introducing yet another > color of shading was excessive. We already have blue for admonitions and > gray for . Red sets the
headers apart. I think simply > outlining the area and increasing the margin slightly would do the > trick. > > I will Bugzilla a RFE for this change to css/fedora.css shortly, but I > thought I would solicit a few comments before I commit the bug. > > -- > Paul W. Frields, RHCE > I like the idea. I noticed this as well when I was reading a document with examples but didn't want to add yet another color. Seems like just adding a box around it would set it apart enough to make it easier to read. File the RFE, and I'd be glad to add it to the CSS. Tammy From tfox at redhat.com Fri Sep 17 16:24:53 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 12:24:53 -0400 Subject: draft notice text In-Reply-To: <1095435145.4419.6.camel@berlin.east.gov> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> Message-ID: <1095438293.6112.79.camel@jadefox.rdu.redhat.com> On Fri, 2004-09-17 at 11:32, Paul W. Frields wrote: > On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > > For docs created for RHEL, etc. we decided that the URL should be part > > of the text since when the decision was made we printed the docs. So, > > our rule was, if the URL is short, it should be inline text. If it is > > long and might line wrap, include it in screen tags so it is always > > rendered on its own line. > > Would you say that the suggested usage is OK, since it is doubtful these > manuals will be printed commercially? I would expect users *might* print > them locally for reference, but most reading will be done online, I > suspect, whether off a local hard disk (installed from a fedora-docs[1] > RPM package) or the Internet. > Sure. I think most of the Fedora docs are going to be read from their HTML versions. So, I don't see any problem with having the URLs rendered as footnotes in the PDF versions. It might look a little weird if the text inside the ulink tags is the actual URL, but I don't think that is a big deal for the Fedora docs. I don't recall turning off footnotes in the Fedora stylesheets, so I'll look at it to make sure it is still rendering them for PDF versions. Do we want the footnotes to show up in the HTML versions as well? I don't think they do by default. My vote is not to show the footnotes in the HTML. Tammy > If we can turn the footnote function back on for Fedora, that would be > great IMHO. Also, I have another minor suggestion (I think for the > stylesheets) which I will post to the list and bugzilla momentarily. > > = = = = = > [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} > Couldn't resist using a footnote in a post about footnotes huh? ;-) Tammy > -- > Paul W. Frields, RHCE From tfox at redhat.com Fri Sep 17 16:35:59 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 12:35:59 -0400 Subject: draft notice text In-Reply-To: <1095438293.6112.79.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095438293.6112.79.camel@jadefox.rdu.redhat.com> Message-ID: <1095438958.6112.88.camel@jadefox.rdu.redhat.com> On Fri, 2004-09-17 at 12:24, Tammy Fox wrote: > On Fri, 2004-09-17 at 11:32, Paul W. Frields wrote: > > On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > > > For docs created for RHEL, etc. we decided that the URL should be part > > > of the text since when the decision was made we printed the docs. So, > > > our rule was, if the URL is short, it should be inline text. If it is > > > long and might line wrap, include it in screen tags so it is always > > > rendered on its own line. > > > > Would you say that the suggested usage is OK, since it is doubtful these > > manuals will be printed commercially? I would expect users *might* print > > them locally for reference, but most reading will be done online, I > > suspect, whether off a local hard disk (installed from a fedora-docs[1] > > RPM package) or the Internet. > > > > Sure. I think most of the Fedora docs are going to be read from their > HTML versions. So, I don't see any problem with having the URLs rendered > as footnotes in the PDF versions. It might look a little weird if the > text inside the ulink tags is the actual URL, but I don't think that is > a big deal for the Fedora docs. I don't recall turning off footnotes in > the Fedora stylesheets, so I'll look at it to make sure it is still > rendering them for PDF versions. > The default behavior for PDFs is to put the URL in brackets: some link [http://www.example.com/] For HTML, it just creates the href without a footnote or brackets. The brackets don't look that bad, but if the URL is too long, it doesn't line wrap. It just goes off the page. We had this problem with DSSSL and SGML for a while, but it was eventually fixed. So, it looks like footnotes in the PDFs are the way to go. Please file an RFE, and I'll look into it unless someone already knows the XSLT to add footnotes for URLs in the PDF output. Tammy > Do we want the footnotes to show up in the HTML versions as well? I > don't think they do by default. My vote is not to show the footnotes in > the HTML. > > Tammy > > > > If we can turn the footnote function back on for Fedora, that would be > > great IMHO. Also, I have another minor suggestion (I think for the > > stylesheets) which I will post to the list and bugzilla momentarily. > > > > = = = = = > > [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} > > > > Couldn't resist using a footnote in a post about footnotes huh? ;-) > > Tammy > > > -- > > Paul W. Frields, RHCE > > From paul at frields.com Fri Sep 17 16:41:25 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 17 Sep 2004 12:41:25 -0400 Subject: draft notice text In-Reply-To: <1095438293.6112.79.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095438293.6112.79.camel@jadefox.rdu.redhat.com> Message-ID: <1095439285.4419.40.camel@berlin.east.gov> On Fri, 2004-09-17 at 12:24, Tammy Fox wrote: > On Fri, 2004-09-17 at 11:32, Paul W. Frields wrote: > > On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > > > For docs created for RHEL, etc. we decided that the URL should be part > > > of the text since when the decision was made we printed the docs. So, > > > our rule was, if the URL is short, it should be inline text. If it is > > > long and might line wrap, include it in screen tags so it is always > > > rendered on its own line. > > > > Would you say that the suggested usage is OK, since it is doubtful these > > manuals will be printed commercially? I would expect users *might* print > > them locally for reference, but most reading will be done online, I > > suspect, whether off a local hard disk (installed from a fedora-docs[1] > > RPM package) or the Internet. > > > > Sure. I think most of the Fedora docs are going to be read from their > HTML versions. So, I don't see any problem with having the URLs rendered > as footnotes in the PDF versions. It might look a little weird if the > text inside the ulink tags is the actual URL, but I don't think that is > a big deal for the Fedora docs. I don't recall turning off footnotes in > the Fedora stylesheets, so I'll look at it to make sure it is still > rendering them for PDF versions. Thanks, I haven't had a chance yet. > Do we want the footnotes to show up in the HTML versions as well? I > don't think they do by default. My vote is not to show the footnotes in > the HTML. I agree. > > If we can turn the footnote function back on for Fedora, that would be > > great IMHO. Also, I have another minor suggestion (I think for the > > stylesheets) which I will post to the list and bugzilla momentarily. > > > > = = = = = > > [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} > > > Couldn't resist using a footnote in a post about footnotes huh? ;-) No, but fortunately I *could* resist doing it in this reply to a post about a footnote in a post about footnotes! (Sorry, loopy from lack of lunch.[1]) = = = = = [1] Should that be a new acronym, "LLL"? Oh no, I broke my vow of footnotelessness! AAAAGGHH! :-( :-D -- Paul W. Frields, RHCE From paul at frields.com Fri Sep 17 16:49:11 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 17 Sep 2004 12:49:11 -0400 Subject: Stylesheet for In-Reply-To: <1095438035.6112.73.camel@jadefox.rdu.redhat.com> References: <1095435568.4419.14.camel@berlin.east.gov> <1095438035.6112.73.camel@jadefox.rdu.redhat.com> Message-ID: <1095439751.4419.55.camel@berlin.east.gov> On Fri, 2004-09-17 at 12:20, Tammy Fox wrote: > On Fri, 2004-09-17 at 11:39, Paul W. Frields wrote: > > I would like to see sections take on a different rendered > > style, somewhat like the sections. I think the right way to do > > this is with an outlined box, but without changing the shade (BG color). > > That should keep an distinct from a . [...snip...] > I like the idea. I noticed this as well when I was reading a document > with examples but didn't want to add yet another color. Seems like just > adding a box around it would set it apart enough to make it easier to > read. File the RFE, and I'd be glad to add it to the CSS. Great. I tried to do it myself to see if I could send you a patch but my CSS skills apparently suck eggs. :-( It's now in Bugzilla: http://bugzilla.redhat.com/132835 -- Paul W. Frields, RHCE From davep at dpawson.co.uk Fri Sep 17 17:51:46 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 17 Sep 2004 18:51:46 +0100 Subject: draft notice text In-Reply-To: <1095435145.4419.6.camel@berlin.east.gov> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> Message-ID: <1095443505.2518.11.camel@homer> On Fri, 2004-09-17 at 16:32, Paul W. Frields wrote: > If we can turn the footnote function back on for Fedora, that would be > great IMHO. Is this project obligued to keep in step with rhel? I see it drifting further and further from docbook. Clinging to sgml is plain daft IMHO. When docbook 5 comes out will it remain with the SGML DTD? What's the objection to keeping up to date? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Fri Sep 17 18:17:25 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Fri, 17 Sep 2004 19:17:25 +0100 Subject: Stylesheet for In-Reply-To: <1095435568.4419.14.camel@berlin.east.gov> References: <1095435568.4419.14.camel@berlin.east.gov> Message-ID: <1095445044.2518.14.camel@homer> On Fri, 2004-09-17 at 16:39, Paul W. Frields wrote: > I hope this doesn't sound trivial in the face of other work; I was > actually doing substantial FDP work when the subject came up. As I was > showing my wife a section of text I had written, which included several > s, she commented that the HTML rendering was confusing because > the content itself does not significantly differ from the > surrounding content. On top of that, the caption appears below > the content. I've found CSS resolves the presentation issue, and the caption is an XSLT parameter. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Fri Sep 17 18:21:06 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 17 Sep 2004 14:21:06 -0400 Subject: Stylesheet for In-Reply-To: <1095445044.2518.14.camel@homer> References: <1095435568.4419.14.camel@berlin.east.gov> <1095445044.2518.14.camel@homer> Message-ID: <1095445266.4419.138.camel@berlin.east.gov> On Fri, 2004-09-17 at 14:17, Dave Pawson wrote: > On Fri, 2004-09-17 at 16:39, Paul W. Frields wrote: > > > I hope this doesn't sound trivial in the face of other work; I was > > actually doing substantial FDP work when the subject came up. As I was > > showing my wife a section of text I had written, which included several > > s, she commented that the HTML rendering was confusing because > > the content itself does not significantly differ from the > > surrounding content. On top of that, the caption appears below > > the content. > > I've found CSS resolves the presentation > issue, and the caption is an XSLT parameter. Thus my request to have css/fedora.css patched in CVS. :-) -- Paul W. Frields, RHCE From tfox at redhat.com Fri Sep 17 19:21:15 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 15:21:15 -0400 Subject: draft notice text In-Reply-To: <1095443505.2518.11.camel@homer> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> Message-ID: <1095448875.6112.125.camel@jadefox.rdu.redhat.com> On Fri, 2004-09-17 at 13:51, Dave Pawson wrote: > On Fri, 2004-09-17 at 16:32, Paul W. Frields wrote: > > > If we can turn the footnote function back on for Fedora, that would be > > great IMHO. > > Is this project obligued to keep in step with rhel? > > I see it drifting further and further from docbook. > Clinging to sgml is plain daft IMHO. > > When docbook 5 comes out will it remain with the SGML DTD? > What's the objection to keeping up to date? > > > -- > Regards DaveP. > XSLT&Docbook FAQ > http://www.dpawson.co.uk/xsl > > No. We are not obligated to keep in step with RHEL. We are using a different toolchain and can agree to upgrade to DocBook 5 when it comes out if we want to. When a question comes up, I have been mentioning how we solved the problem internally with our DocBook SGML toolchain to offer a solution. Sometimes we agree to do the same thing. Sometimes we agree to do something different. Tammy From kwade at redhat.com Fri Sep 17 20:13:18 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 17 Sep 2004 13:13:18 -0700 Subject: draft notice text In-Reply-To: <1095434479.6112.13.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095352094.3014.65780.camel@erato.phig.org> <1095434479.6112.13.camel@jadefox.rdu.redhat.com> Message-ID: <1095451997.4078.281.camel@erato.phig.org> On Fri, 2004-09-17 at 08:21, Tammy Fox wrote: > What part is broken? The footnote for URLs? I turned that off on purpose > in our stylesheets for our internal SGML because we decided that we > preferred the URL inline or inside screen tags if it might line wrap. I now recall working with Tim Waugh to resolve PDF conversion issues with URLs in blocks not wrapping. I was putting URLs in footnotes manually because they wouldn't appear by themselves in PDF as footnotes (inline or in blocks was not an option). It may have never occurred to me to ask about that, I might have assumed it was broken. Oh, well. :) - 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 Sep 17 20:19:47 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 17 Sep 2004 13:19:47 -0700 Subject: draft notice text In-Reply-To: <1095448875.6112.125.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> Message-ID: <1095452387.4078.311.camel@erato.phig.org> On Fri, 2004-09-17 at 12:21, Tammy Fox wrote: > On Fri, 2004-09-17 at 13:51, Dave Pawson wrote: > > On Fri, 2004-09-17 at 16:32, Paul W. Frields wrote: > > > > > If we can turn the footnote function back on for Fedora, that would be > > > great IMHO. > > > > Is this project obligued to keep in step with rhel? > > > > No. We are not obligated to keep in step with RHEL. We are using a > different toolchain and can agree to upgrade to DocBook 5 when it comes > out if we want to. When a question comes up, I have been mentioning how > we solved the problem internally with our DocBook SGML toolchain to > offer a solution. Sometimes we agree to do the same thing. Sometimes we > agree to do something different. I bring up items about the RHEL toolchain to explain the history behind a practice, which may tie in with discovering how it something works better or different in XMLS DocBook. The internal toolchain is very different from the one we are using in FDP. Point of fact, this project may define the future of the RHEL toolchain, in much the same way that Fedora Core influences RHEL. This explains some of why I personally am wrestling with these issues, I'll be working with the decisions we make now for years to come. :) - 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 Sep 17 20:22:46 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 17 Sep 2004 13:22:46 -0700 Subject: Stylesheet for In-Reply-To: <1095439751.4419.55.camel@berlin.east.gov> References: <1095435568.4419.14.camel@berlin.east.gov> <1095438035.6112.73.camel@jadefox.rdu.redhat.com> <1095439751.4419.55.camel@berlin.east.gov> Message-ID: <1095452566.4078.326.camel@erato.phig.org> On Fri, 2004-09-17 at 09:49, Paul W. Frields wrote: > http://bugzilla.redhat.com/132835 Good solution to a problem that I've noticed before without articulating 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 tfox at redhat.com Fri Sep 17 20:56:54 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 17 Sep 2004 16:56:54 -0400 Subject: Stylesheet for In-Reply-To: <1095439751.4419.55.camel@berlin.east.gov> References: <1095435568.4419.14.camel@berlin.east.gov> <1095438035.6112.73.camel@jadefox.rdu.redhat.com> <1095439751.4419.55.camel@berlin.east.gov> Message-ID: <1095454613.6112.319.camel@jadefox.rdu.redhat.com> On Fri, 2004-09-17 at 12:49, Paul W. Frields wrote: > On Fri, 2004-09-17 at 12:20, Tammy Fox wrote: > > On Fri, 2004-09-17 at 11:39, Paul W. Frields wrote: > > > I would like to see sections take on a different rendered > > > style, somewhat like the sections. I think the right way to do > > > this is with an outlined box, but without changing the shade (BG color). > > > That should keep an distinct from a . > > [...snip...] > > I like the idea. I noticed this as well when I was reading a document > > with examples but didn't want to add yet another color. Seems like just > > adding a box around it would set it apart enough to make it easier to > > read. File the RFE, and I'd be glad to add it to the CSS. > > Great. I tried to do it myself to see if I could send you a patch but my > CSS skills apparently suck eggs. :-( It's now in Bugzilla: > > http://bugzilla.redhat.com/132835 > > -- > Paul W. Frields, RHCE > Thanks for filing the bug. I added a light gray outline around examples. If anyone can think of a better color, let me know. I selected gray because I didn't really want it to stand out -- just add separation so you can tell what is part of the example and what is not. You can really see how it helps at: http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html Tammy From paul at frields.com Fri Sep 17 21:39:56 2004 From: paul at frields.com (Paul W. Frields) Date: Fri, 17 Sep 2004 17:39:56 -0400 Subject: Stylesheet for In-Reply-To: <1095454613.6112.319.camel@jadefox.rdu.redhat.com> References: <1095435568.4419.14.camel@berlin.east.gov> <1095438035.6112.73.camel@jadefox.rdu.redhat.com> <1095439751.4419.55.camel@berlin.east.gov> <1095454613.6112.319.camel@jadefox.rdu.redhat.com> Message-ID: <1095457195.22086.1.camel@bettie.internal.frields.org> On Fri, 2004-09-17 at 16:56, Tammy Fox wrote: > Thanks for filing the bug. I added a light gray outline around examples. > If anyone can think of a better color, let me know. I selected gray > because I didn't really want it to stand out -- just add separation so > you can tell what is part of the example and what is not. You can really > see how it helps at: > > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html Thanks for fixing it. The results are just what the doctor ordered! Or, in this case, the spouse. :-) -- Paul W. Frields, RHCE From kwade at redhat.com Fri Sep 17 23:17:05 2004 From: kwade at redhat.com (Karsten Wade) Date: Fri, 17 Sep 2004 16:17:05 -0700 Subject: Stylesheet for In-Reply-To: <1095454613.6112.319.camel@jadefox.rdu.redhat.com> References: <1095435568.4419.14.camel@berlin.east.gov> <1095438035.6112.73.camel@jadefox.rdu.redhat.com> <1095439751.4419.55.camel@berlin.east.gov> <1095454613.6112.319.camel@jadefox.rdu.redhat.com> Message-ID: <1095463024.4078.1099.camel@erato.phig.org> On Fri, 2004-09-17 at 13:56, Tammy Fox wrote: > Thanks for filing the bug. I added a light gray outline around examples. > If anyone can think of a better color, let me know. I selected gray > because I didn't really want it to stand out -- just add separation so > you can tell what is part of the example and what is not. You can really > see how it helps at: > > http://fedora.redhat.com/participate/documentation-guide/s1-screenshots.html /me makes a sound like "Ooooh" -- 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 Sep 18 12:24:57 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 18 Sep 2004 13:24:57 +0100 Subject: draft notice text In-Reply-To: <1095448875.6112.125.camel@jadefox.rdu.redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> Message-ID: <1095510296.2538.9.camel@homer> On Fri, 2004-09-17 at 20:21, Tammy Fox wrote: > > No. We are not obligated to keep in step with RHEL. We are using a > different toolchain and can agree to upgrade to DocBook 5 when it comes > out if we want to. When a question comes up, I have been mentioning how > we solved the problem internally with our DocBook SGML toolchain to > offer a solution. Sometimes we agree to do the same thing. Sometimes we > agree to do something different. What rationale is there for remaining with the SGML toolchain? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Sat Sep 18 18:06:05 2004 From: kwade at redhat.com (Karsten Wade) Date: Sat, 18 Sep 2004 11:06:05 -0700 Subject: draft notice text In-Reply-To: <1095510296.2538.9.camel@homer> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> Message-ID: <1095530764.4078.5271.camel@erato.phig.org> On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > What rationale is there for remaining with the SGML toolchain? Ironically, the same reason that businesses worldwide stick with old-but-working systems, where working == we hacked it to work well enough to ship. For the time to produce Enterprise Linux 4, we didn't have enough cycles to do the R&D ourselves and start writing our guides for the next release. There are significant cross-team constraints, such as having percentages of guides string and code frozen for the translation team to work on. Frankly, it was pretty daunting to imagine doing the XML toolchain all ourselves. At the time that we had to choose go/no-go on switching to XML, there were too many problems in the community tools (xmlto PDF conversion being a big one, iirc), so we had to stick with SGML. Once we started working in SGML for the production release, we had to stick with it all the way through until release. However, and here is the double-good news: because of all the good work we are doing here proving the capabilities and readiness of the latest DocBook using XML, those of us who are writing new guides (i.e., no legacy SGML) _and_ who are not being translated will get to choose to use a parallel XML toolchain based on the FDP tools for the Enterprise Linux 4 release ... well, probably nearly exactly the FDP tools with our XSL or DSSSL (again, prepared to use DSSSL just in case we can't pull the trigger on XSL in time). That means I'm writing 100% in XML, as soon as I take the few hours to convert my existing work from SGML. :-) - 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 Sep 18 18:19:48 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 18 Sep 2004 14:19:48 -0400 Subject: draft notice text In-Reply-To: <1095530764.4078.5271.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> Message-ID: <414C7C44.50501@redhat.com> Karsten Wade wrote: > On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > > >>What rationale is there for remaining with the SGML toolchain? > > However, and here is the double-good news: because of all the good work > we are doing here proving the capabilities and readiness of the latest > DocBook using XML, > those of us who are writing new guides (i.e., no > legacy SGML) _and_ who are not being translated FWIW, this includes me. I *only* write in XML. > will get to choose to > use a parallel XML toolchain based on the FDP tools for the Enterprise > Linux 4 release ... well, probably nearly exactly the FDP tools with our > XSL This is the hope, anyway. FDP certainly provides an excellent test case for a given toolchain. However, we may end up with something entirely different, like a java-based system. We may, e.g., decide that Saxon is more appropriate as an XSLT processor (due to its docbook & other extensions), and that FOP is adequate for our FO --> PDF needs, instead of having to revert to the tried & true jade/DSSSL combo for PDF output. XSLT and XSL-FO are simply easier to deal with than is DSSSL. At any rate, we won't be committing to any new toolchain (and changing all RHEL docs over to XML) until after RHEL4 is released. My $0.02, Mark > That means I'm writing 100% in XML, as soon as I take the few hours to > convert my existing work from SGML. :-) > > - Karsten -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 kwade at redhat.com Sat Sep 18 18:47:47 2004 From: kwade at redhat.com (Karsten Wade) Date: Sat, 18 Sep 2004 11:47:47 -0700 Subject: draft notice text In-Reply-To: <414C7C44.50501@redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> <414C7C44.50501@redhat.com> Message-ID: <1095533267.4078.5400.camel@erato.phig.org> On Sat, 2004-09-18 at 11:19, Mark Johnson wrote: > Karsten Wade wrote: > > will get to choose to > > use a parallel XML toolchain based on the FDP tools for the Enterprise > > Linux 4 release ... well, probably nearly exactly the FDP tools with our > > XSL > > This is the hope, anyway. FDP certainly provides an excellent test > case for a given toolchain. > > However, we may end up with something entirely different, like a > java-based system. > > We may, e.g., decide that Saxon is more appropriate as an XSLT > processor (due to its docbook & other extensions), and that FOP is > adequate for our FO --> PDF needs, instead of having to revert to > the tried & true jade/DSSSL combo for PDF output. XSLT and XSL-FO > are simply easier to deal with than is DSSSL. Well, I was specific about being general ;-) ... perhaps FDP should consider the solution you suggest for the same reasons. There is synergy that would come out of having the toolchains in alignment. - 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 Sep 18 19:55:11 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 18 Sep 2004 20:55:11 +0100 Subject: draft notice text In-Reply-To: <1095530764.4078.5271.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> Message-ID: <1095537311.3580.5.camel@homer> On Sat, 2004-09-18 at 19:06, Karsten Wade wrote: > On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > > > What rationale is there for remaining with the SGML toolchain? > > Ironically, the same reason that businesses worldwide stick with > old-but-working systems, where working == we hacked it to work well > enough to ship. > > For the time to produce Enterprise Linux 4, we didn't have enough cycles > to do the R&D ourselves and start writing our guides for the next > release. There are significant cross-team constraints, such as having > percentages of guides string and code frozen for the translation team to > work on. I gather you're speaking for rhel Karsten? I'm asking about fc2,3. > > Frankly, it was pretty daunting to imagine doing the XML toolchain all > ourselves. It was done for you, open src, 5 years ago. > At the time that we had to choose go/no-go on switching to > XML, there were too many problems in the community tools (xmlto PDF > conversion being a big one, iirc), so we had to stick with SGML. Once > we started working in SGML for the production release, we had to stick > with it all the way through until release. I made those decisions in 99. Why has it taken so long for rh to review them? Are they really so 'big blue bound'? > > That means I'm writing 100% in XML, as soon as I take the few hours to > convert my existing work from SGML. :-) Take a look at James Clarks sx. It works. The XML docbook toolchain started in 98. I see no call for pdf in fc2? So fop shouldn't be a blocker, though its probably more than good enough for our use should pdf be wanted. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Sat Sep 18 19:58:18 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sat, 18 Sep 2004 20:58:18 +0100 Subject: draft notice text In-Reply-To: <414C7C44.50501@redhat.com> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> <414C7C44.50501@redhat.com> Message-ID: <1095537498.3580.9.camel@homer> On Sat, 2004-09-18 at 19:19, Mark Johnson wrote: > > This is the hope, anyway. FDP certainly provides an excellent test > case for a given toolchain. > > However, we may end up with something entirely different, like a > java-based system. > > We may, e.g., decide that Saxon is more appropriate as an XSLT > processor (due to its docbook & other extensions), and that FOP is > adequate for our FO --> PDF needs, instead of having to revert to > the tried & true jade/DSSSL combo for PDF output. XSLT and XSL-FO > are simply easier to deal with than is DSSSL. +1. Which xslt engine is almost immaterial till we move on to xslt 2.0. I've preferred Saxon simply because it appears closer to the 1.0 rec. Apache Xalan is perfectly suited though. > > At any rate, we won't be committing to any new toolchain (and > changing all RHEL docs over to XML) until after RHEL4 is released. Which 'we' Mark? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From mjohnson at redhat.com Sat Sep 18 22:30:37 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Sat, 18 Sep 2004 18:30:37 -0400 Subject: draft notice text In-Reply-To: <1095537498.3580.9.camel@homer> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> <414C7C44.50501@redhat.com> <1095537498.3580.9.camel@homer> Message-ID: <414CB70D.7030209@redhat.com> Dave Pawson wrote: >>At any rate, we won't be committing to any new toolchain (and >>changing all RHEL docs over to XML) until after RHEL4 is released. > > > Which 'we' Mark? Whoops. By 'we" I meant the internal Red Hat docs group, not the FDP. Sorry if my statement misled anyone. Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 kwade at redhat.com Sun Sep 19 05:40:06 2004 From: kwade at redhat.com (Karsten Wade) Date: Sat, 18 Sep 2004 22:40:06 -0700 Subject: draft notice text In-Reply-To: <1095537311.3580.5.camel@homer> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> <1095537311.3580.5.camel@homer> Message-ID: <1095572405.4078.7344.camel@erato.phig.org> On Sat, 2004-09-18 at 12:55, Dave Pawson wrote: > On Sat, 2004-09-18 at 19:06, Karsten Wade wrote: > > On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > > > > > What rationale is there for remaining with the SGML toolchain? > > > > Ironically, the same reason that businesses worldwide stick with > > old-but-working systems, where working == we hacked it to work well > > enough to ship. > > > > For the time to produce Enterprise Linux 4, we didn't have enough cycles > > to do the R&D ourselves and start writing our guides for the next > > release. There are significant cross-team constraints, such as having > > percentages of guides string and code frozen for the translation team to > > work on. > I gather you're speaking for rhel Karsten? Never let it be said that I speak for RHEL ... :) ... I speak for myself only, unless otherwise stated. > I'm asking about fc2,3. I never would have guessed that. Are you asking, "What rationale is there for Fedora to use the SGML toolchain?"? Because the answer is, what are you talking about?, Fedora is not using the SGML toolchain. > > Frankly, it was pretty daunting to imagine doing the XML toolchain all > > ourselves. > It was done for you, open src, 5 years ago. [snip] > I made those decisions in 99. Why has it taken so long for rh to review > them? Are they really so 'big blue bound'? I wasn't around during all that time, so I can't speak for decisions made before I was part of the team. My explanation of how a company can get locked into using an aging system because of the difficulty of change should be explanation enough. It is a common enough occurrence. If you don't understand the example, perhaps it's because you haven't experienced it yet? It's far easier for an individual to change systems than for a company. Anyway, the point is no longer moot, since it turns out you were not asking me about RHEL. > > That means I'm writing 100% in XML, as soon as I take the few hours to > > convert my existing work from SGML. :-) > Take a look at James Clarks sx. It works. I will, thanks; that may help with existing SGML guides. Still, we've been trying to follow XML practices, and in many cases we can get away with just changing the DOCTYPE. Most of the work I have to do is around directory structure and Makefiles, I reckon. > I see no call for pdf in fc2? So fop shouldn't be a blocker, > though its probably more than good enough for our use should pdf be > wanted. PDF is wanted. I'm not personally bound to the dead tree method of documenting, but many of our readers are. An Installation Guide, for example, is a wonderful thing to be printed in front of you when you are doing your first Fedora Core install. - 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 Sun Sep 19 07:42:10 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Sun, 19 Sep 2004 08:42:10 +0100 Subject: draft notice text In-Reply-To: <1095572405.4078.7344.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> <1095537311.3580.5.camel@homer> <1095572405.4078.7344.camel@erato.phig.org> Message-ID: <1095579730.2519.9.camel@homer> On Sun, 2004-09-19 at 06:40, Karsten Wade wrote: > > I gather you're speaking for rhel Karsten? > > Never let it be said that I speak for RHEL ... :) ... I speak for myself > only, unless otherwise stated. In which case my question remains, modified. Are fc documents being processed by 'todays' tools, i.e. xslt and the current docbook stylesheets? > Because the answer is, what are you talking about?, Fedora is not using > the SGML toolchain. You refer to them so regularly Karsten, I'd presumed you were using them? > My explanation of how a company can get locked into using an aging > system because of the difficulty of change should be explanation > enough. It is a common enough occurrence. > > If you don't understand the example, perhaps it's because you haven't > experienced it yet? It's far easier for an individual to change systems > than for a company. I used DSSSL and SGML for about 12 months, then XML and its tools started to appear. I have seen what I called the 'blue' effect though. I find it repugnant, and rarely justifiable in terms of cost. > > > That means I'm writing 100% in XML, as soon as I take the few hours to > > > convert my existing work from SGML. :-) > > Take a look at James Clarks sx. It works. > > I will, thanks; that may help with existing SGML guides. A while back I moved most of the xfree-86 docs over to XML that way. Its not 100% automated, but it covers the grunt work, and leaves workable documents. > Still, we've > been trying to follow XML practices, and in many cases we can get away > with just changing the DOCTYPE. sx, with the doctype remaining that of the SGML dtd is mostly cleaner, especially for those making use of the SGML shorthands. Thereafter, a stylesheet can undo most of the remaining issues to produce a valid document. > PDF is wanted. In the fc2 documentation? I haven't seen any. Is the current fop in use? > > I'm not personally bound to the dead tree method of documenting, but > many of our readers are. Fedora readers? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From georgiq at sexmagnet.com Sun Sep 19 11:38:11 2004 From: georgiq at sexmagnet.com (GEORGiQ) Date: Sun, 19 Sep 2004 14:38:11 +0300 Subject: Release Date? Message-ID: <1095593888.2954.1.camel@georgiq.tcnet> Is it true that release date should/will be on 20 09 2004? Please reply me with the answer. Thanks From Michael.Redinger at uibk.ac.at Sun Sep 19 11:44:14 2004 From: Michael.Redinger at uibk.ac.at (Michael Redinger) Date: Sun, 19 Sep 2004 13:44:14 +0200 Subject: Release Date? In-Reply-To: <1095593888.2954.1.camel@georgiq.tcnet> References: <1095593888.2954.1.camel@georgiq.tcnet> Message-ID: <414D710E.8060706@uibk.ac.at> GEORGiQ wrote: > Is it true that release date should/will be on 20 09 2004? Please reply > me with the answer. Thanks > > > http://fedora.redhat.com/participate/schedule/ Michael -- Michael Redinger Zentraler Informatikdienst (Computer Centre) Universitaet Innsbruck Technikerstrasse 13 Tel.: ++43 512 507 2335 6020 Innsbruck Fax.: ++43 512 507 2944 Austria Mail: Michael.Redinger at uibk.ac.at BB98 D2FE 0F2C 2658 3780 3CB1 0FD7 A9D9 65C2 C11D http://www.uibk.ac.at/~c102mr/mred-pubkey.asc From kwade at redhat.com Mon Sep 20 15:06:12 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 20 Sep 2004 08:06:12 -0700 Subject: draft notice text In-Reply-To: <1095579730.2519.9.camel@homer> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> <1095537311.3580.5.camel@homer> <1095572405.4078.7344.camel@erato.phig.org> <1095579730.2519.9.camel@homer> Message-ID: <1095692771.4078.13297.camel@erato.phig.org> On Sun, 2004-09-19 at 00:42, Dave Pawson wrote: > On Sun, 2004-09-19 at 06:40, Karsten Wade wrote: > > > > I gather you're speaking for rhel Karsten? > > > > Never let it be said that I speak for RHEL ... :) ... I speak for myself > > only, unless otherwise stated. > > In which case my question remains, modified. > Are fc documents being processed by 'todays' tools, i.e. xslt > and the current docbook stylesheets? Are you asking me to open up the FDP Makefile for you? Ok ... Fedora documentation is processed using xmlto and a custom XSL that relies upon the standard DB XSL with some modifications (mostly different Booleans, iirc). fedora-docs/xsl/main-{pdf,html}.xsl > > Because the answer is, what are you talking about?, Fedora is not using > > the SGML toolchain. > > You refer to them so regularly Karsten, I'd presumed you were using > them? I'd have to do an archives search, and I'm not going to :), but I'm pretty sure I usually refer to the SGML toolchain when explaining the history behind a practice that has been carried over to Fedora docs. In other words, people such as you ask why we do something, and in part of explaining that, I give the history. Understanding where you came from is an essential part of understanding where you are today. > > My explanation of how a company can get locked into using an aging > > system because of the difficulty of change should be explanation > > enough. It is a common enough occurrence. > > > > If you don't understand the example, perhaps it's because you haven't > > experienced it yet? It's far easier for an individual to change systems > > than for a company. > I used DSSSL and SGML for about 12 months, then XML and its tools > started to appear. > I have seen what I called the 'blue' effect though. > I find it repugnant, and rarely justifiable in terms of cost. *shrug* Welcome to the real world, Dave. I'd also reckon that in terms of the real world, you are wrong that it is 'rarely' justifiable in terms of cost. I'm not an ROI expert, but I've done a fair number of enterprise assessments, and it's hard to ever know what the exact cost of an existing system. > > PDF is wanted. > In the fc2 documentation? I haven't seen any. Right, I believe there has been a problem with working conversion to PDF? > Is the current fop in use? No. Again checking in the Makefile, we are using xmlto and a custom XSL. It's not perfect. Hence the discussion to use different tools. > > > I'm not personally bound to the dead tree method of documenting, but > > many of our readers are. > Fedora readers? 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 vladeck at sezampro.yu Mon Sep 20 23:48:06 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Tue, 21 Sep 2004 01:48:06 +0200 Subject: Look of Fedora docs Message-ID: <1095724086.2633.6.camel@oxalis.delsystems.net> good day, writers. while doing some mockups of docs look for fsn.org.yu at http://www.gnome-ppp.org/fsn/template.html, i thought about doing some work for fedora community. what i want is to `upgrade the look` of fedora docs? should i try do something pretty (like novell with novell linux desktop will have) or is it a no-no? to do some mockups so you can see what i'm talking about? bye, vladeck. -- "Theres no room for ideals in this mechanical place. There has to be passion. " From sarahs at redhat.com Mon Sep 20 23:59:42 2004 From: sarahs at redhat.com (Sarah Wang) Date: Tue, 21 Sep 2004 09:59:42 +1000 Subject: Look of Fedora docs In-Reply-To: <1095724086.2633.6.camel@oxalis.delsystems.net> References: <1095724086.2633.6.camel@oxalis.delsystems.net> Message-ID: <1095724781.2696.10.camel@sarah.brisbane.redhat.com> Looks nice. I do think we should have different artwork/icons for fedora docs instead of using the same ones as in RH docs. Sarah On Tue, 2004-09-21 at 09:48, Vladimir Djokic wrote: > good day, > writers. while doing some mockups of docs look for fsn.org.yu at > http://www.gnome-ppp.org/fsn/template.html, i thought about doing some > work for fedora community. what i want is to `upgrade the look` of > fedora docs? should i try do something pretty (like novell with novell > linux desktop will have) or is it a no-no? to do some mockups so you can > see what i'm talking about? > > bye, > vladeck. > > -- > "Theres no room for ideals in this mechanical place. There has to be > passion. " > > From kwade at redhat.com Tue Sep 21 00:47:36 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 20 Sep 2004 17:47:36 -0700 Subject: SELinux FAQ editor request Message-ID: <1095727656.4078.15075.camel@erato.phig.org> Howdy all: I'm getting ready to post the SELinux FAQ for FC3test2, and it has been a little while since it has received an edit. http://people.redhat.com/kwade/fedora-docs/fc3/selinux-faq-en/ http://people.redhat.com/kwade/fedora-docs/fc3/selinux-faq-en-fc3test2-xml.tgz >From CVS: export CVSROOT=:pserver:anonymous at rhlinux.redhat.com:/usr/local/CVS cvs -z3 login cvs -z3 co fedora-docs/selinux-faq/ To be honest, it's in pretty good shape; language can always be tweaked, but I'd be surprised if there were any errors. Technical content should be accurate, but I'd like someone to confirm. :) I've updated the XML usage to (hopefully) reflect our current usage. This might be a good learning tool for someone ready to edit and who wants to learn more about how we use DocBook in FDP, as well as get a crash primer on SELinux. Because of release timing I may have to go live before I can get an editor's approval. I can quickly fix anything, if that appeases my breaking the process. ;-D 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 Sep 21 01:10:17 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 20 Sep 2004 18:10:17 -0700 Subject: Look of Fedora docs In-Reply-To: <1095724086.2633.6.camel@oxalis.delsystems.net> References: <1095724086.2633.6.camel@oxalis.delsystems.net> Message-ID: <1095729016.4078.15140.camel@erato.phig.org> On Mon, 2004-09-20 at 16:48, Vladimir Djokic wrote: > good day, > writers. while doing some mockups of docs look for fsn.org.yu at > http://www.gnome-ppp.org/fsn/template.html, i thought about doing some > work for fedora community. what i want is to `upgrade the look` of > fedora docs? should i try do something pretty (like novell with novell > linux desktop will have) or is it a no-no? to do some mockups so you can > see what i'm talking about? Yes, mockups would be good to see. I like some of the ideas I see on that page, such as a terminal icon for blocks. I haven't thought about licensing artwork. I guess you can just contribute it under the FDL? - 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 dasho at ma-isp.com Tue Sep 21 07:30:01 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Tue, 21 Sep 2004 09:30:01 +0200 Subject: About conventions In-Reply-To: <1095343737.2361.18.camel@berlin.east.gov> References: <1095246314.3014.60338.camel@erato.phig.org> <1095322666.3014.64278.camel@erato.phig.org> <1095343737.2361.18.camel@berlin.east.gov> Message-ID: <200409210930.01937.dasho@ma-isp.com> I think that adding 'sn-' etc. before each id is redundant. I have an article which has only sections and where all the ids start with 'sn-'. What is the reason for doing it like that? Can I ommit it? About the names of the files: is it a convention for doing it like this: example-tutorial-en.xml? Is there any problem if I do it like this: example_tutorial_en.xml? (does it break anything, etc.) From paul at frields.com Tue Sep 21 11:25:32 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 21 Sep 2004 07:25:32 -0400 Subject: About conventions In-Reply-To: <200409210930.01937.dasho@ma-isp.com> References: <1095246314.3014.60338.camel@erato.phig.org> <1095322666.3014.64278.camel@erato.phig.org> <1095343737.2361.18.camel@berlin.east.gov> <200409210930.01937.dasho@ma-isp.com> Message-ID: <1095765932.2293.2.camel@berlin.east.gov> On Tue, 2004-09-21 at 03:30, Dashamir Hoxha wrote: > I think that adding 'sn-' etc. before each id is redundant. I have > an article which has only sections and where all the ids start > with 'sn-'. What is the reason for doing it like that? Can I ommit it? Yes, you can probably omit it. If you search the archive for the list you'll see a discussion regarding this topic that probably doesn't bear re-hashing. > About the names of the files: is it a convention for doing it like > this: example-tutorial-en.xml? Is there any problem if I do it like > this: example_tutorial_en.xml? (does it break anything, etc.) Yes, the Makefile will break. Use "-" to simplify your life please. :-) -- Paul W. Frields, RHCE From paul at frields.com Tue Sep 21 11:38:38 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 21 Sep 2004 07:38:38 -0400 Subject: Look of Fedora docs In-Reply-To: <1095729016.4078.15140.camel@erato.phig.org> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095729016.4078.15140.camel@erato.phig.org> Message-ID: <1095766718.2293.15.camel@berlin.east.gov> On Mon, 2004-09-20 at 21:10, Karsten Wade wrote: > On Mon, 2004-09-20 at 16:48, Vladimir Djokic wrote: > > good day, > > writers. while doing some mockups of docs look for fsn.org.yu at > > http://www.gnome-ppp.org/fsn/template.html, i thought about doing some > > work for fedora community. what i want is to `upgrade the look` of > > fedora docs? should i try do something pretty (like novell with novell > > linux desktop will have) or is it a no-no? to do some mockups so you can > > see what i'm talking about? > > Yes, mockups would be good to see. I like some of the ideas I see on > that page, such as a terminal icon for blocks. > > I haven't thought about licensing artwork. I guess you can just > contribute it under the FDL? The icons used are from Fedora itself and GPL'd; I think a notice to that effect in the &LEGALNOTICE; would take care of this part. I personally don't like all the different color bars, but I think the terminal icon is cute. I also think that in the service of consistency, we should try and limit artwork to that already available in Fedora -- or, at worst, request that Garrett or one of his trusty cohort produce something consistent for us. Keep in mind also the a11y factors. The current HTML rendering provides full functionality for text-based browsers, text-to-speech engines, and so forth, with a minimum of effort. Certainly the transformations could be done to take care of this -- at least to provide tags and such, but we'd have to look at the possible impact on visually impaired users, etc. I don't doubt that there's ways around any impediments, but it's not a project I'm personally interested in. Then again, that's the great thing about having a community; someone else likely is! :-) It's early and I haven't had my coffee, so I hope this makes some sense. -- Paul W. Frields, RHCE From mjohnson at redhat.com Tue Sep 21 14:52:17 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Tue, 21 Sep 2004 10:52:17 -0400 Subject: draft notice text In-Reply-To: <1095692771.4078.13297.camel@erato.phig.org> References: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> <1095282739.3483.4.camel@borgan.devel.redhat.com> <4148B647.9030305@redhat.com> <1095286755.4433.17.camel@bettie.internal.frields.org> <1095323339.3014.64328.camel@erato.phig.org> <1095323989.3014.64368.camel@erato.phig.org> <1095342914.2361.3.camel@berlin.east.gov> <1095434637.6112.17.camel@jadefox.rdu.redhat.com> <1095435145.4419.6.camel@berlin.east.gov> <1095443505.2518.11.camel@homer> <1095448875.6112.125.camel@jadefox.rdu.redhat.com> <1095510296.2538.9.camel@homer> <1095530764.4078.5271.camel@erato.phig.org> <1095537311.3580.5.camel@homer> <1095572405.4078.7344.camel@erato.phig.org> <1095579730.2519.9.camel@homer> <1095692771.4078.13297.camel@erato.phig.org> Message-ID: <41504021.1070804@redhat.com> Karsten Wade wrote: > On Sun, 2004-09-19 at 00:42, Dave Pawson wrote: >> Is the current fop in use? > > > No. Again checking in the Makefile, we are using xmlto and a custom > XSL. xmlto is a just bash wrapper script that, for pdf, is using the passivetex macros, and hence the TeX backend. FWIW, we've[1] done some RH docs testing and found that FOP does a *much*, much better job than passivetex, esp when it comes to tables. It appears that passivetex is no longer being actively maintained. (I'll find out about this last point, as I'm currently having a discussion with the passivetex developer about a completely different issue.) [when I say we, I actually mean John Ha, the docs team tech lead:] Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 kwade at redhat.com Tue Sep 21 14:59:36 2004 From: kwade at redhat.com (Karsten Wade) Date: Tue, 21 Sep 2004 07:59:36 -0700 Subject: About conventions In-Reply-To: <1095765932.2293.2.camel@berlin.east.gov> References: <1095246314.3014.60338.camel@erato.phig.org> <1095322666.3014.64278.camel@erato.phig.org> <1095343737.2361.18.camel@berlin.east.gov> <200409210930.01937.dasho@ma-isp.com> <1095765932.2293.2.camel@berlin.east.gov> Message-ID: <1095778775.21077.70.camel@erato.phig.org> On Tue, 2004-09-21 at 04:25, Paul W. Frields wrote: > On Tue, 2004-09-21 at 03:30, Dashamir Hoxha wrote: > > I think that adding 'sn-' etc. before each id is redundant. I have > > an article which has only sections and where all the ids start > > with 'sn-'. What is the reason for doing it like that? Can I ommit it? > > Yes, you can probably omit it. If you search the archive for the list > you'll see a discussion regarding this topic that probably doesn't bear > re-hashing. Yeah, I recently decided that we should make the ID tag existence and details recommended but optional. Recommendation based on previous discussion, not worth rehashing. :) - 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 vladeck at sezampro.yu Tue Sep 21 12:38:48 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Tue, 21 Sep 2004 14:38:48 +0200 Subject: Look of Fedora docs In-Reply-To: <1095766718.2293.15.camel@berlin.east.gov> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095729016.4078.15140.camel@erato.phig.org> <1095766718.2293.15.camel@berlin.east.gov> Message-ID: <1095770328.2424.1.camel@oxalis.delsystems.net> On ???, 2004-09-21 at 07:38 -0400, Paul W. Frields wrote: > On Mon, 2004-09-20 at 21:10, Karsten Wade wrote: > > On Mon, 2004-09-20 at 16:48, Vladimir Djokic wrote: > > > good day, > > > writers. while doing some mockups of docs look for fsn.org.yu at > > > http://www.gnome-ppp.org/fsn/template.html, i thought about doing some > > > work for fedora community. what i want is to `upgrade the look` of > > > fedora docs? should i try do something pretty (like novell with novell > > > linux desktop will have) or is it a no-no? to do some mockups so you can > > > see what i'm talking about? > > > > Yes, mockups would be good to see. I like some of the ideas I see on > > that page, such as a terminal icon for blocks. > > > > ok, great: i'll do some and send you the links in da day or two. bye, vladeck. p.s. i'll consider the things you all mentioned in you emails :) -- "Theres no room for ideals in this mechanical place. There has to be passion. " From tfox at redhat.com Tue Sep 21 19:37:09 2004 From: tfox at redhat.com (Tammy Fox) Date: Tue, 21 Sep 2004 15:37:09 -0400 Subject: Look of Fedora docs In-Reply-To: <1095724781.2696.10.camel@sarah.brisbane.redhat.com> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> Message-ID: <1095795429.6122.431.camel@jadefox.rdu.redhat.com> Yes. We definitely need icons for the Fedora docs. The icons in the OS itself are GPL'ed except the ones with the Shadowman in them. The admonition icons we use for the Fedora docs are the same as the ones we use for the RHEL docs, but they are not GPL'ed: http://fedora.redhat.com/docs/selinux-faq-fc2/ln-legalnotice.html I asked Garrett about GPLing them, but he has since left the company, so it would be nice to create new ones for the Fedora docs and anyone else who wants to use them for DocBook output. We can even try to get them added to Fedora so they are installed by default. That would be ideal. As someone else said, I think the link you sent has too many colors -- they tend to distract from the content. The screen icon is nice. It looks like you are using the icons from Fedora and adding them to the HTML look and feel. If that is the case, that shouldn't be hard to implement via CSS. It would be nice to have graphics for the document navigation. Send us some mockups, and we can go from there. Tammy On Mon, 2004-09-20 at 19:59, Sarah Wang wrote: > Looks nice. I do think we should have different artwork/icons for fedora > docs instead of using the same ones as in RH docs. > > Sarah > > On Tue, 2004-09-21 at 09:48, Vladimir Djokic wrote: > > good day, > > writers. while doing some mockups of docs look for fsn.org.yu at > > http://www.gnome-ppp.org/fsn/template.html, i thought about doing some > > work for fedora community. what i want is to `upgrade the look` of > > fedora docs? should i try do something pretty (like novell with novell > > linux desktop will have) or is it a no-no? to do some mockups so you can > > see what i'm talking about? > > > > bye, > > vladeck. > > > > -- > > "Theres no room for ideals in this mechanical place. There has to be > > passion. " > > > > > From vladeck at sezampro.yu Tue Sep 21 22:06:16 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Wed, 22 Sep 2004 00:06:16 +0200 Subject: Look of Fedora docs In-Reply-To: <1095795429.6122.431.camel@jadefox.rdu.redhat.com> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> Message-ID: <1095804376.2260.0.camel@oxalis.delsystems.net> On ???, 2004-09-21 at 15:37 -0400, Tammy Fox wrote: > As someone else said, I think the link you sent has too many colors -- > they tend to distract from the content. The screen icon is nice. It > looks like you are using the icons from Fedora and adding them to the > HTML look and feel. If that is the case, that shouldn't be hard to > implement via CSS. It would be nice to have graphics for the document > navigation. Send us some mockups, and we can go from there. > > Tammy > ok, i'll do that :) bye, vladeck. -- "Theres no room for ideals in this mechanical place. There has to be passion. " From vladeck at sezampro.yu Wed Sep 22 13:11:14 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Wed, 22 Sep 2004 15:11:14 +0200 Subject: Look of Fedora docs In-Reply-To: <1095804376.2260.0.camel@oxalis.delsystems.net> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> <1095804376.2260.0.camel@oxalis.delsystems.net> Message-ID: <1095858674.2509.3.camel@oxalis.delsystems.net> On ???, 2004-09-22 at 00:06 +0200, Vladimir Djokic wrote: > > > > ok, i'll do that :) > > bye, > vladeck. > quick mockups: http://www.gnome-ppp.org/fedora/docs/network-config-ethernet.html http://www.gnome-ppp.org/fedora/docs/network-config-ethernet-2.html they're allmost the same :) bye, vladeck. -- "Theres no room for ideals in this mechanical place. There has to be passion. " From tfox at redhat.com Wed Sep 22 14:46:59 2004 From: tfox at redhat.com (Tammy Fox) Date: Wed, 22 Sep 2004 10:46:59 -0400 Subject: Look of Fedora docs In-Reply-To: <1095858674.2509.3.camel@oxalis.delsystems.net> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> <1095804376.2260.0.camel@oxalis.delsystems.net> <1095858674.2509.3.camel@oxalis.delsystems.net> Message-ID: <1095864419.6125.30.camel@jadefox.rdu.redhat.com> On Wed, 2004-09-22 at 09:11, Vladimir Djokic wrote: > On ??????, 2004-09-22 at 00:06 +0200, Vladimir Djokic wrote: > > > > > > > ok, i'll do that :) > > > > bye, > > vladeck. > > > > quick mockups: > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet.html > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet-2.html > > they're allmost the same :) > > bye, > vladeck. > > -- > "Theres no room for ideals in this mechanical place. There has to be > passion. " > > I like them. They have a nice, clean look to them. I prefer the logo on the left, but that is just my opinion. The top blue headerseems a little big. I would like to see it smaller. I would also prefer the Fedora Project logo instead of the Fedora Core logo since we might get into documenting software in Fedora Extras or Fedora Legacy. On the Fedora website, we already have a header with a logo, so we would want to use a slightly different css to not add the blue header to them. Just to make sure, did you create the icons or borrow them from somewhere else? If you borrowed them, we need to make sure they are under the GPL. I would prefer to have ones made specifically for the Fedora docs. Also, it looks like you mocked up a page of the help that is included in one of our configuration tools. Since those tools are shipped in both Fedora and RHEL, we might want to do away with the Fedora logo in the CSS for the config tools help inside the tool so the developer doesn't have to make sure the right logo is included for whatever OS he is building the package for. Thanks for doing this! Tammy From vladeck at sezampro.yu Wed Sep 22 16:18:42 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Wed, 22 Sep 2004 18:18:42 +0200 Subject: Look of Fedora docs In-Reply-To: <1095864419.6125.30.camel@jadefox.rdu.redhat.com> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> <1095804376.2260.0.camel@oxalis.delsystems.net> <1095858674.2509.3.camel@oxalis.delsystems.net> <1095864419.6125.30.camel@jadefox.rdu.redhat.com> Message-ID: <1095869922.17142.1.camel@oxalis.delsystems.net> On ???, 2004-09-22 at 10:46 -0400, Tammy Fox wrote: > I like them. They have a nice, clean look to them. I prefer the logo on > the left, but that is just my opinion. The top blue headerseems a little > big. I would like to see it smaller. I would also prefer the Fedora > Project logo instead of the Fedora Core logo since we might get into > documenting software in Fedora Extras or Fedora Legacy. > i understand > On the Fedora website, we already have a header with a logo, so we would > want to use a slightly different css to not add the blue header to them. > ok > Just to make sure, did you create the icons or borrow them from > somewhere else? If you borrowed them, we need to make sure they are > under the GPL. I would prefer to have ones made specifically for the > Fedora docs. > gtk+ docs, but will do some myself > Also, it looks like you mocked up a page of the help that is included in > one of our configuration tools. Since those tools are shipped in both > Fedora and RHEL, we might want to do away with the Fedora logo in the > CSS for the config tools help inside the tool so the developer doesn't > have to make sure the right logo is included for whatever OS he is > building the package for. > > Thanks for doing this! > Tammy > > no problem, will do some mockups again (based on suggestions) bye, vladeck. -- "Theres no room for ideals in this mechanical place. There has to be passion. " From tuxxer at cox.net Wed Sep 22 12:38:45 2004 From: tuxxer at cox.net (tuxxer) Date: Wed, 22 Sep 2004 12:38:45 +0000 Subject: Look of Fedora docs In-Reply-To: <1095864419.6125.30.camel@jadefox.rdu.redhat.com> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> <1095804376.2260.0.camel@oxalis.delsystems.net> <1095858674.2509.3.camel@oxalis.delsystems.net> <1095864419.6125.30.camel@jadefox.rdu.redhat.com> Message-ID: <1095856724.16202.212.camel@bach> On Wed, 2004-09-22 at 14:46, Tammy Fox wrote: > On Wed, 2004-09-22 at 09:11, Vladimir Djokic wrote: > > On ???, 2004-09-22 at 00:06 +0200, Vladimir Djokic wrote: > > > > > > > > > > ok, i'll do that :) > > > > > > bye, > > > vladeck. > > > > > > > quick mockups: > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet.html > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet-2.html > > > > they're allmost the same :) > > > > bye, > > vladeck. > > > > -- > > "Theres no room for ideals in this mechanical place. There has to be > > passion. " > > > > > > I like them. They have a nice, clean look to them. I prefer the logo on > the left, but that is just my opinion. The top blue headerseems a little > big. I would like to see it smaller. I would also prefer the Fedora > Project logo instead of the Fedora Core logo since we might get into > documenting software in Fedora Extras or Fedora Legacy. > > On the Fedora website, we already have a header with a logo, so we would > want to use a slightly different css to not add the blue header to them. > > Just to make sure, did you create the icons or borrow them from > somewhere else? If you borrowed them, we need to make sure they are > under the GPL. I would prefer to have ones made specifically for the > Fedora docs. > > Also, it looks like you mocked up a page of the help that is included in > one of our configuration tools. Since those tools are shipped in both > Fedora and RHEL, we might want to do away with the Fedora logo in the > CSS for the config tools help inside the tool so the developer doesn't > have to make sure the right logo is included for whatever OS he is > building the package for. > > Thanks for doing this! > Tammy I agree with what Tammy has said. My only suggestion is that I would still like to see the text links at the bottom. It's always handy to have text links in addition to image/graphical links. Otherwise, quite nice. :) -Charlie -- -- tuxxer <== tuxxer's gpg key fingerprint ==> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 -------------- 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 vladeck at sezampro.yu Wed Sep 22 21:52:59 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Wed, 22 Sep 2004 23:52:59 +0200 Subject: Look of Fedora docs In-Reply-To: <1095856724.16202.212.camel@bach> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> <1095804376.2260.0.camel@oxalis.delsystems.net> <1095858674.2509.3.camel@oxalis.delsystems.net> <1095864419.6125.30.camel@jadefox.rdu.redhat.com> <1095856724.16202.212.camel@bach> Message-ID: <1095889979.2668.4.camel@localhost.localdomain> > > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet.html > > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet-2.html another mockup: http://www.gnome-ppp.org/fedora/docs/network-config- ethernet-3.html still uses logo (white version from fedora site), bluecurve note icon and modified inverse icons (cleaned up); and makes it hard for packagin: fedora & rhel :/ will figure out how to do something better without logo... bye, vladeck. -- "Theres no room for ideals in this mechanical place. There has to be passion. " From vladeck at sezampro.yu Wed Sep 22 21:56:09 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Wed, 22 Sep 2004 23:56:09 +0200 Subject: Apacheconf docs screenshots Message-ID: <1095890169.2668.7.camel@localhost.localdomain> good day, could you please update (if already not) screenshots of apacheconf in docs, since the new is upon apacheconf? bye, vladeck. -- "Theres no room for ideals in this mechanical place. There has to be passion. " From kwade at redhat.com Thu Sep 23 01:04:13 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 22 Sep 2004 18:04:13 -0700 Subject: Apacheconf docs screenshots In-Reply-To: <1095890169.2668.7.camel@localhost.localdomain> References: <1095890169.2668.7.camel@localhost.localdomain> Message-ID: <1095901452.21077.4443.camel@erato.phig.org> On Wed, 2004-09-22 at 14:56, Vladimir Djokic wrote: > good day, > could you please update (if already not) screenshots of apacheconf in > docs, since the new is upon apacheconf? Which docs are you referring to? - 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 vladeck at sezampro.yu Thu Sep 23 14:57:36 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Thu, 23 Sep 2004 16:57:36 +0200 Subject: Apacheconf docs screenshots In-Reply-To: <1095901452.21077.4443.camel@erato.phig.org> References: <1095890169.2668.7.camel@localhost.localdomain> <1095901452.21077.4443.camel@erato.phig.org> Message-ID: <1095951457.2273.1.camel@localhost.localdomain> On ???, 2004-09-22 at 18:04 -0700, Karsten Wade wrote: > On Wed, 2004-09-22 at 14:56, Vladimir Djokic wrote: > > good day, > > could you please update (if already not) screenshots of apacheconf in > > docs, since the new is upon apacheconf? > > Which docs are you referring to? > the ones in apacheconf or system-config-httpd package. images in figs dir are old, while the ui of the app (.glade file) is new and changed a bit. would be nice that images in docs are the same as the look of app. bye, vladeck. > - 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 > > -- "Theres no room for ideals in this mechanical place. There has to be passion. " From tfox at redhat.com Thu Sep 23 15:21:38 2004 From: tfox at redhat.com (Tammy Fox) Date: Thu, 23 Sep 2004 11:21:38 -0400 Subject: Apacheconf docs screenshots In-Reply-To: <1095951457.2273.1.camel@localhost.localdomain> References: <1095890169.2668.7.camel@localhost.localdomain> <1095901452.21077.4443.camel@erato.phig.org> <1095951457.2273.1.camel@localhost.localdomain> Message-ID: <1095952897.6133.5.camel@localhost.localdomain> On Thu, 2004-09-23 at 10:57, Vladimir Djokic wrote: > On ??????, 2004-09-22 at 18:04 -0700, Karsten Wade wrote: > > On Wed, 2004-09-22 at 14:56, Vladimir Djokic wrote: > > > good day, > > > could you please update (if already not) screenshots of apacheconf in > > > docs, since the new is upon apacheconf? > > > > Which docs are you referring to? > > > > the ones in apacheconf or system-config-httpd package. images in figs > dir are old, while the ui of the app (.glade file) is new and changed a > bit. would be nice that images in docs are the same as the look of app. > > bye, > vladeck. > Will you file a bug in Bugzilla? I used to maintain those docs but don't anymore since I'm not in docs anymore. A bug in Bugzilla will remind them to keep those docs updated. Thanks, Tammy > > > - 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 > > > > > -- > "Theres no room for ideals in this mechanical place. There has to be > passion. " > > From vladeck at sezampro.yu Thu Sep 23 16:15:58 2004 From: vladeck at sezampro.yu (Vladimir Djokic) Date: Thu, 23 Sep 2004 18:15:58 +0200 Subject: Apacheconf docs screenshots In-Reply-To: <1095952897.6133.5.camel@localhost.localdomain> References: <1095890169.2668.7.camel@localhost.localdomain> <1095901452.21077.4443.camel@erato.phig.org> <1095951457.2273.1.camel@localhost.localdomain> <1095952897.6133.5.camel@localhost.localdomain> Message-ID: <1095956158.3541.7.camel@localhost.localdomain> On ???, 2004-09-23 at 11:21 -0400, Tammy Fox wrote: > On Thu, 2004-09-23 at 10:57, Vladimir Djokic wrote: > > On ???, 2004-09-22 at 18:04 -0700, Karsten Wade wrote: > > > On Wed, 2004-09-22 at 14:56, Vladimir Djokic wrote: > > > > good day, > > > > could you please update (if already not) screenshots of apacheconf in > > > > docs, since the new is upon apacheconf? > > > > > > Which docs are you referring to? > > > > > > > the ones in apacheconf or system-config-httpd package. images in figs > > dir are old, while the ui of the app (.glade file) is new and changed a > > bit. would be nice that images in docs are the same as the look of app. > > > > bye, > > vladeck. > > > > Will you file a bug in Bugzilla? I used to maintain those docs but don't > anymore since I'm not in docs anymore. A bug in Bugzilla will remind > them to keep those docs updated. > > Thanks, > Tammy > no prob. -- "Theres no room for ideals in this mechanical place. There has to be passion. " From mjohnson at redhat.com Thu Sep 23 19:12:13 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Thu, 23 Sep 2004 15:12:13 -0400 Subject: pdf toolchain notes & suggestions Message-ID: <4153200D.9010508@redhat.com> Hi All, I believe the broken part of the FDP XML -> PDF toolchain is due to the passivetex component of the TeX backend. After discussing the situation with Sebastian Rahtz, the upstream developer of passivetex, I sadly report that passivetex is no longer being developed or maintained. The last update, in fact, was in November 2003. When I asked Sebastian about the status of passivetex, here's what he had to say (he gave permission to post his remarks, BTW): > PassiveTeX does what it does, ie about 90% of FO, and thats where > its frozen. Fixing the bugs are now so hard, I cannot do them. The > decision to parse the XML using TeX seemed like a good idea, > but in practice its a dead end. If I was starting again I'd work > on a translator to plain TeX markup. thats doable, but a lot of > work. > > [...] > > I convert my XML direct to LaTeX, and process that. It gives > better results, faster :-} > > [...] > > others may disagree, but I don't see this particular path (parsing > XSLFO using xmltex) ever being able to work 100% Hence I think it's time to consider a different toolchain for pdf output. Two possibilities come to mind: FOP [1] and dblatex [2]. IMO fop would be the better choice as customizing the output requires XSL expertise, whereas dblatex requires LaTeX expertise to customize the output. If we were to adopt FOP, it would be nice to get it working under gcj (via gij), so that we stick to a 100% free toolchain, though I think it will also run under kaffe [3]. Some testing would clearly need to be done... And if such a toolchain proves sufficient for the needs of the FDP, it probably wouldn't be too difficult to find someone to package FOP. I hope this info helps us get to work on building a new XML -> PDF toolchain:) Anyway, that's my $0.02. Cheers, Mark [1] http://xml.apache.org/fop/ [2] http://dblatex.sourceforge.net/ [3] http://www.kaffe.org/ -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 kwade at redhat.com Thu Sep 23 20:30:49 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 23 Sep 2004 13:30:49 -0700 Subject: pdf toolchain notes & suggestions In-Reply-To: <4153200D.9010508@redhat.com> References: <4153200D.9010508@redhat.com> Message-ID: <1095971449.21077.5680.camel@erato.phig.org> On Thu, 2004-09-23 at 12:12, Mark Johnson wrote: > Hi All, > > I believe the broken part of the FDP XML -> PDF toolchain is due to > the passivetex component of the TeX backend. Thanks for bringing this up. Obviously most of our target output is HTML, but many readers rely upon PDF. It's been bugging me for a while that we couldn't do this properly. [snip background on broken tools] > Hence I think it's time to consider a different toolchain for pdf > output. Agreed. > Two possibilities come to mind: FOP [1] and dblatex [2]. IMO fop > would be the better choice as customizing the output requires XSL > expertise, whereas dblatex requires LaTeX expertise to customize the > output. Obviously there are going to be many ways to approach this. One reason I support the FOP choice is because of the momentum of development. This is more of a personal gut-feeling than proper research. Mainly, I think our tool choices should tie into our technical philosophy (open, works, XML) and provide us with a wide pool of knowledgeable users (DocBook, XML, XSL, FOP). > If we were to adopt FOP, it would be nice to get it working under > gcj (via gij), so that we stick to a 100% free toolchain, though I > think it will also run under kaffe [3]. Some testing would clearly > need to be done... And if such a toolchain proves sufficient for the > needs of the FDP, it probably wouldn't be too difficult to find > someone to package FOP. Can anyone step up to demonstrate a method to get FOP to compile and run using gcj and gij? *wracks his brain thinking of developers he can bargain with ...* - 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 twaugh at redhat.com Fri Sep 24 08:17:45 2004 From: twaugh at redhat.com (Tim Waugh) Date: Fri, 24 Sep 2004 09:17:45 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <4153200D.9010508@redhat.com> References: <4153200D.9010508@redhat.com> Message-ID: <20040924081745.GX23366@redhat.com> On Thu, Sep 23, 2004 at 03:12:13PM -0400, Mark Johnson wrote: > Two possibilities come to mind: FOP [1] and dblatex [2]. Another possibility would be xmlroff, if only it were further along in its development. Unfortunately it is still in its infancy and there is a lot of mark-up it doesn't handle yet. Tim. */ -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 189 bytes Desc: not available URL: From dasho at ma-isp.com Fri Sep 24 08:37:11 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Fri, 24 Sep 2004 10:37:11 +0200 Subject: pdf toolchain notes & suggestions In-Reply-To: <20040924081745.GX23366@redhat.com> References: <4153200D.9010508@redhat.com> <20040924081745.GX23366@redhat.com> Message-ID: <200409241037.11616.dasho@ma-isp.com> On Friday 24 September 2004 10:17, Tim Waugh wrote: > On Thu, Sep 23, 2004 at 03:12:13PM -0400, Mark Johnson wrote: > > Two possibilities come to mind: FOP [1] and dblatex [2]. > > Another possibility would be xmlroff, if only it were further along in > its development. Unfortunately it is still in its infancy and there > is a lot of mark-up it doesn't handle yet. Do we need all the mark-up? Do we use all the mark-up? Maybe it supports the subset of DocBook that we use. Just an idea; I don't know what is xmlroff and what it supports. From twaugh at redhat.com Fri Sep 24 08:30:51 2004 From: twaugh at redhat.com (Tim Waugh) Date: Fri, 24 Sep 2004 09:30:51 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <200409241037.11616.dasho@ma-isp.com> References: <4153200D.9010508@redhat.com> <20040924081745.GX23366@redhat.com> <200409241037.11616.dasho@ma-isp.com> Message-ID: <20040924083051.GA23366@redhat.com> On Fri, Sep 24, 2004 at 10:37:11AM +0200, Dashamir Hoxha wrote: > Do we need all the mark-up? Do we use all the mark-up? > Maybe it supports the subset of DocBook that we use. No, it doesn't support the output of docbook-xsl yet (last I looked). Tim. */ -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 189 bytes Desc: not available URL: From mjohnson at redhat.com Fri Sep 24 14:14:20 2004 From: mjohnson at redhat.com (Mark Johnson) Date: Fri, 24 Sep 2004 10:14:20 -0400 Subject: pdf toolchain notes & suggestions In-Reply-To: <1095971449.21077.5680.camel@erato.phig.org> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> Message-ID: <41542BBC.1060906@redhat.com> Karsten Wade wrote: > On Thu, 2004-09-23 at 12:12, Mark Johnson wrote: > > Obviously there are going to be many ways to approach this. One reason > I support the FOP choice is because of the momentum of development. > This is more of a personal gut-feeling than proper research. Geesh, I went to http://xml.apache.org/fop to get an idea of the development cycle and found that the latest release (0.20.5) is dated July 2003. So much for active development. (Yikes!) FWIW, we (we=some RH Docs folks) did some testing a few months ago on a doc that had the typical level of complexity that approximated our needs: variablelists, nested lists, and a number of tables. FOP produced excellent output with no funky formatting. OTOH, the passivetex output was quite messed up in a variety of ways (most of which escape me at the moment). Hence my recommedation to try FOP. But if there is a better solution, I'm all ears. My concern is simply to get the print toolchain in working order. Many people (myself included) *do* want to print out a document to read, rather than reading from a screen. Yes, we can print out the HTML, but due to the combo of chunking & formatting, the process is inefficient and can produce low-quality print copy. > > Mainly, I think our tool choices should tie into our technical > philosophy (open, works, XML) and provide us with a wide pool of > knowledgeable users (DocBook, XML, XSL, FOP). I know this may sound crazy, but if we have to, we can use the DSSSL/jade toolchain as a last-resort fallback. Of course, doing so will put some restrictions on the content of the source files (e.g. no Xincludes), but I don't see this as being a problem, as the markup used in Fedora docs is not likely to be complex. DaveP: being the resident XSL-FO expert, what fo -> pdf (or even xml -> pdf) tool(s) do you recommend? > Can anyone step up to demonstrate a method to get FOP to compile and run > using gcj and gij? Strictly speaking, we shouldn't need to recompile it under gcj, but it's a nice, safe thing to do if we're going to use gij as the java interpreter. While on vacation all next week, I'll see if I can get FOP running under gij (I need to do this for an internal project, anyway) and will report back when I return. > > *wracks his brain thinking of developers he can bargain with ...* s/bargain with/bribe/ Cheers, Mark -- ---------------------------------------------------------- Mark Johnson OS Product Documentation 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 tfox at redhat.com Fri Sep 24 16:43:03 2004 From: tfox at redhat.com (Tammy Fox) Date: Fri, 24 Sep 2004 12:43:03 -0400 Subject: pdf toolchain notes & suggestions In-Reply-To: <1095971449.21077.5680.camel@erato.phig.org> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> Message-ID: <1096044183.6116.81.camel@jadefox.rdu.redhat.com> On Thu, 2004-09-23 at 16:30, Karsten Wade wrote: > On Thu, 2004-09-23 at 12:12, Mark Johnson wrote: > > Hi All, > > > > I believe the broken part of the FDP XML -> PDF toolchain is due to > > the passivetex component of the TeX backend. > > Thanks for bringing this up. Obviously most of our target output is > HTML, but many readers rely upon PDF. It's been bugging me for a while > that we couldn't do this properly. > > [snip background on broken tools] > > > Hence I think it's time to consider a different toolchain for pdf > > output. > > Agreed. > > > Two possibilities come to mind: FOP [1] and dblatex [2]. IMO fop > > would be the better choice as customizing the output requires XSL > > expertise, whereas dblatex requires LaTeX expertise to customize the > > output. > > Obviously there are going to be many ways to approach this. One reason > I support the FOP choice is because of the momentum of development. > This is more of a personal gut-feeling than proper research. > > Mainly, I think our tool choices should tie into our technical > philosophy (open, works, XML) and provide us with a wide pool of > knowledgeable users (DocBook, XML, XSL, FOP). > Agreed. If we are going to choose a toolchain, let's try to stick to open source if possible and one that isn't going to be on the un-maintained list any time soon. Mark, thanks for bringing this up again. I hope we can find a reliable solution soon. Tammy > > If we were to adopt FOP, it would be nice to get it working under > > gcj (via gij), so that we stick to a 100% free toolchain, though I > > think it will also run under kaffe [3]. Some testing would clearly > > need to be done... And if such a toolchain proves sufficient for the > > needs of the FDP, it probably wouldn't be too difficult to find > > someone to package FOP. > > Can anyone step up to demonstrate a method to get FOP to compile and run > using gcj and gij? > > *wracks his brain thinking of developers he can bargain with ...* > > - 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 luismott at ig.com.br Sat Sep 25 22:24:31 2004 From: luismott at ig.com.br (Luis Motta) Date: Sat, 25 Sep 2004 19:24:31 -0300 Subject: Good bittorrent Client In-Reply-To: <20040925160011.2A56B73E5A@hormel.redhat.com> References: <20040925160011.2A56B73E5A@hormel.redhat.com> Message-ID: <1096151070.2644.2.camel@quantumbit.net.br> Where I find a good bit torrent client? Thaks! fedora Core 2 User Brasil (folks, it is an "S") From kwade at redhat.com Sun Sep 26 00:19:37 2004 From: kwade at redhat.com (Karsten Wade) Date: Sat, 25 Sep 2004 17:19:37 -0700 Subject: Good bittorrent Client In-Reply-To: <1096151070.2644.2.camel@quantumbit.net.br> References: <20040925160011.2A56B73E5A@hormel.redhat.com> <1096151070.2644.2.camel@quantumbit.net.br> Message-ID: <1096157977.21077.10018.camel@erato.phig.org> On Sat, 2004-09-25 at 15:24, Luis Motta wrote: > Where I find a good bit torrent client? Hi. You probably want to search the archives for fedora-list, or ask your question on that list. Fedora-docs-list is for writers to discuss writing Fedora documentation. http://www.redhat.com/archives/fedora-list But I'd like to help you, since you came this far. Perhaps one of these searches will be informative: http://www.google.com/search?q=bittorrent%20client http://www.google.com/search?q=good%20bittorrent%20client > Brasil (folks, it is an "S") Yes, it certainly is. Would you ever translate your name to "Louis" or "Louie" (pronounced "loo-ee")? Sometimes people do translate their name because it is easier than teaching everyone how to pronounce the real name correctly. :) However, this is a rude thing to do for an entire country without their permission, IMHO. - Karsten, quien se llame "Gar-stone" en espa?ol -- 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 twaugh at redhat.com Mon Sep 27 09:18:16 2004 From: twaugh at redhat.com (Tim Waugh) Date: Mon, 27 Sep 2004 10:18:16 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096044183.6116.81.camel@jadefox.rdu.redhat.com> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <1096044183.6116.81.camel@jadefox.rdu.redhat.com> Message-ID: <20040927091816.GF23366@redhat.com> On Fri, Sep 24, 2004 at 12:43:03PM -0400, Tammy Fox wrote: > Agreed. If we are going to choose a toolchain, let's try to stick to > open source if possible and one that isn't going to be on the > un-maintained list any time soon. Also, whichever tool we choose, I would love to add support to xmlto for using it. Tim. */ -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 189 bytes Desc: not available URL: From paul at frields.com Mon Sep 27 15:30:38 2004 From: paul at frields.com (Paul W. Frields) Date: Mon, 27 Sep 2004 11:30:38 -0400 Subject: Look of Fedora docs In-Reply-To: <1095864419.6125.30.camel@jadefox.rdu.redhat.com> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> <1095804376.2260.0.camel@oxalis.delsystems.net> <1095858674.2509.3.camel@oxalis.delsystems.net> <1095864419.6125.30.camel@jadefox.rdu.redhat.com> Message-ID: <1096299038.8553.6.camel@bettie.internal.frields.org> On Wed, 2004-09-22 at 10:46, Tammy Fox wrote: > > quick mockups: > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet.html > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet-2.html > > > > they're allmost the same :) > > I like them. They have a nice, clean look to them. I prefer the logo on > the left, but that is just my opinion. The top blue headerseems a little > big. I would like to see it smaller. I would also prefer the Fedora > Project logo instead of the Fedora Core logo since we might get into > documenting software in Fedora Extras or Fedora Legacy. > > On the Fedora website, we already have a header with a logo, so we would > want to use a slightly different css to not add the blue header to them. > > Just to make sure, did you create the icons or borrow them from > somewhere else? If you borrowed them, we need to make sure they are > under the GPL. I would prefer to have ones made specifically for the > Fedora docs. > > Also, it looks like you mocked up a page of the help that is included in > one of our configuration tools. Since those tools are shipped in both > Fedora and RHEL, we might want to do away with the Fedora logo in the > CSS for the config tools help inside the tool so the developer doesn't > have to make sure the right logo is included for whatever OS he is > building the package for. I agree with Tammy with one change -- I would prefer to see the navigation icons (arrows) match the ones used in Bluecurve, instead of using a different set of arrows. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Mon Sep 27 16:52:27 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 27 Sep 2004 17:52:27 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <4153200D.9010508@redhat.com> References: <4153200D.9010508@redhat.com> Message-ID: <1096303947.2497.83.camel@homer> On Thu, 2004-09-23 at 20:12, Mark Johnson wrote: > Hi All, > > I believe the broken part of the FDP XML -> PDF toolchain is due to > the passivetex component of the TeX backend. Its been pretty much unused for a long time now Mark. > > XSLFO using xmltex) ever being able to work 100% > > Hence I think it's time to consider a different toolchain for pdf > output. +1 > > Two possibilities come to mind: FOP [1] and dblatex [2]. IMO fop > would be the better choice as customizing the output requires XSL > expertise, whereas dblatex requires LaTeX expertise to customize the > output. +1 to fop. I'd guess that the majority of customisation could be done via the xslt. If not I have some familiarity with xsl-fo. http://www.oreilly.com/catalog/xslfo/index.html > > If we were to adopt FOP, it would be nice to get it working under > gcj (via gij), so that we stick to a 100% free toolchain, though I > think it will also run under kaffe [3]. Some testing would clearly > need to be done... And if such a toolchain proves sufficient for the > needs of the FDP, it probably wouldn't be too difficult to find > someone to package FOP. > > I hope this info helps us get to work on building a new XML -> PDF > toolchain:) Is there any substantial objection to using Sun java as part of a toolchain? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Mon Sep 27 16:58:51 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 27 Sep 2004 17:58:51 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <41542BBC.1060906@redhat.com> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> Message-ID: <1096304331.2497.89.camel@homer> On Fri, 2004-09-24 at 15:14, Mark Johnson wrote: > > FWIW, we (we=some RH Docs folks) did some testing a few months ago > on a doc that had the typical level of complexity that approximated > our needs: variablelists, nested lists, and a number of tables. FOP > produced excellent output with no funky formatting. OTOH, the > passivetex output was quite messed up in a variety of ways (most of > which escape me at the moment). Hence my recommedation to try FOP. The only real place that fop falls down is in the automatic layout of tables, which is also passivetext weak spot. For sensible, non-nested stuff, its more than adquate. > > I know this may sound crazy, but if we have to, we can use the > DSSSL/jade toolchain as a last-resort fallback. Of course, doing so > will put some restrictions on the content of the source files (e.g. > no Xincludes), but I don't see this as being a problem, as the > markup used in Fedora docs is not likely to be complex. An XSLT script could be used to test for nasties which would trip up a fop based toolchain. Perhaps as part of the editorial process? > > DaveP: being the resident XSL-FO expert, what fo -> pdf (or even xml > -> pdf) tool(s) do you recommend? XEP, AH, fop. There are a couple more, but despite its minimal development, there are a couple of people hard at work on fop. Its no mean feat. > > > Can anyone step up to demonstrate a method to get FOP to compile and run > > using gcj and gij? > > Strictly speaking, we shouldn't need to recompile it under gcj, but > it's a nice, safe thing to do if we're going to use gij as the java > interpreter. Is that pure NIH, or are there other reasons? Why make life hard? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From laurels at gmail.com Mon Sep 27 17:40:44 2004 From: laurels at gmail.com (Laurel) Date: Mon, 27 Sep 2004 10:40:44 -0700 Subject: Docbook quick reference card In-Reply-To: <1094674816.6176.91.camel@jadefox.rdu.redhat.com> References: <1094382209.2545.75.camel@homer> <1094397859.22071.94.camel@bettie.internal.frields.org> <1094674816.6176.91.camel@jadefox.rdu.redhat.com> Message-ID: <1a90620b040927104076188959@mail.gmail.com> Try http://www.dpawson.co.uk/docbook/docbookref.pdf On Wed, 08 Sep 2004 16:20:16 -0400, Tammy Fox wrote: > On Sun, 2004-09-05 at 11:24, Paul W. Frields wrote: > > On Sun, 2004-09-05 at 07:03, Dave Pawson wrote: > > > http://sources.redhat.com/ml/docbook-apps/2003-q2/msg00834.html > > > > > > Quick summary of the major docbook elements. > > > May be of help? > > > > I tried the link, but twistedcranium.com doesn't resolve via DNS, so I > > couldn't get to the PDF. Anyone else have any luck? > > > > -- > > Paul W. Frields, RHCE > > > > Nope. I can't get to it either. If someone knows the correct link, I'd > be glad to add it to the Docs Guide as another reference. > > Tammy > > > > > -- > fedora-docs-list mailing list > fedora-docs-list at redhat.com > To unsubscribe: > http://www.redhat.com/mailman/listinfo/fedora-docs-list > From davep at dpawson.co.uk Mon Sep 27 18:03:14 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Mon, 27 Sep 2004 19:03:14 +0100 Subject: Docbook quick reference card In-Reply-To: <1a90620b040927104076188959@mail.gmail.com> References: <1094382209.2545.75.camel@homer> <1094397859.22071.94.camel@bettie.internal.frields.org> <1094674816.6176.91.camel@jadefox.rdu.redhat.com> <1a90620b040927104076188959@mail.gmail.com> Message-ID: <1096308194.2497.94.camel@homer> On Mon, 2004-09-27 at 18:40, Laurel wrote: > Try http://www.dpawson.co.uk/docbook/docbookref.pdf Others have reported problems with it. The original author hasn't got it; I've uploaded it again, please let me know if its OK. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kwade at redhat.com Mon Sep 27 20:09:24 2004 From: kwade at redhat.com (Karsten Wade) Date: Mon, 27 Sep 2004 13:09:24 -0700 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096304331.2497.89.camel@homer> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> Message-ID: <1096315763.4619.7.camel@erato.phig.org> On Mon, 2004-09-27 at 09:58, Dave Pawson wrote: > On Fri, 2004-09-24 at 15:14, Mark Johnson wrote: > > I know this may sound crazy, but if we have to, we can use the > > DSSSL/jade toolchain as a last-resort fallback. Of course, doing so > > will put some restrictions on the content of the source files (e.g. > > no Xincludes), but I don't see this as being a problem, as the > > markup used in Fedora docs is not likely to be complex. > > An XSLT script could be used to test for nasties which would trip > up a fop based toolchain. Perhaps as part of the editorial process? I like that. Either as part of the editorial process, or as a pre-processing step in the Makefile. > > DaveP: being the resident XSL-FO expert, what fo -> pdf (or even xml > > -> pdf) tool(s) do you recommend? > > XEP, AH, fop. There are a couple more, but despite its minimal > development, there are a couple of people hard at work on fop. > Its no mean feat. AH is the tool from Antenna House? Looking over their site, I don't see a free version. FOP is entirely free, so the is the only possible choice for Fedora. Unless I missed something about XEP or AH. > > > Can anyone step up to demonstrate a method to get FOP to compile and run > > > using gcj and gij? > > > > Strictly speaking, we shouldn't need to recompile it under gcj, but > > it's a nice, safe thing to do if we're going to use gij as the java > > interpreter. > > Is that pure NIH, or are there other reasons? > Why make life hard? FOP needs to compile with a free Java compiler and run in a free Java environment to be part of a completely free toolchain. Personally, I'd prefer it to be compiled with gcj. One reason for using gcj for compiling is that if we need to report bugs with other free software, our components are going to be suspect if they have been tainted by non-free components during compiling or runtime. There are developers who will push bug reports back at us in those situations, and I support them in doing so. As hard as it may be to start, having a completely free toolchain will be blessing. - 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 Sep 28 16:20:06 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Tue, 28 Sep 2004 17:20:06 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096315763.4619.7.camel@erato.phig.org> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> Message-ID: <1096388405.2517.27.camel@homer> On Mon, 2004-09-27 at 21:09, Karsten Wade wrote: > > > Strictly speaking, we shouldn't need to recompile it under gcj, but > > > it's a nice, safe thing to do if we're going to use gij as the java > > > interpreter. > > > > Is that pure NIH, or are there other reasons? > > Why make life hard? > > FOP needs to compile with a free Java compiler and run in a free Java > environment to be part of a completely free toolchain. That's a view. I don't support it. Sun provide Java. Lets use it. > > One reason for using gcj for compiling is that if we need to report bugs > with other free software, our components are going to be suspect if they > have been tainted by non-free components during compiling or runtime. Your definition. Not mine. What's your definition of a bug in this context? Any reason we shouldn't support fop by feeding back to them? Or would you prefer to fix them on the version used here? I can't see the rationale there. > There are developers who will push bug reports back at us in those > situations, and I support them in doing so. > > As hard as it may be to start, having a completely free toolchain will > be blessing. To whom? Sounds like whipping yourself to me. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From kevin.hobbs.1 at ohiou.edu Tue Sep 28 17:02:01 2004 From: kevin.hobbs.1 at ohiou.edu (Kevin H. Hobbs) Date: Tue, 28 Sep 2004 13:02:01 -0400 Subject: kernel-compilation-tutorial Message-ID: <1096390921.15076.88.camel@gargon.hooperlab> I just got frustrated with the flame war on kernel building. I'd like to at least try to put together something along the lines of documentation. So far I've gone to the fabulous steps of: export CVSROOT=:pserver:anonymous at rhlinux.redhat.com:/usr/local/CVS cvs -z3 login cvs -z3 co fedora-docs cd fedora-docs/ cp -r example-tutorial/ kernel-compilation-tutorial cd kernel-compilation-tutorial/ mv example-tutorial-en.xml kernel-compilation-tutorial-en.xml gvim ~/.vimrc gvim kernel-compilation-tutorial-en.xml gvim Makefile make All this is useless except that the page is no longer blank. -------------- 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 kevin.hobbs.1 at ohiou.edu Tue Sep 28 18:19:10 2004 From: kevin.hobbs.1 at ohiou.edu (Kevin H. Hobbs) Date: Tue, 28 Sep 2004 14:19:10 -0400 Subject: kernel-compilation-tutorial In-Reply-To: <1096390921.15076.88.camel@gargon.hooperlab> References: <1096390921.15076.88.camel@gargon.hooperlab> Message-ID: <1096395550.15076.94.camel@gargon.hooperlab> I just hacked together what I understand form the flamewars. I am about to try to follow my own instructions now and see if I'm even close. :-) Coments are absolutely welcome. I really have no idea what I'm doing. -------------- next part -------------- A non-text attachment was scrubbed... Name: kernel-compilation-tutorial.tar.gz Type: application/x-compressed-tar Size: 16915 bytes Desc: not available URL: -------------- 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 robilad at kaffe.org Tue Sep 28 20:06:24 2004 From: robilad at kaffe.org (Dalibor Topic) Date: Tue, 28 Sep 2004 20:06:24 +0000 (UTC) Subject: pdf toolchain notes & suggestions References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> Message-ID: Dave Pawson dpawson.co.uk> writes: > > On Mon, 2004-09-27 at 21:09, Karsten Wade wrote: > > > FOP needs to compile with a free Java compiler and run in a free Java > > environment to be part of a completely free toolchain. > > That's a view. I don't support it. > Sun provide Java. Lets use it. FOP is free software. GNU/Linux is free software. There is no need to use a non-free wedge in between if equivalent[1] free software replacements exist. :) > > One reason for using gcj for compiling is that if we need to report bugs > > with other free software, our components are going to be suspect if they > > have been tainted by non-free components during compiling or runtime. > Your definition. Not mine. Some non-free java compilers are known to generate broken bytecode that nicely passes through Sun's VM, but fails to meet the constraints of the JVM specification 2nd edition. Jacks[2] is your friend if you want to verify quality of java compilers. > What's your definition of a bug in this context? A bug in the shipped bytecode introduced by a bug in a non-free compiler, obviously. You can fix the free software ones, but you can't fix the non-free ones. A cursory glance over the fixed bugs list of the JDK 1.4.2[3] suffices to show that Sun keeps finding and fixing bugs in their compiler. Relying on proprietary software for the toolchain puts a free software distributor at the disadvantage of not being able to fix the bugs themselves. They end up being at the mercy of the proprietary vendor. > Any reason we shouldn't support fop by feeding back to them? I don't see how using gcj would prevent feeding back to fop. Would you care to elaborate? > > As hard as it may be to start, having a completely free toolchain will > > be blessing. > > To whom? To everyone, obviously. Including Sun.[4] Given that Sun does not certify JDK on Fedora, what's the point in going out of one's ways in order to support it? It's not certified to be compatible anyway, therefore there is no guarantee from Sun that the JDK on Fedora will behave in the same way as the JDK on a certified distribution. Why expose oneself to issues that one has no chance of addressing? cheers, dalibor topic [1] Or better, in my obviously opiniated opinion. :) [2] http://www-124.ibm.com/developerworks/oss/cvs/jikes/jacks/ [3] http://java.sun.com/j2se/1.4.2/fixedbugs/fixedbugs.html [4] They'll finally get a break from all the people telling them how to license Java. From mark at klomp.org Tue Sep 28 20:58:32 2004 From: mark at klomp.org (Mark Wielaard) Date: Tue, 28 Sep 2004 20:58:32 +0000 (UTC) Subject: pdf toolchain notes & suggestions References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> Message-ID: Mark Johnson redhat.com> writes: > > Can anyone step up to demonstrate a method to get FOP to compile and run > > using gcj and gij? > > Strictly speaking, we shouldn't need to recompile it under gcj, but > it's a nice, safe thing to do if we're going to use gij as the java > interpreter. > > While on vacation all next week, I'll see if I can get FOP running > under gij (I need to do this for an internal project, anyway) and > will report back when I return. > > > > > *wracks his brain thinking of developers he can bargain with ...* > > s/bargain with/bribe/ For Debian people tried and (almost) succeeded. See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=271654 In general when you want to get some of these things working with a free toolchain make sure that you check how the Debian hackers are doing and/or cooperate with them: http://java.debian.net/index.php/MovingJavaToMain Last year Dalibor got most of it working with kaffe: http://www.kaffe.org/pipermail/kaffe/2003-December/096361.html We have a much more complete class library now (both kaffe and gcj use GNU Classpath as provider of the core class libraries). But you might need to use CVS versions of kaffe or gcj. Feel free to ask for support on any of the kaffe, gcj or GNU Classpath mailinglist if you try it out. Thanks, Mark From paul at frields.com Tue Sep 28 21:16:01 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 28 Sep 2004 17:16:01 -0400 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096388405.2517.27.camel@homer> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> Message-ID: <1096406161.10240.4.camel@bettie.internal.frields.org> On Tue, 2004-09-28 at 12:20, Dave Pawson wrote: > On Mon, 2004-09-27 at 21:09, Karsten Wade wrote: > > > > Strictly speaking, we shouldn't need to recompile it under gcj, but > > > > it's a nice, safe thing to do if we're going to use gij as the java > > > > interpreter. > > > > > > Is that pure NIH, or are there other reasons? > > > Why make life hard? > > > > FOP needs to compile with a free Java compiler and run in a free Java > > environment to be part of a completely free toolchain. > > That's a view. I don't support it. That's a pity, I *do* support it. > Sun provide Java. Lets use it. Adobe provides Acrobat; shall we simply use that instead? ;-) > > One reason for using gcj for compiling is that if we need to report bugs > > with other free software, our components are going to be suspect if they > > have been tainted by non-free components during compiling or runtime. > Your definition. Not mine. > What's your definition of a bug in this context? > Any reason we shouldn't support fop by feeding back to them? > Or would you prefer to fix them on the version used here? > I can't see the rationale there. A look at the kernel developers' list and searching for "Nvidia" might convince you otherwise. > > There are developers who will push bug reports back at us in those > > situations, and I support them in doing so. > > > > As hard as it may be to start, having a completely free toolchain will > > be blessing. > > To whom? > Sounds like whipping yourself to me. No, I think it's more a case that Karsten is trying to cleave to the purpose of the Fedora Project as a 100% free O/S. Violating that principle on the docs side just means that, at best, we fail to support or act on a free alternative; at worst, we support a crippled O/S. IMHO, anyone should be able to use a totally free O/S to "bootstrap" the building of any component thereof, including docs. -- Paul W. Frields, RHCE From paul at frields.com Tue Sep 28 21:46:21 2004 From: paul at frields.com (Paul W. Frields) Date: Tue, 28 Sep 2004 17:46:21 -0400 Subject: kernel-compilation-tutorial In-Reply-To: <1096395550.15076.94.camel@gargon.hooperlab> References: <1096390921.15076.88.camel@gargon.hooperlab> <1096395550.15076.94.camel@gargon.hooperlab> Message-ID: <1096407980.10240.28.camel@bettie.internal.frields.org> On Tue, 2004-09-28 at 14:19, Kevin H. Hobbs wrote: > I just hacked together what I understand form the flamewars. I am about > to try to follow my own instructions now and see if I'm even close. :-) > > Coments are absolutely welcome. I really have no idea what I'm doing. Your work is welcome. A couple hints on how to proceed: 1. Check out the Quick Start Guide [1] for an easy to read intro to how things [are supposed to] work with FDP. Especially important is the section on what you as a writer should be doing other than just working through the ideas. 2. You might want to learn enough Emacs to make your DocBook XML editing easier. I never knew more vi than I needed to get by, but learning the same amount of Emacs wasn't any more difficult. The Docs Guide [2] has a chapter on using psgml, but there's also nXML and psgmlx out there too. 3. You should include a better Introduction in your tutorial. Doing this helps you get an idea of what you want to accomplish in the tutorial, and also what you *don't* want to accomplish. That helps keep you on point and prevents your document from spinning off-topic. If you want an example, I will humbly offer my mirror-tutorial as an example. My current build is viewable at http://docs.frields.org -- you will find other docs there that are not good examples, but the mirror-tutorial follows guidelines we hashed out on the list previously. Thanks for participating! [1] http://fedora.redhat.com/participate/documentation-quick-start/ [2] http://fedora.redhat.com/participate/documentation-guide/ -- Paul W. Frields, RHCE From kevin.hobbs.1 at ohiou.edu Tue Sep 28 23:44:58 2004 From: kevin.hobbs.1 at ohiou.edu (Kevin H. Hobbs) Date: Tue, 28 Sep 2004 19:44:58 -0400 Subject: kernel-compilation-tutorial In-Reply-To: <1096407980.10240.28.camel@bettie.internal.frields.org> References: <1096390921.15076.88.camel@gargon.hooperlab> <1096395550.15076.94.camel@gargon.hooperlab> <1096407980.10240.28.camel@bettie.internal.frields.org> Message-ID: <1096415098.22877.15.camel@dhcp024-208-178-227.columbus.rr.com> On Tue, 2004-09-28 at 17:46 -0400, Paul W. Frields wrote: > On Tue, 2004-09-28 at 14:19, Kevin H. Hobbs wrote: > > I just hacked together what I understand form the flamewars. I am about > > to try to follow my own instructions now and see if I'm even close. :-) > > > > Coments are absolutely welcome. I really have no idea what I'm doing. > > Your work is welcome. A couple hints on how to proceed: > > 1. Check out the Quick Start Guide [1] for an easy to read intro to how > things [are supposed to] work with FDP. Especially important is the > section on what you as a writer should be doing other than just working > through the ideas. > Ya I read it, sigh. I was going to just make a text file but nooOOoo I get to learn how to make it all pretty. > 2. You might want to learn enough Emacs to make your DocBook XML editing > easier. I never knew more vi than I needed to get by, but learning the > same amount of Emacs wasn't any more difficult. The Docs Guide [2] has a > chapter on using psgml, but there's also nXML and psgmlx out there too. > gvim seems to be doing an ok job. It likes REALLY big indents but whatever. I'll give emacs another go though. > 3. You should include a better Introduction in your tutorial. Doing this > helps you get an idea of what you want to accomplish in the tutorial, > and also what you *don't* want to accomplish. That helps keep you on > point and prevents your document from spinning off-topic. I'll definitely want to flesh it out more for sure. I don't quite know enough to get too off topic. And the more people try to tell me to include stu > If you want an > example, I will humbly offer my mirror-tutorial as an example. My > current build is viewable at http://docs.frields.org -- you will find > other docs there that are not good examples, but the mirror-tutorial > follows guidelines we hashed out on the list previously. > > Thanks for participating! > > > [1] http://fedora.redhat.com/participate/documentation-quick-start/ > [2] http://fedora.redhat.com/participate/documentation-guide/ > -- > Paul W. Frields, RHCE I'll check those out for sure. -------------- 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 davep at dpawson.co.uk Wed Sep 29 16:29:49 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 29 Sep 2004 17:29:49 +0100 Subject: Not nice. Message-ID: <1096475389.2543.8.camel@homer> http://www.rollerweblogger.org/page/roller/20040928#fleury_on_open_source_girly -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Wed Sep 29 16:35:45 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 29 Sep 2004 17:35:45 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> Message-ID: <1096475744.2543.14.camel@homer> On Tue, 2004-09-28 at 21:06, Dalibor Topic wrote: > > Sun provide Java. Lets use it. > > FOP is free software. GNU/Linux is free software. There is no need > to use a non-free wedge in between if equivalent[1] free software > replacements exist. :) I guessed Karsten was assuming an else, rather than the if above? > > What's your definition of a bug in this context? > > A bug in the shipped bytecode introduced by a bug in a non-free compiler, > obviously. You can fix the free software ones, but you can't fix the > non-free ones. A cursory glance over the fixed bugs list of the JDK > 1.4.2[3] suffices to show that Sun keeps finding and fixing bugs in > their compiler. So... in order to use fop, we need to go hunting for bugs in alternatives to Sun's java? Not report it to the fop group? > > Relying on proprietary software for the toolchain puts a free software > distributor at the disadvantage of not being able to fix the bugs > themselves. They end up being at the mercy of the proprietary vendor. > > > Any reason we shouldn't support fop by feeding back to them? > > I don't see how using gcj would prevent feeding back to fop. Would you care > to elaborate? Just trying to put the focus where it seems to me, to belong. > > > > As hard as it may be to start, having a completely free toolchain will > > > be blessing. > > > > To whom? > > To everyone, obviously. Including Sun.[4] Certainly not obvious to me. > > Given that Sun does not certify JDK on Fedora, what's the point in going > out of one's ways in order to support it? Now that's where we differ. I'd say chasing alts to Sun java was 'going out of ones way', but never mind. I'm beginning to feel I don't fit with this logic. -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Wed Sep 29 16:40:11 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Wed, 29 Sep 2004 17:40:11 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096406161.10240.4.camel@bettie.internal.frields.org> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> Message-ID: <1096476010.2543.19.camel@homer> On Tue, 2004-09-28 at 22:16, Paul W. Frields wrote: > > > Sun provide Java. Lets use it. > > Adobe provides Acrobat; shall we simply use that instead? ;-) fop produces pdf output? > > I can't see the rationale there. > > A look at the kernel developers' list and searching for "Nvidia" might > convince you otherwise. I don't know Paul. No idea what Nvidia is. > > > As hard as it may be to start, having a completely free toolchain will > > > be blessing. > > > > To whom? > > Sounds like whipping yourself to me. > > No, I think it's more a case that Karsten is trying to cleave to the > purpose of the Fedora Project as a 100% free O/S. Violating that > principle on the docs side just means that, at best, we fail to support > or act on a free alternative; at worst, we support a crippled O/S. > > IMHO, anyone should be able to use a totally free O/S to "bootstrap" the > building of any component thereof, including docs. I guess I'd consider that an extremist view. Especially for a tool to produce documentation, a third order product. How far back does this view go? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From tfox at redhat.com Wed Sep 29 18:18:02 2004 From: tfox at redhat.com (Tammy Fox) Date: Wed, 29 Sep 2004 14:18:02 -0400 Subject: Look of Fedora docs In-Reply-To: <1096299038.8553.6.camel@bettie.internal.frields.org> References: <1095724086.2633.6.camel@oxalis.delsystems.net> <1095724781.2696.10.camel@sarah.brisbane.redhat.com> <1095795429.6122.431.camel@jadefox.rdu.redhat.com> <1095804376.2260.0.camel@oxalis.delsystems.net> <1095858674.2509.3.camel@oxalis.delsystems.net> <1095864419.6125.30.camel@jadefox.rdu.redhat.com> <1096299038.8553.6.camel@bettie.internal.frields.org> Message-ID: <1096481882.6136.274.camel@localhost.localdomain> On Mon, 2004-09-27 at 11:30, Paul W. Frields wrote: > On Wed, 2004-09-22 at 10:46, Tammy Fox wrote: > > > quick mockups: > > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet.html > > > http://www.gnome-ppp.org/fedora/docs/network-config-ethernet-2.html > > > > > > they're allmost the same :) > > > > I like them. They have a nice, clean look to them. I prefer the logo on > > the left, but that is just my opinion. The top blue headerseems a little > > big. I would like to see it smaller. I would also prefer the Fedora > > Project logo instead of the Fedora Core logo since we might get into > > documenting software in Fedora Extras or Fedora Legacy. > > > > On the Fedora website, we already have a header with a logo, so we would > > want to use a slightly different css to not add the blue header to them. > > > > Just to make sure, did you create the icons or borrow them from > > somewhere else? If you borrowed them, we need to make sure they are > > under the GPL. I would prefer to have ones made specifically for the > > Fedora docs. > > > > Also, it looks like you mocked up a page of the help that is included in > > one of our configuration tools. Since those tools are shipped in both > > Fedora and RHEL, we might want to do away with the Fedora logo in the > > CSS for the config tools help inside the tool so the developer doesn't > > have to make sure the right logo is included for whatever OS he is > > building the package for. > > I agree with Tammy with one change -- I would prefer to see the > navigation icons (arrows) match the ones used in Bluecurve, instead of > using a different set of arrows. > > -- > Paul W. Frields, RHCE > Sure. We could do that. It would definitely fit into the style of the website. Garrett doesn't work at Red Hat anymore, but I have most of his source files. The trick is finding the right ones and sizing them properly. I'll add it to my list of things to do but as a low priority because we have big news coming out about the magazine soon. ;-) Sorry I can't share just yet... Tammy From christian.huegel at redhatforum.net Wed Sep 29 20:32:48 2004 From: christian.huegel at redhatforum.net (Christian Huegel) Date: Wed, 29 Sep 2004 22:32:48 +0200 Subject: Missing end-tag in the documentation guide Message-ID: <415B1BF0.2010108@redhatforum.net> Hi everyone, i?ve noticed a small error on the documentation guide (Chapter 6.29) The line: and should be: and It?s a missing end-tag. Can you correct this? Have a nice day Christian From robilad at kaffe.org Wed Sep 29 21:06:48 2004 From: robilad at kaffe.org (Dalibor Topic) Date: Wed, 29 Sep 2004 21:06:48 +0000 (UTC) Subject: pdf toolchain notes & suggestions References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096475744.2543.14.camel@homer> Message-ID: Dave Pawson dpawson.co.uk> writes: > So... in order to use fop, we need to go hunting for bugs in > alternatives to Sun's java? No. You are welcome to hunt for bugs, though, and submit patches, bug reports, critique and sensible comments to respective projects for consideration. > Not report it to the fop group? I'd assume that the fop group would welcome bug reports from their users. cheers, dalibor topic From robilad at kaffe.org Wed Sep 29 21:09:18 2004 From: robilad at kaffe.org (Dalibor Topic) Date: Wed, 29 Sep 2004 21:09:18 +0000 (UTC) Subject: pdf toolchain notes & suggestions References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> <1096476010.2543.19.camel@homer> Message-ID: Dave Pawson dpawson.co.uk> writes: > fop produces pdf output? Yes. > I guess I'd consider that an extremist view. Especially for a tool to > produce documentation, a third order product. How far back does this > view go? > Different people have different standards. cheers, dalibor topic From Tommy.Reynolds at MegaCoder.com Wed Sep 29 22:38:29 2004 From: Tommy.Reynolds at MegaCoder.com (Tommy Reynolds) Date: Wed, 29 Sep 2004 17:38:29 -0500 Subject: Missing end-tag in the documentation guide In-Reply-To: <415B1BF0.2010108@redhatforum.net> References: <415B1BF0.2010108@redhatforum.net> Message-ID: <20040929173829.54dfb2a8.Tommy.Reynolds@MegaCoder.com> Uttered Christian Huegel , spake thus: > The line: > and linkend="s1-tutorial-parent"> Well, actually, since the content model for is EMPTY, the proper form should be: Cheers! From kwade at redhat.com Thu Sep 30 04:45:43 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 29 Sep 2004 21:45:43 -0700 Subject: Missing end-tag in the documentation guide In-Reply-To: <20040929173829.54dfb2a8.Tommy.Reynolds@MegaCoder.com> References: <415B1BF0.2010108@redhatforum.net> <20040929173829.54dfb2a8.Tommy.Reynolds@MegaCoder.com> Message-ID: <1096519542.506.6.camel@erato.phig.org> On Wed, 2004-09-29 at 15:38, Tommy Reynolds wrote: > Uttered Christian Huegel , spake thus: > > > The line: > > and > linkend="s1-tutorial-parent"> > > Well, actually, since the content model for is EMPTY, the > proper form should be: > > Ha! Another SGMLism sneaking through. Christian, can you file a bug report for this? The Product should be "Fedora Core", the component "fedora-docs", Version "devel". Thanks for the good bug catch! - 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 Sep 30 05:08:27 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 29 Sep 2004 22:08:27 -0700 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096476010.2543.19.camel@homer> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> <1096476010.2543.19.camel@homer> Message-ID: <1096520906.506.22.camel@erato.phig.org> On Wed, 2004-09-29 at 09:40, Dave Pawson wrote: > On Tue, 2004-09-28 at 22:16, Paul W. Frields wrote: > > > > No, I think it's more a case that Karsten is trying to cleave to the > > purpose of the Fedora Project as a 100% free O/S. Violating that > > principle on the docs side just means that, at best, we fail to support > > or act on a free alternative; at worst, we support a crippled O/S. > > > > IMHO, anyone should be able to use a totally free O/S to "bootstrap" the > > building of any component thereof, including docs. > > I guess I'd consider that an extremist view. Especially for a tool to > produce documentation, a third order product. How far back does this > view go? So ... should we abandon all this stuff and use Framemaker + SGML? Intel makes a proprietary C/C++ compiler, icc. Some call icc a "better" compiler because it optimizes for x86 (obvious how it gains that advantage), and these same people wonder why we should use a free compiler (gcc) since there is a better alternative available? Forget the idealism for a second. The technical reason is simple. If I write a program, compile it, and six months later get a bug report, how do I know if the bug is in my program or the compiler? I don't know, and I can't know, because I can't look at the source to figure it out. If I run my C++ program on Linux and it causes the kernel to fall over, when I report that to the kernel developers, they are going to want to see my program, including Makefile. "Gee," they will say, "this looks like you compile with Intel's proprietary compiler. Since I can't see the source code for icc, it's impossible for me to know where or what your problem is. I can't help you, sorry." Okay, they won't really say "sorry." It is impossible to debug something happening in a toolchain if there is a link in the chain that is closed source. Take the above example, substitute "XEM" for "icc" and "FOP" for "gcc". The *entirety* of Fedora _must_be_ free. The point of Fedora documentation is _not_ to build a toolchain that will run on Solaris, HP-UX, AIX, Windows, or OSX. It is to build a toolchain that runs under Fedora. To do that, the packages should be at least part of the Core packages, and in either case (Core or Extras) they _must_ be 100% free. It's not like I made up these rules, although I do approve of them with all my heart. 'Nuff said. - 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 christian.huegel at redhatforum.net Thu Sep 30 05:55:46 2004 From: christian.huegel at redhatforum.net (Christian Huegel) Date: Thu, 30 Sep 2004 07:55:46 +0200 Subject: Missing end-tag in the documentation guide In-Reply-To: <1096519542.506.6.camel@erato.phig.org> References: <415B1BF0.2010108@redhatforum.net> <20040929173829.54dfb2a8.Tommy.Reynolds@MegaCoder.com> <1096519542.506.6.camel@erato.phig.org> Message-ID: <415B9FE2.3010807@redhatforum.net> Karsten Wade wrote: > On Wed, 2004-09-29 at 15:38, Tommy Reynolds wrote: > >>Uttered Christian Huegel , spake thus: >> >> >>>The line: >>> and >>linkend="s1-tutorial-parent"> >> >>Well, actually, since the content model for is EMPTY, the >>proper form should be: >> >> > > > Ha! Another SGMLism sneaking through. > > Christian, can you file a bug report for this? The Product should be > "Fedora Core", the component "fedora-docs", Version "devel". > > Thanks for the good bug catch! > > - Karsten As good as done.. Have a nice day Christian From kwade at redhat.com Thu Sep 30 06:34:04 2004 From: kwade at redhat.com (Karsten Wade) Date: Wed, 29 Sep 2004 23:34:04 -0700 Subject: pdf toolchain notes & suggestions In-Reply-To: <4153200D.9010508@redhat.com> References: <4153200D.9010508@redhat.com> Message-ID: <1096526044.506.104.camel@erato.phig.org> On Thu, 2004-09-23 at 12:12, Mark Johnson wrote: > If we were to adopt FOP, it would be nice to get it working under > gcj (via gij), so that we stick to a 100% free toolchain, though I > think it will also run under kaffe [3]. Some testing would clearly > need to be done... And if such a toolchain proves sufficient for the > needs of the FDP, it probably wouldn't be too difficult to find > someone to package FOP. Considering that we have the attention of Kaffe.org developer(s), I'd definitely like to try parallel testing with (at least) kaffe and gcj/gij. You might think it is preferable to use what has been invented at Red Hat, where the resources exist for gcj work. It is not preferable. We all want things to be interoperable and open. Knowing that we can swap virtual machines means people get to make their own choice about free notJavaVMs. For the same reason, perhaps we can (at least) share testing data and results with Debian people tackling the same issues. It would _rock_ if we could get FOP to do everything well in all free scenarios. Perhaps an informal sub-committee? Just people interested in the topic, keep part of the conversation, and volunteer. What's next? Ideas: * Get a new sub-project into CVS (fedora-docs/toolchain? or somesuch name). Tammy, Mark, and I can commit into this for now, acting as conduits for changes from the rest of the project. * We need ** Someone from kaffe ** Someone from gcj ** A willing FOP expert (either one who knows the code and use, or a coder and an expert user) ** A DocBook XML expert (or three) ** Volunteers willing to test parallel toolchains ** A Debian liaison ** ??? * ... ? Just some ideas. I really do mean, "What's next?" - Karsten, who's volunteering for what he knows -- beta testing -- 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 dasho at ma-isp.com Thu Sep 30 07:20:36 2004 From: dasho at ma-isp.com (Dashamir Hoxha) Date: Thu, 30 Sep 2004 09:20:36 +0200 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096526044.506.104.camel@erato.phig.org> References: <4153200D.9010508@redhat.com> <1096526044.506.104.camel@erato.phig.org> Message-ID: <200409300920.36893.dasho@ma-isp.com> On Thursday 30 September 2004 08:34, Karsten Wade wrote: > * We need > ** Someone from kaffe > ** Someone from gcj > ** A willing FOP expert (either one who knows the code and use, or a > coder and an expert user) > ** A DocBook XML expert (or three) > ** Volunteers willing to test parallel toolchains I would be interested in testing toolchains, however I need some instructions on how to do it. From tfox at redhat.com Thu Sep 30 15:02:50 2004 From: tfox at redhat.com (Tammy Fox) Date: Thu, 30 Sep 2004 11:02:50 -0400 Subject: Missing end-tag in the documentation guide In-Reply-To: <415B9FE2.3010807@redhatforum.net> References: <415B1BF0.2010108@redhatforum.net> <20040929173829.54dfb2a8.Tommy.Reynolds@MegaCoder.com> <1096519542.506.6.camel@erato.phig.org> <415B9FE2.3010807@redhatforum.net> Message-ID: <1096556570.6133.16.camel@jadefox.rdu.redhat.com> On Thu, 2004-09-30 at 01:55, Christian Huegel wrote: > Karsten Wade wrote: > > On Wed, 2004-09-29 at 15:38, Tommy Reynolds wrote: > > > >>Uttered Christian Huegel , spake thus: > >> > >> > >>>The line: > >>> and >>>linkend="s1-tutorial-parent"> > >> > >>Well, actually, since the content model for is EMPTY, the > >>proper form should be: > >> > >> > > > > PSGML mode still allows me to close it with . Should we change the docs guide to use this method instead? > > Ha! Another SGMLism sneaking through. > > > > Christian, can you file a bug report for this? The Product should be > > "Fedora Core", the component "fedora-docs", Version "devel". > > > > Thanks for the good bug catch! > > > > - Karsten > > As good as done.. > > Have a nice day > > Christian I added the missing / in CVS and the website. It should appear shortly. Tammy From tfox at redhat.com Thu Sep 30 15:10:45 2004 From: tfox at redhat.com (Tammy Fox) Date: Thu, 30 Sep 2004 11:10:45 -0400 Subject: kernel-compilation-tutorial In-Reply-To: <1096415098.22877.15.camel@dhcp024-208-178-227.columbus.rr.com> References: <1096390921.15076.88.camel@gargon.hooperlab> <1096395550.15076.94.camel@gargon.hooperlab> <1096407980.10240.28.camel@bettie.internal.frields.org> <1096415098.22877.15.camel@dhcp024-208-178-227.columbus.rr.com> Message-ID: <1096557045.6133.23.camel@jadefox.rdu.redhat.com> On Tue, 2004-09-28 at 19:44, Kevin H. Hobbs wrote: > On Tue, 2004-09-28 at 17:46 -0400, Paul W. Frields wrote: > > On Tue, 2004-09-28 at 14:19, Kevin H. Hobbs wrote: > > > I just hacked together what I understand form the flamewars. I am about > > > to try to follow my own instructions now and see if I'm even close. :-) > > > > > > Coments are absolutely welcome. I really have no idea what I'm doing. > > > > Your work is welcome. A couple hints on how to proceed: > > > > 1. Check out the Quick Start Guide [1] for an easy to read intro to how > > things [are supposed to] work with FDP. Especially important is the > > section on what you as a writer should be doing other than just working > > through the ideas. > > > > Ya I read it, sigh. I was going to just make a text file but nooOOoo I > get to learn how to make it all pretty. > > > 2. You might want to learn enough Emacs to make your DocBook XML editing > > easier. I never knew more vi than I needed to get by, but learning the > > same amount of Emacs wasn't any more difficult. The Docs Guide [2] has a > > chapter on using psgml, but there's also nXML and psgmlx out there too. > > > > gvim seems to be doing an ok job. It likes REALLY big indents but > whatever. I'll give emacs another go though. > > > 3. You should include a better Introduction in your tutorial. Doing this > > helps you get an idea of what you want to accomplish in the tutorial, > > and also what you *don't* want to accomplish. That helps keep you on > > point and prevents your document from spinning off-topic. > > I'll definitely want to flesh it out more for sure. I don't quite know > enough to get too off topic. And the more people try to tell me to > include stu > > > If you want an > > example, I will humbly offer my mirror-tutorial as an example. My > > current build is viewable at http://docs.frields.org -- you will find > > other docs there that are not good examples, but the mirror-tutorial > > follows guidelines we hashed out on the list previously. > > > > Thanks for participating! > > > > > > [1] http://fedora.redhat.com/participate/documentation-quick-start/ > > [2] http://fedora.redhat.com/participate/documentation-guide/ > > -- > > Paul W. Frields, RHCE > > > I'll check those out for sure. > > ______________________________________________________________________ Kevin, Thanks for writing this. It is a much needed tutorial. I moved the open bug to block the docs in progress tracker instead. I co-authored an article in the first issue of Wide Open Magazine about the 2.6 kernel, including how to recompile it. I'll compare your version with mine and see if I can add to it. Please send me your latest version if you have made any changes since the version you posted and I can send you a patch. Or, if you prefer I can just list the changes in an email. Let me know which you prefer. Cheers, Tammy Tammy From davep at dpawson.co.uk Thu Sep 30 15:36:41 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 30 Sep 2004 16:36:41 +0100 Subject: Missing end-tag in the documentation guide In-Reply-To: <1096519542.506.6.camel@erato.phig.org> References: <415B1BF0.2010108@redhatforum.net> <20040929173829.54dfb2a8.Tommy.Reynolds@MegaCoder.com> <1096519542.506.6.camel@erato.phig.org> Message-ID: <1096558600.2517.9.camel@homer> On Thu, 2004-09-30 at 05:45, Karsten Wade wrote: > On Wed, 2004-09-29 at 15:38, Tommy Reynolds wrote: > > Uttered Christian Huegel , spake thus: > > > > > The line: > > > and > > linkend="s1-tutorial-parent"> > > > > Well, actually, since the content model for is EMPTY, the > > proper form should be: > > > > > > Ha! Another SGMLism sneaking through. No Karsten. This came in with XML 1.0. An SGML empty element is It was one of the 'short cuts'? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Thu Sep 30 15:42:57 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 30 Sep 2004 16:42:57 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096520906.506.22.camel@erato.phig.org> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> <1096476010.2543.19.camel@homer> <1096520906.506.22.camel@erato.phig.org> Message-ID: <1096558977.2517.16.camel@homer> On Thu, 2004-09-30 at 06:08, Karsten Wade wrote: > > I guess I'd consider that an extremist view. Especially for a tool to > > produce documentation, a third order product. How far back does this > > view go? > > So ... should we abandon all this stuff and use Framemaker + SGML? More extremism Karsten? > > Forget the idealism for a second. The technical reason is simple. > > If I write a program, compile it, and six months later get a bug report, > how do I know if the bug is in my program or the compiler? I don't > know, and I can't know, because I can't look at the source to figure it > out. Practically speaking, would you be able to resolve compiler bugs? I know I wouldn't. > It is impossible to debug something happening in a toolchain if there is > a link in the chain that is closed source. To which I'd posit the notion of limited sphere of influence. I.e. I'm unlikely to use fop in such a way that I'd break the compiler. > The *entirety* of Fedora _must_be_ free. If that's your position I've no problem with that. I'll guess that Tammy won't come in on this debate, so I'll ask how/if/whether that position is supported by others in this group? I personally don't think its reasonable for documentation. > The point of Fedora > documentation is _not_ to build a toolchain that will run on Solaris, > HP-UX, AIX, Windows, or OSX. It is to build a toolchain that runs under > Fedora. To do that, the packages should be at least part of the Core > packages, and in either case (Core or Extras) they _must_ be 100% free. > > It's not like I made up these rules, although I do approve of them with > all my heart. OK lets blame someone else. My usual question now follows. Who? Can you point to a document/person/project manager who has this documented somewhere? -- Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From davep at dpawson.co.uk Thu Sep 30 15:49:01 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 30 Sep 2004 16:49:01 +0100 Subject: Missing end-tag in the documentation guide In-Reply-To: <1096556570.6133.16.camel@jadefox.rdu.redhat.com> References: <415B1BF0.2010108@redhatforum.net> <20040929173829.54dfb2a8.Tommy.Reynolds@MegaCoder.com> <1096519542.506.6.camel@erato.phig.org> <415B9FE2.3010807@redhatforum.net> <1096556570.6133.16.camel@jadefox.rdu.redhat.com> Message-ID: <1096559341.2517.21.camel@homer> On Thu, 2004-09-30 at 16:02, Tammy Fox wrote: > > >>Well, actually, since the content model for is EMPTY, the > > >>proper form should be: > > >> > > >> > > > > > > > > PSGML mode still allows me to close it with . Should we change > the docs guide to use this method instead? Either is syntactically correct according to XML 1.0 production 44 [1]. psgml isn't a good validator, its author admits as much. My preference is for rxp for a validator. For the example above, I guess might be nominally preferable. [1]http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-eetag Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl From paul at frields.com Thu Sep 30 17:47:50 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 30 Sep 2004 13:47:50 -0400 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096558977.2517.16.camel@homer> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> <1096476010.2543.19.camel@homer> <1096520906.506.22.camel@erato.phig.org> <1096558977.2517.16.camel@homer> Message-ID: <1096566469.3622.27.camel@berlin.east.gov> On Thu, 2004-09-30 at 11:42, Dave Pawson wrote: > On Thu, 2004-09-30 at 06:08, Karsten Wade wrote: > > > > I guess I'd consider that an extremist view. Especially for a tool to > > > produce documentation, a third order product. How far back does this > > > view go? > > > > So ... should we abandon all this stuff and use Framemaker + SGML? > More extremism Karsten? Your use of the word "extremism" is ungracious. I would recommend you take a look again at the Fedora Project overall goals: "The goal of The Fedora Project is to work with the Linux community to build a complete, general purpose operating system exclusively from free software." The Docs Project, which is part of the overall Fedora Project, builds documentation which is to eventually be included in the operating system, as a fedora-docs RPM I would imagine. Any .src.rpm in the Fedora tree should be buildable on Fedora itself, with free software. Karsten's point -- which is the same as my earlier point in essenc, I think, although Karsten may correct me if I'm wrong -- is that when we add non-free tools to the toolchain we break the project. Period. I don't know much about some of the tools whose names have been bandied about, but that's irrelevant. What is relevant is their status as free software (or otherwise). If it's not free we shouldn't be using it. To do otherwise runs directly counter to the ambitions of the Project. It's not about being a zealot; it's about simply accepting the goals of the &FP; and the &FDP;. They are what they are, and our project either follows them or gets jettisoned. > > Forget the idealism for a second. The technical reason is simple. > > > > If I write a program, compile it, and six months later get a bug report, > > how do I know if the bug is in my program or the compiler? I don't > > know, and I can't know, because I can't look at the source to figure it > > out. > Practically speaking, would you be able to resolve compiler bugs? > I know I wouldn't. Your skills, my skills, and/or Karsten's skills are not particularly relevant to the discussion either. You're missing the forest for the trees here. What Karsten is saying, I think, is that any reliance on non-free software puts us at the mercy of that tool. You or I might not be able to resolve compiler bugs, but there are plenty of people working (either now or in the future) on FDP that could. If any of those people can't resolve problems because the software isn't free for them to examine, suggest changes, or fix, then the toolchain is broken by definition. Making a decision that ties those people's hands based on our own personal experience or skill set is poor planning and a Bad Idea(tm). > > It is impossible to debug something happening in a toolchain if there is > > a link in the chain that is closed source. > To which I'd posit the notion of limited sphere of influence. > I.e. I'm unlikely to use fop in such a way that I'd break the compiler. Again, your specific case does not override the rule, by which I mean, the fact that *you* wouldn't use it in that way doesn't mean that *no one* would do so. In fact, can you guarantee that this problem would never occur? If you can, I need your help with my investments! :-) > > The *entirety* of Fedora _must_be_ free. > > If that's your position I've no problem with that. > I'll guess that Tammy won't come in on this debate, so > I'll ask how/if/whether that position is supported by others > in this group? > I personally don't think its reasonable for documentation. I don't see why Tammy *wouldn't* enter into this debate. She has done this kind of work for a while as well, from what I understand, and probably has some insight too. I'm in agreement with Karsten, for the reasons stated in my topmost comments. > > The point of Fedora > > documentation is _not_ to build a toolchain that will run on Solaris, > > HP-UX, AIX, Windows, or OSX. It is to build a toolchain that runs under > > Fedora. To do that, the packages should be at least part of the Core > > packages, and in either case (Core or Extras) they _must_ be 100% free. > > > > It's not like I made up these rules, although I do approve of them with > > all my heart. > > OK lets blame someone else. > My usual question now follows. Who? > > Can you point to a document/person/project manager who has this > documented somewhere? There's no reason to "blame" anyone. The goals of the Fedora Project are axiomatic -- or more correctly, maxims, meaning they are principles that we accept when we participate. Anyone who doesn't agree with them is free to move ahead with their own project. These goals, and their antecedents (see above), are not really something subject to discussion and mitigation. -- Paul W. Frields, RHCE From davep at dpawson.co.uk Thu Sep 30 18:03:46 2004 From: davep at dpawson.co.uk (Dave Pawson) Date: Thu, 30 Sep 2004 19:03:46 +0100 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096566469.3622.27.camel@berlin.east.gov> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> <1096476010.2543.19.camel@homer> <1096520906.506.22.camel@erato.phig.org> <1096558977.2517.16.camel@homer> <1096566469.3622.27.camel@berlin.east.gov> Message-ID: <1096567425.2517.55.camel@homer> On Thu, 2004-09-30 at 18:47, Paul W. Frields wrote: > > > So ... should we abandon all this stuff and use Framemaker + SGML? > > More extremism Karsten? > > Your use of the word "extremism" is ungracious. I would recommend you > take a look again at the Fedora Project overall goals: I use extreme in its simplest form Paul. Out at one end. I never mentioned Frame or SGML in this thread. > > "The goal of The Fedora Project is to work with the Linux community to > build a complete, general purpose operating system exclusively from free > software." > > The Docs Project, which is part of the overall Fedora Project, builds > documentation which is to eventually be included in the operating > system, as a fedora-docs RPM I would imagine. Any .src.rpm in the Fedora > tree should be buildable on Fedora itself, with free software. Karsten's > point -- which is the same as my earlier point in essenc, I think, > although Karsten may correct me if I'm wrong -- is that when we add > non-free tools to the toolchain we break the project. Period. OK, that's enough for me. > > I don't know much about some of the tools whose names have been bandied > about, but that's irrelevant. What is relevant is their status as free > software (or otherwise). If it's not free we shouldn't be using it. To > do otherwise runs directly counter to the ambitions of the Project. Set by RH? A commercial supplier. > It's > not about being a zealot; it's about simply accepting the goals of the > &FP; and the &FDP;. They are what they are, and our project either > follows them or gets jettisoned. There are other options. > > Your skills, my skills, and/or Karsten's skills are not particularly > relevant to the discussion either. You're missing the forest for the > trees here. What Karsten is saying, I think, is that any reliance on > non-free software puts us at the mercy of that tool. I'd use the word extreme again. I really don't believe the statement above. > I'm in agreement with Karsten, for the > reasons stated in my topmost comments. OK. > > > > OK lets blame someone else. > > My usual question now follows. Who? > > > > Can you point to a document/person/project manager who has this > > documented somewhere? > > There's no reason to "blame" anyone. The goals of the Fedora Project are > axiomatic -- or more correctly, maxims, meaning they are principles that > we accept when we participate. Anyone who doesn't agree with them is > free to move ahead with their own project. These goals, and their > antecedents (see above), are not really something subject to discussion > and mitigation. So much for community development? Bye. From paul at frields.com Thu Sep 30 20:13:43 2004 From: paul at frields.com (Paul W. Frields) Date: Thu, 30 Sep 2004 16:13:43 -0400 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096567425.2517.55.camel@homer> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> <1096476010.2543.19.camel@homer> <1096520906.506.22.camel@erato.phig.org> <1096558977.2517.16.camel@homer> <1096566469.3622.27.camel@berlin.east.gov> <1096567425.2517.55.camel@homer> Message-ID: <1096575223.4594.87.camel@berlin.east.gov> On Thu, 2004-09-30 at 14:03, Dave Pawson wrote: > On Thu, 2004-09-30 at 18:47, Paul W. Frields wrote: > > > > > So ... should we abandon all this stuff and use Framemaker + SGML? > > > More extremism Karsten? > > > > Your use of the word "extremism" is ungracious. I would recommend you > > take a look again at the Fedora Project overall goals: > I use extreme in its simplest form Paul. Out at one end. I never > mentioned Frame or SGML in this thread. Dave, I understand that you did not bring up Framemaker or SGML, but you sound like you're being deliberately obtuse here. Karsten's reply is not about either of those things in specific. You originally said that using Sun's Java would be fine. According to the Fedora Project goals, which you seem to agree with below, that's *not* fine. What Karsten is trying to tell you above is that if we follow the logic of using whatever works, even if it's not free, because that approach is expedient in this particular case, that's what's referred to as a "slippery slope" argument in logic/philosophy. If it's OK to do it then, why not use a doc-building tool that's even "less free"? Why use free tools at all for docs? Why use them for building the O/S itself? Do you see what I'm getting at? I think this was the point Karsten was making. He killed the horse with a single, subtle shot, whereas I am now beating its dead, flyblown corpse. :-P (yuck, sorry) > > "The goal of The Fedora Project is to work with the Linux community to > > build a complete, general purpose operating system exclusively from free > > software." > > > > The Docs Project, which is part of the overall Fedora Project, builds > > documentation which is to eventually be included in the operating > > system, as a fedora-docs RPM I would imagine. Any .src.rpm in the Fedora > > tree should be buildable on Fedora itself, with free software. Karsten's > > point -- which is the same as my earlier point in essenc, I think, > > although Karsten may correct me if I'm wrong -- is that when we add > > non-free tools to the toolchain we break the project. Period. > > OK, that's enough for me. Well OK, by this statement, are you saying, "I agree with the goals of the Fedora Project"? Because if that's what you're saying, we can proceed with argument (the word "argument" here in its good sense, not "mindless bickering," which I'm sure you don't want any more than I do). If not, there's really no way to discuss this subject. > > I don't know much about some of the tools whose names have been bandied > > about, but that's irrelevant. What is relevant is their status as free > > software (or otherwise). If it's not free we shouldn't be using it. To > > do otherwise runs directly counter to the ambitions of the Project. > Set by RH? A commercial supplier. Dave, am I mistaking a tone of "beware the Red (Hat) Menace" in some of your posts? The Project goals are pretty clear, and have been since the Fedora Project was started by Warren Togami: http://www.newsforge.com/article.pl?sid=03/10/01/1417208&mode=thread&tid=51 It's about partnership, not dictatorship. No one has to partner up with Fedora who isn't interested in its goals. Commercial interests are not mutually exclusive with the interests of the free software community. Even RMS agrees with that. > > It's > > not about being a zealot; it's about simply accepting the goals of the > > &FP; and the &FDP;. They are what they are, and our project either > > follows them or gets jettisoned. > There are other options. Sure; for one thing, people are free to fork if desired. But they lose some of the infrastructure that Red Hat will be providing for the &FP; in that case. And it may be slow in coming, but it is coming. > > Your skills, my skills, and/or Karsten's skills are not particularly > > relevant to the discussion either. You're missing the forest for the > > trees here. What Karsten is saying, I think, is that any reliance on > > non-free software puts us at the mercy of that tool. > I'd use the word extreme again. > I really don't believe the statement above. How so? You make a sweeping pronouncement that you don't believe it, but you don't support your position with logic. I'm willing to admit I'm completely off-base but only if you can prove it to me. > > I'm in agreement with Karsten, for the > > reasons stated in my topmost comments. > > OK. > > > OK lets blame someone else. > > > My usual question now follows. Who? > > > > > > Can you point to a document/person/project manager who has this > > > documented somewhere? > > > > There's no reason to "blame" anyone. The goals of the Fedora Project are > > axiomatic -- or more correctly, maxims, meaning they are principles that > > we accept when we participate. Anyone who doesn't agree with them is > > free to move ahead with their own project. These goals, and their > > antecedents (see above), are not really something subject to discussion > > and mitigation. > > So much for community development? > Bye. Any project, whether it's about free software in one's spare time, or at one's full-time workplace, has to have goals. The goals must be agreed upon by participants. In some cases, "agreed upon" == "agreed to", especially when the goals are established prior to gaining participants. Again, they're maxims, so if you buy the goals, you now have at least very basic rules for completing any task under the project. When I participate in a project in the free software world, I buy into the goals for the project. There's no barrier to entry; I just decide, "that sounds good to me," and jump in. If I change my mind, no one bars my exit either. I can even take the product with me and change it however I like, but I then have to either (1) get other people to help me, or (2) do it all myself. If I buy into the goals, though, everything else follows. 100% free means just what it says. Our docs are supposed to be buildable under Fedora, as it is, 100% free, not with third-party proprietary add-ons. I hope this is easier to understand than what I first wrote, if that was confusing. -- Paul W. Frields, RHCE From kwade at redhat.com Thu Sep 30 20:55:55 2004 From: kwade at redhat.com (Karsten Wade) Date: Thu, 30 Sep 2004 13:55:55 -0700 Subject: pdf toolchain notes & suggestions In-Reply-To: <1096575223.4594.87.camel@berlin.east.gov> References: <4153200D.9010508@redhat.com> <1095971449.21077.5680.camel@erato.phig.org> <41542BBC.1060906@redhat.com> <1096304331.2497.89.camel@homer> <1096315763.4619.7.camel@erato.phig.org> <1096388405.2517.27.camel@homer> <1096406161.10240.4.camel@bettie.internal.frields.org> <1096476010.2543.19.camel@homer> <1096520906.506.22.camel@erato.phig.org> <1096558977.2517.16.camel@homer> <1096566469.3622.27.camel@berlin.east.gov> <1096567425.2517.55.camel@homer> <1096575223.4594.87.camel@berlin.east.gov> Message-ID: <1096577754.506.613.camel@erato.phig.org> On Thu, 2004-09-30 at 13:13, Paul W. Frields wrote: > Do you see what I'm getting at? I think this was the point Karsten was > making. He killed the horse with a single, subtle shot, whereas I am now > beating its dead, flyblown corpse. :-P (yuck, sorry) I think both you and Dalibor were eloquent and accurate, and I think the three of us are all essentially saying the same thing. "Free is free is free." When you introduce non-free, you get a chain like this: "Free is free is not-free." Ooops, broken. Here is the bottom line -- we will *not* be able to put a non-free toolchain in Fedora. We might as well rename our project and do something else, if that is what we are going to do. The Fedora community won't stand for it, packages won't get included, etc. However, if we do the right thing and remain 100% free, then we get the entire community's support. Meaning compiler engineers will debug our compiler problems for us. :) The fact is, no matter what we choose, there will be bugs to fix now and later. Proprietary software is not free of bugs, it's just free of the ability to fix it yourself _within_your_community_. On Thu, 2004-09-30 at 14:03, Dave Pawson wrote: > > So much for community development? > > > Bye. Dave, if this is truly a good-bye, I'm sorry to see you go. You have brought a perspective and opinion that, at least, keeps us on our toes. I don't always agree with you, that's obvious, but I appreciate your input, energy, focus, passion, community spirit, and expertise. On the last item, the project needs your contributions to the present and future toolchain, whether done as part of this project, or just in the work you do otherwise. However, if you are not playing Devil's advocate or are just troll-baiting for the fun of it, and you _truly_ disagree with these simple fundamentals of free software development, then I can't see how we can work together within the Fedora documentation project. If there is something you are not understanding or appreciating about free software and the reality of open source development, I will be happy to continue to explain. At the moment, it sounds as if we are at an impasse, in that you disagree with the most basic concepts at the heart of Fedora. - 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