Date: Fri, 24 May 2013 19:35:58 +0200 From: Gabor Kovesdan <gabor@FreeBSD.org> To: doc@freebsd.org Subject: RFC: Upgrading to DocBook 5.0 Message-ID: <519FA4FE.4030305@FreeBSD.org>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?519FA4FE.4030305>