[groff] 27/35: [sboxes]: Document GSBOX register.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit eaf9df347a739ac4d98148408fef13bd2c3e2973
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Oct 24 18:31:49 2021 +1100

    [sboxes]: Document GSBOX register.
    
    * contrib/sboxes/sboxes.tmac: Define GSBOX register as 0, then redefine
      it as 1 only if the output device is `pdf`.  (This way a document
      author can easily and separately test the presence of the package and
      whether the device-specific feature is likely to work.)
    
    * contrib/sboxes/msboxes.ms.in: Document this aspect of the package
      interface.
---
 contrib/sboxes/ChangeLog     |  8 ++++++++
 contrib/sboxes/msboxes.ms.in | 12 ++++++++++++
 contrib/sboxes/sboxes.tmac   |  7 ++++++-
 3 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/contrib/sboxes/ChangeLog b/contrib/sboxes/ChangeLog
index 94097d3..7708d7e 100644
--- a/contrib/sboxes/ChangeLog
+++ b/contrib/sboxes/ChangeLog
@@ -1,3 +1,11 @@
+2021-10-24  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * sboxes.tmac: Define GSBOX register as 0, then redefine it as 1
+       only if the output device is `pdf`.  (This way a document author
+       can easily and separately test the presence of the package and
+       whether the device-specific feature is likely to work.)
+       * msboxes.ms.in: Document this aspect of the package interface.
+
 2021-10-21  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * sboxes.am (SBOXES_FLAGS): Drop variable since we only expand
diff --git a/contrib/sboxes/msboxes.ms.in b/contrib/sboxes/msboxes.ms.in
index 2a3934c..74e0337 100644
--- a/contrib/sboxes/msboxes.ms.in
+++ b/contrib/sboxes/msboxes.ms.in
@@ -224,6 +224,18 @@ after adding its
 spacing.
 .BOXSTOP
 .QE
+Your
+.I groff
+documents can conditionally exercise the
+.I sboxes
+macros.
+The register
+.Lt GSBOX
+is defined if the package is loaded, and interpolates a true value if
+the
+.Lt pdf
+output device is in use.
+.LP
 .I sboxes
 has one further feature: it hooks into the
 .I "groff ms"
diff --git a/contrib/sboxes/sboxes.tmac b/contrib/sboxes/sboxes.tmac
index 68f775f..569be34 100644
--- a/contrib/sboxes/sboxes.tmac
+++ b/contrib/sboxes/sboxes.tmac
@@ -40,7 +40,12 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 .
 .\" See if already loaded.
 .if r GSBOX .nx
-.nr GSBOX 1
+.
+.\" GSBOX is defined if the package is loaded, and true if it will work.
+.nr GSBOX 0
+.if '\*[.T]'pdf' \
+.  nr GSBOX 1
+.
 .nr bx@stack 0
 .
 .de sboxes*error