On Thu, 2005-09-08 at 10:51 -0400, Brad Smith wrote: > I am a bit confused about these tags. > > At first I had assumed that <application> was for referring to a program > as a proper noun and <command> was for instructions that one might > execute. For example: > > <para> > <application>links</application> is an unusual web > browser in that, unlike graphical browsers such as > <application>Firefox</application>, it is run > from the command-line with an instruction like > <command>links http://fedora.redhat.com</command>. > </para> > > However, upon closer inspection of the docbook docs, <command> seems to > be meant for any reference a CLI command, whereas <application> is meant > for any GUI application. So the "correct" markup for the above would be: > > <para> > <command>links</command> is an unusual web > browser in that, unlike graphical browsers such as > <application>Firefox</application>, it is run > from the command-line with an instruction like > <command>links http://fedora.redhat.com</command>. > </para> > > I can understand why we might want to differentiate between commands the > user might run and commands that are just being mentioned (my initial > assumption), but the official definition, which requires a different tag > for links and Firefox when mentioned in the same context, seems > arbitrary and kind of silly. > > Can someone please shed some light on what the rationale is here? Your understanding is correct. Although this harkens back to a Red Hat documentation team convention -- AIUI -- it also reflects the fact that <command>s are what you type in a terminal to run that program. Examples include <command>yum</command> and <command>emacs</command>. This is not always the case for <application>s. (Emacs brings up an interesting case. I suppose that you could really do <application>Emacs</application> if you wanted to, since there is in fact a GUI version.) For instance, we would use <application> to mark the name for a tool whose command name is not as easy for the user to remember. We might instruct the user to run the <application>Text Editor</application>, as opposed to <command>gedit</command>. This avoids having to rewrite the documentation if and when the program behind the "Text Editor" on the menu changes either because the user has changed it, or a new default is installed in a newer Fedora release. It's also easier for the user since they can find "Text Editor" on their menu, but not "gedit". Telling the user to run <command>gedit</command> is not helpful because you are now assuming they know how to interact with a terminal. Many users don't want to do that, and shouldn't be required to. (The Text Editor is not the best example I could have chosen here, since many tutorials are all about interacting with a terminal to do sysadmin tasks, but hopefully you get my point.) The FDP convention is to always point users to GUI tools where possible. So, make sure that you are being appropriately generic when it's required, to avoid unnecessary maintenance later. Using the application (menu) name instead of the command (CLI) name is helpful. Does this make things clear as mud, then? -- 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
