Thanks guys,
Mike
__________________________________________________________________________ Mike MacCana Consultant RHCX, MCSE, MCP+I 0419 394 504
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&grou... 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.
That is my take on it as well:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-command...
At the end of this page, I started a list of items that should be tagged with the command tag, even though they aren't exactly commands.
HTH, Tammy
On Thu, 2004-02-12 at 08: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&grou... 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.
-- Paul W. Frields, RHCE
On Thu, 12 Feb 2004, Tammy Fox wrote:
That is my take on it as well:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-command...
At the end of this page, I started a list of items that should be tagged with the command tag, even though they aren't exactly commands.
Cheers. Want to add syslog facilities?
Mike
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&grou... 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: <p> This is a test of the various uses of <application>. Here is a class of <b class="application">daemon</b>, this is a class of <b class="application">service</b>, and these are regular <tt class="command">command</tt> and <b class="application">application</b> for comparison. </p>
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 <b class="application">. The resulting HTML is not-jarring, although the daemon, service and application are all in boldface, with the command in fixed-width font.
On Fri, 2004-02-13 at 16:01, Karsten Wade wrote:
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&grou... 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:
<p> This is a test of the various uses of <application>. Here is a class of <b class="application">daemon</b>, this is a class of <b class="application">service</b>, and these are regular <tt class="command">command</tt> and <b class="application">application</b> for comparison. </p>
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 <b class="application">. The resulting HTML is not-jarring, although the daemon, service and application are all in boldface, with the command in fixed-width font.
When I was in RH Docs, we had the command versus application debate many times over. ;-) Basically, my reasoning for ultimately deciding to use command tags for services, daemons, and the like was because I think of an application as something that has an interface other than the command line -- GUI or at least a TUI. If you use a class of an application, it gets marked as bold using our stylesheets instead of a mono font. I know DocBook is about removing yourself from the style, but you have to consider it as well. To the reader, IMO it is more fitting to use the same style for commands, services, daemons, etc. and leave the very noticeable bold style for application names such as Mozilla and GAIM. Of course, you could probably change the stylesheet to use bold for application tags with no class and a mono font for words tagged as an application with certain classes.
My 2 cents, Tammy
On Tue, 17 Feb 2004, Tammy Fox wrote:
When I was in RH Docs, we had the command versus application debate many times over. ;-) Basically, my reasoning for ultimately deciding to use command tags for services, daemons, and the like was because I think of an application as something that has an interface other than the command line -- GUI or at least a TUI.
service have an interface other than the command line.
In each of the tutorials I'm writing, if there's an appropriate Red Hat GUI config tool for the service, I provide instructions on installing, configuring, enabling and starting the service graphically (as well as the standard command line method provided for all services).
Hence you end up with something like:
<para> Start the <command>httpd</command> service and set it to start by default. <guimenu>Main Menu</guimenu> => <guimenuitem>System Settings</guimenuitem> => <guimenuitem>Services</guimenuitem>, select the <command>httpd</command> service and click Start to start the service (use Restart if it is already running). </para>
IMO it is more fitting to use the same style for commands, services, daemons, etc.
To be honest I don't know why Red Hat even bothers using the word 'daemon'. It has too many meanings in Unix (some people use it descrive a Sys V service, others the binaries run by that service, others an application that has been backgrounded by any method).
I find it best to avoid using the term 'daemon' completely. The only place where it still matters is TCP Wrappers, which is fast becoming irrelevant, due its limited application support and filtering capabilities.
Mike
On Tue, 2004-02-17 at 23:47, Mike MacCana wrote:
On Tue, 17 Feb 2004, Tammy Fox wrote:
When I was in RH Docs, we had the command versus application debate many times over. ;-) Basically, my reasoning for ultimately deciding to use command tags for services, daemons, and the like was because I think of an application as something that has an interface other than the command line -- GUI or at least a TUI.
service have an interface other than the command line.
Right, but those interface are applications or menu items and should be tagged accordingly.
In each of the tutorials I'm writing, if there's an appropriate Red Hat GUI config tool for the service, I provide instructions on installing, configuring, enabling and starting the service graphically (as well as the standard command line method provided for all services).
Hence you end up with something like:
<para> Start the <command>httpd</command> service and set it to start by default. <guimenu>Main Menu</guimenu> => <guimenuitem>System Settings</guimenuitem> => <guimenuitem>Services</guimenuitem>, select the <command>httpd</command> service and click Start to start the service (use Restart if it is already running). </para>
In this instance, the menu item is HTTP and should be tagged as a guimenuitem. You are referring to the name of the menu item, not the actual service.
IMO it is more fitting to use the same style for commands, services, daemons, etc.
To be honest I don't know why Red Hat even bothers using the word 'daemon'. It has too many meanings in Unix (some people use it descrive a Sys V service, others the binaries run by that service, others an application that has been backgrounded by any method).
I find it best to avoid using the term 'daemon' completely. The only place where it still matters is TCP Wrappers, which is fast becoming irrelevant, due its limited application support and filtering capabilities.
Mike
On Tue, 24 Feb 2004, Tammy Fox wrote:
On Tue, 2004-02-17 at 23:47, Mike MacCana wrote:
In each of the tutorials I'm writing, if there's an appropriate Red Hat GUI config tool for the service, I provide instructions on installing, configuring, enabling and starting the service graphically (as well as the standard command line method provided for all services).
Hence you end up with something like:
<para> Start the <command>httpd</command> service and set it to start by default. <guimenu>Main Menu</guimenu> => <guimenuitem>System Settings</guimenuitem> => <guimenuitem>Services</guimenuitem>, select the <command>httpd</command> service and click Start to start the service (use Restart if it is already running). </para>
In this instance, the menu item is HTTP and should be tagged as a guimenuitem. You are referring to the name of the menu item, not the actual service.
That's correct - I should have used a better example:
'The service name for Samba is smb'
Here we're clearly not referring to command line applications or graphical interfaces - but simply telling people what the service for a particular application is.
I;'m not really too fussed about this, but I hope you can see the point that it would be nice to have a specific markup for a service.
Mike
On Tue, 2004-02-24 at 22:15, Mike MacCana wrote:
On Tue, 24 Feb 2004, Tammy Fox wrote:
On Tue, 2004-02-17 at 23:47, Mike MacCana wrote:
In each of the tutorials I'm writing, if there's an appropriate Red Hat GUI config tool for the service, I provide instructions on installing, configuring, enabling and starting the service graphically (as well as the standard command line method provided for all services).
Hence you end up with something like:
<para> Start the <command>httpd</command> service and set it to start by default. <guimenu>Main Menu</guimenu> => <guimenuitem>System Settings</guimenuitem> => <guimenuitem>Services</guimenuitem>, select the <command>httpd</command> service and click Start to start the service (use Restart if it is already running). </para>
In this instance, the menu item is HTTP and should be tagged as a guimenuitem. You are referring to the name of the menu item, not the actual service.
That's correct - I should have used a better example:
'The service name for Samba is smb'
Here we're clearly not referring to command line applications or graphical interfaces - but simply telling people what the service for a particular application is.
I;'m not really too fussed about this, but I hope you can see the point that it would be nice to have a specific markup for a service.
Mike
Sure. I agreed that we need a service tag as well as many others such as directive for configuration file options as opposed to the option tag which is only supposed to be used for options to command line utilities.
Tammy
docs@lists.stg.fedoraproject.org
-
Karsten Wade -
Mike MacCana -
Paul W. Frields -
Tammy Fox