Passthrough mode in doxygen2boostbook is not pass-through and ignores doxygen references

[Mathias Gaunard <loufoque@…>]

The passthrough mode in doxygen2boostbook is not pass-through at all since it doesn't allow arbitrary xml to be left as-is, which can be useful to directly insert boostbook from descriptions in doxygen.

The passthrough mode is also ignoring <ref> elements doxygen provides.

The attached patch fixes both issues.

[Daniel James]

Can you give some examples of how this is used? Such as: some xml that it currently doesn't support, an example of why initializer elements are ignored and an example of how \ref is used.

[Mathias Gaunard <loufoque@…>]

1)

/** The argument must model the \c \xmlonly<conceptname>Foo</conceptname>\endxmlonly concept. */
template<typename T>
void use_foo(T& t);

Without this patch, <conceptname> will simply be ignored.

2) I had to special case initializer elements so that they don't match *, but unfortunately my code is wrong, they certainly should not be ignored. This is the correct code:

  <xsl:template match="initializer" mode="passthrough">
    <xsl:apply-templates mode="passthrough"/>
  </xsl:template>

3) doxygen provides some useful <ref> in the following scenario:

/** This function uses an instance of \c thingy */
void bar();

with "thingy" a type doxygen knows about, this will generate the following xml :

<detaileddescription><para>
This function uses an instance of <computeroutput><ref refid="..." kindref="compound">thingy</ref></computeroutput>
</para></detaileddescription>

[Daniel James]

I'm going to do this in two parts because for a lot of the existing documentation, doxygen converts words to refs that probably shouldn't be refs. Do you know if there's a way to stop it?

[Daniel James]

(In [55370]) Pass through more elements in doxygen2boostbook. Refs #3309.

[Daniel James]

(In [56702]) Merge some documentation changes and inspect fixes.

Merged revisions 55370,55729,56440,56570-56571,56603,56697-56699 via svnmerge from ​https://svn.boost.org/svn/boost/trunk

........

r55370 | danieljames | 2009-08-02 19:18:14 +0100 (Sun, 02 Aug 2009) | 1 line

Pass through more elements in doxygen2boostbook. Refs #3309.

........

r55729 | danieljames | 2009-08-23 11:07:25 +0100 (Sun, 23 Aug 2009) | 3 lines

Add depencies on doxygen documentation to standalone documentation targets.

This seems to be needed for building pdfs.

........

r56440 | danieljames | 2009-09-27 20:11:39 +0100 (Sun, 27 Sep 2009) | 1 line

Fix silly error in doxygen test file.

........

r56570 | danieljames | 2009-10-04 11:37:36 +0100 (Sun, 04 Oct 2009) | 1 line

Clean up some unordered TODOs.

........

r56571 | danieljames | 2009-10-04 11:37:56 +0100 (Sun, 04 Oct 2009) | 1 line

Detab.

........

r56603 | danieljames | 2009-10-05 22:29:39 +0100 (Mon, 05 Oct 2009) | 1 line

Various inspect fixes.

........

r56697 | danieljames | 2009-10-10 14:00:28 +0100 (Sat, 10 Oct 2009) | 1 line

Add forwarding html file for accumulators.

........

r56698 | danieljames | 2009-10-10 14:01:14 +0100 (Sat, 10 Oct 2009) | 1 line

Missing newline.

........

r56699 | danieljames | 2009-10-10 14:01:30 +0100 (Sat, 10 Oct 2009) | 1 line

Add copyright to boostbook reference xml.

........

[Daniel James]

Resolving as fixed. If anyone wants to deal with <ref> I created #5243. No example of why <initializer> support is needed, so I can't do anything there.

[Daniel James]

Resolving properly this time.