<command> vs <application>

[Paul W. Frields]

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/
-------------- 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/20050908/321fb474/attachment.bin