[src/trunk]: src/usr.bin/menuc Try to provide the typesetting help requested.

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/916ee7b6b19a
branches:  trunk
changeset: 446067:916ee7b6b19a
user:      uwe <uwe%NetBSD.org@localhost>
date:      Wed Nov 21 22:42:26 2018 +0000

description:
Try to provide the typesetting help requested.

diffstat:

 usr.bin/menuc/menuc.1 |  376 ++++++++++++++++++++++++++++---------------------
 1 files changed, 216 insertions(+), 160 deletions(-)

diffs (truncated from 642 to 300 lines):

diff -r c0915971aa2c -r 916ee7b6b19a usr.bin/menuc/menuc.1
--- a/usr.bin/menuc/menuc.1     Wed Nov 21 21:24:42 2018 +0000
+++ b/usr.bin/menuc/menuc.1     Wed Nov 21 22:42:26 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: menuc.1,v 1.32 2018/11/21 20:04:48 martin Exp $
+.\"    $NetBSD: menuc.1,v 1.33 2018/11/21 22:42:26 uwe Exp $
 .\"
 .\" Copyright 1997 Piermont Information Systems Inc.
 .\" All rights reserved.
@@ -50,14 +50,6 @@
 The
 .Fl o Ar name
 can be used to specify a different base name.
-.Sh ENVIRONMENT
-.Bl -tag -width MENUDEF
-.It Ev MENUDEF
-Can be set to point to a different set of definition files for
-.Nm .
-The current location defaults to
-.Pa /usr/share/misc .
-.El
 .Sh MENU DESCRIPTIONS
 The input
 .Ar file
@@ -66,18 +58,16 @@
 for definitions and other code necessary for the menu system, and an
 option declaration if dynamic menus are requested.
 .Pp
-Comments may appear anywhere in the input
-.Ar file
+Comments may appear anywhere in the input file
 and are like a space in the input.
 They are like C comments starting with
-.Em /*
+.Li "/*"
 and ending with
-.Em */ .
+.Li "*/" .
 They are unlike C comments in that they may be nested.
 A comment does not end until a matching end comment is found.
 .Pp
-In many places, C code is included in the definition
-.Ar file .
+In many places, C code is included in the definition file.
 All C code is passed verbatim to the C output file.
 .Nm
 comments do not start in C code and comments in the C code are
@@ -85,26 +75,24 @@
 The C comments are not recognized by
 .Nm .
 In all cases, C code starts with a left brace
-.Pq Em \&{
+.Pq Ql \&{
 and ends with the matching right brace
-.Pq Em \&} .
+.Pq Ql \&} .
 It is important to recognize that in code segments, any brace
 will be counted, even if it is in a C comment inside the code.
 .Pp
-The
-.Ar file
+The file
 contains an initial (and optional) code block followed by any
 number of menu definition elements in any order.
 The initial code block usually contains includes of header files used by
-code in the menu code blocks later in the
-.Ar file .
+code in the menu code blocks later in the file.
 If
 .Dv USER_MENU_INIT
-is #defined, then it will be evaluated before the
+preprocessor symbol
+is defined, then it will be evaluated before the
 rest of the menu is initialised, if it evaluates to a non-zero value
 then the initialisation will fail.
-The file is free format, so the actual formatting of the input
-.Ar file
+The file is free format, so the actual formatting of the input file
 is to the taste of the programmer.
 .Pp
 All other C code that will appear in an
@@ -113,15 +101,16 @@
 .Aq Em action
 in later text.
 Such an action will appear as:
-.Dl action <opt_endwin> <code>
-in the
-.Ar file .
+.Pp
+.D1 Li action Ao Em opt_endwin Ac Ao Em code Ac
+.Pp
+in the file.
 The
 .Aq Em opt_endwin ,
-if present is:
-.Dl ( endwin )
+is optional
+.Ql "(endwin)"
 and specifies that the curses
-.Fn endwin
+.Xr endwin 3
 function should be called before executing the code and
 then reinstating the current curses window after the
 code has been run.
@@ -139,54 +128,56 @@
 Dynamic menus provide the programmer with a method to create and
 modify menus during the running of the program.
 To include dynamic menus, one needs only add the declaration:
-.Dl allow dynamic menus ;
+.Pp
+.Dl "allow dynamic menus;"
+.Pp
 The semicolon is required to terminate this declaration.
-This declaration may appear anywhere in the
-.Ar file ,
+This declaration may appear anywhere in the file,
 but usually appears before any menus are defined.
 See below for a detailed explanation of dynamic menus.
 .Pp
-To allow dynamic messages, one needs to add the declaration:
-.Dl allow dynamic messages ;
-This enables internationalization by loading message files at
-run time.
+To enable internationalization by loading message files at
+run time one needs to add the declaration:
+.Pp
+.Dl "allow dynamic messages;"
 .Pp
-To allow argument expansion on static menu strings, one needs to add
-the declaration:
-.Dl allow expand ;
-This enables the expand action.
-See below for a detailed explanation.
+To allow argument expansion on static menu strings (see below for a
+detailed explanation), one needs to add the declaration:
+.Pp
+.Dl "allow expand;"
 .Pp
 The next element is a code block to execute if the curses
 screen can not be successfully initialized.
 The declaration
-.Dl error code ;
+.Pp
+.D1 Li error Li action Ao Em code Ac Ns Li \&;
+.Pp
 tells the menu system to execute the associated code block
 if the initialization fails.
 If no code is provided, a default code block is used that prints
-.Dl Could not initialize curses.
+.Dq Could not initialize curses.
 and exits.
-This element may appear anywhere in the
-.Ar file
+This element may appear anywhere in the file
 but usually appears before any menus are defined.
 .Pp
-The next element defines default options for menus.
 Each menu is built from a list of options.
 These options include the location of the upper left corner of the menu,
-whether there is a "box" drawn around the menu, whether the menu is
+whether there is a
+.Dq box
+drawn around the menu, whether the menu is
 scrollable, the menu's title, whether shortcut letters are
 allowed, whether a standard exit option should be included
 in the menu and text associated with the standard exit option.
+.Pp
+The
+.Ic default
+declaration defines default options for menus.
 The general format is:
-.Dl default <comma separated option list> ;
+.Pp
+.D1 Li default Ao Em comma separated option list Ac Ns Li \&;
 .Pp
 The supported options are:
-.Bl -tag -width ".Ic exitstring Va text"
-.It Ic x = Va startx
-The column number of the upper left corner of the menu window.
-If
-.Va startx
-is -1 the menu will be centered horizontally.
+.Bl -tag -width ".Ic exitstring Va text" -offset indent
 .It Ic y = Va starty
 The row number of the upper left corner of the menu window.
 If
@@ -194,10 +185,15 @@
 is negative then the menu will be placed below any message text, but
 in at least row
 .Va -starty .
+.It Ic x = Va startx
+The column number of the upper left corner of the menu window.
+If
+.Va startx
+is -1 the menu will be centered horizontally.
 .It Ic h = Va height
 Specifies the number of menu entries to be displayed.
 If zero, the height will be based on the number of entries.
-.It Ic h = Va width
+.It Ic w = Va width
 Specifies the width of the menu window.
 If zero, the width will be that of the longest menu text line.
 .It Ic title Va text
@@ -210,34 +206,35 @@
 If specified, clear the window before performing the
 .Va action .
 .It Ic exit
-If specified add an addition option to exit the menu.
+If specified, add an additional option to exit the menu.
 .It Ic exitstring Va text
 The menu label for the
 .Va exit
 option.
-If not specified defaults to "exit".
+If not specified defaults to
+.Dq "Exit" .
 .It Ic default exit
-If specified, place the cursor on the
-.Va exit
+If specified, place the cursor on the exit
 line of the menu, instead of the top line.
 .It Ic shortcut
 If specified, add alphabetic tags to each menu line.
 .It Ic scrollable
 If specified, and the menu has more lines than will fit in its window, then
 only part of the menu will be displayed and the
-.Sq <
+.Ql <
 and
-.Sq >
+.Ql >
 keys will scroll the displayed menu lines.
 .It Ic always scroll
 If specified, allow for the scroll message line even if the menu doesn't
 appear to have too many lines.
 Useful for dynamic menus, when the number of entries isn't known when the
-menu window is created..
+menu window is created.
 .It Ic sub menu
 If specified, the screen contents that the menu window overwrites are saved
 and restored when the menu exits.
 .El
+.Pp
 The
 .Ic box , clear , exit , default exit , shortcut , scrollable , always scroll ,
 and
@@ -248,67 +245,88 @@
 .Pp
 The
 .Va text
-arguments can be either a quoted text string or a name #defined to something
-suitable for initialising a const char * field.
+arguments can be either a quoted text string or a preprocessor symbol defined
+to something suitable for initialising a
+.Vt "const char *"
+field.
 .Pp
-The default declaration may appear multiple times.
+The
+.Ic default
+declaration may appear multiple times.
 Each time, it sets the default values for menu definitions that follow
-in the
-.Ar file .
+in the file.
 In each menu definition, any or all of these default definitions
 may be overridden for that menu.
 .Pp
-The final element is the actual static menu definitions.
+The
+.Ic menu
+element is the actual static menu definitions.
 The format and order for a menu definition is:
-.Bd -ragged -offset indent
-menu <name> <options> ;
-  <expand action>
-  <display action>
-  <menu items>
-  <exit action>
-  <help text>
+.Bd -unfilled -offset indent
+.Li menu Ao Em name Ac Ao Em options Ac Ns Li \&;
+.Li " " Aq Em expand action
+.Li " " Aq Em display action
+.Li " " Aq Em menu items
+.Li " " Aq Em exit action
+.Li " " Aq Em help text
 .Ed
 .Pp
-Names are unquoted strings of alpha-numeric and underscore
+Menu names are unquoted strings of alpha-numeric and underscore
 characters.
 They must start with an alpha character.
 In C source, a menu named
 .Dq foo
 is appears as
-.Dq MENU_foo .
+.Li MENU_foo .
 (Capitalization is important.)
 This is important, because the menu is displayed and processed by