<command> vs <application>

Karsten Wade kwade at redhat.com
Thu Sep 8 19:45:21 UTC 2005


On Thu, 2005-09-08 at 14:25 -0400, Paul W. Frields wrote:

> It is possible to *way* overdo the XML tagging for commands, and we made
> a decision a couple years back to simplify snippets of user input or
> computer output for everyone's sanity.

FWIW, it is precisely those decisions that are currently under review.

Mark is going to send a more detailed email later, he and I are working
with the example-tutorial and/or the Doc Guide to complete our XML usage
guidelines.  This is where Brad's questions are coming from, helping us
all to see where the problems are and (re)consider our standards.

My personal feeling, stated on-list a while back, is that we _want_ to
use the most semantically correct markup possible, but that we cannot
require it.

For this reason, we may have mandatory and recommended usages.  I don't
know if this is the best thing, however.

For example, we may say this style is mandatory:

<screen>
cd foo
./bar -o baaz
cat baaz > quux
</screen>

and this is recommended or preferred:

<screen>
<userinput><command>cd</command> <filename>foo</filename>
<command>./bar</command> <option>-o baaz</option> 
<command>cat</command> <filename>baaz</filename></userinput>
<computeroutput>[contents of baaz]</computeroutput>
</screen>

Crazy, eh?  But sure helpful when you need to parse that content into a
Braille reader, keyboard, and low-vision console.

I think we need to decide for these cases i) what is mandatory, and ii)
what is recommended.

- 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/c471fd7b/attachment.sig>


More information about the fedora-docs-list mailing list