RFC: Upgrading to DocBook 5.0

[Gabor Kovesdan]

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