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/
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list@xxxxxxxxxx To unsubscribe: http://www.redhat.com/mailman/listinfo/fedora-docs-list
