Hi, On Thu, 8 Oct 2015 17:16:39 +1100 Aristedes Maniatis <a...@ish.com.au> wrote:
> [...] > Thanks Thomas. And thanks to everyone else who responded. You're welcome. :) > [...] Overall my experience with docbook has been good, > tempered only with a lack of good examples. You can find some examples in the following link, although they are created as test files: https://github.com/docbook/xslt10-stylesheets/tree/master/testdocs/tests > Yes, there is reasonable technical documentation. But not much of the > "best practices" kind of stuff. I guess it has something to do that DocBook supports different use cases. As such, it has a broad spectrum how to markup your text. I tried to collect some of these "best practices" that I've learned over the years in my cookbook (see link below). > I'd like some more "structure your > document like this unless you know what you are doing" sort of thing. > When does it make sense to use <simplelist> instead of > <itemizedlist>? Or why would I want a <segmentedlist> instead of > <variablelist>? Or what's the point of <sectx> instead of nested > <section>s. You can find some of your questions answered in my cookbook: http://doccookbook.sf.net/html/en/dbc.markup.html Regarding the simplelist vs. itemizedlist: yes, it may be confusing, but in most cases you can use itemizedlist and don't care about simplelist. According to the TDG, "ironically, the processing expectations of a simplelist are quite complex." You can render your simplelist inline, in a row- or column-major table. > [...] there is a whole > lot of docbook which is best avoided unless you have really > specialised needs. That is true. It is always a good idea to go through of all DocBook elements and think about what is useful or not. You can also use the simplified version of DocBook which is a subset of the complete schema. That may make it easier for you and your team. Another alternative would be to create your own DocBook schema. With the help of RELAX NG, this is really easy now! Especially if you want to remove elements, this can be done in a simple line. > [...] -- Gruß/Regards, Thomas Schraitle --------------------------------------------------------------------- To unsubscribe, e-mail: docbook-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-h...@lists.oasis-open.org