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
_______________________________________________
freebsd-doc@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-doc
To unsubscribe, send any mail to "freebsd-doc-unsubscr...@freebsd.org"
