7:39 p.m.
Thanks guys,
Mike
__________________________________________________________________________
Mike MacCana Consultant RHCX, MCSE, MCP+I
0419 394 504
7:05 a.m.
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&g...
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
1 p.m.
That is my take on it as well:
http://fedora.redhat.com/participate/documentation-guide/s1-xml-tags-comm...
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&g...
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
4:57 p.m.
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-comm...
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
3:01 p.m.
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&g...
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.
--
Karsten Wade : Tech Writer, RHCE : o: +1.831.466.9664
kwade(a)redhat.com : http://rhea.redhat.com/ : c: +1.831.818.9995
Red Hat Applications : WAF, CMS, Portal Server
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
10:36 p.m.
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&g...
> 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
10:47 p.m.
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
8:30 p.m.
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
9:15 p.m.
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
9:42 p.m.
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
7377
days inactive
7390
days old
9 comments
4 participants
participants (4)
-
Karsten Wade -
Mike MacCana -
Paul W. Frields -
Tammy Fox