RFC: Upgrading to DocBook 5.0

[Gabor Kovesdan]

Em 17-06-2013 22:05, Dru Lavigne escreveu:
> Can we have a summary for the FDP (and for the benefit of Handbook editors) of when/if systemitem class= should be used? Are there also systemitems for the different types of <filename>s which should be used instead?
The systemitem element is documented well here:
http://www.docbook.org/tdg5/en/html/systemitem.html

When to specify the class atttribute is our decision and as you see, 
there are different preferences. And it is important to note that at the 
moment we are using our extensions and <systemitem> will only be used 
once we upgrade to DB 5.0. So the documentation should not be updated 
with this in head but in db5.

As for filename, it will be still <filename> and we already use 
correctly the class names, yet it should be documented. The DocBook 
reference is here:
http://www.docbook.org/tdg5/en/html/filename.html

As for the FDP, it is another item, which we have to solve. I have some 
ideas in my mind but I haven't got there yet so I haven't started a 
discussion. First, I would like to more clearly separate it into 2-3 parts:
1, A technology introduction: XML, XHTML, DocBook, XSLT. A concise 
introduction to the ideas behind these technologies and how they can be 
used for technical documentation. I think it should be like a tutorial, 
which includes references but it's no use trying to create another XML, 
XHTML or DocBook reference. It should be limited to the minimal 
knowledge that is necessary to get started with our docs.
2, How we use these technologies in our documentation set, i.e. the 
FreeBSD-specific things. One with previous knowledge in DocBook would be 
able to start reading here. It could fit here whether we use classes on 
systemitems and how our .mk files work, etc.
3, The FreeBSD writing style. General advices, spelling, etc.

Gabor