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/
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
