Docbook v5.0 documents - best practices ?

[Fredrik Svensson <fred@ludd.ltu.se>]

Hi,

I was looking into starting to make Docbook version 5.0 documents.
Since I am starting a document from scratch I would like to get to know the
recommended way, for the future. I guess that is using RNG and Xinclude.

I started to look at how to start the document and the Howto[1] suggests

<?xml version="1.0" encoding="utf-8"?>
<article xmlns="http://docbook.org/ns/docbook"; version="5.0" xml:lang="en">
  <title>Sample article</title>
  <para>This is really very short article.</para>
</article>

while the TDG5[2] disuses :

<?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V5.0//EN"
               "http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd";>

There are also unexplained examples (The Document (or Root) Element)
<book xmlns="http://docbook.org/ns/docbook";>…</book>

Still is the version="5.0" needed ? recommended ?

I am also interested in using several files[3] and I am a bit unsure how to
start. From what I read this would be the way (the example does not contain
the xml markup or version) ?

book.xml
========
<?xml version="1.0" encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook"; version="5.0" xml:lang="en"
      xmlns:xi="http://www.w3.org/2001/XInclude";>
<title>My First Book</title>
<xi:include href="chap1.xml"/>
<xi:include href="appa.xml"/>
</book>

chap1.xml
=========
<?xml version="1.0" encoding="utf-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"; version="5.0" xml:lang="en">
<title>My First Chapter</title>
<para>My first paragraph.</para>
…


I understand that the documentation is under development. Still I am trying to
set up an environment for Docbook 5 for the future, and I was looking for a
best practices page..

[1] http://www.docbook.org/docs/howto/
[2] http://www.docbook.org/tdg5/en/html/ch02.html#ch02-makexml
[3] http://www.docbook.org/tdg5/en/html/ch02.html#ch02-physdiv