Re: [docbook] feedback on RTC Quickstart Guide

[Daniel Pocock <daniel@pocock.pro>]

On 22/09/15 20:59, Thomas Schraitle wrote:
> 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
> 

Hi Thomas,

Thanks for all that feedback, I've tried to fix all those things and
pushed the latest version of the guide.

Regards,

Daniel