refactor: simplify handlebars generators

Apart from the DocVisitor, the Adoc and HTML generators are nearly 100% duplicated code.

This is the main reason the HTML Generator is always behind the Adoc Generator: simple features were not duplicated in the HTML generator. This even justified #656, where we would temporarily remove the HTML generator.

This commit unifies the standard code to remove duplicated code, simplify maintenance, and ensure that both generators always have access to the same features.

In passing, many missing features in the HTML generator are now available.

fix #656

Author: alandefreitas

include/mrdocs/Generator.hpp

@@ -82,10 +82,19 @@ class MRDOCS_VISIBLE
         depending on the generator and how it is
         configured.
 
+        The default implentation assumes the output
+        is single-page and emits the file `reference.ext`
+        using @ref buildOne to generate the content.
+
+        The typical implementation will have behavior
+        similar to the default implementation if the
+        output is single-page, or will iterate over
+        the symbols in the corpus to generate multiple
+        files if the output is multi-page.
+
         @return The error, if any occurred.
 
-        @param outputPath An existing directory or
-        a filename.
+        @param outputPath A directory or filename.
 
         @param corpus The symbols to emit. The
         generator may modify the contents of

include/mrdocs/Support/Error.hpp

@@ -2747,6 +2747,13 @@ void
 setMinimumLevel(
     Level level) noexcept;
 
+/** If true, source location information will be
+    printed with warnings, errors, and fatal messages.
+*/
+MRDOCS_DECL
+void
+setSourceLocationWarnings(bool b) noexcept;
+
 /** Report a message to the console.
 
     @param text The message to print. A

share/mrdocs/addons/generator/asciidoc/helpers/add.js share/mrdocs/addons/generator/adoc/helpers/add.js

@@ -1,5 +1,2 @@
 {{! The section with a symbol in single page output or the symbol page in multi page output }}
-{{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
-[#{{#if (is_multipage)}}{{symbol.id}}{{else}}{{symbol.ref}}{{/if}}]
-
 {{> (concat 'symbols' '/' (lookup symbol 'kind')) symbol=symbol}}

share/mrdocs/addons/generator/asciidoc/layouts/overload-set.adoc.hbs share/mrdocs/addons/generator/adoc/layouts/overload-set.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- alias --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/layouts/single-footer.adoc.hbs share/mrdocs/addons/generator/adoc/layouts/single-footer.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- concept --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}</h2>
         {{symbol.doc.brief}}

share/mrdocs/addons/generator/asciidoc/layouts/single-header.adoc.hbs share/mrdocs/addons/generator/adoc/layouts/single-header.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- enum --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{#if symbol.name}}Enum {{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}{{else}}Unnamed enum{{/if}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/layouts/single-symbol.adoc.hbs share/mrdocs/addons/generator/adoc/layouts/single-symbol.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- enumerator --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>Enumerator {{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/alias.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/alias.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- field --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/concept.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/concept.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- friend --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>Friend {{#if symbol.symbol}}{{symbol.symbol.name}}{{else}}{{symbol.type.name}}{{/if}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/enum.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/enum.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- function --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>Function {{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/enumerator.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/enumerator.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- guides --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>Deduction guide {{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/field.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/field.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- namespace --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{#if symbol.name}}Namespace {{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}{{else if symbol.parent}}Unnamed namespace{{else}}Global namespace{{/if}}</h2>
     </div>

share/mrdocs/addons/generator/asciidoc/partials/signature/friend.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/friend.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- record --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{#if symbol.name}}Class {{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}{{else}}Unnamed class{{/if}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/function.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/function.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- typedef --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/guide.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/guide.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- symbols/using.html.hbs --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>Using {{#if (eq symbol.class "namespace")}}Directive: {{symbol.qualifier.name}}{{else}}Declaration: {{symbol.name}}{{/if}}</h2>
         {{{symbol.doc.brief}}}

share/mrdocs/addons/generator/asciidoc/partials/signature/namespace.adoc.hbs share/mrdocs/addons/generator/adoc/partials/signature/namespace.adoc.hbs

@@ -1,5 +1,5 @@
 {{!-- variable --}}
-<div id="{{symbol.id}}">
+<div {{#if sectionref}}id="{{sectionref}}"{{/if}}>
     <div>
         <h2>{{>types/nested-name-specifier symbol=symbol.parent}}{{symbol.name}}</h2>
         {{{symbol.doc.brief}}}