Re: [docbook] feedback on RTC Quickstart Guide

[Thomas Schraitle <tom_schr@web.de>]

Hi Daniel,

Am Dienstag, 22. September 2015, 17:16:53 schrieb Daniel Pocock:
> 
> I've now put the Docbook source code of the RTC Quickstart Guide[1] onto
> Github:
> 
> https://github.com/opentelecoms-org/RTCQuickstartGuide
> 
> If anybody can share any ideas about how I can improve this further or
> even just point me at other documents or example that might help me
> improve what I'm doing it would be really welcome.

It seems, you have a mixture of DocBook4 and DocBook5. IMHO this is not a good 
idea; keep it consistent. :)

Here are some of the things that I would change:

1. Missing DocBook 5 and XLink namespaces
   The files which contains, for example, a chapter are missing the
   DocBook 5 namespace. Probably also the XLink namespace.

2. <ulink url="..."/> vs <link xlink:href="..."/>
   There is no <ulink/> in DocBook5 anymore. It has been renamed to
   <link/>. 

3. id vs. xml:id
   Lots of files contain id attribute; this is wrong in DocBook5. Use the
   attribute xml:id instead.

4. Validation
   In make-book.sh you just run xsltproc, but there is no validation step.
   If you don't use validation you won't spot any errors in your files.
   *Always* validate your files. :)

Read also the following section about what has been changed:
http://docbook.org/tdg5/en/html/ch01.html#introduction-whats-new


Hope this helps. :)

-- 
Gruß/Regards
  Thomas Schraitle