Appropriate tags for service names and syslog facilties?

Fri Feb 13 21:01:34 UTC 2004

On Thu, 2004-02-12 at 05:05, Paul W. Frields wrote: 
> I think you're looking for <command>. Since there's nothing more
> appropriate, that's currently used not just for non-GUI apps, but also
> configuration file options and daemons like services. I would expect for
> now that you should use it for syslog facilities as well. If anyone
> wants to differ, please feel free.
> 
> I do notice that a DocBook RFE at:
> http://sourceforge.net/tracker/index.php?func=detail&aid=564776&group_id=21935&atid=384107
> suggests that the more proper way to do this is
> 
> <application class="daemon">syslogd</application>
> <application class="service">syslog</application>
> <application class="service">kern.*</application>
> 
> That was the end of 2002, but a *really* quick check of the DocBook book
> doesn't reveal anything more appropriate.

Unfortunately, it also doesn't reveal these classes being added to
<application>. Even though Norm Walsh made the final comment in your
above link, saying:

"We'll add process, service, server, and daemon to class values. 
This isn't the perfect solution, but it's a short-term answer."

Which sums up my feelings about it. I'm unhappy using <command> for
that which is not a command but in fact is an application launching a
service thread. I'd like us to use these new attributes for
<application>, but it appears that they are not available[1]. Yet
another XSL hack for the queue?

We could follow Norm Walsh's short-term solution, with the plan to fix
the XSL or incorporate in a long-term solution when it arrives.  I
mostly take that approach, except where the rendered format is too
jarring and the stylesheet fix is non-trivial.  There are times when you
have to choose what looks best in HTML and PDF and leave "do it right"
for another time.  I'm not sure this is such a time.

The reason for having correct tagging even when it makes no difference
in the output you are using is because you need to remain accessible for
future output formats. Imagine a stylesheet that renders a programming
tutorial to Braille, grabbing <example>s that include <screen>,
<computeroutput>, or <programlisting> and putting those directly to the
Braille screen, with associated <para> sets and <xref>s on a separate
Braille screen. In other words, proper tagging supports accessibility.

Since we are starting out from scratch with the Fedora docs project,
this is an opportunity to "do it right" for DocBook in every way we can.

- Karsten

[1] Trying the new attributes with the DocBook in FC1 yields this in the
HTML:

The XML:

<para>
 This is a test of the various uses of <application>. Here is a 
 class of <application class="daemon">daemon</application>, this is a
 class of <application class="service">service</application>, and these
 are regular <command>command</command> and
 <application>application</application> for comparison.
</para>

The resulting HTML:

This is a test of the various uses of <application>. Here is a
class of daemon, this is a class of
service, and these are regular
<tt class="command">command</tt> and application 
for comparison.

Since I don't use HTML for email, I'll use a form of structured markup
to show how the resulting HTML page looks in the Web browser:

This is a test of the various uses of <application>. Here is a class of
b:daemon, this is a class of b:service, and these are regular tt:command
and b:application for comparison.

Summary: the attributes were ignored, and all rendered with the default
stylesheet for <application>, which is . The
resulting HTML is not-jarring, although the daemon, service and
application are all in boldface, with the command in fixed-width font.

-- 
Karsten Wade   :      Tech Writer, RHCE     :  o: +1.831.466.9664
kwade at redhat.com : http://rhea.redhat.com/ :   c: +1.831.818.9995
         Red Hat Applications : WAF, CMS, Portal Server         
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --