From miles at brennan.id.au Sat Sep 3 03:30:32 2005 From: miles at brennan.id.au (Miles Brennan) Date: Sat, 03 Sep 2005 07:30:32 +0400 Subject: Submission: Home Server Setup Guide Message-ID: <431918D8.3060009@brennan.id.au> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 G'day to all, As Karsten queried a few weeks earlier, yes I?m one of those lurking, too busy at the moment, don't know where to begin, never used CVS and not sure what to do - classic post and you caught me out ;) Over the new year break I wrote the 'Linux Home Server HOWTO' (http://www.brennan.id.au). It is a complete HOWTO for setting up a Linux gateway server connected to the Internet and providing network resources to the internal workstations (MS/Linux). Firewall/Samba/DNS/NTP/FTP guides etc... It was originally written for FC3 so some of it may need a little tweaking as I haven't yet updated it. However it is a complete HOWTO, 20 chapters in all (~180 pages when printed). I now offer it for comment / criticism / appraisal / submission. I would prefer to keep the content / concept complete if possible, but open to suggestions. BTW, hello list :) Regards, Miles. -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (MingW32) Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org iD8DBQFDGRjY1zxPeMAaUBIRAve3AJwPRzVBVakuVgy63vlCt9JosHYnlACfWT+d akTBrjZYqkYnWGg9d1Cm4p0= =sP7T -----END PGP SIGNATURE----- From kwade at redhat.com Sat Sep 3 16:58:23 2005 From: kwade at redhat.com (Karsten Wade) Date: Sat, 03 Sep 2005 09:58:23 -0700 Subject: quick update about translation for FC5 Message-ID: <1125766703.5228.5.camel@erato.phig.org> Sorry that we went silent on this for a little while. The translation team, the documentation team, and the infrastructure/CVS admins are discussing how to best integrate translation with cvs.fedora.redhat.com. The goals are: * Same or similar locking tools, so translators can lock something for translation * Usage of CVS without making translators learn a whole new set of tools * Translation process that is the same translators are used to, using PO files, etc. We'll let you know more about how this is shaping up. thx - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 Mon Sep 5 07:09:14 2005 From: kwade at redhat.com (Karsten Wade) Date: Mon, 05 Sep 2005 00:09:14 -0700 Subject: quick update about translation for FC5 In-Reply-To: <5eb2c922050904083776fc3228@mail.gmail.com> References: <1125766703.5228.5.camel@erato.phig.org> <5eb2c922050904083776fc3228@mail.gmail.com> Message-ID: <1125904154.5261.7.camel@erato.phig.org> On Sun, 2005-09-04 at 17:37 +0200, Xavier Conde Rueda wrote: > Hi Karsten > > will there be any way to get the contents of just a translation team? > Actually when we do a cvs update it copies the translations of all > teams. I think it would be better to just work with you own team's > files. Thanks for the suggestion. I think this could work for documentation, even if it is just a well-crafted cvsignore file. The people working on the infrastructure are on this list, hopefully they read your message. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 Mon Sep 5 20:45:34 2005 From: kwade at redhat.com (Karsten Wade) Date: Mon, 05 Sep 2005 13:45:34 -0700 Subject: Submission: Home Server Setup Guide In-Reply-To: <431918D8.3060009@brennan.id.au> References: <431918D8.3060009@brennan.id.au> Message-ID: <1125953134.5261.34.camel@erato.phig.org> On Sat, 2005-09-03 at 07:30 +0400, Miles Brennan wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > G'day to all, G'day. Nice, long holiday weekend here in the States, just getting around to some email. :) > As Karsten queried a few weeks earlier, yes I?m one of those lurking, > too busy at the moment, don't know where to begin, never used CVS and > not sure what to do - classic post and you caught me out ;) Excellent. Glad we drew you out. > Over the new year break I wrote the 'Linux Home Server HOWTO' > (http://www.brennan.id.au). I haven't read all the way through, so this is a preliminary overview. 0. Thank you for bringing this here, we are very interested in working with you to get this into Fedora Documentation. 1. Great work. Very useful. Covers -lots- of common topics we have no documentation for. This project will benefit greatly from the inclusion of this guide. 2. A small book this size would benefit from more help; I'd be concerned that maintenance by yourself would be tiring. Recruit help? 3. Fedora docs focuses on solutions found only in Core and Extras; if there are solutions you choose outside of those, we would want them changed to Fedora-only solutions. We can reference other solutions in a stand-alone chapter, if you don't want to totally kill the content. I haven't finished reading through yet, so I have no examples, _if_ they exist. 4. Small style changes, throughout. For example, consistent use of the active ("Click OK and a dialog opens") v. passive ("When you click on OK, then a dialog will open"). We like the active voice, it engages the reader with what they actually experience. We expect most folks to do the task with the documentation present, so what they see is not what they -will- see but what the -are- seeing. ;-D Another example is changing the pronouns from first-person plural ("we") to second-person singular/plural ("you"). I'll be happy to explain these style choices further, if anyone needs. > It is a complete HOWTO for setting up a Linux gateway server connected > to the Internet and providing network resources to the internal > workstations (MS/Linux). Firewall/Samba/DNS/NTP/FTP guides etc... > > It was originally written for FC3 so some of it may need a little > tweaking as I haven't yet updated it. However it is a complete HOWTO, 20 > chapters in all (~180 pages when printed). IMO, this is more of a guide than a how-to. It's definitely in the how-to format, but it is really a full length book/guide. Once it has chapters, it's a book. :) > I now offer it for comment / criticism / appraisal / submission. What do you want to do: 1. Maintain sole authorship, under the FDP 2. Lead a team of writers, under the FDP 3. Toss over the wall to the FDP, let us recruit writers and editors to continue your work Option 3 is the one we try to avoid. I recommend option 2. It keeps you in charge of the document, as the lead writer. As for the CVS parts, that is much easier than you think. Easier than learning to use DocBook, and much easier than the concepts you cover in this guide. A first step is to work with an editor to convert the guide to use the FDP DocBook template and style. The we can publish it for FC3. We can also recruit interested writers to work on sections to update to FC4, unless you are able to do that yourself. > I would prefer to keep the content / concept complete if possible, but > open to suggestions. Content and concept are easy to keep together. Normally, we would have written up each chapter as a stand-alone document, then tie them all together. This comes prepackaged, which is fantastic. Our only changes would be minor formatting via the stylesheets and XML choices we make, and writing style. The latter, btw, focuses partially on making it easier to translate by reducing idioms, etc. > BTW, hello list :) Hello! Welcome, this was quite a nice self-introduction. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 nman64 at n-man.com Tue Sep 6 01:58:55 2005 From: nman64 at n-man.com (Patrick Barnes) Date: Mon, 05 Sep 2005 20:58:55 -0500 Subject: FAQ Message-ID: <431CF7DF.9050406@n-man.com> Karsten, Stuart and Rahul, Following your earlier conversation on IRC, I revamped the FAQ page (http://fedoraproject.org/wiki/FAQ) as an actual list of Frequently Asked Questions. The real content of the page isn't much different, but it is at least a bit more intuitive, and actually deserves the name 'FAQ' now. :-) -- Patrick "The N-Man" Barnes nman64 at n-man.com www.n-man.com -- -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: OpenPGP digital signature URL: From mospina at redhat.com Tue Sep 6 02:17:14 2005 From: mospina at redhat.com (Manuel Eduardo Ospina Sarmiento) Date: Tue, 06 Sep 2005 12:17:14 +1000 Subject: translation-guide Message-ID: <1125973034.7628.29.camel@dhcp-118.brisbane.redhat.com> Hi, I would like to help on this doc: translation-guide. I am not sure if there is someone currently working on it. The following chapters need to be written: Chapter 2 PO files Chapter 3 PO file editing tools Chapter 4 Screenshot Chapter 5 GNU Gettext I believe an extra chapter should be included: Translation guidelines. This chapter would include hints on how to deal with common translation issues. If there is nobody maintaining this doc I would like to work on it. Cheers, -- Manuel Ospina Technical Translator Red Hat Asia-Pacific Phone: +61 7 3514 8112 Fax : +61 7 3514 8199 Disclaimer: http://apac.redhat.com/disclaimer From nman64 at n-man.com Tue Sep 6 08:27:27 2005 From: nman64 at n-man.com (Patrick Barnes) Date: Tue, 06 Sep 2005 03:27:27 -0500 Subject: Have you signed up for the Fedora Mentors program yet? Message-ID: <431D52EF.2010003@n-man.com> The new Fedora Mentors program (http://fedoraproject.org/wiki/Mentors) is looking for more volunteer mentors. If you haven't already, you should really consider signing up to be a mentor. It's easy, and (at least for now) the volume is light. While your at it, we are also trying to put together resources for new contributors to avoid common questions reaching mentors or the mailing lists. If you know of any important reading materials for new contributors to your project, we'd love to hear about it. If you would like to write some introductory information for new contributors, to help them get started, we'd love to see it. We could also use some help in preparing resources to help new mentors get started. As you work to be a mentor, please let us know what kind of resources you would find helpful. If you have any questions about the Fedora Mentors program, catch us in #fedora-mentors on freenode. Our mailing list (fedora-mentors-list at redhat.com) isn't quite ready yet. >From now on, when you see someone who needs a little guidance to start contributing, know that the Fedora Mentors program is here to help. http://fedoraproject.org/wiki/Mentors - We look forward to seeing you there! -- Patrick "The N-Man" Barnes nman64 at n-man.com www.n-man.com -- -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: OpenPGP digital signature URL: From sundaram at redhat.com Tue Sep 6 09:50:22 2005 From: sundaram at redhat.com (Rahul Sundaram) Date: Tue, 06 Sep 2005 15:20:22 +0530 Subject: FAQ In-Reply-To: <431CF7DF.9050406@n-man.com> References: <431CF7DF.9050406@n-man.com> Message-ID: <431D665E.4070800@redhat.com> Patrick Barnes wrote: >Karsten, Stuart and Rahul, > >Following your earlier conversation on IRC, I revamped the FAQ page >(http://fedoraproject.org/wiki/FAQ) as an actual list of Frequently >Asked Questions. The real content of the page isn't much different, but >it is at least a bit more intuitive, and actually deserves the name >'FAQ' now. :-) > > > Looks much better now. Thanks regards Rahul From sundaram at redhat.com Tue Sep 6 09:51:49 2005 From: sundaram at redhat.com (Rahul Sundaram) Date: Tue, 06 Sep 2005 15:21:49 +0530 Subject: translation-guide In-Reply-To: <1125973034.7628.29.camel@dhcp-118.brisbane.redhat.com> References: <1125973034.7628.29.camel@dhcp-118.brisbane.redhat.com> Message-ID: <431D66B5.8010200@redhat.com> Manuel Eduardo Ospina Sarmiento wrote: >Hi, >I would like to help on this doc: translation-guide. I am not sure if >there is someone currently working on it. The following chapters need to >be written: >Chapter 2 PO files >Chapter 3 PO file editing tools >Chapter 4 Screenshot >Chapter 5 GNU Gettext >I believe an extra chapter should be included: Translation guidelines. >This chapter would include hints on how to deal with common translation >issues. > >If there is nobody maintaining this doc I would like to work on it. > >Cheers, > > > Go ahead. There are many other translators looking for better guidance on this. A step by step guide would be very useful regards Rahul From tim at birdsnest.maths.tcd.ie Tue Sep 6 11:24:35 2005 From: tim at birdsnest.maths.tcd.ie (Timothy Murphy) Date: Tue, 06 Sep 2005 12:24:35 +0100 Subject: FAQ References: <431CF7DF.9050406@n-man.com> Message-ID: Patrick Barnes wrote: > Following your earlier conversation on IRC, I revamped the FAQ page > (http://fedoraproject.org/wiki/FAQ) as an actual list of Frequently > Asked Questions. The real content of the page isn't much different, but > it is at least a bit more intuitive, and actually deserves the name > 'FAQ' now. :-) I looked briefly through this FAQ, and a couple of points struck me. 1. I wonder if it is good advice to suggest people should use NetworkManager to set up a network? It seems to me that if a network does not work after running system-config-network or whatever, the problem is not likely to be solved by NetworkManager. In any case, the first advice should be to use the standard tools. Having played with NetworkManager a bit, I would say it is more likely to confuse the issue than solve it. 2. I noticed in the same answer that it appearded to be assumed the user was running GNOME. That seems a mistake in a FAQ. 3. I thought the section on hardware problems was slightly misguided. The fact is, there are many hardware configurations where one can have problems installing Fedora without overheating of the CPU, etc. In fact, I would have thought problems of that kind were pretty rare nowadays. -- Timothy Murphy e-mail (<80k only): tim /at/ birdsnest.maths.tcd.ie tel: +353-86-2336090, +353-1-2842366 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland From sundaram at redhat.com Tue Sep 6 11:36:03 2005 From: sundaram at redhat.com (Rahul Sundaram) Date: Tue, 06 Sep 2005 17:06:03 +0530 Subject: FAQ In-Reply-To: References: <431CF7DF.9050406@n-man.com> Message-ID: <431D7F23.3000603@redhat.com> Hi >I looked briefly through this FAQ, >and a couple of points struck me. > >1. I wonder if it is good advice to suggest people should use >NetworkManager to set up a network? > > If its a wireless network, it is not a bad idea to suggest that >2. I noticed in the same answer that it appearded to be assumed >the user was running GNOME. >That seems a mistake in a FAQ. > > I dont see any such assumptions >3. I thought the section on hardware problems was slightly misguided. >The fact is, there are many hardware configurations >where one can have problems installing Fedora >without overheating of the CPU, etc. >In fact, I would have thought problems of that kind >were pretty rare nowadays. > > The list of hardware issues to check is written by me based on Dave Jones's blog at the number of bugs filed against the kernel which are really due to flaky or bad hardware, so there is a real need for it regards Rahul From sundaram at redhat.com Tue Sep 6 12:20:10 2005 From: sundaram at redhat.com (Rahul Sundaram) Date: Tue, 06 Sep 2005 17:50:10 +0530 Subject: FAQ In-Reply-To: <200509061259.24472.tim@birdsnest.maths.tcd.ie> References: <431CF7DF.9050406@n-man.com> <431D7F23.3000603@redhat.com> <200509061259.24472.tim@birdsnest.maths.tcd.ie> Message-ID: <431D897A.6080506@redhat.com> Hi >In general, IMHO the advice in all cases >should be to start with the standard tools provided. >If they don't work, then by all means try something more sophisticated. > > For all future versions of Fedora, Network Manager effectively would be the standard tool. It tends to exposure the missing functionality is some of the Linux drivers and depends on dbus and hal which itself are rapidly evolving but there is no reason Network Manager shouldnt work for any needs, basic or sophisticated. >If you click on the NetworkManager button >the advice on setting up NM seems to assume one is running GNOME. > >I would say it should be a general rule in documentation >(except that explicitly dealing with KDE or GNOME) >not to assume that one is being used rather than the other. > > Have you reported it?. If not please do, but the general design has been that while the backends are desktop neutral the UI itself would assume a particular desktop environment. GNOME Volume Manager vs it's KDE equivalent is an example of this >Possibly; >but the implication to me seemed to be >that if FC did not run it was probably due to a hardware failure, >whereas my estimation would be that the probability of this is < 5%. > >However, these are just my opinions; >I would expect you to know better. > Not really. The question explicitly assumes that the users suspect that their problems are hardware related and then there are a good number of users who refuse to accept that their hardware could have problems and insist that it is a kernel bug. Even a 5% is a good number to wreak havoc on those looking at kernel reports "My general impression is that this FAQ is in the long tradition of Unix FAQs, which answer questions the writer would like to have been asked rather than ones which are actually likely to be asked in the real world. " I hope that you understand that this is precisely what we want to avoid. If there are questions that we can answer within legal constraints go ahead and suggest that or better yet get yourself wiki access and show us how its done better regards Rahul From tim at birdsnest.maths.tcd.ie Tue Sep 6 12:33:30 2005 From: tim at birdsnest.maths.tcd.ie (Timothy Murphy) Date: Tue, 06 Sep 2005 13:33:30 +0100 Subject: FAQ References: <431CF7DF.9050406@n-man.com> <431D7F23.3000603@redhat.com> <200509061259.24472.tim@birdsnest.maths.tcd.ie> <431D897A.6080506@redhat.com> Message-ID: Rahul Sundaram wrote: > If there are questions that we can answer within legal constraints go > ahead and suggest that or better yet get yourself wiki access and show > us how its done better You mean, "get off your backside"! I guess the area I would feel most advice was needed in would be, What to do if FC does not install (or upgrade) on your computer? Eg what are the parameters one can add to the boot response such as "linux text", etc. Then, what to do if Fedora installs OK in text mode but X is not running properly? I feel that the questions that arise once one has Linux running, eg how to view DVDs, while important are not so fundamental as issues involved in getting the system running. Just my 0.01 euro's worth. -- Timothy Murphy e-mail (<80k only): tim /at/ birdsnest.maths.tcd.ie tel: +353-86-2336090, +353-1-2842366 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland From sundaram at redhat.com Tue Sep 6 12:42:20 2005 From: sundaram at redhat.com (Rahul Sundaram) Date: Tue, 06 Sep 2005 18:12:20 +0530 Subject: FAQ In-Reply-To: References: <431CF7DF.9050406@n-man.com> <431D7F23.3000603@redhat.com> <200509061259.24472.tim@birdsnest.maths.tcd.ie> <431D897A.6080506@redhat.com> Message-ID: <431D8EAC.1080009@redhat.com> Timothy Murphy wrote: >Rahul Sundaram wrote: > > > >>If there are questions that we can answer within legal constraints go >>ahead and suggest that or better yet get yourself wiki access and show >>us how its done better >> >> > >You mean, "get off your backside"! > > Oh my. It was a invitation to participate. >I guess the area I would feel most advice was needed in would be, >What to do if FC does not install (or upgrade) on your computer? >Eg what are the parameters one can add to the boot response >such as "linux text", etc. > >Then, what to do if Fedora installs OK in text mode >but X is not running properly? > There are questions that better fit into the installation and a system administration guide itself regards Rahul From kwade at redhat.com Tue Sep 6 16:27:49 2005 From: kwade at redhat.com (Karsten Wade) Date: Tue, 06 Sep 2005 09:27:49 -0700 Subject: FAQ In-Reply-To: <431D8EAC.1080009@redhat.com> References: <431CF7DF.9050406@n-man.com> <431D7F23.3000603@redhat.com> <200509061259.24472.tim@birdsnest.maths.tcd.ie> <431D897A.6080506@redhat.com> <431D8EAC.1080009@redhat.com> Message-ID: <1126024069.6907.7.camel@erato.phig.org> On Tue, 2005-09-06 at 18:12 +0530, Rahul Sundaram wrote: > Timothy Murphy wrote: > > >Rahul Sundaram wrote: > > > > > > > >>If there are questions that we can answer within legal constraints go > >>ahead and suggest that or better yet get yourself wiki access and show > >>us how its done better > >> > >> > > > >You mean, "get off your backside"! > > > > > Oh my. It was a invitation to participate. Yes, that is how Tim interpreted it, a call for -him- to get off his backside. IIUC. > > > >Then, what to do if Fedora installs OK in text mode > >but X is not running properly? > > > There are questions that better fit into the installation and a system > administration guide itself Right, the FAQ tries to steer people the answer, where the answer is not in scope to provide, i.e., is more than a short answer. Another item of note is that we are -not- trying to supplant the fedorafaq.org, but to supplement it. That is much more of a user-driven FAQ, at it's start. We obviously want to be real questions with real answers, so participation in making the questions real is a Good Thing. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 stuart at elsn.org Tue Sep 6 18:35:00 2005 From: stuart at elsn.org (Stuart Ellis) Date: Tue, 06 Sep 2005 19:35:00 +0100 Subject: FAQ In-Reply-To: <1126024069.6907.7.camel@erato.phig.org> References: <431CF7DF.9050406@n-man.com> <431D7F23.3000603@redhat.com> <200509061259.24472.tim@birdsnest.maths.tcd.ie> <431D897A.6080506@redhat.com> <431D8EAC.1080009@redhat.com> <1126024069.6907.7.camel@erato.phig.org> Message-ID: <1126031701.2847.26.camel@localhost.localdomain> On Tue, 2005-09-06 at 09:27 -0700, Karsten Wade wrote: > On Tue, 2005-09-06 at 18:12 +0530, Rahul Sundaram wrote: > > Timothy Murphy wrote: > > > > >Rahul Sundaram wrote: > > > > > > > > > > > >>If there are questions that we can answer within legal constraints go > > >>ahead and suggest that or better yet get yourself wiki access and show > > >>us how its done better > > >> > > >> > > > > > >You mean, "get off your backside"! > > > > > > > > Oh my. It was a invitation to participate. > > Yes, that is how Tim interpreted it, a call for -him- to get off his > backside. IIUC. > > > > > > >Then, what to do if Fedora installs OK in text mode > > >but X is not running properly? > > > > > There are questions that better fit into the installation and a system > > administration guide itself To clarify the issue of access, for those following this: Anyone interested in working on the material in the Wiki can get access just by e-mailing a member of the Edit Group. Amongst many others, members of the Edit Group active on this list include: - All of the members of the FDSCo (Karsten, Gavin, Mark, Paul, Tammy, Tommy and myself) - Patrick Barnes (nman64) - Rahul If you have already posted a self-introduction (so that we know who you are), the only other thing that we need is your preferred Wiki username. Wiki usernames should be in the format: FirstnameLastname. To work on any of the existing draft FDP documents being developed on the Wiki (including the Administration Guide), e-mail an FDSCo member. Or you can propose a new document on this list. The full Edit Group: http://www.fedoraproject.org/wiki/EditGroup The draft documents: http://www.fedoraproject.org/wiki/Docs/Drafts -- Stuart Ellis stuart at elsn.org Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ GPG key ID: 7098ABEA GPG key fingerprint: 68B0 E291 FB19 C845 E60E 9569 292E E365 7098 ABEA -------------- 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 sarahs at redhat.com Tue Sep 6 22:29:56 2005 From: sarahs at redhat.com (Sarah Wang) Date: Wed, 07 Sep 2005 08:29:56 +1000 Subject: translation-guide In-Reply-To: <1125973034.7628.29.camel@dhcp-118.brisbane.redhat.com> References: <1125973034.7628.29.camel@dhcp-118.brisbane.redhat.com> Message-ID: <1126045796.5097.16.camel@localhost.localdomain> Good on you Manuel! I initially drew out the skeleton of this guide. "Translation Guidelines" is a great suggestion. Let me know if I can help in any way. Cheers, Sarah On Tue, 2005-09-06 at 12:17 +1000, Manuel Eduardo Ospina Sarmiento wrote: > Hi, > I would like to help on this doc: translation-guide. I am not sure if > there is someone currently working on it. The following chapters need to > be written: > Chapter 2 PO files > Chapter 3 PO file editing tools > Chapter 4 Screenshot > Chapter 5 GNU Gettext > I believe an extra chapter should be included: Translation guidelines. > This chapter would include hints on how to deal with common translation > issues. > > If there is nobody maintaining this doc I would like to work on it. > > Cheers, > > -- > Manuel Ospina > Technical Translator > Red Hat Asia-Pacific > Phone: +61 7 3514 8112 > Fax : +61 7 3514 8199 > > Disclaimer: http://apac.redhat.com/disclaimer > > From stickster at gmail.com Wed Sep 7 13:25:40 2005 From: stickster at gmail.com (Paul W. Frields) Date: Wed, 07 Sep 2005 09:25:40 -0400 Subject: A few nice bits in CVS Message-ID: <1126099540.3104.19.camel@localhost.localdomain> While I was on and in various planes and hotel rooms in Seattle I managed to cobble together a couple kibbles 'n' bits in the docs-common module that should make our documentation easier to read. One of the common complaints was that the revision history block on the title page made readers wade through a lot of material in which they weren't interested just to get to the real narrative. The revision history now is linked in the same manner as the legal notice, so people can get right to the table of contents as expected. (You can see the results in the "yum" and "jargon-buster" documents on the fedora.redhat.com web site now.) If you generate a "nochunks" version of the HTML, the revision history appears inline, just as the legal notice does. One tiny drawback is that the build process (i.e. "make") issues a warning about context. It's only a warning and does not affect the efficacy of the build. I'm sure this is a small problem easily fixed by someone who understands XSL better than I. That someone might even find a better way to accomplish the task, and if so, please have at it. In the meantime, if you have a docs-common/ module checked out of CVS, you should update it ("cvs up") now. If you have no idea what I'm talking about, then you need to speak up on the list so we can answer any of your questions and get you working on some of the good stuff! ;-) -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ -------------- 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 Wed Sep 7 20:26:14 2005 From: kwade at redhat.com (Karsten Wade) Date: Wed, 07 Sep 2005 13:26:14 -0700 Subject: commit log scraper Message-ID: <1126124774.6907.200.camel@erato.phig.org> We are implementing a script that will look for certain keywords in commit logs, and finding one, Cc:'s the commit message to a particular mailing list. Our first implementation looks for *docs* and Cc:'s the commit log to relnotes at fedoraprojects.org. The release notes beat writers can then decide which beat is appropriate for that note, pass it on to a particular guide or tutorial, or drop it as irrelevant. This script is live now. Before we ask developers to start using it, we need to give them some guidelines of where, when, and why to use it. This page is a first pass at guidelines for developers on what to document: http://fedoraproject.org/wiki/DocsProject/WhatToDocument Please help fill out these guidelines. We'll announce to the developers when we have enough of a guideline for them to follow. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 stuart at elsn.org Wed Sep 7 20:45:51 2005 From: stuart at elsn.org (Stuart Ellis) Date: Wed, 07 Sep 2005 21:45:51 +0100 Subject: commit log scraper In-Reply-To: <1126124774.6907.200.camel@erato.phig.org> References: <1126124774.6907.200.camel@erato.phig.org> Message-ID: <1126125951.2847.47.camel@localhost.localdomain> On Wed, 2005-09-07 at 13:26 -0700, Karsten Wade wrote: > We are implementing a script that will look for certain keywords in > commit logs, and finding one, Cc:'s the commit message to a particular > mailing list. > > Our first implementation looks for *docs* and Cc:'s the commit log to > relnotes at fedoraprojects.org. The release notes beat writers can then > decide which beat is appropriate for that note, pass it on to a > particular guide or tutorial, or drop it as irrelevant. > > This script is live now. Before we ask developers to start using it, we > need to give them some guidelines of where, when, and why to use it. > > This page is a first pass at guidelines for developers on what to > document: > > http://fedoraproject.org/wiki/DocsProject/WhatToDocument > > Please help fill out these guidelines. We'll announce to the developers > when we have enough of a guideline for them to follow. Per IRC discussion, technical types tend to automatically read the * character as the "any" wildcard, so instructions will have to clear that developers need to use the exact string "*docs*". If square brackets aren't appropriate, perhaps you could use **, e.g. **docs** ? -- Stuart Ellis stuart at elsn.org Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ GPG key ID: 7098ABEA GPG key fingerprint: 68B0 E291 FB19 C845 E60E 9569 292E E365 7098 ABEA -------------- 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 miles at brennan.id.au Thu Sep 8 03:36:20 2005 From: miles at brennan.id.au (Miles Brennan) Date: Thu, 08 Sep 2005 07:36:20 +0400 Subject: Submission: Home Server Setup Guide In-Reply-To: <1125953134.5261.34.camel@erato.phig.org> References: <431918D8.3060009@brennan.id.au> <1125953134.5261.34.camel@erato.phig.org> Message-ID: <431FB1B4.9010802@brennan.id.au> -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Karsten Wade wrote: > I haven't read all the way through, so this is a preliminary overview. > > 0. Thank you for bringing this here, we are very interested in working > with you to get this into Fedora Documentation. > > 1. Great work. Very useful. Covers -lots- of common topics we have no > documentation for. This project will benefit greatly from the inclusion > of this guide. > > 2. A small book this size would benefit from more help; I'd be concerned > that maintenance by yourself would be tiring. Recruit help? It probably could be turned into a neat book with a little more info. Maintenance is a little slow atm (bit busy), some help would be beneficial. > > 3. Fedora docs focuses on solutions found only in Core and Extras; if > there are solutions you choose outside of those, we would want them > changed to Fedora-only solutions. We can reference other solutions in a > stand-alone chapter, if you don't want to totally kill the content. I > haven't finished reading through yet, so I have no examples, _if_ they > exist. I have tried to utilise Fedora only solutions, the extra ones you mention are: - SquidGuard - which is TODO ( I never DO'd it yet anyway!), squash it. - phpMyAdmin - MySQL Web Admin, can move to annex if need be. - phpLDAPadmin - LDAP Web Admin, can also go to annex if needed. The remainder is pure Fedora fun ;) > > 4. Small style changes, throughout. For example, consistent use of the > active ("Click OK and a dialog opens") v. passive ("When you click on > OK, then a dialog will open"). We like the active voice, it engages the > reader with what they actually experience. We expect most folks to do > the task with the documentation present, so what they see is not what > they -will- see but what the -are- seeing. ;-D Totally agree. My target audience was the new Linux users, this would be more suitable. See then do. > > Another example is changing the pronouns from first-person plural ("we") > to second-person singular/plural ("you"). I'll be happy to explain > these style choices further, if anyone needs. > Agreed, infact this was my original intent (for consistancy), but after writing so much I got a little sloppy. > > IMO, this is more of a guide than a how-to. It's definitely in the > how-to format, but it is really a full length book/guide. Once it has > chapters, it's a book. :) > I originally wrote it in the traditional form so stuck with the HOWTO style etc... but a guide it is. > >>I now offer it for comment / criticism / appraisal / submission. > > > What do you want to do: > > 1. Maintain sole authorship, under the FDP > 2. Lead a team of writers, under the FDP > 3. Toss over the wall to the FDP, let us recruit writers and editors to > continue your work I think option 2 would be the best avenue here. > > Option 3 is the one we try to avoid. I recommend option 2. It keeps > you in charge of the document, as the lead writer. > > As for the CVS parts, that is much easier than you think. Easier than > learning to use DocBook, and much easier than the concepts you cover in > this guide. This is really what stopped me from progressing it any further, DocBook/LinuxDoc etc... After I wrote it all, that last thing I wanted to do was then convert it all again into a format I knew nothing about. But if CVS it easy, lets do it. > > A first step is to work with an editor to convert the guide to use the > FDP DocBook template and style. The we can publish it for FC3. We can > also recruit interested writers to work on sections to update to FC4, > unless you are able to do that yourself. > I would suggest conversion to DocBook then publish FC3 'as it is', make minor modifications to version FC4 (with small team) to bring it up to date (file paths, version numbers), then concentrate on FC5 as a major revamp. > Content and concept are easy to keep together. Normally, we would have > written up each chapter as a stand-alone document, then tie them all > together. This comes prepackaged, which is fantastic. Our only changes > would be minor formatting via the stylesheets and XML choices we make, > and writing style. Anythings better than the current HOWTO format :) I have had plenty of requests for PDF version also, mainly because when they are building their server it is offline. > >>BTW, hello list :) > > > Hello! Welcome, this was quite a nice self-introduction. > :) :) -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (MingW32) Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org iD8DBQFDH7G01zxPeMAaUBIRAu5gAJ4n0LPXqQJ8Th2REVf6lKmYtHzNrACcDtIF SacqPy1T7yVuZ46PADZPhFA= =lXEH -----END PGP SIGNATURE----- From brads at redhat.com Thu Sep 8 14:51:05 2005 From: brads at redhat.com (Brad Smith) Date: Thu, 08 Sep 2005 10:51:05 -0400 Subject: vs Message-ID: <1126191066.7947.40.camel@satsuki.geekdome.lan> I am a bit confused about these tags. At first I had assumed that was for referring to a program as a proper noun and was for instructions that one might execute. For example: links is an unusual web browser in that, unlike graphical browsers such as Firefox, it is run from the command-line with an instruction like links http://fedora.redhat.com. However, upon closer inspection of the docbook docs, seems to be meant for any reference a CLI command, whereas is meant for any GUI application. So the "correct" markup for the above would be: links is an unusual web browser in that, unlike graphical browsers such as Firefox, it is run from the command-line with an instruction like links http://fedora.redhat.com. I can understand why we might want to differentiate between commands the user might run and commands that are just being mentioned (my initial assumption), but the official definition, which requires a different tag for links and Firefox when mentioned in the same context, seems arbitrary and kind of silly. Can someone please shed some light on what the rationale is here? Thanks, --Brad -- -------------- 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 tim at birdsnest.maths.tcd.ie Thu Sep 8 14:47:11 2005 From: tim at birdsnest.maths.tcd.ie (Timothy Murphy) Date: Thu, 08 Sep 2005 15:47:11 +0100 Subject: Submission: Home Server Setup Guide References: <431918D8.3060009@brennan.id.au> <1125953134.5261.34.camel@erato.phig.org> <431FB1B4.9010802@brennan.id.au> Message-ID: Miles Brennan wrote: > It probably could be turned into a neat book with a little more info. > Maintenance is a little slow atm (bit busy), some help would be > beneficial. While I found your tutorial at interesting, and will study it at greater length, it wasn't entirely clear to me who it was aimed at. What exactly is a "home server"? What would be a typical configuration for such a beast? Are we talking about a home LAN with a couple of machines on it? Or is it basically a model to practise on for larger systems? This isn't meant as a criticism - just that a few words describing the kind of setup in question might be useful in the introduction. -- Timothy Murphy e-mail (<80k only): tim /at/ birdsnest.maths.tcd.ie tel: +353-86-2336090, +353-1-2842366 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland From stickster at gmail.com Thu Sep 8 15:28:44 2005 From: stickster at gmail.com (Paul W. Frields) Date: Thu, 08 Sep 2005 11:28:44 -0400 Subject: vs In-Reply-To: <1126191066.7947.40.camel@satsuki.geekdome.lan> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> Message-ID: <1126193324.3377.33.camel@localhost.localdomain> On Thu, 2005-09-08 at 10:51 -0400, Brad Smith wrote: > I am a bit confused about these tags. > > At first I had assumed that was for referring to a program > as a proper noun and was for instructions that one might > execute. For example: > > > links is an unusual web > browser in that, unlike graphical browsers such as > Firefox, it is run > from the command-line with an instruction like > links http://fedora.redhat.com. > > > However, upon closer inspection of the docbook docs, seems to > be meant for any reference a CLI command, whereas is meant > for any GUI application. So the "correct" markup for the above would be: > > > links is an unusual web > browser in that, unlike graphical browsers such as > Firefox, it is run > from the command-line with an instruction like > links http://fedora.redhat.com. > > > I can understand why we might want to differentiate between commands the > user might run and commands that are just being mentioned (my initial > assumption), but the official definition, which requires a different tag > for links and Firefox when mentioned in the same context, seems > arbitrary and kind of silly. > > Can someone please shed some light on what the rationale is here? Your understanding is correct. Although this harkens back to a Red Hat documentation team convention -- AIUI -- it also reflects the fact that s are what you type in a terminal to run that program. Examples include yum and emacs. This is not always the case for s. (Emacs brings up an interesting case. I suppose that you could really do Emacs if you wanted to, since there is in fact a GUI version.) For instance, we would use to mark the name for a tool whose command name is not as easy for the user to remember. We might instruct the user to run the Text Editor, as opposed to gedit. This avoids having to rewrite the documentation if and when the program behind the "Text Editor" on the menu changes either because the user has changed it, or a new default is installed in a newer Fedora release. It's also easier for the user since they can find "Text Editor" on their menu, but not "gedit". Telling the user to run gedit is not helpful because you are now assuming they know how to interact with a terminal. Many users don't want to do that, and shouldn't be required to. (The Text Editor is not the best example I could have chosen here, since many tutorials are all about interacting with a terminal to do sysadmin tasks, but hopefully you get my point.) The FDP convention is to always point users to GUI tools where possible. So, make sure that you are being appropriately generic when it's required, to avoid unnecessary maintenance later. Using the application (menu) name instead of the command (CLI) name is helpful. Does this make things clear as mud, then? -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ -------------- 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 8 17:26:46 2005 From: kwade at redhat.com (Karsten Wade) Date: Thu, 08 Sep 2005 10:26:46 -0700 Subject: Submission: Home Server Setup Guide In-Reply-To: References: <431918D8.3060009@brennan.id.au> <1125953134.5261.34.camel@erato.phig.org> <431FB1B4.9010802@brennan.id.au> Message-ID: <1126200406.6907.295.camel@erato.phig.org> On Thu, 2005-09-08 at 15:47 +0100, Timothy Murphy wrote: > This isn't meant as a criticism - > just that a few words describing the kind of setup in question > might be useful in the introduction. This is a good point. All of the FDP documents are supposed to have such information in the introduction, so this is the kind of thing we'll be working with Miles on the FDP version of this doc. This introduction section is going to be detailed in the updated Documentation Guide, and is in the jumble of suggestions here: http://fedoraproject.org/wiki/DocsProject/DocumentationGuide - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 8 17:41:36 2005 From: kwade at redhat.com (Karsten Wade) Date: Thu, 08 Sep 2005 10:41:36 -0700 Subject: vs In-Reply-To: <1126193324.3377.33.camel@localhost.localdomain> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> <1126193324.3377.33.camel@localhost.localdomain> Message-ID: <1126201296.6907.302.camel@erato.phig.org> On Thu, 2005-09-08 at 11:28 -0400, Paul W. Frields wrote: > Your understanding is correct. Although this harkens back to a Red Hat > documentation team convention -- AIUI -- it also reflects the fact that > s are what you type in a terminal to run that program. > Examples include yum and emacs. > This is not always the case for s. (Emacs brings up an > interesting case. I suppose that you could really do > Emacs if you wanted to, since there is in > fact a GUI version.) I don't know all the history, but the practice is, if the command line typing produces a GUI, you use . So, yes, you do this: "After installing the emacs package, the emacs & command opens the Emacs window as a stand-alone GUI." do s/filename/package/ when the tag is in our DTD. > The FDP > convention is to always point users to GUI tools where possible. Yes, with caveats. It is possible to write a guide that is entirely CLI or entirely GUI, or shows both solutions. The guide should be i) consistent, and ii) clearly state the audience and method. Readers should know up-front what method is in use. That said, tutorials for users who want to use GUIs exclusively are in more demand than tutorials that use the CLI. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 8 17:44:42 2005 From: kwade at redhat.com (Karsten Wade) Date: Thu, 08 Sep 2005 10:44:42 -0700 Subject: vs In-Reply-To: <1126191066.7947.40.camel@satsuki.geekdome.lan> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> Message-ID: <1126201482.6907.307.camel@erato.phig.org> On Thu, 2005-09-08 at 10:51 -0400, Brad Smith wrote: > > links is an unusual web > browser in that, unlike graphical browsers such as > Firefox, it is run > from the command-line with an instruction like > links http://fedora.redhat.com. > > > I can understand why we might want to differentiate between commands the > user might run and commands that are just being mentioned (my initial > assumption), but the official definition, which requires a different tag > for links and Firefox when mentioned in the same context, seems > arbitrary and kind of silly. The difference is, Firefox is the GUI app, while the command firefox uses the script at /usr/bin/firefox to run the firefox- bin binary. Does that make sense? I'm pretty sure that is what the DocBook committee meant. :-D - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 brads at redhat.com Thu Sep 8 17:55:57 2005 From: brads at redhat.com (Brad Smith) Date: Thu, 08 Sep 2005 13:55:57 -0400 Subject: vs In-Reply-To: <1126193324.3377.33.camel@localhost.localdomain> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> <1126193324.3377.33.camel@localhost.localdomain> Message-ID: <1126202157.7947.117.camel@satsuki.geekdome.lan> > So, make sure that you are being appropriately generic when it's > required, to avoid unnecessary maintenance later. Using the application > (menu) name instead of the command (CLI) name is helpful. Does this > make things clear as mud, then? Well, to clarify, here's what's giving me trouble at the moment. How would the following be marked up? Restart the smb service: service smb restart I'd like to standardize on referring to services by the names of their init scripts in contexts like this in order to avoid having to refer to httpd as "The Apache HTTP Server", which is technically the correct name for it. Obviously "service smb restart" is a , but what about that initial "smb"? Technically it's neither a nor and because by its self it is neither a GUI nor a CLI app. Then again, neither is "Text Editor", though the convention if not the docbook spec seems to accept using it within ... but "smb" is, if anything, CLI so... you see how this gets complicated. A similar problem arises when dealing with "system-config-network". This is both a CLI and the proper name of the app that gets run when Internet Configuration Wizard (or whatever it is from the menus) is selected. I'm becoming convinced that and as currently defined are just inadequate for a number of scenarios, all of which could be dealt with by treating as the proper name of an application/service/command and as something one might run from the CLI. I don't expect the docbook standard to be revamped on my account, but can anyone offer a better way of addressing these problems without breaking convention? --Brad -------------- 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 stickster at gmail.com Thu Sep 8 18:25:18 2005 From: stickster at gmail.com (Paul W. Frields) Date: Thu, 08 Sep 2005 14:25:18 -0400 Subject: vs In-Reply-To: <1126202157.7947.117.camel@satsuki.geekdome.lan> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> <1126193324.3377.33.camel@localhost.localdomain> <1126202157.7947.117.camel@satsuki.geekdome.lan> Message-ID: <1126203918.3377.64.camel@localhost.localdomain> On Thu, 2005-09-08 at 13:55 -0400, Brad Smith wrote: > > So, make sure that you are being appropriately generic when it's > > required, to avoid unnecessary maintenance later. Using the application > > (menu) name instead of the command (CLI) name is helpful. Does this > > make things clear as mud, then? > > Well, to clarify, here's what's giving me trouble at the moment. How > would the following be marked up? > > Restart the smb service: service smb restart I would mark it up in this fashion, changing the style slightly to make the markup reflect better English usage: = = = = = Restart the smb service with the following command: service smb restart = = = = = It is possible to *way* overdo the XML tagging for commands, and we made a decision a couple years back to simplify snippets of user input or computer output for everyone's sanity. > I'd like to standardize on referring to services by the names of their > init scripts in contexts like this in order to avoid having to refer to > httpd as "The Apache HTTP Server", which is technically the correct name > for it. Right on! > Obviously "service smb restart" is a , but what about that > initial "smb"? Technically it's neither a nor and > because by its self it is neither a GUI nor a CLI app. > Then again, neither is "Text Editor", though the convention if not the > docbook spec seems to accept using it within ... but "smb" > is, if anything, CLI so... you see how this gets complicated. A service name is a CLI script and thus should be marked . > A similar problem arises when dealing with "system-config-network". This > is both a CLI and the proper name of the app that gets run > when Internet Configuration Wizard (or > whatever it is from the menus) is selected. If you refer to it as "s-c-n," use . If the latter, use . Simple. > I'm becoming convinced that and as currently > defined are just inadequate for a number of scenarios, all of which > could be dealt with by treating as the proper name of an > application/service/command and as something one might run > from the CLI. Funny, we haven't really had many problems up until now. ;-) I think you may just be unfamiliar with our conventions, but using them a few times will take care of that. > I don't expect the docbook standard to be revamped on my account, but > can anyone offer a better way of addressing these problems without > breaking convention? The guidance Karsten gave seems simple enough. The key is not to overthink it too much. ;-) -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ -------------- 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 stickster at gmail.com Thu Sep 8 18:29:51 2005 From: stickster at gmail.com (Paul W. Frields) Date: Thu, 08 Sep 2005 14:29:51 -0400 Subject: vs In-Reply-To: <1126202157.7947.117.camel@satsuki.geekdome.lan> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> <1126193324.3377.33.camel@localhost.localdomain> <1126202157.7947.117.camel@satsuki.geekdome.lan> Message-ID: <1126204191.3377.68.camel@localhost.localdomain> Oops, forgot to note these: http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-command.html http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-application.html -- Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/ -------------- 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 8 19:45:21 2005 From: kwade at redhat.com (Karsten Wade) Date: Thu, 08 Sep 2005 12:45:21 -0700 Subject: vs In-Reply-To: <1126203918.3377.64.camel@localhost.localdomain> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> <1126193324.3377.33.camel@localhost.localdomain> <1126202157.7947.117.camel@satsuki.geekdome.lan> <1126203918.3377.64.camel@localhost.localdomain> Message-ID: <1126208721.6907.391.camel@erato.phig.org> On Thu, 2005-09-08 at 14:25 -0400, Paul W. Frields wrote: > It is possible to *way* overdo the XML tagging for commands, and we made > a decision a couple years back to simplify snippets of user input or > computer output for everyone's sanity. FWIW, it is precisely those decisions that are currently under review. Mark is going to send a more detailed email later, he and I are working with the example-tutorial and/or the Doc Guide to complete our XML usage guidelines. This is where Brad's questions are coming from, helping us all to see where the problems are and (re)consider our standards. My personal feeling, stated on-list a while back, is that we _want_ to use the most semantically correct markup possible, but that we cannot require it. For this reason, we may have mandatory and recommended usages. I don't know if this is the best thing, however. For example, we may say this style is mandatory: cd foo ./bar -o baaz cat baaz > quux and this is recommended or preferred: cd foo ./bar cat baaz [contents of baaz] Crazy, eh? But sure helpful when you need to parse that content into a Braille reader, keyboard, and low-vision console. I think we need to decide for these cases i) what is mandatory, and ii) what is recommended. - Karsten -- Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 Red Hat SELinux Guide http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/ -------------- 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 brads at redhat.com Thu Sep 8 19:52:14 2005 From: brads at redhat.com (Brad Smith) Date: Thu, 08 Sep 2005 15:52:14 -0400 Subject: Some more convention questions Message-ID: <1126209135.7947.167.camel@satsuki.geekdome.lan> A colleague has raised the following questions, which I thought I would forward here for suggestions: 1. How should we mark up something like "www.example.com"? Note that we're here referring to a hostname, not a uri like "http://www.example.com" 2. Should we do anything to these (, , etc.): DNS DDNS SELinux ACL FQDN RPM BIND Most of these would fit under , but how would SELinux be marked up? Should BIND be treated as an ackronym or a service name? 3. During an installation, we have some SELinux choices: Disabled, Warn, Active. How should these be presented in CM? Would this work: SELinux Disabled Warn Active Or perhaps an itemizedlist? ...in other words, what's the proper markup for referring to a checkbox or radio button in a GUI form? 5. Should kernel options (e.g., enforcing=0) be or ? 6. Which is more appropriate? ls -l /etc/passwd or just ls -l /etc/passwd Finally, is there an established tag for use as a "catch-all" for things that we might want to be visually distinct, but that don't have docbook tags? SELinux contexts and dns hostnames come to mind. We're using , but is there already a standard for this? On that note, is there anywhere that these conventions, like using for package names, which I saw in one of Karsten's examples, are codified? Or is it just something you have to ask a docs person? Thanks for all the help, --Brad -- -------------- 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 brads at redhat.com Thu Sep 8 19:57:03 2005 From: brads at redhat.com (Brad Smith) Date: Thu, 08 Sep 2005 15:57:03 -0400 Subject: vs In-Reply-To: <1126208721.6907.391.camel@erato.phig.org> References: <1126191066.7947.40.camel@satsuki.geekdome.lan> <1126193324.3377.33.camel@localhost.localdomain> <1126202157.7947.117.camel@satsuki.geekdome.lan> <1126203918.3377.64.camel@localhost.localdomain> <1126208721.6907.391.camel@erato.phig.org> Message-ID: <1126209423.7947.173.camel@satsuki.geekdome.lan> > > cd foo > ./bar > cat baaz > [contents of baaz] > Another element missing from this, which it would be nice to adopt a standard for for consistency's sake, is the input prompt. The current GLS standard (as of last week) is: [student at stationX ~]$ unless a different user, host or cwd is specifically warranted. The stationX has to do with the way systems are named in our classrooms (station1, station2, etc), so it might not make a good FDP or Red Hat-wide convention, but a standard of some sort would be good nonetheless. Just a thought, --Brad -------------- 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 8 20:21:44 2005 From: kwade at redhat.com (Karsten Wade) Date: Thu, 08 Sep 2005 13:21:44 -0700 Subject: Some more convention questions In-Reply-To: <1126209135.7947.167.camel@satsuki.geekdome.lan> References: <1126209135.7947.167.camel@satsuki.geekdome.lan> Message-ID: <1126210904.6907.414.camel@erato.phig.org> On Thu, 2005-09-08 at 15:52 -0400, Brad Smith wrote: > A colleague has raised the following questions, which I thought I would > forward here for suggestions: > > 1. How should we mark up something like "www.example.com"? Note that > we're here referring to a hostname, not a uri like > "http://www.example.com" There are two ways I've seen it done: * As , which is a kludge * Without markup Perhaps there should be a ? My preference has been to not use a tag at all, when there is not a correct tag. > 2. Should we do anything to these (, , etc.): > DNS > DDNS > SELinux > ACL > FQDN > RPM > BIND > > Most of these would fit under , but how would SELinux be > marked up? Should BIND be treated as an ackronym or a service name? Except the service name is 'named'. ;-) One practice is to mark acronyms and abbreviations as such on first usage. This is what I did with SELinux, iirc: "Security Enhanced Linux (SELinux) is blah and foo." Then subsequent usages are SELinux without tags. > 3. During an installation, we have some SELinux choices: Disabled, > Warn, Active. How should these be presented in CM? Would this work: > > SELinux > Disabled > Warn > Active > > > Or perhaps an itemizedlist? Depends on context. You could be saying, the following are choices in the UI, and that would be a list. If you are referring to an actual menu, on context, then works best. > ...in other words, what's the proper markup for referring to a checkbox > or radio button in a GUI form? is OK in context. We usually default to if there is no other more appropriate tag. A can be anything in a GUI. :) > 5. Should kernel options (e.g., enforcing=0) be or ? They are usually referred to as kernel parameters. Another choice is