Some more convention questions

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

[Karsten Wade]

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/

[Paul W. Frields]

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" 
<systemitem class="systemname">www.example.com</systemitem>


>  2.  Should we do anything to these (<application>,
> <code>, etc.):
>      DNS
>      DDNS
>      SELinux
>      ACL
>      FQDN
>      RPM
>      BIND 
I don't see a good reason to do so, since markup for these would not
only be tiresome for writers, but the semantics in a tutorial don't
really place these in a special case that demands markup.  I could see
using <acronym> for a first usage perhaps...
	
>  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? 
SELinux is an acronym, albeit mixed... As for BIND, it's not used as a
service name in Fedora, but it might be defined in a networking guide
somewhere.

>  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? 
A <guimenuitem> can be used outside the <menuchoice> paradigm, say, in a
<para>.  I would mark these as <guimenuitem>, but use proper English to
note their radio-button quality:

<para>
From the <guimenu>SELinux</guimenu> menu, choose one of the following
modes: <guimenuitem>Disabled</guimenuitem>,
<guimenuitem>Warn</guimenuitem>, or
<guimenuitem>Active</guimenuitem>.
</para>


>  5.  Should kernel options (e.g., enforcing=0) be <command> or
> <code>? 
Why not <option>?

>  6.  Which is more appropriate?
>  	<command>ls -l <filename>/etc/passwd</filename></command>
>      or just
>  	<command>ls -l /etc/passwd</command> 
This goes back to the question about overtagging commands.  Maybe the
semantics should be the guide here -- if the command is a generic
command where the filename is just an example, tagging it with
<filename> is probably useful.  If the command is very specific and the
filename is vital to the sense of what you're trying to teach the user,
<filename> may not be as useful.

>  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? 
Hmm, this maybe begs a question, since the whole idea of DocBook is to
keep the visual distinction issue completely separate from the idea of
what the content is.  I would say that <systemitem> is best for these
things due to how DocBook defines it.

>  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? 
The Documentation Guide has much of this, but not all.  Are you
interested in helping with the XML tags portion, to give sense where you
see some lacking?

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/

[Brad Smith]

>  The Documentation Guide has much of this, but not all.  Are you
>  interested in helping with the XML tags portion, to give sense where you
>  see some lacking? 
Sure, though the time I will be able to spend on it, at least in the
near future, will be very limited. What would this type of help entail?

--Brad