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 <filename>, which is a kludge
* Without markup
Perhaps there should be a <hostname>?
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 (<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?
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
(<firstterm><acronym>SELinux</acronym></firstterm>) 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:
<menuchoice>
<guimenu>SELinux</guimenu>
<guimenuitem>Disabled</guimenuitem>
<guimenuitem>Warn</guimenuitem>
<guimenuitem>Active</guimenuitem>
</menuchoice>
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 <gui*> works best.
...in other words, what's the proper markup for referring to a
checkbox
or radio button in a GUI form?
<guimenuitem> is OK in context. We usually default to <guilabel> if
there is no other more appropriate tag. A <guilabel> can be anything in
a GUI. :)
5. Should kernel options (e.g., enforcing=0) be <command> or
<code>?
<parameter>
They are usually referred to as kernel parameters. Another choice is
<option>, which is for <command>s usually.
6. Which is more appropriate?
<command>ls -l <filename>/etc/passwd</filename></command>
or just
<command>ls -l /etc/passwd</command>
I think we are going to have to decide on a practical v. perfect choice.
Thusly, the former is recommended, while the latter is mandatory.
There is some argument that the entire thing is a command. *shrug*
That leaves room for us to interpret.
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?
Well, the visual distinctness comes the semantic distinctness.
Therefore, there can never be a catch-all tag.
That said, we have often used <guilabel> where nothing else is
sufficient.
In practice, many of us have used <computeroutput> for anything that is
shown on the screen. That is what I did for contexts in the SELinux
guide:
"Under the targeted policy, every subject and object runs in the
<computeroutput>unconfined_t</computeroutput> domain ..."
Which I guess is a catch-all usage, to be honest.
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?
These should all be covered in the FDP Doc Guide and/or example-tutorial
from CVS. These are both derived from Red Hat's conventions. Where
they are inadequate, this is what our current task is to fix.
BTW, our practice has been this:
1. Use what is said in TDG (
http://www.docbook.org/tdg/en/)
2. If we do anything different or in addition to that, put it in our Doc
Guide
TDG is canonical, but our situation has required us to occasionally do
things differently to work through a toolchain problem or insufficient
tags.
- 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/