This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: suitable markup for "service" ?


Leni Mayo <leni@moniker.net> writes:

> I'm working on a document where the notion of a "service" frequently
> crops up.  Examples of services: syslog, network, cron, inetd,
> sendmail, sshd etc.
> 
> Some properties of "service":
> - long-running - usually starts when a computer boots
> - considered infrastructure by other applications
> - service may be a process (eg syslog), or may not (eg network)
> 
> As a docbook newbie, none of the following seem to quite fit the bill:
> 
>   <application>syslog</application>
>   <command>syslog</command>
>   <systemitem class="resource">syslog</systemitem>
> 
> <systemitem> seems like the right element, but none of the class
> values seem right.

I agree that neither Application nor Command seems correct, but of the
three choices, <systemitem class="resource">syslog</systemitem> (or
systemitem class= anything else) seems to me an even less attractive
choice. If I came across that markup in a document, I think I'd assume
that what you were marking up was the name of the syslog file --
/var/log/syslog -- not the syslog daemon.

> I wondered whether a new class value for <systemitem> would make
> sense, but subsequently discarded all of:
> - "servicename" - too vague
> - "processname", to label a (long running) process on an
>   operating system, eg:
>     <systemitem class="processname">init</systemitem> 
>   but service is a slightly more general notion,
> - "assignedname", referring to names assigned by some authority,
>   capturing (for example) the keywords at:
>   http://www.iana.org/assignments/port-numbers

IMO, the best choice for now might be <application role="service">.

I realize the Definitive Guide says that "The appelation 'application'
is usually reserved for larger software packages -- WordPerfect, for
example, but not grep", but I think the intended implication there is
that genuine commands like grep should be marked up with Command instead.

But Command doesn't seem to me to be appropriate for marking up names
of services, server processes, and daemons.

Anyway, this doesn't help you solve your problem for now, but I've
filed a DocBook RFE[1] to propose that the DocBook TC discuss adding
standard markup for services/servers/processes/daemons so we don't all
have to continue resorting to ad-hoc solutions for marking them up.

  --Mike

[1] http://sourceforge.net/tracker/index.php?func=detail&aid=564776&group_id=21935&atid=384107




Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]