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