Date: Tue, 28 May 2013 23:06:08 +0200 From: Gabor Kovesdan <gabor@FreeBSD.org> To: doc@freebsd.org Subject: Re: RFC: Upgrading to DocBook 5.0 Message-ID: <51A51C40.1030205@FreeBSD.org> In-Reply-To: <519FA4FE.4030305@FreeBSD.org> References: <519FA4FE.4030305@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Em 24-05-2013 19:35, Gabor Kovesdan escreveu: > 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 I have a patch to preview how it would look like: http://kovesdan.org/patches/fbsd-docbook5.diff Please comment on this. It is very important to discuss this kind of changes. Thanks, Gabor
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?51A51C40.1030205>