Some more convention questions
Karsten Wade
kwade at redhat.com
Thu Sep 8 20:21:44 UTC 2005
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/
-------------- 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: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050908/9032d303/attachment.sig>
More information about the fedora-docs-list
mailing list