RFC: Upgrading to DocBook 5.0

Gabor Kovesdan gabor at FreeBSD.org
Fri May 24 17:36:04 UTC 2013


Hi,

I'm working on upgrading our documentation set to DocBook 5.0 and I'd 
like to discuss some details. We have some customizations and strange 
uses, which can be expressed with DocBook 5.0's own vocabulary. This 
upgrade is a good opportunity to change these, as well. I propose the 
following changes in our vocabulary:

DocBook 5.0 has a systemitem element, which expresses actors of a 
human-system interactions. This has the class attribute to further 
classify the actor. Alternatively, we can just mark up each of them as 
systemitem without class attributes since they are not distinguished in 
rendering. Actually, I tend to prefer this solution since it simplifies 
the markup and thus lowers the learning curve of DocBook, which is often 
criticized by people, who would prefer markdown or wiki-style documentation.
username --> systemitem class="username"
groupname --> systemitem class="groupname"
hostid role="fqdn" --> systemitem class="fqdomainname"
hostid role="hostname" --> systemitem class="fqdomainname"
hostid role="domainname" --> systemitem class="fqdomainname"
hostid role="netmask" --> systemitem class="netmask"
hostid role="mac" --> systemitem class="etheraddress"
hostid role="ipaddr" --> systemitem class="ipaddress"
hostid --> systemitem

This is actually a type of file and the filename class attribute may 
also be devicefile, which expresses its semantics. Again, we should 
consider dropping the class attributes to simplify things:
devicename --> filename class="devicefile"

These are not actually distinguished in formatting and the package 
element expresses them better:
filename role="package" --> package
filename role="port" --> package

Comments are welcome.

Thanks,
Gabor


More information about the freebsd-doc mailing list