Ability to specify multiple arguments to \cfg{html-template-fragment};

Halibut will output fragment names in all specified formats. (I forget now
precisely why I thought this was necessary, but it seems potentially useful.)

Also ensure that legal fragment names are generated even if none of the
characters from the original turn out to be legal (e.g., %k with an entirely
numeric keyword), and correct an untruth I inserted in the documentation of
this.

(This commit hits more than just the HTML backend as I've generalised an error
message, and fixed a fault in the info backend's error handling while there.)

[originally from svn r5457]

1 files changed, 13 insertions, 6 deletions

diff --git a/doc/output.but b/doc/output.but
index 35613ca..351726e 100644
--- a/doc/output.but
+++ b/doc/output.but
@@ -711,12 +711,12 @@ available variants are:
 
 }
 
-\dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}
+\dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}[\cw{\{}\e{template}\cw{\}\{}...\cw{\}}]
 
 \dd This directive lets you specify a \i{template}, with exactly the
 same syntax used in \cw{\\cfg\{html-template-filename\}} (see
-\k{output-html-file}), to be used for the anchor names (\i\cw{<A
-NAME="...">}) used to allow URLs to refer to specific sections
+\k{output-html-file}), to be used for the anchor names (\i\cw{<a
+name="...">}) used to allow URLs to refer to specific sections
 within a particular HTML file. So if you set this to \cq{%k},
 for example, then each individual section in your document will be
 addressable by means of a URL ending in a \c{#} followed by your
@@ -724,9 +724,16 @@ internal section keyword.
 
 \lcont{
 
-Note that no checking is done that the anchor name is valid HTML. So
-if you use \cq{%k}, for example, you may need to restrict your use of
-keyword names.
+If more than one template is specified, anchors are generated in all
+the specified formats; Halibut's own cross-references are generated
+with the first template.
+
+Characters that are not permitted in anchor names are stripped. If
+there are no valid characters left, or a fragment is non-unique,
+Halibut starts inventing fragment names and suffixes as appropriate.
+
+Note that there are potentially fragment names that are not controlled
+by this mechanism, such as index references.
 
 }