[PATCH 4/4] man/MKada_config.in: Revise.

[G. Branden Robinson]

* Add page-local versions of `EX`/`EE` man(7) macros from Ninth Edition
  Unix (1986) and groff 1.20+ (2009), defining them only if the
  formatter does not claim groff compatibiity via the `.g` register.
  This same technique was recently adopted by man-db 2.12.0.
* Define "``", "''", and "'" strings for typographer's (directional)
  double quotes and a neutral (non-directional) single quote.
* Recast synopsis and description to say more about what the
  adacurses6-config tool _does_, and less about how it's implemented.
  (Does anyone care if it's a shell script?)
* Explicitly identify all available options in the synopsis; unlike
  ncurses6-config, this tool lacks an extravagant efflorescence thereof.
* Synopsize distinct operation modes separately.
* Set "@ADA_LIBNAME@" (often "AdaCurses") in italics, not roman, by
  analogy to "ncurses", "terminfo", and "termcap".
* Speaking of, set "ncurses" in italics.
* Set tagged paragraph indentation in option list sufficient to prevent
  a break after "--version".
* Capitalize "GNAT"; that seems to be its own documentation's practice.
* Say "reports" instead of "echos" [sic].  (It's spelled "echoes".)
* Be less informal when describing `--version`'s output.
* Document `--version` and `--help` as exiting (early and) successfully.
* Set non-ncurses program name "gnatmake" in italics.
* Revise example.  Introduce it less lazily.
* Set file name literal in italics instead of U+0022-quoting it.
* Use man(7) macros `PP`, `RS`/`RE`, and `EX`/`EE` to format example
  instead of punching through the floor to access formatter requests.
* Tighten example vertically a little, dropping some blank lines, and
  following examples I've seen in Ada literature (Watt, Wichmann,
  Findlay 1987; Barnes 2022).  Similarly for `case`/`when` indentation.
* Improve code style of Ada example.  Define "Hello, World!" as a
  (named) constant object and access its length with the tick operator
  and `Length` attribute instead of hard-coding it.  If we're going to
  present an elementary Ada example to knuckle-dragging C programmers,
  we might as well show off a basic Ada convenience.
* Use `br` and `ne` requests before a paragraphing macro to avoid
  stranding the first line of a paragraph at the bottom of a page.  (Not
  hypothetical: the problem affects this page when formatted for
  PostScript or PDF and U.S. letter paper with groff.)  I term this a
  "poor man's keep", and have proposed a man(7) extension (ignorable by
  any implementation that doesn't care about this aspect of good
  typography) to accommodate it.  See <https://lists.gnu.org/archive/\
  html/groff/2022-12/msg00075.html>.
* Obtain glyphs for hyphen-minus and grave accent using appropriate
  *roff escape sequences.
* Use our new strings above, to obtain typographer's double quotation
  marks and neutral single quotes.
* Favor present tense over future tense.
* Protect man page cross reference in "SEE ALSO" section from
  hyphenation.
---
 man/MKada_config.in | 141 +++++++++++++++++++++++++++++---------------
 1 file changed, 94 insertions(+), 47 deletions(-)

diff --git a/man/MKada_config.in b/man/MKada_config.in
index 6f655b35..94d63477 100644
--- a/man/MKada_config.in
+++ b/man/MKada_config.in
@@ -36,96 +36,143 @@
 .ie \n(.g .ds CW CR
 .el       .ds CW CW
 .\}
+.
+.nr mE 0 \" in an example (EX/EE)?
+.
+.\" Start example.
+.if !\n(.g \{\
+.de EX
+.  br
+.  if !\\n(mE \{\
+.    nr mF \\n(.f
+.    nr mP \\n(PD
+.    nr PD 1v
+.    nf
+.    ft \\*(CW
+.    nr mE 1
+.  \}
+..
+.\}
+.
+.\" End example.
+.if !\n(.g \{\
+.de EE
+.  br
+.  if \\n(mE \{\
+.    ft \\n(mF
+.    nr PD \\n(mP
+.    fi
+.    nr mE 0
+.  \}
+..
+.\}
+.
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.ds '  \(aq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.ie t .ds '  \(aq
+.el   .ds '  '
+.\}
+.
 .SH NAME
 \fB\%adacurses@USE_CFG_SUFFIX@\-config\fP \-
-helper script for @ADA_LIBNAME@ libraries
+configuration helper for \fI@ADA_LIBNAME@\fP libraries
 .SH SYNOPSIS
 .B \*C
-[\fIoptions\fP]
+.RB [ \-\-cflags ]
+.RB [ \-\-libs ]
+.PP
+.B \*C \-\-version
+.PP
+.B \*C \-\-help
 .SH DESCRIPTION
-This is a shell script which simplifies configuring an application to use
-the @ADA_LIBNAME@ library binding to ncurses.
+This program development aid simplifies the process of configuring
+applications to use the \fI@ADA_LIBNAME@\fP library binding to
+\fIncurses\fP.
 .SH OPTIONS
-.TP
+.TP 11 \" "--version" + 2n
 \fB\-\-cflags\fP
-echos the gnat (Ada compiler) flags needed to compile with @ADA_LIBNAME@.
+reports the GNAT (Ada compiler) flags needed to compile with
+\fI@ADA_LIBNAME@\fP.
 .TP
 \fB\-\-libs\fP
-echos the gnat libraries needed to link with @ADA_LIBNAME@.
+reports the GNAT libraries needed to link with \fI@ADA_LIBNAME@\fP.
 .TP
 \fB\-\-version\fP
-echos the release+patchdate version of the ncurses libraries used
-to configure and build @ADA_LIBNAME@.
+reports the release and patch date information of the \fIncurses\fP
+libraries used to configure and build \fI@ADA_LIBNAME@\fP and exits
+successfully.
 .TP
 \fB\-\-help\fP
-prints a list of the \fB\*C\fP script's options.
+issues a usage message and exits successfully.
 .PP
-If no options are given, \fB\*C\fP prints the combination
-of
-\fB\-\-cflags\fP and
-\fB\-\-libs\fP
-that \fBgnatmake\fP expects (see example).
+Omitting options implies \*(``\fB\-\-cflags \-\-libs\fP\*(''.
 .SH EXAMPLE
-For example, supposing that you want to compile the "Hello World!"
-program for @ADA_LIBNAME@.
-Make a file named "hello.adb":
-.RS
-.nf
-.ft \*(CW
+Consider a program using \fI@ADA_LIBNAME@\fP to write the message
+\*(``Hello, world!\*('' in the center of the screen and wait for the
+user to press the \*(``q\*('' key before exiting.
+Populate a file \fIhello.adb\fP with the following.
+.PP
+.RS 4
+.EX
 with Terminal_Interface.Curses; use Terminal_Interface.Curses;
 
 procedure Hello is
-
    Visibility : Cursor_Visibility := Invisible;
+   Message : constant String := "Hello, World!";
    done : Boolean := False;
    c : Key_Code;
-
 begin
-
    Init_Screen;
    Set_Echo_Mode (False);
-
    Set_Cursor_Visibility (Visibility);
    Set_Timeout_Mode (Standard_Window, Non_Blocking, 0);
 
-   Move_Cursor (Line => Lines / 2, Column => (Columns - 12) / 2);
-   Add (Str => "Hello World!");
+   Move_Cursor (Line => Lines / 2,
+                Column => (Columns - Message\*'Length) / 2);
+   Add (Str => Message);
 
    while not done loop
-
       c := Get_Keystroke (Standard_Window);
+
       case c is
-      when Character'Pos ('q') => done := True;
-      when others => null;
+          when Character\*'Pos (\*'q\*') => done := True;
+          when others => null;
       end case;
 
       Nap_Milli_Seconds (50);
    end loop;
 
    End_Windows;
-
 end Hello;
-.fi
+.EE
 .RE
+.br
+.ne 2
 .PP
 Then, using
-.RS
-.ft \*(CW
-gnatmake `adacurses@USE_CFG_SUFFIX@-config --cflags` hello \e
-    -largs `adacurses@USE_CFG_SUFFIX@-config --libs`
-.ft
+.RS 4
+.EX
+gnatmake \(gaadacurses@USE_CFG_SUFFIX@\-config \-\-cflags\(ga hello \e
+    \-largs \(gaadacurses@USE_CFG_SUFFIX@\-config \-\-libs\(ga
+.EE
 .RE
-.PP
-or (simpler):
-.RS
-.ft \*(CW
-gnatmake hello `adacurses@USE_CFG_SUFFIX@-config`
-.ft
+or, more simply,
+.RS 4
+.EX
+gnatmake hello \(gaadacurses@USE_CFG_SUFFIX@\-config\(ga
+.EE
 .RE
-.PP
-you will compile and link the program.
+you can compile and link the program.
 .SH "SEE ALSO"
-\fBcurses\fP(3X)
+\fB\%curses\fP(3X)
 .PP
-This describes \fBncurses\fP
+This describes \fIncurses\fP
 version @NCURSES_MAJOR@.@NCURSES_MINOR@ (patch @NCURSES_PATCH@).
-- 
2.30.2

signature.asc
Description: PGP signature