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