docs September 2005

docs@lists.stg.fedoraproject.org

21 participants
33 discussions

Spell-checking docbook?
by Brad Smith 13 Sep '05

13 Sep '05

Can anyone recommend a markup-aware spell-checker for docbook docs? I need something that checks the text of the document but ignores anything inside <>. Thanks, --Brad --

3 2

Some more convention questions
by Brad Smith 13 Sep '05

13 Sep '05

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 (<application>, <code>, etc.): DNS DDNS SELinux ACL FQDN RPM BIND Most of these would fit under <ackronym>, 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: <menuchoice> <guimenu>SELinux</guimenu> <guimenuitem>Disabled</guimenuitem> <guimenuitem>Warn</guimenuitem> <guimenuitem>Active</guimenuitem> </menuchoice> 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 <command> or <code>? 6. Which is more appropriate? <command>ls -l <filename>/etc/passwd</filename></command> or just <command>ls -l /etc/passwd</command> 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 <code>, but is there already a standard for this? On that note, is there anywhere that these conventions, like using <filename> 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 --

3 3

Request for review of latest revision of Building Packages guide
by Ignacio Vazquez-Abrams 13 Sep '05

13 Sep '05

I've just completed a few more sections in my guide and I'd like someone to look it over for language, consistency, and flow, as well as actually trying out the instructions to see if they make sense. The relevant sections are the introduction for "Creating a New Package" as well as the entire contents of the "Case Study: leafpad" section. http://www.fedoraproject.org/wiki/Docs/Drafts/BuildingPackagesGuide -- Ignacio Vazquez-Abrams <ivazquez(a)ivazquez.net> http://fedora.ivazquez.net/ gpg --keyserver hkp://subkeys.pgp.net --recv-key 38028b72

2 2

Dehard Fedora Tester? Why not help with the Release Notes?
by Gavin Henry 12 Sep '05

12 Sep '05

Dear List, On behalf of the Fedora Documentation Steering Committee, I ask you: * Live life on the edge? * Always trying out the Release Candidates? * Discovered bugs or already have the solutions? * The Fedora Community needs to know!!! * Please help us document these to save others from your headaches and make FC5 the best release yet!! It's that time again: Time to help write the release notes. I have edited the Beats page for FC4 and turned it into one for FC5: http://fedoraproject.org/wiki/DocsProject/ReleaseNotes/Beats If you feel that some topics/sections are missing, let us know!!! Please have a read, submit bugs and see if you can help! We look forward to working with you, Thanks, Gavin. -- Kind Regards, Gavin Henry. Managing Director. T +44 (0) 1224 279484 M +44 (0) 7930 323266 F +44 (0) 1224 742001 E ghenry(a)suretecsystems.com Open Source. Open Solutions(tm). http://www.suretecsystems.com/

1 0

<command> vs <application>
by Brad Smith 09 Sep '05

09 Sep '05

I am a bit confused about these tags. At first I had assumed that <application> was for referring to a program as a proper noun and <command> was for instructions that one might execute. For example: <para> <application>links</application> is an unusual web browser in that, unlike graphical browsers such as <application>Firefox</application>, it is run from the command-line with an instruction like <command>links http://fedora.redhat.com</command>. </para> However, upon closer inspection of the docbook docs, <command> seems to be meant for any reference a CLI command, whereas <application> is meant for any GUI application. So the "correct" markup for the above would be: <para> <command>links</command> is an unusual web browser in that, unlike graphical browsers such as <application>Firefox</application>, it is run from the command-line with an instruction like <command>links http://fedora.redhat.com</command>. </para> 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 --

4 15

Submission: Home Server Setup Guide
by Miles Brennan 09 Sep '05

09 Sep '05

-----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-----

3 5

commit log scraper
by Karsten Wade 07 Sep '05

07 Sep '05

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(a)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/

2 1

translation-guide
by Manuel Ospina 06 Sep '05

06 Sep '05

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

3 2

Re: FAQ
by Rahul Sundaram 06 Sep '05

06 Sep '05

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

4 4

FAQ
by Patrick W. Barnes 06 Sep '05

06 Sep '05

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(a)n-man.com www.n-man.com --

3 3

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

2006

2005

2004

2003

2002

docs September 2005