<command> vs <application>

[Paul W. Frields]

On Thu, 2005-09-08 at 13:55 -0400, Brad Smith wrote:
> > 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?
> 
> Well, to clarify, here's what's giving me trouble at the moment. How
> would the following be marked up?
> 
> Restart the smb service: service smb restart

I would mark it up in this fashion, changing the style slightly to make
the markup reflect better English usage:

= = = = =
  <para>
    Restart the <command>smb</command> service with the
    following command:
  </para>

<screen>
<userinput>service smb restart</userinput>
</screen>
= = = = =

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.

> I'd like to standardize on referring to services by the names of their
> init scripts in contexts like this in order to avoid having to refer to
> httpd as "The Apache HTTP Server", which is technically the correct name
> for it. 

Right on!

> Obviously "service smb restart" is a <command>, but what about that
> initial "smb"? Technically it's neither a <command> nor and
> <application> because by its self it is neither a GUI nor a CLI app.
> Then again, neither is "Text Editor", though the convention if not the
> docbook spec seems to accept using it within <application>... but "smb"
> is, if anything, CLI so... you see how this gets complicated.

A service name is a CLI script and thus should be marked <command>.

> A similar problem arises when dealing with "system-config-network". This
> is both a CLI <command> and the proper name of the app that gets run
> when <application>Internet Configuration Wizard</application> (or
> whatever it is from the menus) is selected. 

If you refer to it as "s-c-n," use <command>.  If the latter, use
<application>.  Simple.

> I'm becoming convinced that <application> and <command> as currently
> defined are just inadequate for a number of scenarios, all of which
> could be dealt with by treating <application> as the proper name of an
> application/service/command and <command> as something one might run
> from the CLI. 

Funny, we haven't really had many problems up until now.  ;-)  I think
you may just be unfamiliar with our conventions, but using them a few
times will take care of that.

> I don't expect the docbook standard to be revamped on my account, but
> can anyone offer a better way of addressing these problems without
> breaking convention?

The guidance Karsten gave seems simple enough.  The key is not to
overthink it too much. ;-)

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