Re: DOCBOOK: Elements for describing machine names and Oracle instances

[Michael Smith <smith@xml-doc.org>]

Mike Broschinsky <mbroschi@das.state.ut.us> writes:

> I'm writing documentation for an application that we have had written
> for us. In the documentation I make mention of the different machines
> on which different parts of the application reside, identifying the
> machines by the server name assigned by our network people.
> 
> One part of the application is an Oracle instance, that also has a
> specific name.
> 
> In DocBook, is there an element that is used for machine/server names,

Yes, <systemitem> element with the class="systemname" attribute.

Here's a example instance from the DocBook reference documentation.

  <!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
  <para>
  For many years, O'Reilly's primary web server, 
  <ulink url="http://www.oreilly.com/">http://www.oreilly.com/</ulink>,
  was hosted by <application>WN</application> on
  <systemitem class="systemname">helio.oreilly.com</systemitem>.
  </para>

BTW, during the June 19 telcon[1] the DocBook Technical Committee
considered but rejected adding a "hostname" value for the class
attribute on <systemitem> (because that's what "systemname" already
is) but resolved to add some additional values: domainname,
fqdomainname, ipaddress, netmask, etheraddress.

> and is there an element for things like Oracle instances?

Nope, don't think so. But maybe use a role attribute on <systemitem>
for that, e.g. <systemitem role="orainstance"> (or maybe "dbinstance",
so you could use for other kinds of database instances as well-- not
just Oracle).

Or if you have a customization layer, add "orainstance", "dbinstance"
(or maybe just "database"?) to the enumerated list of values for the
class attribute on <systemitem>

[1] http://lists.oasis-open.org/archives/docbook-tc/200106/msg00003.html