Docbook writer: add XML namespaces to top-level elements

[jtojnar]

Previously, we only added xmlns attributes to chapter elements, even when running with --top-level-division=section. Let’s add the namespaces to part and section elements too, when they are the selected top-level divisions.

We do not need to add namespaces to documents produced with --standalone flag, since those will already have xmlns attribute on the root element in the template.

[jgm]

I'm not sure why this is needed. Fragment mode (not --standalone) is intended for use in generating parts of documents, and these documents will presumably have the needed xmlns on the root element, so this would be redundant.

[jtojnar]

Hmm, we use this in Nixpkgs for generating sections and chapters that we then include using XInclude into the final DocBook book. Included documents need to be well-formed so they need to declare all the namespaces used in the file.

I guess it might make some sense to use --standalone for the sections too – they can be rendered on their own, even though it is not their purpose. But the default docbook5 template only supports creating articles.

I guess we could create a custom template like the one bellow but we would need to pass the id and block variables manually in a front matter and could no longer use headings. That is

---
title: Sect
id: sect
block: section
---

foo.

instead of

# Sect {#sect}

foo.

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE $block$>
<$block$
$if(lang)$
  xml:lang="$lang$"
$endif$
  xmlns="http://docbook.org/ns/docbook" version="5.0"
$if(mathml)$
  xmlns:mml="http://www.w3.org/1998/Math/MathML"
$endif$
$if(id)$
  xml:id="$id$"
$endif$
  xmlns:xlink="http://www.w3.org/1999/xlink" >
  <info>
    <title>$title$</title>
$if(subtitle)$
    <subtitle>$subtitle$</subtitle>
$endif$
$if(author)$
    <authorgroup>
$for(author)$
      <author>
        $author$
      </author>
$endfor$
    </authorgroup>
$endif$
$if(date)$
    <date>$date$</date>
$endif$
  </info>
$for(include-before)$
  $include-before$
$endfor$
  $body$
$for(include-after)$
  $include-after$
$endfor$
</$block$>

But this template could be added to pandoc and the writer updated so that it gets block from writerTopLevelDivision and id and title from the first heading.

[jtojnar]

Then again, it is completely fine to declare XML namespaces on non-root elements and chapters were already adding xmlns attributes even when not in standalone mode.

[jgm]

On the custom template solution: you might find it handy to use --shift-heading-level-by=-1 here. This will populate the metadata title with the top-level header.

[jgm]

Hm, yes, we do have code (l. 173) that says:

      nsAttr = if version == DocBook5 && lvl == 0 then [("xmlns", "http://docbook.org/ns/docbook"),("xmlns:xlink", "http://www.w3.org/1999/xlink")]

I'm not sure what motivated this. But maybe it was exactly the thing you're talking about -- included chapters in separate files.

[jgm]

OK, now that I've actually looked at your code, I see that you knew all that!

I'm persuaded. I'll merge this.