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/