Maven Doxia

Book output in doc-book format is not well formed

Details

  • Type: Bug Bug
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Fixed
  • Affects Version/s: 1.0-alpha-9
  • Fix Version/s: 1.1
  • Component/s: Book
  • Labels:
    None
  • Number of attachments :
    4

Description

I tried using the output from a book in doc-book to run it through a postprocesing step with docbook and found that it barfed on the source generated by doxia. Not surprising when you consider that it is not well formed, e.g. it has two <<<DOCTYPE>>> headers in it, and no root element:

+---
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<chapter><section>Bar<para>This is bar</para>
</section>
</chapter>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<chapter><section>Spam<para>This is spam</para>
</section>
</chapter>
</book>
+---

When I changed it to this it worked better

+---
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book>
<chapter><section>Bar<para>This is bar</para>
</section>
</chapter>
<chapter><section>Spam<para>This is spam</para>
</section>
</chapter>
</book>
+---

Issue Links

This issue is related to:
DOXIA-116 DocBook Simple module "book" type Sink Major Closed
This issue is depended upon by:
DOXIA-166 Book output ignores book, chapter and section titles Major Closed

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Dave Syer added a comment -

Update: when you put a title and author in the APT source itself

+---
—
Bar Section
—
Dave
—
+---

then the duplicate <<<DOCTYPE>>> declarations go away - still a bug but there is a workaround. But there is still no root element and the entity declaration is wrong (no system location) - I haven't found a workaround for that.

Show
Dave Syer added a comment - Update: when you put a title and author in the APT source itself +--- — Bar Section — Dave — +--- then the duplicate <<<DOCTYPE>>> declarations go away - still a bug but there is a workaround. But there is still no root element and the entity declaration is wrong (no system location) - I haven't found a workaround for that.
Hide
Permalink
Dave Syer added a comment -

I notice from the source code of DocBookSink

1. it has getters and setters for systemId and publicId - is there a configuration option somewhere for those?

2. it has book() and book_() methods which are non-standard for a Sink I think. It looks like book_() is used but book() is not. Shouldn't book() be used explicitly at the start of a book (and all the logic about dcotypes and everything from head() should be in book())? This would make sure that only one DOCTYPE was emitted.

Show
Dave Syer added a comment - I notice from the source code of DocBookSink 1. it has getters and setters for systemId and publicId - is there a configuration option somewhere for those? 2. it has book() and book_() methods which are non-standard for a Sink I think. It looks like book_() is used but book() is not. Shouldn't book() be used explicitly at the start of a book (and all the logic about dcotypes and everything from head() should be in book())? This would make sure that only one DOCTYPE was emitted.
Hide
Permalink
Lukas Theussl added a comment -

Dave, we need to keep things apart. The reason for this issue is most likely in the docbook module, see DOXIA-184 for a list of known issues. We have to improve the quality of our Parsers/Sinks before we can expect them to be used seriously in applications like book.

ad 1) not sure what you mean with configuration option, from the pom? In that case it should be injected via the doxia-maven-plugin.

ad 2) I have no idea what the book() methods are used for, but since it's docbook module specific, they shouldn't do anything vital

Show
Lukas Theussl added a comment - Dave, we need to keep things apart. The reason for this issue is most likely in the docbook module, see DOXIA-184 for a list of known issues. We have to improve the quality of our Parsers/Sinks before we can expect them to be used seriously in applications like book. ad 1) not sure what you mean with configuration option, from the pom? In that case it should be injected via the doxia-maven-plugin. ad 2) I have no idea what the book() methods are used for, but since it's docbook module specific, they shouldn't do anything vital
Hide
Permalink
Dave Syer added a comment -

> The reason for this issue is most likely in the docbook module

But DocbookRenderer is in the doxia-book project (not the Docbook module), so I think this issue is in the right place unless the renderers get factored out.

> ad 1) not sure what you mean with configuration option, from the pom? In
> that case it should be injected via the doxia-maven-plugin.

How? As far as I can see, the doxia-maven-plugin only has configuration options for the book declaration, not for the renderers. I have tried asking this question in 4 different ways, now, in 4 different forums. If you know how to configure the DocbookRenderer from the plugin please show an example.

> ad 2) I have no idea what the book() methods are used for, but since it's docbook
> module specific, they shouldn't do anything vital

They are internal to DocbookRenderer (as I already said). Doesn't mean they don't do anything vital (otherwise why would they exist?). It was just a hint - the book() method is called in the wrong place.

Show
Dave Syer added a comment - > The reason for this issue is most likely in the docbook module But DocbookRenderer is in the doxia-book project (not the Docbook module), so I think this issue is in the right place unless the renderers get factored out. > ad 1) not sure what you mean with configuration option, from the pom? In > that case it should be injected via the doxia-maven-plugin. How? As far as I can see, the doxia-maven-plugin only has configuration options for the book declaration, not for the renderers. I have tried asking this question in 4 different ways, now, in 4 different forums. If you know how to configure the DocbookRenderer from the plugin please show an example. > ad 2) I have no idea what the book() methods are used for, but since it's docbook > module specific, they shouldn't do anything vital They are internal to DocbookRenderer (as I already said). Doesn't mean they don't do anything vital (otherwise why would they exist?). It was just a hint - the book() method is called in the wrong place.
Hide
Permalink
Dave Syer added a comment -

For Xhtml format the BookRenderer uses a subclass of XhtmlSink physically located in the book module. I think this is a better approach than that in the Docbook case because it keeps the responsibilities separate. If I work on a patch for this can it drop the "isBook" flag from the DocbookSink and move that logic to a subclass, like the Xhtml case?

Show
Dave Syer added a comment - For Xhtml format the BookRenderer uses a subclass of XhtmlSink physically located in the book module. I think this is a better approach than that in the Docbook case because it keeps the responsibilities separate. If I work on a patch for this can it drop the "isBook" flag from the DocbookSink and move that logic to a subclass, like the Xhtml case?
Hide
Permalink
Lukas Theussl added a comment -

Yes, I think it should be like that for all modules, so the output can be decoupled from the core modules.

Show
Lukas Theussl added a comment - Yes, I think it should be like that for all modules, so the output can be decoupled from the core modules.
Hide
Permalink
Dave Syer added a comment -

Patch (DOXIA-160.patch) attached. Splits DocBook Book generation into a separate Sink in the book module, following the pattern of Xhtml.

There are some outstanding tasks for tidying up which I will raise separately since they might or might not be valid and/or doable.

Show
Dave Syer added a comment - Patch (DOXIA-160.patch) attached. Splits DocBook Book generation into a separate Sink in the book module, following the pattern of Xhtml. There are some outstanding tasks for tidying up which I will raise separately since they might or might not be valid and/or doable.
Hide
Permalink
Lukas Theussl added a comment -

Dave, I can't apply this patch, something's wrong with the directory structure. Did you create it wrt current svn trunk?

Show
Lukas Theussl added a comment - Dave, I can't apply this patch, something's wrong with the directory structure. Did you create it wrt current svn trunk?
Hide
Permalink
Dave Syer added a comment -

Updated patch DOXIA-160.1.patch after SVN update - there was a conflict which probably explains why the old patch couldn't be applied.

Show
Dave Syer added a comment - Updated patch DOXIA-160.1.patch after SVN update - there was a conflict which probably explains why the old patch couldn't be applied.
Hide
Permalink
Lukas Theussl added a comment -

Applied a privatly submitted patch (r594680). Thanks!

Show
Lukas Theussl added a comment - Applied a privatly submitted patch (r594680). Thanks!

People

Vote (0)
Watch (0)

Dates

  • Created:
    Updated:
    Resolved:
Atlassian JIRA (v4.4.3#663-r165197) | Report a problem
Powered by a free Atlassian JIRA open source license for Codehaus. Try JIRA - bug tracking software for your team.