From e6918187568dbd01842d8d1d2c808ce16a894239 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 21 Apr 2024 13:54:28 +0200 Subject: Adding upstream version 18.2.2. Signed-off-by: Daniel Baumann --- src/boost/tools/docca/CHANGELOG.md | 1 + src/boost/tools/docca/LICENSE_1_0.txt | 23 + src/boost/tools/docca/README.md | 26 + src/boost/tools/docca/docca.jam | 231 ++++++++ src/boost/tools/docca/example/Jamfile | 129 +++++ src/boost/tools/docca/example/boostbook.dtd | 439 ++++++++++++++ .../docca/example/include/docca/issue_101.hpp | 22 + .../tools/docca/example/include/docca/issue_33.hpp | 27 + .../tools/docca/example/include/docca/issue_34.hpp | 37 ++ .../tools/docca/example/include/docca/issue_38.hpp | 35 ++ .../tools/docca/example/include/docca/issue_44.hpp | 60 ++ .../tools/docca/example/include/docca/issue_47.hpp | 34 ++ .../tools/docca/example/include/docca/issue_48.hpp | 47 ++ .../tools/docca/example/include/docca/issue_52.hpp | 35 ++ .../tools/docca/example/include/docca/issue_53.hpp | 44 ++ .../tools/docca/example/include/docca/issue_55.hpp | 26 + .../tools/docca/example/include/docca/issue_63.hpp | 41 ++ .../tools/docca/example/include/docca/issue_69.hpp | 27 + .../tools/docca/example/include/docca/issue_70.hpp | 32 ++ .../tools/docca/example/include/docca/issue_78.hpp | 27 + src/boost/tools/docca/example/index.xml | 14 + src/boost/tools/docca/example/main.qbk | 31 + src/boost/tools/docca/example/makeqbk.sh | 13 + src/boost/tools/docca/example/reference.xsl | 14 + .../tools/docca/example/xsl/custom-overrides.xsl | 25 + .../docca/include/docca/assemble-quickbook.xsl | 20 + .../tools/docca/include/docca/base-config.xsl | 47 ++ .../docca/include/docca/base-extract-xml-pages.xsl | 476 +++++++++++++++ .../tools/docca/include/docca/base-stage1.xsl | 635 +++++++++++++++++++++ .../tools/docca/include/docca/base-stage2.xsl | 278 +++++++++ src/boost/tools/docca/include/docca/common.xsl | 107 ++++ .../include/docca/debug-friendly-quickbook.xsl | 23 + .../docca/include/docca/extract-xml-pages.xsl | 13 + src/boost/tools/docca/include/docca/stage1.xsl | 13 + src/boost/tools/docca/include/docca/stage2.xsl | 12 + src/boost/tools/docca/util/comparison/README.md | 28 + .../docca/util/comparison/build-and-compare.sh | 24 + .../tools/docca/util/comparison/compare-all.sh | 27 + .../tools/docca/util/comparison/grep-expressions | 4 + src/boost/tools/docca/util/comparison/sed-commands | 2 + .../docca/util/comparison/update-all-baselines.sh | 16 + .../docca/util/comparison/update-baseline-html.sh | 19 + .../docca/util/comparison/watch-all-builds.sh | 6 + 43 files changed, 3190 insertions(+) create mode 100644 src/boost/tools/docca/CHANGELOG.md create mode 100644 src/boost/tools/docca/LICENSE_1_0.txt create mode 100644 src/boost/tools/docca/README.md create mode 100644 src/boost/tools/docca/docca.jam create mode 100644 src/boost/tools/docca/example/Jamfile create mode 100644 src/boost/tools/docca/example/boostbook.dtd create mode 100644 src/boost/tools/docca/example/include/docca/issue_101.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_33.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_34.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_38.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_44.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_47.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_48.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_52.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_53.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_55.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_63.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_69.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_70.hpp create mode 100644 src/boost/tools/docca/example/include/docca/issue_78.hpp create mode 100644 src/boost/tools/docca/example/index.xml create mode 100644 src/boost/tools/docca/example/main.qbk create mode 100644 src/boost/tools/docca/example/makeqbk.sh create mode 100644 src/boost/tools/docca/example/reference.xsl create mode 100644 src/boost/tools/docca/example/xsl/custom-overrides.xsl create mode 100644 src/boost/tools/docca/include/docca/assemble-quickbook.xsl create mode 100644 src/boost/tools/docca/include/docca/base-config.xsl create mode 100644 src/boost/tools/docca/include/docca/base-extract-xml-pages.xsl create mode 100644 src/boost/tools/docca/include/docca/base-stage1.xsl create mode 100644 src/boost/tools/docca/include/docca/base-stage2.xsl create mode 100644 src/boost/tools/docca/include/docca/common.xsl create mode 100644 src/boost/tools/docca/include/docca/debug-friendly-quickbook.xsl create mode 100644 src/boost/tools/docca/include/docca/extract-xml-pages.xsl create mode 100644 src/boost/tools/docca/include/docca/stage1.xsl create mode 100644 src/boost/tools/docca/include/docca/stage2.xsl create mode 100644 src/boost/tools/docca/util/comparison/README.md create mode 100755 src/boost/tools/docca/util/comparison/build-and-compare.sh create mode 100755 src/boost/tools/docca/util/comparison/compare-all.sh create mode 100644 src/boost/tools/docca/util/comparison/grep-expressions create mode 100644 src/boost/tools/docca/util/comparison/sed-commands create mode 100755 src/boost/tools/docca/util/comparison/update-all-baselines.sh create mode 100755 src/boost/tools/docca/util/comparison/update-baseline-html.sh create mode 100755 src/boost/tools/docca/util/comparison/watch-all-builds.sh (limited to 'src/boost/tools/docca') diff --git a/src/boost/tools/docca/CHANGELOG.md b/src/boost/tools/docca/CHANGELOG.md new file mode 100644 index 000000000..637b66c87 --- /dev/null +++ b/src/boost/tools/docca/CHANGELOG.md @@ -0,0 +1 @@ +* Version 1 diff --git a/src/boost/tools/docca/LICENSE_1_0.txt b/src/boost/tools/docca/LICENSE_1_0.txt new file mode 100644 index 000000000..36b7cd93c --- /dev/null +++ b/src/boost/tools/docca/LICENSE_1_0.txt @@ -0,0 +1,23 @@ +Boost Software License - Version 1.0 - August 17th, 2003 + +Permission is hereby granted, free of charge, to any person or organization +obtaining a copy of the software and accompanying documentation covered by +this license (the "Software") to use, reproduce, display, distribute, +execute, and transmit the Software, and to prepare derivative works of the +Software, and to permit third-parties to whom the Software is furnished to +do so, all subject to the following: + +The copyright notices in the Software and this entire statement, including +the above license grant, this restriction and the following disclaimer, +must be included in all copies of the Software, in whole or in part, and +all derivative works of the Software, unless such copies or derivative +works are solely in the form of machine-executable object code generated by +a source language processor. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT +SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE +FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/src/boost/tools/docca/README.md b/src/boost/tools/docca/README.md new file mode 100644 index 000000000..03e050eab --- /dev/null +++ b/src/boost/tools/docca/README.md @@ -0,0 +1,26 @@ +# docca + +Docca is a set of XSLT transformations which converts Doxygen +XML extracted from Javadoc comments in C++ source code, into +Boost.Quickbook output + +These scripts are used by +[Boost.Beast](https://github.com/boostorg/beast/) +to generate the reference. +For example, this +[Javadoc comment](https://github.com/boostorg/beast/blob/b7230f12f16fe7a9f7a1ece5be1f607c8552448a/include/boost/beast/core/buffers_cat.hpp#L68]) +is extracted by Doxygen into an intermediate XML representation, +then processed by the XSLT script via Saxon-HE to produce this +[Boost.Quickbook page](https://www.boost.org/doc/libs/1_71_0/libs/beast/doc/html/beast/ref/boost__beast__buffers_cat.html). + +## Usage + +The following Doxygen configuration settings must be set as indicated: + + DISTRIBUTE_GROUP_DOC = YES + +## License + +Distributed under the Boost Software License, Version 1.0. +(See accompanying file [LICENSE_1_0.txt](LICENSE_1_0.txt) or copy at +https://www.boost.org/LICENSE_1_0.txt) diff --git a/src/boost/tools/docca/docca.jam b/src/boost/tools/docca/docca.jam new file mode 100644 index 000000000..94028d880 --- /dev/null +++ b/src/boost/tools/docca/docca.jam @@ -0,0 +1,231 @@ +# +# Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) +# Copyright (c) 2021 Dmitry Arkhipov (grisumbras@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 +# + + +import "class" : new ; +import doxygen ; +import param ; +import path ; +import project ; +import property-set ; +import quickbook ; +import saxonhe ; +import sequence ; +import toolset ; +import type ; + + +.here = [ path.make [ modules.binding $(__name__) ] ] ; +.here = $(.here:D) ; + + +rule reference ( target : sources * : requirements * : default-build * + : usage-requirements * ) +{ + param.handle-named-params + sources requirements default-build usage-requirements ; + + local overrides = $(sources[1]) ; + sources = $(sources[2-]) ; + + local project = [ project.current ] ; + local target-dir = $(target:S=) ; + target-dir = $(target-dir:B=_$(target-dir:B)-dir) ; + + # Generate doxygen configuration file from sources + sources = [ sequence.transform fix-source $(project) : $(sources) ] ; + doxyfile $(target-dir)/sources.dox + : $(sources) + : $(requirements) + GENERATE_HTML=NO + GENERATE_XML=YES + XML_OUTPUT=$(target-dir) + : $(default-build) + ; + $(project).mark-target-as-explicit $(target-dir)/sources.dox ; + + #-------------------------------------------------------------------------- + # + # Invoke Doxygen to process the header files and produce the XML + # containing the description of the C++ declarations and extracted + # Javadoc comments. + doxygen-xml-multifile $(target-dir)/stamp + : $(target-dir)/sources.dox + : $(requirements) + : $(default-build) + ; + $(project).mark-target-as-explicit $(target-dir)/stamp ; + + + # Adopt as a target index.xml which was created as a side-effect + make-explicit $(target-dir)/index.xml $(project) + : $(target-dir)/stamp + : @docca.null-action + ; + + #-------------------------------------------------------------------------- + # + # Copy the project-specific config XSLT + copy-xsl $(overrides) $(project) $(target-dir)/custom-overrides.xsl ; + + # Copy all the XSLT modules to the target directory. + # Also, specify their dependencies. + local src-dir = $(.here)/include/docca ; + copy-xsl $(src-dir)/common.xsl $(project) $(target-dir) ; + copy-xsl $(src-dir)/base-config.xsl $(project) $(target-dir) ; + copy-xsl $(src-dir)/assemble-quickbook.xsl $(project) $(target-dir) ; + + copy-xsl $(src-dir)/base-extract-xml-pages.xsl $(project) $(target-dir) + : common.xsl + ; + + copy-xsl $(src-dir)/base-stage1.xsl $(project) $(target-dir) + : common.xsl + ; + + copy-xsl $(src-dir)/extract-xml-pages.xsl $(project) $(target-dir) + : base-extract-xml-pages.xsl + base-config.xsl + custom-overrides.xsl + ; + + copy-xsl $(src-dir)/stage1.xsl $(project) $(target-dir) + : base-stage1.xsl + base-config.xsl + custom-overrides.xsl + ; + + copy-xsl $(src-dir)/base-stage2.xsl $(project) $(target-dir) + : common.xsl + ; + + copy-xsl $(src-dir)/stage2.xsl $(project) $(target-dir) + : base-stage2.xsl + base-config.xsl + custom-overrides.xsl + ; + + #------------------------------------------------------------------------------- + # + # Run index.xml through the first transformation stage + # (assembling and splitting the XML into page-specific files). + # + make-explicit $(target-dir)/xml-pages.xml $(project) + : $(target-dir)/index.xml + $(target-dir)/extract-xml-pages.xsl + : @saxonhe.saxonhe + ; + + # Adopt as a target xml-pages directory which was created as a side-effect + make-explicit $(target-dir)/xml-pages $(project) + : $(target-dir)/xml-pages.xml + : @docca.null-action + ; + + make-explicit $(target-dir)/stage1/results $(project) + : $(target-dir)/xml-pages + $(target-dir)/stage1.xsl + : @saxonhe.saxonhe_dir + : $(requirements) + ; + + make-explicit $(target-dir)/stage2/results $(project) + : $(target-dir)/stage1/results + $(target-dir)/stage2.xsl + : @saxonhe.saxonhe_dir + : $(requirements) + ; + + generate $(target) + : $(target-dir)/xml-pages.xml + $(target-dir)/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!) + $(target-dir)/stage2/results + : @docca.make-qbk + $(requirements) + : $(default-build) + : $(usage-requirements) + ; +} + + +rule make-qbk ( project name : property-set : sources * ) +{ + local action-name = saxonhe.saxonhe ; + local relevant = [ toolset.relevant $(action-name) ] ; + local action = [ + new action $(sources) + : $(action-name) + : [ $(property-set).relevant $(relevant) ] + ] ; + local target = [ + new file-target $(name) exact + : [ type.type $(name) ] + : $(project) + : $(action) + ] ; + local path = [ path.root $(name) [ $(target).path ] ] ; + return [ property-set.create $(path:D) ] $(target) ; +} + + +local rule copy-xsl ( source project target-or-dir : dependencies * ) +{ + local target ; + local dir ; + if .xsl = $(target-or-dir:S) + { + dir = $(target-or-dir:D) ; + target = $(target-or-dir:D=) ; + } + else + { + dir = $(target-or-dir) ; + target = $(source:D=) ; + } + + make-explicit $(target:TD=$(dir)) $(project) + : $(source) + : @common.copy + : $(dependencies:TD=$(dir)) + ; +} + + +local rule make-explicit ( target project : sources * : make-rule + : reqs * + : ureqs * ) +{ + make $(target) : $(sources) : $(make-rule) : $(reqs) : $(ureqs) ; + $(project).mark-target-as-explicit $(target) ; +} + + +local rule fix-source ( project path ) +{ + # Unfortunately, rule doxygen.run was written with the assumption that + # current project is located in the current directory (which is very likely + # to not be the case). We have to convert paths into a form that is both + # usable by doxygen and usable by b2 from the current project. This + # effectively means absolute paths. + # + # NOTE: doxygen.run should really do this by itself. + + path = [ path.root $(path) [ $(project).location ] ] ; + path = [ path.root $(path) [ path.pwd ] ] ; + return $(path) ; +} + + +rule null-action +{ +} diff --git a/src/boost/tools/docca/example/Jamfile b/src/boost/tools/docca/example/Jamfile new file mode 100644 index 000000000..4a68cc56b --- /dev/null +++ b/src/boost/tools/docca/example/Jamfile @@ -0,0 +1,129 @@ +# +# Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) +# Copyright (c) 2021 Dmitry Arkhipov (grisumbras@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 boostbook ; +import ../../../tools/docca/docca.jam ; + + +# Produce the reference.qbk from C++ sources +docca.reference reference.qbk + : xsl/custom-overrides.xsl + [ glob-tree-ex include/docca : *.hpp ] + : PROJECT_NAME=docca + PROJECT_NUMBER= + PROJECT_BRIEF="Documentation Library" + ABBREVIATE_BRIEF= + ALWAYS_DETAILED_SEC=YES + INLINE_INHERITED_MEMB=YES + FULL_PATH_NAMES=NO + JAVADOC_AUTOBRIEF=YES + MULTILINE_CPP_IS_BRIEF=YES + DISTRIBUTE_GROUP_DOC=YES + EXTRACT_ALL=YES + EXTRACT_PRIVATE=YES + EXTRACT_STATIC=YES + EXTRACT_LOCAL_CLASSES=NO + SHOW_INCLUDE_FILES=NO + INLINE_INFO=NO + SORT_MEMBER_DOCS=NO + SORT_MEMBERS_CTORS_1ST=YES + GENERATE_TODOLIST=NO + GENERATE_TESTLIST=NO + GENERATE_BUGLIST=NO + GENERATE_DEPRECATEDLIST=NO + SHOW_USED_FILES=NO + SHOW_FILES=NO + SHOW_NAMESPACES=NO + FILE_PATTERNS= + EXAMPLE_PATTERNS= + MACRO_EXPANSION=YES + EXPAND_ONLY_PREDEF=YES + PREDEFINED="\\ + DOXYGEN \\ + GENERATING_DOCS \\ + _MSC_VER" + CLASS_DIAGRAMS=NO + #STRIP_FROM_PATH=$(EXAMPLE_DIR)/include/docca + #STRIP_FROM_INC_PATH=$(EXAMPLE_DIR)/include/docca + ; + +#------------------------------------------------------------------------------- +# +# Produce the reference.qbk file by running +# the reference xml through the transform. +# +#make reference.qbk +# : +# reference.xml +# transform.xsl +# : +# saxonhe.saxonhe +# ; + +#------------------------------------------------------------------------------- +# +# Produce the Boost.Book XML from the QuickBook +# + +install images + : + [ glob images/*.png ] + : + html/json/images + ; + +explicit images ; + +xml json_doc + : + main.qbk + : + reference.qbk + images + ; + +explicit json_doc ; + +#------------------------------------------------------------------------------- +# +# HTML documentation for $(BOOST_ROOT)/doc/html +# +#------------------------------------------------------------------------------- + +boostbook json + : + json_doc + : + boost.root=../../../.. + chapter.autolabel=1 + chunk.section.depth=8 # Depth to which sections should be chunked + chunk.first.sections=1 # Chunk the first top-level section? + toc.section.depth=2 # How deep should recursive sections appear in the TOC? + toc.max.depth=8 # How many levels should be created for each TOC? + generate.section.toc.level=8 # Control depth of TOC generation in sections + generate.toc="chapter toc,title section nop reference nop" + ../../../tools/boostbook/dtd + : + 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 ; diff --git a/src/boost/tools/docca/example/boostbook.dtd b/src/boost/tools/docca/example/boostbook.dtd new file mode 100644 index 000000000..bd4c3f871 --- /dev/null +++ b/src/boost/tools/docca/example/boostbook.dtd @@ -0,0 +1,439 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +%DocBook; diff --git a/src/boost/tools/docca/example/include/docca/issue_101.hpp b/src/boost/tools/docca/example/include/docca/issue_101.hpp new file mode 100644 index 000000000..8b5b53991 --- /dev/null +++ b/src/boost/tools/docca/example/include/docca/issue_101.hpp @@ -0,0 +1,22 @@ +// +// Copyright (c) 2021 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_101_HPP +#define EXAMPLE_ISSUE_101_HPP + +namespace example { + +/** Issue 101 + + `typename` parameters should be handled (without generating an error). +*/ +template +class issue_101; + +} // example + +#endif diff --git a/src/boost/tools/docca/example/include/docca/issue_33.hpp b/src/boost/tools/docca/example/include/docca/issue_33.hpp new file mode 100644 index 000000000..8323356c9 --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_34.hpp b/src/boost/tools/docca/example/include/docca/issue_34.hpp new file mode 100644 index 000000000..c05f8058d --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_38.hpp b/src/boost/tools/docca/example/include/docca/issue_38.hpp new file mode 100644 index 000000000..eb515033d --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_44.hpp b/src/boost/tools/docca/example/include/docca/issue_44.hpp new file mode 100644 index 000000000..790f77f81 --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_47.hpp b/src/boost/tools/docca/example/include/docca/issue_47.hpp new file mode 100644 index 000000000..03324e131 --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_48.hpp b/src/boost/tools/docca/example/include/docca/issue_48.hpp new file mode 100644 index 000000000..9f0b9ea9f --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_52.hpp b/src/boost/tools/docca/example/include/docca/issue_52.hpp new file mode 100644 index 000000000..a39cbd493 --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_53.hpp b/src/boost/tools/docca/example/include/docca/issue_53.hpp new file mode 100644 index 000000000..53cfe7521 --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_55.hpp b/src/boost/tools/docca/example/include/docca/issue_55.hpp new file mode 100644 index 000000000..85628f445 --- /dev/null +++ b/src/boost/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 diff --git a/src/boost/tools/docca/example/include/docca/issue_63.hpp b/src/boost/tools/docca/example/include/docca/issue_63.hpp new file mode 100644 index 000000000..5b2ab07a3 --- /dev/null +++ b/src/boost/tools/docca/example/include/docca/issue_63.hpp @@ -0,0 +1,41 @@ +// +// Copyright (c) 2021 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_63_HPP +#define EXAMPLE_ISSUE_63_HPP + +namespace example { + +/** Issue 63 + + @li Markup (@ commands) in tables should be rendered +*/ +enum class issue_63 +{ + /** + * foo brief + + foo description + + @see issue_55 + */ + foo, + + /** + * bar brief + + bar description + + @li First bullet referencing @ref issue_55 + @li Second bullet + */ + bar +}; + +} // example + +#endif diff --git a/src/boost/tools/docca/example/include/docca/issue_69.hpp b/src/boost/tools/docca/example/include/docca/issue_69.hpp new file mode 100644 index 000000000..28a0d9338 --- /dev/null +++ b/src/boost/tools/docca/example/include/docca/issue_69.hpp @@ -0,0 +1,27 @@ +// +// Copyright (c) 2021 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_69_HPP +#define EXAMPLE_ISSUE_69_HPP + +namespace example { + +/** Issue 69 + + The brackets in the @ref operator[] page's + code block should not appear escaped. Nor + should they in that link just there (in this + sentence). +*/ +struct issue_69 +{ + operator[](string_view key); +}; + +} // example + +#endif diff --git a/src/boost/tools/docca/example/include/docca/issue_70.hpp b/src/boost/tools/docca/example/include/docca/issue_70.hpp new file mode 100644 index 000000000..89271d789 --- /dev/null +++ b/src/boost/tools/docca/example/include/docca/issue_70.hpp @@ -0,0 +1,32 @@ +// +// Copyright (c) 2021 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_70_HPP +#define EXAMPLE_ISSUE_70_HPP + +namespace example { + +/** Issue 70 + + This reference, @ref issue_70_b::foo, should link to the issue_70_b page + (not issue_63). +*/ +enum class issue_70 +{ + foo, + bar +}; + +enum class issue_70_b +{ + foo, + bar +}; + +} // example + +#endif diff --git a/src/boost/tools/docca/example/include/docca/issue_78.hpp b/src/boost/tools/docca/example/include/docca/issue_78.hpp new file mode 100644 index 000000000..f1b090516 --- /dev/null +++ b/src/boost/tools/docca/example/include/docca/issue_78.hpp @@ -0,0 +1,27 @@ +// +// Copyright (c) 2021 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_78_HPP +#define EXAMPLE_ISSUE_78_HPP + +namespace example { + +/** Issue 78 + + foo() should show up under the heading "Static Member Functions" + and bar should show up under the heading "Static Members" +*/ +class issue_78 +{ +public: + static foo(); + static bar; +}; + +} // example + +#endif diff --git a/src/boost/tools/docca/example/index.xml b/src/boost/tools/docca/example/index.xml new file mode 100644 index 000000000..c364e4ed2 --- /dev/null +++ b/src/boost/tools/docca/example/index.xml @@ -0,0 +1,14 @@ + + + + + +
+ Index + +
diff --git a/src/boost/tools/docca/example/main.qbk b/src/boost/tools/docca/example/main.qbk new file mode 100644 index 000000000..d9938111a --- /dev/null +++ b/src/boost/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] ''''''[term1]''''''] +[template indexterm2[term1 term2] ''''''[term1]''''''[term2]''''''] + +[template include_file[path][^<''''''[path]''''''>]] + +[section:ref Reference] +[include reference.qbk] +[endsect] + +[xinclude index.xml] diff --git a/src/boost/tools/docca/example/makeqbk.sh b/src/boost/tools/docca/example/makeqbk.sh new file mode 100644 index 000000000..e6fa0c30a --- /dev/null +++ b/src/boost/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 + diff --git a/src/boost/tools/docca/example/reference.xsl b/src/boost/tools/docca/example/reference.xsl new file mode 100644 index 000000000..de5675294 --- /dev/null +++ b/src/boost/tools/docca/example/reference.xsl @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/src/boost/tools/docca/example/xsl/custom-overrides.xsl b/src/boost/tools/docca/example/xsl/custom-overrides.xsl new file mode 100644 index 000000000..7f1a4d143 --- /dev/null +++ b/src/boost/tools/docca/example/xsl/custom-overrides.xsl @@ -0,0 +1,25 @@ + + + + + + + + + + + + {$nl} + Convenience header [include_file boost/{$convenience-header}] + {$nl} + + + + json.hpp + + + diff --git a/src/boost/tools/docca/include/docca/assemble-quickbook.xsl b/src/boost/tools/docca/include/docca/assemble-quickbook.xsl new file mode 100644 index 000000000..fe39870a0 --- /dev/null +++ b/src/boost/tools/docca/include/docca/assemble-quickbook.xsl @@ -0,0 +1,20 @@ + + + + + + + + + + + + + [endsect] + + + diff --git a/src/boost/tools/docca/include/docca/base-config.xsl b/src/boost/tools/docca/include/docca/base-config.xsl new file mode 100644 index 000000000..b45f5bdb5 --- /dev/null +++ b/src/boost/tools/docca/include/docca/base-config.xsl @@ -0,0 +1,47 @@ + + + + + + + + + + + + + + + + + + Defined in header [include_file {substring-after(@file, 'include/')}] + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/base-extract-xml-pages.xsl b/src/boost/tools/docca/include/docca/base-extract-xml-pages.xsl new file mode 100644 index 000000000..bf9ba53c4 --- /dev/null +++ b/src/boost/tools/docca/include/docca/base-extract-xml-pages.xsl @@ -0,0 +1,476 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {name} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {d:make-id(name)} + + + + + + + + + + + + + + + + + + + + + + + + + + + + {d:make-id(../name||'::'||name)} + {d:make-id(../name||'.' ||name)} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Unable to find referenced ID: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/base-stage1.xsl b/src/boost/tools/docca/include/docca/base-stage1.xsl new file mode 100644 index 000000000..e57defe16 --- /dev/null +++ b/src/boost/tools/docca/include/docca/base-stage1.xsl @@ -0,0 +1,635 @@ + + +]> + + + + + + + + + + + <xsl:apply-templates mode="page-title" select="."/> + + + + + + + +
(Inherited from {../@d:base-compound-name})
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {d:strip-doc-ns(compounddef/compoundname)} + + {(compounddef/sectiondef/memberdef/name)[1]} + + + + + + {$compound-name}:: + + + + + + + + + + + + + + ( + + of + + overloads) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {name} + + + + + + + + + {local-name(.)} + + + virtual + + + + + + + + + + + + + + + + + + +
+ + + + +
+ + + + + + + Synopsis + Description + + Remarks + See Also + Return Value + {title} + + Exceptions + Template Parameters + Parameters + + Types + + Friends + Related Functions + Values + + + + + + + + + Protected + Private + + + Static + + Members + Data Members + Member Functions + Types + + + + + + + + + +
+ + + +
+ + + Name + Description + + Type + + Thrown On + + + + + + + + + + + + + + + + + + + + + + + + + + + + {name} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {current-grouping-key()} + + + + + + + + + + + + + + +   + + + [destructor] + [constructor] + + + + + + + + + + + + + + + + +
+ — +
+ + + + + + + + + + + + + + + + + + {@kind} + {d:strip-ns(compoundname)} + + + {@prot} + {d:strip-doc-ns(.)} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {substring-before(.,' ')} + {substring-after(.,' ')} + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + + + + + +
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/base-stage2.xsl b/src/boost/tools/docca/include/docca/base-stage2.xsl new file mode 100644 index 000000000..0dee970cc --- /dev/null +++ b/src/boost/tools/docca/include/docca/base-stage2.xsl @@ -0,0 +1,278 @@ + + +]> + + + + + + + + + + + + + + + {$nl} + [section:{tokenize(@id,'\.')[last()]} {d:qb-escape(title)}] + + + + + {$nl}[indexterm1 {d:qb-escape(@primary-index-term)}]{$nl} + {$nl}[indexterm2 {d:qb-escape(@primary-index-term)}..{ + d:qb-escape(@secondary-index-term)}]{$nl} + + + + + {$nl}[heading {.}] + + + {$nl}{.} + + + + + + + + + + {$nl}```{$nl} + {$nl}```{$nl} + + + + {$nl}{$nl} + + {$nl} + + ; + + + ;{$nl} + + '''&raquo;''' more... + + `` + + `` + + + ``[link {$doc-ref}.{@d:refid} {d:qb-escape(.)}]`` + [link {$doc-ref}.{@d:refid} {d:qb-escape(.)}] + [link {$doc-ref}.{@d:refid} `{.}`] + + ` + ` + + enum + + using + = + ; + + ``['implementation-defined]`` + ``['see-below]`` + ``__deduced__`` + + {' '} + ; + + {' '} + + :{$nl} + {$nl} + , + + {' '} + + template< + >{$nl} + + {$nl} + , + + {' '} + + + ( + ) + + __{translate(.,'_','')}__ + + = + + {' '} + + + {$nl} + + + [role red error.{@message}] + + {$nl}[table + {$nl}] + + + [ + ] + + {$nl} [ + {$nl} ] + + {$nl} [ + {$nl} ] + + [* + ] + + [' + ] + + [role {@class} + ] + + [@{@url} + ] + + {$nl} + + + {$nl} + + + + + + + + + {ancestor::listitem ! (1 to $list-indent-width) ! ' '} + + * + # + + + + [ + + + + ] + + + itemized_list + ordered_list + + + [ + + ] + + + + + [' + [role red \[Page type: [*{/*/@type}]\]] + [role green \[[@../../doc/html/{translate($doc-ref,'.','/')}/{ + translate(/page/@id,'.','/')}.html [role green doc_build_html]]\]] + [@../build/xml-pages/{/page/@id}.xml [role blue [*\[doxygen_page_xml\]]]] + [@../build/stage1_visualized/visualized/{/page/@id}.html [role magenta ---stage1_visualized-->]] + [@../build/stage1_visualized/results/{ /page/@id}.xml [role blue [*\[docca_page_xml\]]]] + [@../build/stage2_visualized/visualized/{/page/@id}.html [role magenta ---stage2_visualized-->]] + [@../build/stage2_visualized/results/{ /page/@id}.txt [role blue [*\[quickbook_result\]]]] + ] + + + + {$nl} + + {' '} + + {$nl}{$nl} + + [br] + + {$nl}```{$nl} + ```{$nl} + + {$nl} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/common.xsl b/src/boost/tools/docca/include/docca/common.xsl new file mode 100644 index 000000000..b557b124f --- /dev/null +++ b/src/boost/tools/docca/include/docca/common.xsl @@ -0,0 +1,107 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/debug-friendly-quickbook.xsl b/src/boost/tools/docca/include/docca/debug-friendly-quickbook.xsl new file mode 100644 index 000000000..4d2cb7393 --- /dev/null +++ b/src/boost/tools/docca/include/docca/debug-friendly-quickbook.xsl @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/extract-xml-pages.xsl b/src/boost/tools/docca/include/docca/extract-xml-pages.xsl new file mode 100644 index 000000000..6a3721d2a --- /dev/null +++ b/src/boost/tools/docca/include/docca/extract-xml-pages.xsl @@ -0,0 +1,13 @@ + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/stage1.xsl b/src/boost/tools/docca/include/docca/stage1.xsl new file mode 100644 index 000000000..b1331cae9 --- /dev/null +++ b/src/boost/tools/docca/include/docca/stage1.xsl @@ -0,0 +1,13 @@ + + + + + + + + + diff --git a/src/boost/tools/docca/include/docca/stage2.xsl b/src/boost/tools/docca/include/docca/stage2.xsl new file mode 100644 index 000000000..6bd01b3c1 --- /dev/null +++ b/src/boost/tools/docca/include/docca/stage2.xsl @@ -0,0 +1,12 @@ + + + + + + + + + diff --git a/src/boost/tools/docca/util/comparison/README.md b/src/boost/tools/docca/util/comparison/README.md new file mode 100644 index 000000000..0c869e0d9 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/README.md @@ -0,0 +1,28 @@ +# Docca comparison scripts + +The scripts in this directory help guard against docca regressions by +comparing a previous doc build's output with the latest output +(after normalizing/scrubbing the results to eliminate non-substantive +changes). + +Probably the easiest thing to do is add this directory to your PATH +(or create an alias to the two scripts herein). + +The normal sequence goes like this: + +1. Run a baseline build from inside your project's doc directory by invoking + *update-baseline-html.sh* +2. Implement new feature or bug fix in docca (usually by updating XSLT) +3. Run a comparison build from inside your project's doc directory by invoking + *build-and-compare.sh* +4. Review the output (in diffs.txt) to make sure everything looks good and nothing broke +5. Otherwise, fix the regression and try again! + +This utility can also be useful for examining the impacts of other changes +(such as a Doxygen upgrade!). + +## Implementation details + +The file named *grep-expressions* is used to filter out all but the matching files +that need scrubbing. The resulting files are passed to sed and updated *in situ* based +on the commands in the file named *sed-commands*. diff --git a/src/boost/tools/docca/util/comparison/build-and-compare.sh b/src/boost/tools/docca/util/comparison/build-and-compare.sh new file mode 100755 index 000000000..182f5da9c --- /dev/null +++ b/src/boost/tools/docca/util/comparison/build-and-compare.sh @@ -0,0 +1,24 @@ +# This script runs a build and compares the scrubbed/normalized +# results against the scrubbed results of a previous build (run using +# update-baseline-html.sh). It is primarily used to guard against +# XSLT regressions in docca. + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" + +! test -d htmlPREVIOUS_SCRUBBED && echo "First run update-baseline-html.sh" && exit + +rm -rf html_SCRUBBED + +echo "Running clean build..." +b2 clean +b2 + +echo "Scrubbing results and storing as html_SCRUBBED..." +cp -r html html_SCRUBBED +cd html_SCRUBBED +grep -rl -f ${SCRIPT_DIR}/grep-expressions . | xargs sed -i -f ${SCRIPT_DIR}/sed-commands + +echo "Showing diffs from previous build (stored in diffs.txt):" +cd .. +diff -r htmlPREVIOUS_SCRUBBED html_SCRUBBED >diffs.txt +cat diffs.txt diff --git a/src/boost/tools/docca/util/comparison/compare-all.sh b/src/boost/tools/docca/util/comparison/compare-all.sh new file mode 100755 index 000000000..1a8dbd9d9 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/compare-all.sh @@ -0,0 +1,27 @@ +cd ~/boost/tools/docca/example +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/static_string/doc +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/url/doc +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/json/doc +build-and-compare.sh 2>&1 & + +cd ~/boost/libs/beast/doc +build-and-compare.sh 2>&1 & + +wait + +echo "~/boost/tools/docca/example/diffs.txt:" +cat ~/boost/tools/docca/example/diffs.txt +echo "~/boost/libs/static_string/doc/diffs.txt:" +cat ~/boost/libs/static_string/doc/diffs.txt +echo "~/boost/libs/url/doc/diffs.txt:" +cat ~/boost/libs/url/doc/diffs.txt +echo "~/boost/libs/json/doc/diffs.txt:" +cat ~/boost/libs/json/doc/diffs.txt +echo "~/boost/libs/beast/doc/diffs.txt:" +cat ~/boost/libs/beast/doc/diffs.txt diff --git a/src/boost/tools/docca/util/comparison/grep-expressions b/src/boost/tools/docca/util/comparison/grep-expressions new file mode 100644 index 000000000..5b47be5f6 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/grep-expressions @@ -0,0 +1,4 @@ +

Last revised: diff --git a/src/boost/tools/docca/util/comparison/sed-commands b/src/boost/tools/docca/util/comparison/sed-commands new file mode 100644 index 000000000..3e2da7bf3 --- /dev/null +++ b/src/boost/tools/docca/util/comparison/sed-commands @@ -0,0 +1,2 @@ +s/\(

Last revised: \)[^<]\+/\1/g diff --git a/src/boost/tools/docca/util/comparison/update-all-baselines.sh b/src/boost/tools/docca/util/comparison/update-all-baselines.sh new file mode 100755 index 000000000..23928710c --- /dev/null +++ b/src/boost/tools/docca/util/comparison/update-all-baselines.sh @@ -0,0 +1,16 @@ +cd ~/boost/tools/docca/example +update-baseline-html.sh 2>&1 & + +cd ~/boost/libs/static_string/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +cd ~/boost/libs/url/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +cd ~/boost/libs/json/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +cd ~/boost/libs/beast/doc +update-baseline-html.sh >build_output.txt 2>&1 & + +wait diff --git a/src/boost/tools/docca/util/comparison/update-baseline-html.sh b/src/boost/tools/docca/util/comparison/update-baseline-html.sh new file mode 100755 index 000000000..8306cfc9e --- /dev/null +++ b/src/boost/tools/docca/util/comparison/update-baseline-html.sh @@ -0,0 +1,19 @@ +# This script runs a new build and moves the results so they +# can be used as a comparison baseline against subsequent builds +# that are run using build-and-compare.sh + +SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" + +rm -rf htmlPREVIOUS htmlPREVIOUS_SCRUBBED + +echo "Running clean build..." +b2 clean +b2 + +echo "Moving results to htmlPREVIOUS..." +mv html htmlPREVIOUS + +echo "Scrubbing htmlPREVIOUS and storing as htmlPREVIOUS_SCRUBBED for use by build-and-compare.sh..." +cp -r htmlPREVIOUS htmlPREVIOUS_SCRUBBED +cd htmlPREVIOUS_SCRUBBED +grep -rl -f ${SCRIPT_DIR}/grep-expressions . | xargs sed -i -f ${SCRIPT_DIR}/sed-commands diff --git a/src/boost/tools/docca/util/comparison/watch-all-builds.sh b/src/boost/tools/docca/util/comparison/watch-all-builds.sh new file mode 100755 index 000000000..cf6f9fbcd --- /dev/null +++ b/src/boost/tools/docca/util/comparison/watch-all-builds.sh @@ -0,0 +1,6 @@ +tail -f \ +~/boost/tools/docca/example/build_output.txt \ +~/boost/libs/static_string/doc/build_output.txt \ +~/boost/libs/url/doc/build_output.txt \ +~/boost/libs/json/doc/build_output.txt \ +~/boost/libs/beast/doc/build_output.txt -- cgit v1.2.3