[DEV] add v1.76.0

tools/docca/example/Jamfile

@@ -0,0 +1,305 @@
+#
+# Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+#
+# Official repository: https://github.com/cppalliance/json
+#
+
+project json/doc ;
+
+import os ;
+import path ;
+import boostbook ;
+import quickbook ;
+import xsltproc ;
+import doxygen ;
+import modules ;
+import saxonhe ;
+
+path-constant out : . ;
+
+#-------------------------------------------------------------------------------
+#
+# Build the list of header files that Doxygen will scan. We need
+# this list to inform the build system of the dependencies so the
+# docs can be rebuild if any of the header files change.
+#
+
+local sources = [ path.glob-tree ../include/boost/json : *.hpp *.ipp : detail impl ] ;
+
+# Get the configured paths to doxygen and xsltproc
+
+.doxygen = [ doxygen.name ] ;
+.doxygen ?= doxygen ;
+
+.xsltproc = [ xsltproc.name ] ;
+.xsltproc ?= xsltproc ;
+
+#-------------------------------------------------------------------------------
+#
+# Invoke Doxygen to process the header files and produce the XML
+# containing the description of the C++ declarations and extracted
+# Javadoc comments.
+#
+make index.xml
+:
+./source.dox
+:
+@make_doxygen_xml
+:
+<dependency>$(sources)
+;
+
+rule make_doxygen_xml ( targets * : sources * : properties * )
+{
+  EXAMPLE_DIR on $(targets) =
+    [ path.native [  path.root
+    [ on $(sources[1]) return $(SEARCH) ] [ path.pwd ] ] ]  ;
+}
+
+if [ os.name ] = NT
+{
+    actions make_doxygen_xml
+    {
+        SET EXAMPLE_DIR=$(EXAMPLE_DIR)
+        SET XML_OUTPUT=$(1:D)
+        "$(.doxygen)" $(2)
+    }
+}
+else
+{
+    actions make_doxygen_xml
+    {
+        export EXAMPLE_DIR=$(EXAMPLE_DIR)
+        export XML_OUTPUT=$(1:D)
+        "$(.doxygen)" $(2)
+    }
+}
+
+#-------------------------------------------------------------------------------
+#
+# Copy all the XSLT modules to the target directory.
+#
+# FIXME: Change this so we can just specify a directory,
+#        rather than every file individually.
+#
+#        Also, somehow force dependencies in a general way
+#        such that the XSLT has to be executed again
+#        if any of the modules change. For example,
+#        if base-extract-xml-pages.xml changes, then
+#        an invocation of extract-xml-pages.xsl (which
+#        imports the former) must be run again.
+#
+path-constant docca : ../../../tools/docca ;
+make extract-xml-pages.xsl      : $(docca)/include/docca/extract-xml-pages.xsl      : @copy_script ;
+make base-extract-xml-pages.xsl : $(docca)/include/docca/base-extract-xml-pages.xsl : @copy_script ;
+make common.xsl                 : $(docca)/include/docca/common.xsl                 : @copy_script ;
+make stage1.xsl                 : $(docca)/include/docca/stage1.xsl                 : @copy_script ;
+make base-stage1.xsl            : $(docca)/include/docca/base-stage1.xsl            : @copy_script ;
+make stage2.xsl                 : $(docca)/include/docca/stage2.xsl                 : @copy_script ;
+make base-stage2.xsl            : $(docca)/include/docca/base-stage2.xsl            : @copy_script ;
+make assemble-quickbook.xsl     : $(docca)/include/docca/assemble-quickbook.xsl     : @copy_script ;
+make emphasized-types.xsl       : $(docca)/include/docca/emphasized-types.xsl       : @copy_script ;
+make base-config.xsl            : $(docca)/include/docca/base-config.xsl            : @copy_script ;
+
+# Copy the project-specific config XSLT
+make custom-overrides.xsl : xsl/custom-overrides.xsl : @copy_script ;
+
+# Make a copy of the given file.
+#
+actions copy_script
+{
+    cp $(2[1]) $(1)
+}
+
+
+# This is to initially create the directory as a side effect; I'm sure there's a better way...
+make xml-pages/directory/placeholder : index.xml : @null_action ;
+
+#-------------------------------------------------------------------------------
+#
+# Run index.xml through the first transformation stage
+# (assembling and splitting the XML into page-specific files).
+#
+make xml-pages.xml
+    :
+        index.xml
+        extract-xml-pages.xsl
+
+        # Make bjam aware of additional dependencies
+        base-extract-xml-pages.xsl
+        base-config.xsl
+        custom-overrides.xsl
+        common.xsl
+    :
+        saxonhe.saxonhe
+    ;
+
+# This is just to make the directory eligible as a source
+make xml-pages : index.xml : @null_action ;
+
+# Not ready for prime time until I figure out how to get the xslt-visualizer code in place
+#make stage1/code-trace-enabled/stage1.xsl
+#    :
+#        stage1.xsl
+#        xslt-visualizer/xsl/trace-enable.xsl
+#    :
+#        saxonhe.saxonhe
+#    ;
+
+# This is to initially create the directory as a side effect; I'm sure there's a better way...
+make stage1/results/directory/placeholder : xml-pages.xml : @null_action ;
+make stage2/results/directory/placeholder : xml-pages.xml : @null_action ;
+
+# TODO: figure out why this (and the following stage) get built every time
+make stage1/results
+    :
+        xml-pages
+        stage1.xsl
+
+        # additional dependencies
+        xml-pages.xml
+        base-stage1.xsl
+        base-config.xsl
+        custom-overrides.xsl
+        common.xsl
+    :
+        saxonhe.saxonhe_dir
+    ;
+
+make stage2/results
+    :
+        stage1/results
+        stage2.xsl
+
+        # additional dependencies
+        emphasized-types.xsl
+        base-stage2.xsl
+        base-config.xsl
+        custom-overrides.xsl
+        common.xsl
+    :
+        saxonhe.saxonhe_dir
+    ;
+
+make reference.qbk
+    :
+        xml-pages.xml
+        assemble-quickbook.xsl
+
+        # TODO: make this input to the XSLT somehow
+        #       rather than relying on it being hard-coded
+        #       in the XSLT (which it is!)
+        stage2/results
+    :
+        saxonhe.saxonhe
+    ;
+
+actions make_dir
+{
+    mkdir $(1)
+}
+
+make combine.xslt : index.xml : @null_action ;
+
+actions touch_file
+{
+    touch $(1) ;
+}
+
+actions null_action
+{
+    touch -c $(1) ;
+}
+
+make reference.xml
+    :
+        combine.xslt
+        index.xml
+    :
+        @call-xsltproc
+    ;
+
+actions call-xsltproc
+{
+    "$(.xsltproc)" $(2) > $(1)
+}
+
+#-------------------------------------------------------------------------------
+#
+# Produce the reference.qbk file by running
+# the reference xml through the transform.
+#
+#make reference.qbk
+#    :
+#        reference.xml
+#        transform.xsl
+#    :
+#        saxonhe.saxonhe
+#    ;
+
+# We have to make a copy of reference.qbk and put it
+# in a place where the static .qbk files can find it
+#
+install qbk : reference.qbk ;
+
+#-------------------------------------------------------------------------------
+#
+# Produce the Boost.Book XML from the QuickBook
+#
+
+install images
+    :
+        [ glob images/*.png ]
+    :
+        <location>html/json/images
+    ;
+
+explicit images ;
+
+xml json_doc
+    :
+        main.qbk
+    :
+        <dependency>images
+        <dependency>qbk
+    ;
+
+explicit json_doc ;
+
+#-------------------------------------------------------------------------------
+#
+# HTML documentation for $(BOOST_ROOT)/doc/html
+#
+#-------------------------------------------------------------------------------
+
+boostbook json
+    :
+        json_doc
+    :
+        <xsl:param>boost.root=../../../..
+        <xsl:param>chapter.autolabel=1
+        <xsl:param>chunk.section.depth=8                # Depth to which sections should be chunked
+        <xsl:param>chunk.first.sections=1               # Chunk the first top-level section?
+        <xsl:param>toc.section.depth=2                  # How deep should recursive sections appear in the TOC?
+        <xsl:param>toc.max.depth=8                      # How many levels should be created for each TOC?
+        <xsl:param>generate.section.toc.level=8         # Control depth of TOC generation in sections
+        <xsl:param>generate.toc="chapter toc,title section nop reference nop"
+        <include>../../../tools/boostbook/dtd
+    :
+        <dependency>images
+    ;
+
+#-------------------------------------------------------------------------------
+#
+# These are used to inform the build system of the
+# means to build the integrated and stand-alone docs.
+#
+
+alias boostdoc ;
+explicit boostdoc ;
+
+alias boostrelease : json ;
+explicit boostrelease ;

tools/docca/example/boostbook.dtd

@@ -0,0 +1,439 @@
+<!--
+   BoostBook DTD - development version
+
+   For further information, see: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?Boost_Documentation_Format
+
+   Copyright (c) 2002 by Peter Simons <simons@cryp.to>
+   Copyright (c) 2003-2004 by Douglas Gregor <doug.gregor -at- gmail.com>
+   Copyright (c) 2007 by Frank Mori Hess <fmhess@users.sourceforge.net>
+
+   Distributed under the Boost Software License, Version 1.0.
+   (See accompanying file LICENSE_1_0.txt or copy at
+   http://www.boost.org/LICENSE_1_0.txt)
+
+   The latest stable DTD module is identified by the PUBLIC and SYSTEM identifiers:
+
+   PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
+   SYSTEM "http://www.boost.org/tools/boostbook/dtd/1.1/boostbook.dtd"
+
+   $Revision$
+   $Date$
+-->
+
+<!--========== Define XInclude features. ==========-->
+<!-- This is not really integrated into the DTD yet. Needs more
+     research. -->
+<!--
+<!ELEMENT xi:include (xi:fallback)?>
+<!ATTLIST xi:include
+    xmlns:xi   CDATA       #FIXED    "http://www.w3.org/2001/XInclude"
+    href       CDATA       #REQUIRED
+    parse      (xml|text)  "xml"
+    encoding   CDATA       #IMPLIED>
+
+<!ELEMENT xi:fallback ANY>
+<!ATTLIST xi:fallback
+    xmlns:xi   CDATA   #FIXED   "http://www.w3.org/2001/XInclude">
+ -->
+
+<!ENTITY % local.common.attrib "last-revision CDATA  #IMPLIED">
+
+<!--========== Define the BoostBook extensions ==========-->
+<!ENTITY % boost.common.attrib "%local.common.attrib;
+                                id            CDATA  #IMPLIED">
+
+<!ENTITY % boost.namespace.mix
+        "class|class-specialization|struct|struct-specialization|
+         union|union-specialization|typedef|enum|
+         free-function-group|function|overloaded-function|
+         namespace">
+
+<!ENTITY % boost.template.mix
+        "template-type-parameter|template-nontype-parameter|template-varargs">
+
+<!ENTITY % boost.class.members
+        "static-constant|typedef|enum|
+         copy-assignment|constructor|destructor|method-group|
+         method|overloaded-method|data-member|class|class-specialization|struct|
+         struct-specialization|union|union-specialization">
+
+<!ENTITY % boost.class.mix
+        "%boost.class.members;|free-function-group|function|overloaded-function">
+
+<!ENTITY % boost.class.content
+             "template?, inherit*, purpose?, description?,
+              (%boost.class.mix;|access)*">
+
+<!ENTITY % boost.class-specialization.content
+             "template?, specialization?, inherit?, purpose?, description?,
+              (%boost.class.mix;|access)*">
+
+<!ENTITY % boost.function.semantics
+        "purpose?, description?, requires?, effects?, postconditions?,
+         returns?, throws?, complexity?, notes?, rationale?">
+
+<!ENTITY % library.content
+        "libraryinfo, (title, ((section|library-reference|testsuite))+)?">
+
+<!ELEMENT library (%library.content;)>
+<!ATTLIST library
+    name      CDATA   #REQUIRED
+    dirname   CDATA   #REQUIRED
+    html-only CDATA   #IMPLIED
+    url       CDATA   #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT boostbook (title, (chapter|library)*)>
+<!ATTLIST boostbook %boost.common.attrib;>
+
+<!ELEMENT libraryinfo (author+, copyright*, legalnotice*, librarypurpose, librarycategory*)>
+<!ATTLIST libraryinfo %boost.common.attrib;>
+
+<!ELEMENT librarypurpose (#PCDATA|code|ulink|functionname|methodname|classname|macroname|headername|enumname|globalname)*>
+<!ATTLIST librarypurpose %boost.common.attrib;>
+
+<!ELEMENT librarycategory (#PCDATA)>
+<!ATTLIST librarycategory
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT libraryname  (#PCDATA)>
+<!ATTLIST libraryname %boost.common.attrib;>
+
+<!ELEMENT library-reference ANY>
+<!ATTLIST library-reference
+    %boost.common.attrib;>
+
+<!ELEMENT librarylist EMPTY>
+<!ATTLIST librarylist %boost.common.attrib;>
+
+<!ELEMENT librarycategorylist (librarycategorydef)*>
+<!ATTLIST librarycategorylist %boost.common.attrib;>
+
+<!ELEMENT librarycategorydef (#PCDATA)>
+<!ATTLIST librarycategorydef
+         name   CDATA   #REQUIRED
+         %boost.common.attrib;>
+
+<!ELEMENT header ANY>
+<!ATTLIST header
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT namespace (%boost.namespace.mix;)*>
+<!ATTLIST namespace
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT class (%boost.class.content;)>
+<!ATTLIST class
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT struct (%boost.class.content;)>
+<!ATTLIST struct
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT union (%boost.class.content;)>
+<!ATTLIST union
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT class-specialization (%boost.class-specialization.content;)>
+<!ATTLIST class-specialization
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT struct-specialization (%boost.class-specialization.content;)>
+<!ATTLIST struct-specialization
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT union-specialization (%boost.class-specialization.content;)>
+<!ATTLIST union-specialization
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT access (%boost.class.members;)+>
+<!ATTLIST access
+    name CDATA #REQUIRED
+    %boost.common.attrib;>
+
+<!--========= C++ Templates =========-->
+<!ELEMENT template (%boost.template.mix;)*>
+<!ATTLIST template %boost.common.attrib;>
+
+<!ELEMENT template-type-parameter (default?, purpose?)>
+<!ATTLIST template-type-parameter
+    name                     CDATA  #REQUIRED
+    pack                     CDATA  #IMPLIED 
+    %boost.common.attrib;>
+
+<!ELEMENT template-nontype-parameter (type, default?, purpose?)>
+<!ATTLIST template-nontype-parameter
+    name                     CDATA  #REQUIRED
+    pack                     CDATA  #IMPLIED 
+    %boost.common.attrib;>
+
+<!ELEMENT template-varargs EMPTY>
+<!ATTLIST template-varargs %boost.common.attrib;>
+
+<!ELEMENT specialization (template-arg)*>
+<!ATTLIST specialization %boost.common.attrib;>
+
+<!ELEMENT template-arg ANY>
+<!ATTLIST template-arg
+    pack    CDATA  #IMPLIED 
+    %boost.common.attrib;>
+
+<!ELEMENT default ANY>
+<!ATTLIST default %boost.common.attrib;>
+
+<!ELEMENT inherit (type, purpose?)>
+<!ATTLIST inherit
+    access  CDATA  #IMPLIED
+    pack    CDATA  #IMPLIED 
+    %boost.common.attrib;>
+
+<!ELEMENT purpose ANY>
+<!ATTLIST purpose %boost.common.attrib;>
+
+<!ELEMENT description ANY>
+<!ATTLIST description %boost.common.attrib;>
+
+<!ELEMENT type ANY>
+<!ATTLIST type %boost.common.attrib;>
+
+<!ELEMENT typedef (type, purpose?, description?)>
+<!ATTLIST typedef
+    name     CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT enum (enumvalue*, purpose?, description?)>
+<!ATTLIST enum
+    name     CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT enumvalue (default?, purpose?, description?)>
+<!ATTLIST enumvalue
+    name     CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT static-constant (type, default, purpose?, description?)>
+<!ATTLIST static-constant
+    name   CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT data-member (type, purpose?, description?)>
+<!ATTLIST data-member
+    name         CDATA  #REQUIRED
+    specifiers   CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT paramtype ANY>
+<!ATTLIST paramtype %boost.common.attrib;>
+
+<!ELEMENT effects ANY>
+<!ATTLIST effects %boost.common.attrib;>
+
+<!ELEMENT postconditions ANY>
+<!ATTLIST postconditions %boost.common.attrib;>
+
+<!ELEMENT method-group (method|overloaded-method)*>
+<!ATTLIST method-group
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT constructor (template?, parameter*, %boost.function.semantics;)>
+<!ATTLIST constructor
+    specifiers   CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT destructor (%boost.function.semantics;)>
+<!ATTLIST destructor
+    specifiers   CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT method (template?, type, parameter*, %boost.function.semantics;)>
+<!ATTLIST method
+    name         CDATA  #REQUIRED
+    cv           CDATA  #IMPLIED
+    specifiers   CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT function (template?, type, parameter*, %boost.function.semantics;)>
+<!ATTLIST function
+    name         CDATA  #REQUIRED
+    specifiers   CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT overloaded-method (signature*, %boost.function.semantics;)>
+<!ATTLIST overloaded-method
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT overloaded-function (signature*, %boost.function.semantics;)>
+<!ATTLIST overloaded-function
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT signature (template?, type, parameter*)>
+<!ATTLIST signature
+    cv           CDATA  #IMPLIED
+    specifiers   CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT requires ANY>
+<!ATTLIST requires %boost.common.attrib;>
+
+<!ELEMENT returns ANY>
+<!ATTLIST returns %boost.common.attrib;>
+
+<!ELEMENT throws ANY>
+<!ATTLIST throws %boost.common.attrib;>
+
+<!ELEMENT complexity ANY>
+<!ATTLIST complexity %boost.common.attrib;>
+
+<!ELEMENT notes ANY>
+<!ATTLIST notes %boost.common.attrib;>
+
+<!ELEMENT rationale ANY>
+<!ATTLIST rationale %boost.common.attrib;>
+
+<!ELEMENT functionname (#PCDATA)>
+<!ATTLIST functionname
+    alt          CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT enumname (#PCDATA)>
+<!ATTLIST enumname
+    alt          CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT macroname (#PCDATA)>
+<!ATTLIST macroname
+    alt          CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT headername (#PCDATA)>
+<!ATTLIST headername
+    alt          CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT globalname (#PCDATA)>
+<!ATTLIST globalname
+    alt          CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT copy-assignment
+    (template?, type?, parameter*, %boost.function.semantics;)>
+<!ATTLIST copy-assignment
+    cv           CDATA  #IMPLIED
+    specifiers   CDATA  #IMPLIED
+    %boost.common.attrib;>
+
+<!ELEMENT free-function-group (function|overloaded-function)*>
+<!ATTLIST free-function-group
+    name  CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT precondition ANY>
+<!ATTLIST precondition %boost.common.attrib;>
+
+<!ELEMENT code ANY>
+<!ATTLIST code %boost.common.attrib;>
+
+<!ELEMENT using-namespace EMPTY>
+<!ATTLIST using-namespace
+    name   CDATA  #REQUIRED
+    %boost.common.attrib;>
+
+<!ELEMENT using-class EMPTY>
+<!ATTLIST using-class
+     name        CDATA #REQUIRED
+     %boost.common.attrib;>
+
+<!--========== Boost Testsuite Extensions ==========-->
+<!ENTITY % boost.testsuite.tests
+        "compile-test|link-test|run-test|
+         compile-fail-test|link-fail-test|run-fail-test">
+<!ENTITY % boost.testsuite.test.content
+        "source*, lib*, requirement*, purpose, if-fails?">
+
+<!ELEMENT testsuite ((%boost.testsuite.tests;)+)>
+<!ATTLIST testsuite %boost.common.attrib;>
+
+<!ELEMENT compile-test (%boost.testsuite.test.content;)>
+<!ATTLIST compile-test
+     filename CDATA #REQUIRED
+     name     CDATA #IMPLIED>
+
+<!ELEMENT link-test (%boost.testsuite.test.content;)>
+<!ATTLIST link-test
+     filename CDATA #REQUIRED
+     name     CDATA #IMPLIED>
+
+<!ELEMENT run-test (%boost.testsuite.test.content;)>
+<!ATTLIST run-test
+     filename CDATA #REQUIRED
+     name     CDATA #IMPLIED>
+
+<!ELEMENT compile-fail-test (%boost.testsuite.test.content;)>
+<!ATTLIST compile-fail-test
+     filename CDATA #REQUIRED
+     name     CDATA #IMPLIED>
+
+<!ELEMENT link-fail-test (%boost.testsuite.test.content;)>
+<!ATTLIST link-fail-test
+     filename CDATA #REQUIRED
+     name     CDATA #IMPLIED>
+
+<!ELEMENT run-fail-test (%boost.testsuite.test.content;)>
+<!ATTLIST run-fail-test
+     filename CDATA #REQUIRED
+     name     CDATA #IMPLIED>
+
+<!ELEMENT source (#PCDATA|snippet)*>
+
+<!ELEMENT snippet EMPTY>
+<!ATTLIST snippet
+     name CDATA #REQUIRED>
+
+<!ELEMENT lib (#PCDATA)>
+
+<!ELEMENT requirement (#PCDATA)>
+<!ATTLIST requirement
+     name CDATA #REQUIRED>
+
+<!ELEMENT if-fails ANY>
+
+<!ELEMENT parameter (paramtype, default?, description?)>
+<!ATTLIST parameter
+     name CDATA #IMPLIED
+     pack CDATA #IMPLIED>
+
+<!ELEMENT programlisting ANY>
+<!ATTLIST programlisting
+     name        CDATA #IMPLIED>
+
+<!--========== Customize the DocBook DTD ==========-->
+<!ENTITY % local.tech.char.class "|functionname|libraryname|enumname|headername|macroname|code">
+<!ENTITY % local.para.class
+        "|using-namespace|using-class|librarylist|librarycategorylist">
+<!ENTITY % local.descobj.class "|libraryinfo">
+<!ENTITY % local.classname.attrib "alt CDATA #IMPLIED">
+<!ENTITY % local.methodname.attrib "alt CDATA #IMPLIED">
+<!ENTITY % local.refentry.class "|library-reference|testsuite">
+<!ENTITY % local.title.char.mix "">
+<!ENTITY % programlisting.module "IGNORE">
+<!ENTITY % parameter.module      "IGNORE">
+<!ENTITY % function.module       "IGNORE">
+<!ENTITY % type.module           "IGNORE">
+
+<!--========== Import DocBook DTD ==========-->
+<!ENTITY % DocBook PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+%DocBook;

tools/docca/example/include/docca/issue_33.hpp

@@ -0,0 +1,27 @@
+//
+// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_33_HPP
+#define EXAMPLE_ISSUE_33_HPP
+
+namespace example {
+
+/** Issue 33
+
+    The Note and See Also sections should be distinct.
+
+    @note This is a note
+
+    @see https://boost.org
+*/
+struct issue_33
+{
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_34.hpp

@@ -0,0 +1,37 @@
+//
+// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_34_HPP
+#define EXAMPLE_ISSUE_34_HPP
+
+namespace example {
+
+/** Issue 34
+*/
+class issue_34
+{
+    /// Should not be displayed
+    struct P
+    {
+    };
+
+public:
+    /// Base of Q
+    struct R
+    {
+    };
+
+    /** Q should be derived only from R
+    */
+    struct Q : private P, R
+    {
+    };
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_38.hpp

@@ -0,0 +1,35 @@
+//
+// Copyright (c) 2020 Evan Lenz (evan@lenzconsulting.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_38_HPP
+#define EXAMPLE_ISSUE_38_HPP
+
+namespace example {
+
+/** Issue 38
+
+    Open:      [a, b]
+    Half-open: [a, b)
+    Closed:    (a, b)
+
+    @li Gracefully handle brackets in javadoc comments
+*/
+class issue_38
+{
+    int i_;
+
+public:
+    /** Half-open: [a, b)
+
+        first to last exclusive, i.e. [ first, last )
+    */
+    issue_38();
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_44.hpp

@@ -0,0 +1,60 @@
+//
+// Copyright (c) 2020 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_44_HPP
+#define EXAMPLE_ISSUE_44_HPP
+
+namespace example {
+
+/** Issue 44
+
+    @li All of the constructors should be
+    grouped together on the overload
+    resolution page.
+
+    @li The class page should show three
+    unique briefs for the constructor.
+*/
+class issue_44
+{
+    int i_;
+
+public:
+    /** Default constructor.
+
+        Description.
+    */
+    issue_44();
+
+    /** Constructor.
+
+        Description.
+    */
+    /** @{ */
+    issue_44(char);
+    issue_44(short, short);
+    /** @} */
+
+    /** Constructor.
+
+        Description.
+    */
+    /** @{ */
+    issue_44(char, int);
+    issue_44(long, long);
+    /** @} */
+
+    /** Void constructor
+
+        Description.
+    */
+    issue_44(void*);
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_47.hpp

@@ -0,0 +1,34 @@
+//
+// Copyright (c) 2020 Vinnie Falco (vinnie dot falco at gmail dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_47_HPP
+#define EXAMPLE_ISSUE_47_HPP
+
+namespace example {
+
+/** Issue 47
+
+    The function `max_size` should be
+    listed as a static member.
+*/
+class issue_47
+{
+    int i_;
+
+public:
+    /** Member
+    */
+    void f();
+
+    /** Static Member
+    */
+    static int max_size() noexcept;
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_48.hpp

@@ -0,0 +1,47 @@
+//
+// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_48_HPP
+#define EXAMPLE_ISSUE_48_HPP
+
+namespace example {
+
+class X
+{
+};
+
+struct Y
+{
+};
+
+/** Issue 48
+
+    The class should show one regular
+    public member function and two friend
+    functions.
+*/
+class issue_48
+{
+    /// This should not be emitted.
+    friend class X;
+
+    /// This should not be emitted.
+    friend struct Y;
+
+    /// This should be emitted
+    friend void g( issue_48 );
+
+public:
+    void f();
+
+    /// This should be emitted
+    friend void h( issue_48 );
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_52.hpp

@@ -0,0 +1,35 @@
+//
+// Copyright (c) 2020 Evan Lenz (evan@lenzconsulting.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_52_HPP
+#define EXAMPLE_ISSUE_52_HPP
+
+namespace example {
+
+/** Issue 52
+
+    Constructor and destructor are annotated as such.
+*/
+class issue_52
+{
+public:
+    /** Default constructor.
+
+        Description
+    */
+    issue_52();
+
+    /** Destructor.
+
+        Description
+    */
+    ~issue_52();
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_53.hpp

@@ -0,0 +1,44 @@
+//
+// Copyright (c) 2020 Evan Lenz (evan@lenzconsulting.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_53_HPP
+#define EXAMPLE_ISSUE_53_HPP
+
+namespace example {
+
+/** Issue 53
+
+    @li Distinct constructor descriptions
+    should be separated by a silver em dash.
+*/
+class issue_53
+{
+    int i_;
+
+public:
+    /** Default constructor.
+
+        Description.
+    */
+    issue_53();
+
+    /** Constructor.
+
+        Description.
+    */
+    issue_53(char);
+
+    /** Void constructor
+
+        Description.
+    */
+    issue_53(void*);
+};
+
+} // example
+
+#endif

tools/docca/example/include/docca/issue_55.hpp

@@ -0,0 +1,26 @@
+//
+// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+#ifndef EXAMPLE_ISSUE_55_HPP
+#define EXAMPLE_ISSUE_55_HPP
+
+namespace example {
+
+/** Issue 55
+
+    Clicking @ref f should lead to the
+    overload resolution landing page.
+*/
+struct issue_55
+{
+    void f(int);
+    void f(double);
+};
+
+} // example
+
+#endif

tools/docca/example/index.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "boostbook.dtd">
+
+<!--
+  Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+  Distributed under the Boost Software License, Version 1.0. (See accompanying
+  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+-->
+
+<section id="docca.index">
+  <title>Index</title>
+  <index/>
+</section>

tools/docca/example/main.qbk

@@ -0,0 +1,31 @@
+[/
+    Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[library docca
+    [quickbook 1.6]
+    [copyright 2016 Vinnie Falco]
+    [purpose Documentation Library]
+    [license
+        Distributed under the Boost Software License, Version 1.0.
+        (See accompanying file LICENSE_1_0.txt or copy at
+        [@http://www.boost.org/LICENSE_1_0.txt])
+    ]
+    [category template]
+    [category generic]
+]
+
+[template mdash[] '''— ''']
+[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
+[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
+
+[template include_file[path][^<'''<ulink url="https://github.com/boostorg/docca/blob/master/example/include/'''[path]'''">'''[path]'''</ulink>'''>]]
+
+[section:ref Reference]
+[include qbk/reference.qbk]
+[endsect]
+
+[xinclude index.xml]

tools/docca/example/makeqbk.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/bash
+
+# Copyright (c) 2013-2016 Vinnie Falco (vinnie dot falco at gmail dot com)
+#
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+mkdir -p temp
+doxygen source.dox
+cd temp
+xsltproc combine.xslt index.xml > all.xml
+xsltproc ../reference.xsl all.xml > ../reference.qbk
+

tools/docca/example/reference.xsl

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<!-- Variables (Edit for your project) -->
+<xsl:variable name="doc-ref" select="'docca.ref.'"/>
+<xsl:variable name="doc-ns" select="'example'"/>
+<xsl:variable name="debug" select="0"/>
+<xsl:variable name="private" select="0"/>
+<!-- End Variables -->
+
+<xsl:include href="../include/docca/doxygen.xsl"/>
+
+</xsl:stylesheet>
+

tools/docca/example/source.dox

@@ -0,0 +1,337 @@
+#---------------------------------------------------------------------------
+
+INPUT                  = $(EXAMPLE_DIR)/include/docca/
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "docca"
+PROJECT_NUMBER         =
+PROJECT_BRIEF          = Documentation Library
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       =
+CREATE_SUBDIRS         = NO
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       =
+ALWAYS_DETAILED_SEC    = YES
+INLINE_INHERITED_MEMB  = YES
+FULL_PATH_NAMES        = NO
+#STRIP_FROM_PATH        = $(EXAMPLE_DIR)/include/docca
+#STRIP_FROM_INC_PATH    = $(EXAMPLE_DIR)/include/docca
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = YES
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+ALIASES                =
+TCL_SUBST              =
+OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+EXTENSION_MAPPING      =
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = YES
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = NO
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = NO
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = NO
+SORT_MEMBER_DOCS       = NO
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = YES
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = NO
+GENERATE_TESTLIST      = NO
+GENERATE_BUGLIST       = NO
+GENERATE_DEPRECATEDLIST= NO
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = NO
+SHOW_FILES             = NO
+SHOW_NAMESPACES        = NO
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          =
+RECURSIVE              = NO
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+EXCLUDE_SYMBOLS        =
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       =
+EXAMPLE_RECURSIVE      = YES
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE =
+
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = NO
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION    = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+CLANG_ASSISTED_PARSING = NO
+CLANG_OPTIONS          =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 1
+IGNORE_PREFIX          =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = NO
+HTML_OUTPUT            = dhtm
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = NO
+HTML_DYNAMIC_SECTIONS  = NO
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME  = Publisher
+GENERATE_HTMLHELP      = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     =
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+GENERATE_QHP           = NO
+QCH_FILE               =
+QHP_NAMESPACE          = org.doxygen.Project
+QHP_VIRTUAL_FOLDER     = doc
+QHP_CUST_FILTER_NAME   =
+QHP_CUST_FILTER_ATTRS  =
+QHP_SECT_FILTER_ATTRS  =
+QHG_LOCATION           =
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.doxygen.Project
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = NO
+ENUM_VALUES_PER_LINE   = 4
+TREEVIEW_WIDTH         = 250
+EXT_LINKS_IN_WINDOW    = NO
+FORMULA_FONTSIZE       = 10
+FORMULA_TRANSPARENT    = YES
+USE_MATHJAX            = NO
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4
+EXTRA_PACKAGES         =
+LATEX_HEADER           =
+LATEX_FOOTER           =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES      =
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+LATEX_SOURCE_CODE      = NO
+LATEX_BIB_STYLE        = plain
+LATEX_TIMESTAMP        = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+RTF_SOURCE_CODE        = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_SUBDIR             =
+MAN_LINKS              = NO
+
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = YES
+XML_OUTPUT             = $(XML_OUTPUT)
+XML_PROGRAMLISTING     = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to the DOCBOOK output
+#---------------------------------------------------------------------------
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
+DOCBOOK_PROGRAMLISTING = NO
+
+#---------------------------------------------------------------------------
+# Configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             = DOXYGEN \
+                         GENERATING_DOCS \
+                         _MSC_VER
+
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = YES
+
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       =
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+PERL_PATH              = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = NO
+MSCGEN_PATH            =
+DIA_PATH               =
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+UML_LIMIT_NUM_FIELDS   = 10
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               =
+DOTFILE_DIRS           =
+MSCFILE_DIRS           =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_INCLUDE_PATH  =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES

tools/docca/example/xsl/custom-overrides.xsl

@@ -0,0 +1,25 @@
+<xsl:stylesheet version="3.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  exclude-result-prefixes="xs"
+  expand-text="yes">
+
+  <xsl:variable name="doc-ref" select="'docca.ref'"/>
+  <xsl:variable name="doc-ns" select="'example'"/>
+  <xsl:variable name="include-private-members" select="false()"/>
+
+  <xsl:template mode="includes-template-footer" match="location">
+    <xsl:variable name="convenience-header" as="xs:string?">
+      <xsl:apply-templates mode="convenience-header" select="@file"/>
+    </xsl:variable>
+    <xsl:if test="$convenience-header">
+      <xsl:text>{$nl}</xsl:text>
+      <xsl:text>Convenience header [include_file boost/{$convenience-header}]</xsl:text>
+      <xsl:text>{$nl}</xsl:text>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:template mode="convenience-header" match="@file[contains(., 'boost/json')]">json.hpp</xsl:template>
+  <xsl:template mode="convenience-header" match="@file"/>
+
+</xsl:stylesheet>