Utilities/Sphinx: Improve word wrap of signatures

Implement logic to support several styles of parsing in the new
signature directive that control where line breaks are allowed in a
signature.

The default is 'smart', which forbids breaks inside of square- or
angle-brackets. The 'verbatim' option forbids all breaks. In all cases,
breaks are always allowed where a newline appears in the source.

This seems to Just Work for most writers, but HTML needs some special
handling that is accomplished by a new CSS rule and assigning the 'nbsp'
class to spaces that are not allowed to break. (ROFF's line wrapping is
rather unfortunate here, as it prefers splitting and hyphenating words
rather than breaking at a space.)

1 files changed, 17 insertions, 0 deletions

diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst
index 8cd71b40cd..52525df9c1 100644
--- a/Help/dev/documentation.rst
+++ b/Help/dev/documentation.rst
@@ -301,6 +301,23 @@ The ``signature`` directive generates a hyperlink target for each signature:
   headers, the targets do not work with Sphinx ``:ref:`` syntax, however
   they can be globally referenced using e.g. ``:command:`string(APPEND)```.
 
+Although whitespace in the signature is not preserved, by default, line breaks
+are suppressed inside of square- or angle-brackets.  This behavior can be
+controlled using the ``:break:`` option; note, however, that there is no way
+to *force* a line break.  The default value is 'smart'.  Allowable values are:
+
+  ``all``
+    Allow line breaks at any whitespace.
+
+  ``smart`` (default)
+    Allow line breaks at whitespace, except between matched square- or
+    angle-brackets.  For example, if a signature contains the text
+    ``<input>... [OUTPUT_VARIABLE <out-var>]``, a line break would be allowed
+    after ``<input>...`` but not between ``OUTPUT_VARIABLE`` and ``<out-var>``.
+
+  ``verbatim``
+    Allow line breaks only where the source document contains a newline.
+
 The directive treats its content as the documentation of the signature(s).
 Indent the signature documentation accordingly.