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