Spell-checking docbook?
by Brad Smith
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
--
18 years, 6 months
Some more convention questions
by Brad Smith
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
--
18 years, 6 months
Dehard Fedora Tester? Why not help with the Release Notes?
by Gavin Henry
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/
18 years, 6 months
<command> vs <application>
by Brad Smith
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
--
18 years, 6 months
Submission: Home Server Setup Guide
by Miles Brennan
-----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-----
18 years, 6 months
commit log scraper
by Karsten Wade
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/
18 years, 6 months
translation-guide
by Manuel Ospina
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
18 years, 6 months
Re: FAQ
by Rahul Sundaram
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
18 years, 6 months
FAQ
by Patrick W. Barnes
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
--
18 years, 6 months