Some more convention questions

[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/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://lists.fedoraproject.org/pipermail/docs/attachments/20050909/8fff16c4/attachment.bin