path: root/autoopts/tpl/cmd-doc.tlib

[+: -*- Mode: nroff -*-

  AutoGen5 template man

# cmd-doc.tlib -- Template for command line man/mdoc pages
#
# Time-stamp:      "2012-05-12 20:52:33 bkorb"
#
#  This file is part of AutoOpts, a companion to AutoGen.
#  AutoOpts is free software.
#  Copyright (c) 1992-2012 Bruce Korb - all rights reserved
#
#  AutoOpts is available under any one of two licenses.  The license
#  in use must be one of these two and the choice is under the control
#  of the user of the license.
#
#   The GNU Lesser General Public License, version 3 or later
#      See the files "COPYING.lgplv3" and "COPYING.gplv3"
#
#   The Modified Berkeley Software Distribution License
#      See the file "COPYING.mbsd"
#
#  These files have the following md5sums:
#
#  43b91e8ca915626ed3818ffb1b71248b COPYING.gplv3
#  06a1a2e4760c90ea5e1dad8dfaac4d39 COPYING.lgplv3
#  66a5cedaf62c4b2637025f049f9b826f COPYING.mbsd

# Produce a man page for section 1, 5, 6 or 8 commands.  Which is
# selected via: -DMAN_SECTION=n.  "n" may have a suffix, if desired.
# These sections have default section names that may be overridden
# with -DSECTIN_NAME=XX, also passed to the autogen invocation.
#
:+][+:

   ;;# START-BUILDTREE-ISMS
   ;;
   (shell "CLexe=${AGexe%/agen5/*}/columns/columns
  test -x \"${CLexe}\" || {
    CLexe=${AGexe%/autogen}/columns
    test -x \"${CLexe}\" || die 'columns program is not findable'
  }")

:+][+: # END-BUILDTREE-ISMS

   (shell "CLexe=${AGexe%/autogen}/columns")

# END-INSTALL-ONLY-CODE :+][+:

(define down-prog-name (string-downcase! (get "prog-name")))
(define UP-PROG-NAME   (get-up-name "prog-name"))

(define tmp-val        (getenv "MAN_SECTION"))
(define man-sect       (if (exist? "cmd-section") (get "cmd-section") "1"))
(define file-name      "")
(define sect-name      "")
(define macro-name     "")
(define tmp-str        "")
(define fname-line     "")
(define use-flags      (exist? "flag.value"))
(define named-mode     (not (or use-flags (exist? "long-opts") )))

(if (defined? 'tmp-val)
    (if (string? tmp-val)
        (set! man-sect tmp-val)))

(define section-name
   (if (=* man-sect "1") "User Commands"
   (if (=* man-sect "5") "File Formats"
   (if (=* man-sect "6") "Games"
   (if (=* man-sect "8") "System Management"
   (error
    "the agman-cmd template only produces section 1, 5, 6 and 8 man pages")
)))))
(set! tmp-val (getenv "SECTION_NAME"))
(if (defined? 'tmp-val) (if (string? tmp-val)
    (set! section-name tmp-val) ))

(define package-text "")
(define package+version (and (exist? "package") (exist? "version")))

(if (or (exist? "package") (exist? "version")) (begin
  (set! package-text (string-append
        (get "package")
        (if package+version " (" "")
        (get "version")
        (if package+version ")" "") ))
) )

(define name-to-fname (lambda (nm)
    (string-tr (string-downcase nm) " " "-") ))

(define sect-line-fname (lambda () (begin
    (out-push-new file-name)
    (emit (string-append ".Sh \"" sect-name "\"\n"))
    (string-append "mk-" macro-name) )))

(make-tmp-dir)

(define home-rc-files (exist? "homerc"))
(define home-rc-text
  "\nSee \\fBOPTION PRESETS\\fP for configuration files.")

(define environ-init  (exist? "environrc"))
(define environ-text
  "\nSee \\fBOPTION PRESETS\\fP for configuration environment variables.")

(set! tmp-str (find-file (if man-page "texi2man" "texi2mdoc")))
(if (not (defined? 'tmp-str))
    (error (string-append "cannot locate "
           (if man-page "texi2man" "texi2mdoc"))))
(shell (string-append "cvt_prog='" tmp-str
       "'\ntest -x \"$cvt_prog\" || die 'no conversion program'" ))

(define get-cvt (lambda (nm alt-txt)
    (shell (string-append
      "{\n${cvt_prog} || die ${cvt_prog} failed in $PWD\n"
      "} <<\\_EndOfTexiSection_\n"
      (get nm alt-txt)
      "\n_EndOfTexiSection_"
    ))
))

(emit (head-line))
(dne ".\\\"  ")                       :+][+:

INCLUDE "tpl-config.tlib"             :+][+:#

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  B U I L D   D O C
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE build-doc                      :+][+:

INVOKE doc-sections                   :+][+:
INVOKE ao-sections                    :+][+:

(out-push-new (string-append tmp-dir "/.assemble")) \:+]

cat_n_rm() {
  test -f ${tmp_dir}/$1 || return 0
  [+:(. egrep-prog):+] -v '^[ 	]*$' ${tmp_dir}/$1
  rm -f ${tmp_dir}/$1
}

#.\" Insert these sections first, in the prescribed order
#
for f in synopsis description options option-presets
do cat_n_rm $f ; done
test -f ${tmp_dir}/name && rm -f ${tmp_dir}/name

#.\" These sections go last, in the prescribed order
#
for f in implementation-notes environment files examples exit-status errors \
      compatibility see-also conforming-to history authors copyright bugs notes
do cat_n_rm $f ; done > ${tmp_dir}/.fini

#.\" Insert the contents of all remaining files in alphabetic order,
#.\" except remove any blank lines.
#
set XX ${tmp_dir}/* ; shift
test -f "$1" && cat $* | [+:(. egrep-prog):+] -v '^[ 	]*$'

#.\" Now insert the sections we squirreled away for the end.
#
cat  ${tmp_dir}/.fini
[+: (out-pop)
    (shell ". ${tmp_dir}/.assemble")  :+][+:

ENDDEF build-doc

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  D O C   S E C T I O N S
.\"
.\" Emit the files for each section that was provided.
.\"
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE doc-sections                   :+][+:

FOR doc-section                       :+][+:

  CASE
    (define sec-type (string-upcase (get "ds-type")))
    (define sec-name (name-to-fname sec-type))
    (out-push-new (string-append tmp-dir "/" sec-name))
    (define cvt-fn (find-file (string-append
         (get "ds-format" "man") "2mdoc")))
    (if (not (defined? 'cvt-fn))
        (error (sprintf "Cannot locate converter for %s"
               (get "ds-format" "man"))))
    sec-type :+][+:
    == ""    :+][+: (error "unnamed doc-section") :+][+:
    *==* " " :+].Sh "[+: (. sec-type)            :+]"[+:
    *        :+].Sh [+: (. sec-type)              :+][+:
    ESAC     :+]
[+:
    (shell (string-append
      "fn='" cvt-fn "'\n"
      "test -f ${fn} || die ${fn} not found from $PWD\n"
      "${fn} <<\\_EndOfDocSection_ || die ${fn} failed in $PWD\n"
      (get "ds-text")
      "\n_EndOfDocSection_"
    ))                                :+][+:

    CASE (. sec-type)                 :+][+:
    == FILES                          :+][+:
        (if home-rc-files (emit home-rc-text))
        (set! home-rc-files #f)       :+][+:

    == ENVIRONMENT                    :+][+:
        (if environ-init (emit environ-text))
        (set! environ-init #f)        :+][+:
    ESAC                              :+][+:

    (out-pop)
    :+][+:

ENDFOR doc-section                    :+][+:

ENDDEF doc-sections

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  A O   S E C T I O N S
.\"
.\" Emit the files for the sections that these templates augment,
.\" replace or conditionally replace
.\"
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE ao-sections              :+][+:

INVOKE cond-section  sec = "OPTIONS"           mode = "replace"       :+][+:
INVOKE cond-section  sec = "SYNOPSIS"          mode = "alt"           :+][+:
INVOKE cond-section  sec = "DESCRIPTION"       mode = "append"        :+][+:
INVOKE cond-section  sec = "EXIT STATUS"       mode = "insert"        :+][+:
INVOKE cond-section  sec = "AUTHORS"           mode = "alt"           :+][+:
INVOKE cond-section  sec = "BUGS"              mode = "append"        :+][+:
INVOKE cond-section  sec = "NOTES"             mode = "append"        :+][+:

IF (exist? "copyright")                                               :+][+:
  INVOKE cond-section   sec = "COPYRIGHT"      mode = "alt"           :+][+:
ENDIF                                                                 :+][+:

IF (or home-rc-files environ-init)                                    :+][+:
  INVOKE cond-section   sec = "OPTION PRESETS" mode = "replace"       :+][+:

  IF (. home-rc-files)                                                :+][+:
    INVOKE cond-section sec = "FILES"          mode = "append"        :+][+:
  ENDIF                                                               :+][+:

  IF (. environ-init)                                                 :+][+:
    INVOKE cond-section sec = "ENVIRONMENT"    mode = "append"        :+][+:
  ENDIF                                                               :+][+:

ENDIF                                                                 :+][+:

ENDDEF ao-sections

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  C O N D I T I O N A L   S E C T I O N
.\"
.\" Figure out what to do for AutoOpts required sections, depending on "mode"
.\" In all cases, if the file does not exist, invoke the "mk" macro to create
.\" a new file.  If it does exist, then:
.\"
.\" alt       Alternate -- emit no text
.\" replace   throw away any pre-existing file.
.\" append    invoke the "append" macro to emit additional text
.\" insert    save the current contents, replacing the .Sh line with .Pp.
.\"           invoke the "mk" macro then emit the saved text
.\"
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE cond-section                     :+][+:

  IF 
     (set! sect-name   (string-upcase! (string-substitute
                       (get "sec") "-" " " )))
     (set! macro-name  (string-downcase! (string-substitute
                       sect-name " " "-" )))
     (set! file-name   (string-append tmp-dir "/" macro-name))

     (not (access? file-name R_OK))     :+][+:

     INVOKE (sect-line-fname)           :+][+:
     (out-pop)                          :+][+:

  ELSE file exists                      :+][+:

     CASE (get "mode")                  :+][+:

     ==  replace                        :+][+:
         INVOKE (sect-line-fname)       :+][+:
         (out-pop)                      :+][+:

     ==  append                         :+][+:
         (out-push-add file-name)       :+][+:
         INVOKE (string-append "append-" macro-name) :+][+:
         (out-pop)                      :+][+:

     ==  insert                         :+][+:
         (set! fname-line (shellf "sed '1s/.Sh .*/.Pp/' %s" file-name)) :+][+:
         INVOKE (sect-line-fname)       :+][+:
         (emit fname-line)
         (out-pop)                      :+][+:

     # * -- otherwise, do nothing       :+][+:

     ESAC                               :+][+:

  ENDIF file existence/non-existence    :+][+:
ENDDEF cond-section

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - D E S C R I P T I O N
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-description                   :+][+:

  (if (exist? "prog-man-descrip")
      (stack-join "\n.Pp\n" "prog-man-descrip")
      (if (exist? "detail")
          (stack-join "\n.Pp\n" "detail")
          "There is no description for this command."
  )   )                                 :+]
[+:
  INVOKE append-description             :+][+:

ENDDEF mk-description

.\" = = = = = APPEND TO IT:             :+][+:

DEFINE append-description               :+][+:

IF (= (get "main.main-type") "for-each"):+][+:

  CASE main.handler-type                :+][+:
  ~* ^(name|file)|.*text               \:+]
.Pp
This program will perform its function for every file named on the command
line or every file named in a list read from stdin.  The arguments or input
names must be pre\-existing files.  The input list may contain comments,
which[+:

  !E                                   \:+]
.Pp
This program will perform its function for every command line argument
or every non\-comment line in a list read from stdin.
The input list comments[+:

  *                                     :+][+:
  (error "the 'for-each' main has in invalid handler-type.") :+][+:
  ESAC                                 \:+]
 are blank lines or lines beginning with a '[+:
  ?% comment-char "%s" "#" :+]' character.
[+:

ENDIF - "main" exists                   :+][+:
ENDDEF append-description

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - O P T I O N S
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-options

:+][+:

(define opt-arg       "")
(define dis-name      "")
(define opt-name      "")
(define optname-from  "A-Z_^")
(define optname-to    "a-z--")
(define cvt-cmd       "")
(define formatted-doc (exist? "option-doc-format"))

(if formatted-doc (begin
    (out-push-new)
    (set! cvt-cmd (string-append (get "option-doc-format") "2mdoc"))
)   )

(if (exist? "preserve-case")
   (begin
      (set! optname-from "_^")
      (set! optname-to   "--")
)  )

(define fix-optname (lambda (o_nm) (begin
   (set! o_nm (string-tr o_nm optname-from optname-to))
   (set! o_nm (string-substitute o_nm "-" "\\-" ))
   o_nm )))

(if (exist? "option-info")
    (string-append ".Pp\n" (get "option-info") "\n") )
\:+]
.Bl -tag[+:

FOR flag                              :+][+:
  IF (not (exist? "documentation"))   :+][+:
    IF (exist? "aliases")             :+][+:
      INVOKE emit-alias-opt           :+][+:
    ELSE                              :+][+:
      INVOKE emit-flag-text           :+][+:
    ENDIF                             :+][+:

  ELSE                                :+]
.Ss "[+: (get-cvt "descrip" "") :+]"[+:

    IF (set! tmp-str (get-cvt "documentation" ""))
       (> (string-length tmp-str) 3)  :+]
[+: (. tmp-str) :+]
[+: ENDIF                             :+][+:

  ENDIF                               :+][+:
ENDFOR flag

.\" = = = = = = = = = = = = = = = = =
.\"  help option
.\" = = = = = = = = = = = = = = = = =

:+]
.It [+:

  IF (. use-flags)  :+]\-[+: (get "help-value" "?") :+][+:
     (if (exist? "long-opts") " , \" \\-\\-help\"") :+][+:
  ELSE   :+][+:
     (if (exist? "long-opts") "\\-\\-") :+]help[+:
  ENDIF  :+]
Display usage information and exit.[+:#

.\" = = = = = = = = = = = = = = = = =
.\"  more-help option
.\" = = = = = = = = = = = = = = = = = :+][+:

  IF (not (exist? "no-libopts")) :+]
.It [+:

  IF (. use-flags)  :+]\-[+: ?% more-help-value "%s" "!" :+][+:
     IF (exist? "long-opts") :+] , " \-\-more-help"[+: ENDIF :+][+:
  ELSE   :+][+:
     IF (exist? "long-opts") :+]\-\-[+: ENDIF :+]more-help[+:
  ENDIF  :+]
Pass the extended usage information through a pager.[+:

ENDIF no no-libopts

.\" = = = = = = = = = = = = = = = = =
.\"  save and load configuration
.\" = = = = = = = = = = = = = = = = = :+][+:

IF (exist? "homerc") :+]
.It [+:

  IF (. use-flags)  :+]\-[+: ?% save-opts-value "%s" ">"
     :+] " [\fIrcfile\fP][+:
     IF (exist? "long-opts") :+]," " \-\-save-opts" "[=\fIrcfile\fP][+:
     ENDIF :+]"[+:
  ELSE     :+][+:
     IF (exist? "long-opts") :+]\-\-[+:
     ENDIF :+]save-opts "[=\fIrcfile\fP]"[+:
  ENDIF    :+]
Save the option state to \fIrcfile\fP.  The default is the \fIlast\fP
configuration file listed in the \fBOPTION PRESETS\fP section, below.
.It [+:

  IF (. use-flags)  :+]\-[+: ?% load-opts-value "%s" "<"
     :+] " \fIrcfile\fP[+:
     IF (exist? "long-opts")
           :+]," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts[+:
     ENDIF :+]"[+:
  ELSE     :+][+:
     IF (exist? "long-opts") :+]\-\-[+:
     ENDIF :+]load-opts "=\fIrcfile\fP," " \-\-no-load-opts"[+:
  ENDIF    :+]
Load options from \fIrcfile\fP.
The \fIno-load-opts\fP form will disable the loading
of earlier RC/INI files.  \fI\-\-no-load-opts\fP is handled early,
out of order.[+:
ENDIF (exist? "homerc")

.\" = = = = = = = = = = = = = = = = =
.\"  version
.\" = = = = = = = = = = = = = = = = = :+][+:

IF (exist? "version") :+]
.It [+:

  IF (. use-flags)  :+]\-[+: ?% version-value "%s" "v"
     :+] " [{\fIv|c|n\fP}][+:
     IF (exist? "long-opts") :+]," " \-\-version" "[=\fI{v|c|n}\fP][+:
     ENDIF :+]"[+:
  ELSE     :+][+:
     IF (exist? "long-opts") :+]\-\-[+:
     ENDIF :+]version "[=\fI{v|c|n}\fP]"[+:
  ENDIF    :+]
Output version of program and exit.  The default mode is `v', a simple
version.  The `c' mode will print copyright information and `n' will
print the full copyright notice.[+:
ENDIF                                 :+]
.El
[+:

(if formatted-doc
    (shell (string-append
    "fn='" (find-file cvt-cmd)
    "'\ntest -f ${fn} || die '" cvt-cmd " not found'\n"
    "${fn} <<\\_EndOfMdoc_ || die ${fn} failed in $PWD\n"
    (out-pop #t)
    "\n_EndOfMdoc_" )) )           :+][+:

ENDDEF mk-options

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - O P T I O N - P R E S E T S
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-option-presets              \:+]
Any option that is not marked as \fInot presettable\fP may be preset
by loading values from [+:
  IF (. home-rc-files)
    :+]configuration ("RC" or ".INI") file(s)[+:
    IF (. environ-init) :+] and values from
[+:
    ENDIF                             :+][+:
  ENDIF                               :+][+:
  IF (. environ-init) :+]environment variables named:
.nf
  \fB[+: (. UP-PROG-NAME) :+]_<option-name>\fP or \fB[+: (. UP-PROG-NAME) :+]\fP
.fi
.ad[+:
    IF (. home-rc-files)              :+]
The environmental presets take precedence (are processed later than)
the configuration files.[+:
    ENDIF                             :+][+:
  ELSE                                :+].[+:
  ENDIF                               :+][+:

  CASE
    (define rc-file
       (get "rcfile" (string-append "." (get "prog-name") "rc")) )
    (count "homerc")                  :+][+:

  == "0"                              :+][+:
  == "1"                              :+][+:

    CASE homerc                       :+][+:
    ~~ '\.|\$HOME'                    :+]
The file "\fI[+: (string-append (get "homerc") "/" rc-file)
:+]\fP" will be used, if present.[+:
    *                                 :+]
The \fIhomerc\fP file is "\fI[+:homerc:+]\fP", unless that is a directory.
In that case, the file "\fI[+: (. rc-file) :+]\fP"
is searched for within that directory.[+:
    ESAC                              :+][+:

  *                                   :+]
The \fIhomerc\fP files are [+:
    FOR homerc ", "                   :+][+:
      IF (last-for?)                  :+]and [+:
      ENDIF :+]"\fI[+: homerc :+]\fP"[+: ENDFOR :+].
If any of these are directories, then the file \fI[+: (. rc-file) :+]\fP
is searched for within those directories.[+:
  ESAC                                :+][+:

ENDDEF mk-option-presets

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - E X I T - S T A T U S
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-exit-status                \:+]
One of the following exit values will be returned:
.Bl -tag
[+:
(ag-fprintf 0 ".It 0 \" (EXIT_%s)\"\n%s\n"
    (string->c-name! (string-upcase (get "exit-name[0]" "SUCCESS")))
    (get-cvt "exit-desc[0]" "Successful program execution.") )

(define need-ex-noinput  (exist? "homerc"))
(define need-ex-software #t)

(ag-fprintf 0 ".It 1 \" (EXIT_%s)\"\n%s\n"
    (string->c-name! (string-upcase (get "exit-name[1]" "FAILURE")))
    (get-cvt "exit-desc[1]"
    "The operation failed or the command syntax was not valid.")) :+][+:

FOR exit-desc (for-from 2)            :+][+:
  (if (= (for-index) 66)
      (set! need-ex-noinput  #f)
      (if (= (for-index) 70)
          (set! need-ex-software #f) ))

  (set! tmp-str (get (sprintf "exit-name[%d]" (for-index)) "* unnamed *"))
  (sprintf ".It %d \" (EXIT_%s)\"\n%s\n"
    (for-index)
    (string-upcase (string->c-name! tmp-str))
    (get-cvt "exit-desc" ""))    :+][+:
ENDFOR exit-desc                      :+][+:
(if need-ex-noinput
    (emit ".It 66 \" (EX_NOINPUT)\"
A specified configuration file could not be loaded.\n"))

(if need-ex-noinput
    (emit ".It 70 \" (EX_SOFTWARE)\"
libopts had an internal operational error.  Please report
it to autogen-users@lists.sourceforge.net.  Thank you.\n"))

(if (> (string-length fname-line) 1)
    (emit fname-line)) :+]
.El
[+:

ENDDEF exit-status

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - A U T H O R S
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-authors                     :+][+:

  (define remove-authors #t)

  (set! tmp-val
      (if (exist? "copyright.author")
          (stack-join ",\n" "copyright.author")
          (stack-join ",\n" "copyright.owner") ))

  (if (> (string-length tmp-val) 1)
      (string-append tmp-val "\n")
      (delete-file file-name))

  :+][+:

ENDDEF mk-authors

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - B U G S
.\"
.\"  This section is guaranteed to be the last section in the man page
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-bugs                        :+][+:

    (set! tmp-val (get "copyright.eaddr" (get "eaddr")))
    (if (> (string-length tmp-val) 1)
        (string-append "Please send bug reports to: " tmp-val "\n")
        (delete-file file-name) )
    :+][+:

ENDDEF mk-bugs                        :+][+:

DEFINE append-bugs                    :+][+:

    (set! tmp-val (get "copyright.eaddr" (get "eaddr")))
    (if (> (string-length tmp-val) 1)
        (string-append "Please send bug reports to: " tmp-val "\n") )
    :+][+:

ENDDEF append-bugs

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - C O P Y R I G H T  (+ licensing)
.\"
.\"  This section is guaranteed to be the last section in the man page
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-copyright                    \:+]
Copyright (C) [+: copyright.date        :+] [+:
  (get "copyright.owner" (get "copyright.author" (get "copyright.eaddr")))
  :+] all rights reserved.
[+: CASE (get "copyright.type")         :+][+:
    = note  :+][+: (get "copyright.text") :+][+:
    == ''   :+]This program has an unspecified license.[+:

    *       :+][+:
    (string-append "This program is released under the terms of "
            (license-name (get "copyright.type")) ".")    :+][+:

  ESAC      :+]
[+:
ENDDEF mk-copyright

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - N O T E S
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-notes                       \:+]
This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
option definitions.
[+:

ENDDEF mk-notes

.\" = = = = = APPEND TO IT:           :+][+:

DEFINE append-notes                  \:+]
.Pp
This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
option definitions.[+:

ENDDEF append-notes

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - E N V I R O N M E N T
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-environment                 :+][+:
  INVOKE  append-environment          :+][+:
ENDDEF mk-environment

.\" = = = = = APPEND TO IT:           :+][+:

DEFINE append-environment             :+][+:
   (. environ-text)                   :+][+:
ENDDEF append-environment

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  M K - F I L E S
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE mk-files                       :+][+:
  INVOKE  append-files                :+][+:
ENDDEF mk-files

.\" = = = = = APPEND TO IT:           :+][+:

DEFINE append-files                   :+][+:
   (. home-rc-text)                   :+][+:
ENDDEF append-files

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  E M I T   A L I A S   O P T
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE emit-alias-opt                   :+]
.It [+:
  IF (exist? "value")                   :+][+:
    IF (exist? "long-opts")            \:+]
 \-[+:value:+] ", " -\-[+: name         :+][+:
    ELSE                               \:+]
 \-[+:value:+][+:
    ENDIF  (exist? "long-opts")         :+][+:

  ELSE  value does not exist -- named option only  :+][+:

    IF (not (exist? "long-opts"))      \:+]
 [+: name :+][+:
    ELSE                               \:+]
 \-\-[+: (. opt-name)                   :+][+:
    ENDIF                               :+][+:
  ENDIF                                 :+]
This is an alias for the [+: aliases :+] option.[+:
ENDDEF emit-alias-opt

.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
.\"  E M I T   F L A G   T E X T
.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:

DEFINE emit-flag-text                 :+][+:

  (if (exist? "enable")
      (set! opt-name (string-append (get "enable") "-" (get "name")))
      (set! opt-name (get "name")) )
  (if (exist? "disable")
      (set! dis-name (string-append (get "disable") "-" (get "name")))
      (set! dis-name "") )

  (set! opt-name (fix-optname opt-name))
  (if (> (string-length dis-name) 0)
      (set! dis-name (fix-optname dis-name)) )

  (if (not (exist? "arg-type"))
      (set! opt-arg "")
      (set! opt-arg (string-append "\\fI"
            (fix-optname (if (exist? "arg-name")
                (get "arg-name")
                (string-downcase! (get "arg-type"))  ))
            "\\fP" ))
  )

:+]
.It [+:
  IF (exist? "value")                   :+][+:
    IF (exist? "long-opts")             :+][+:

          # * * * * * * * * * * * * * * * * * * * *
          *
          *  The option has a flag value (character) AND
          *  the program uses long options
          *
          \:+]
 \-[+:value:+][+:
      IF (not (exist? "arg-type"))      :+] ", " -\-[+:
      ELSE  :+] " [+:(. opt-arg):+], " \-\-[+:
      ENDIF :+][+: (. opt-name)         :+][+:
      IF (exist? "arg-type")            :+][+:
              ? arg-optional " [ =" ' "=" '
              :+][+:  (. opt-arg)       :+][+:
              arg-optional " ]"         :+][+:
      ENDIF                             :+][+:
      IF (exist? "disable") :+], " \fB\-\-[+:(. dis-name):+]\fP"[+:
      ENDIF                             :+][+:

    ELSE                                :+][+:

          # * * * * * * * * * * * * * * * * * * * *
          *
          *  The option has a flag value (character) BUT
          *  the program does _NOT_ use long options
          *
          \:+]
 \-[+:value:+][+:
      IF (exist? "arg-type")            :+][+:
            arg-optional "["     :+] "[+:(. opt-arg):+][+:
            arg-optional '"]"'          :+][+:
      ENDIF "                           :+][+:
    ENDIF  (exist? "long-opts")         :+][+:


  ELSE  value does not exist -- named option only  :+][+:

    IF (not (exist? "long-opts"))       :+][+:

          # * * * * * * * * * * * * * * * * * * * *
          *
          *  The option does not have a flag value (character).
          *  The program does _NOT_ use long options either.
          *  Special magic:  All arguments are named options.
          *
          \:+]
 [+: (. opt-name) :+][+:
      IF (exist? "arg-type")            :+] [+:
         ? arg-optional " [ =" ' "=" '
         :+][+:(. opt-arg)              :+][+:
         arg-optional "]"               :+][+:
      ENDIF:+][+:
      IF (exist? "disable") :+], " \fB[+:(. dis-name):+]\fP"[+:
      ENDIF                             :+][+:


    ELSE                                :+][+:
          # * * * * * * * * * * * * * * * * * * * *
          *
          *  The option does not have a flag value (character).
          *  The program, instead, only accepts long options.
          *
          \:+]
 \-\-[+: (. opt-name) :+][+:

      IF (exist? "arg-type") :+] "[+: #" :+][+:
            arg-optional "[" :+]=[+:(. opt-arg):+][+:
            arg-optional "]" :+]"[+: #" :+][+:
      ENDIF                             :+][+:

      IF (exist? "disable")
        :+], " \fB\-\-[+:(. dis-name):+]\fP"[+:
      ENDIF                             :+][+:
    ENDIF                               :+][+:
  ENDIF                                 :+]
[+: (get-cvt "descrip" "") :+].[+:

  IF (exist? "min")                     :+]
This option is required to appear.[+:
  ENDIF                                 :+][+:

  IF (exist? "max") :+]
This option may appear [+:
    IF % max (= "%s" "NOLIMIT")
      :+]an unlimited number of times[+:ELSE
      :+]up to [+: max :+] times[+:
    ENDIF:+].[+:
  ENDIF:+][+:

  IF (exist? "disable")               :+]
The \fI[+:(. dis-name):+]\fP form will [+:
    IF (exist? "stack-arg")
          :+]clear the list of option arguments[+:
    ELSE  :+]disable the option[+:
    ENDIF :+].[+:
  ENDIF:+][+:

  IF (exist? "enabled")               :+]
This option is enabled by default.[+:
  ENDIF                               :+][+:

  IF (exist? "no-preset")             :+]
This option may not be preset with environment variables
or in initialization (rc) files.[+:
  ENDIF                               :+][+:

  IF (and (exist? "default") named-mode) :+]
This option is the default option.[+:
  ENDIF                               :+][+:

  IF (exist? "equivalence")           :+]
This option is a member of the [+:equivalence:+] class of options.[+:
  ENDIF                               :+][+:

  IF (exist? "flags-must")            :+]
This option must appear in combination with the following options:
[+: FOR flags-must ", " :+][+:flags-must:+][+:ENDFOR:+].[+:
  ENDIF                               :+][+:

  IF (exist? "flags-cant")            :+]
This option must not appear in combination with any of the following options:
[+: FOR flags-cant ", " :+][+:flags-cant:+][+:ENDFOR:+].[+:
  ENDIF                               :+][+:


  IF (~* (get "arg-type") "key|set") :+]
This option takes a keyword as its argument[+:

    IF (=* (get "arg-type") "set")

:+] list.  Each entry turns on or off
membership bits.  The bits are set by name or numeric value and cleared
by preceding the name or number with an exclamation character ('!').
They can all be cleared with the magic name \fInone\fR and they can all be set
with
.IR all .
A single option will process a list of these values.[+:

    ELSE

:+].  The argument sets an enumeration value that can
be tested by comparing them against the option value macro.[+:

    ENDIF

:+]
The available keywords are:
.in +4
.nf
.na
[+: (shellf "${CLexe} --indent='' --spread=1 -W50 <<_EOF_\n%s\n_EOF_"
            (join "\n" (stack "keyword"))  )   :+]
.fi
or their numeric equivalent.
.in -4[+: (if (exist? "arg-default") "\n.sp" ) :+][+:

  ELIF (=* (get "arg-type") "num")    :+]
This option takes an integer number as its argument.[+:

    IF  (exist? "arg-range")          :+]
The value of [+:(. opt-arg):+] is constrained to being:
.in +4
.nf
.na[+:FOR arg_range ", or"            :+]
[+: (shellf "
range='%s'

case \"X${range}\" in
X'->'?*  )
  echo \"less than or equal to\" `
    echo $range | sed 's/->//' ` ;;

X?*'->'  )
  echo \"greater than or equal to\" `
    echo $range | sed 's/->.*//' ` ;;

X?*'->'?* )
  echo \"in the range \" `
    echo $range | sed 's/->/ through /' ` ;;

X?* )
  echo exactly $range ;;

X* ) echo $range is indeterminate
esac"

(get "arg-range") )
:+][+:
      ENDFOR arg-range :+]
.fi
.in -4[+:

    ENDIF  arg-range exists           :+][+:

  ENDIF  arg-type key/set/num         :+][+:

  IF (exist? "arg-default")           :+]
The default [+: (. opt-arg) :+] for this option is:
.ti +4
 [+: (join " + " (stack "arg-default" )) :+][+:
  ENDIF                               :+]
.sp
[+:
 (if (exist? "doc")
        (get-cvt "doc" "")
        "This option has not been fully documented." ) :+][+:
  IF (exist? "deprecated")            :+]
.sp
.B
NOTE: THIS OPTION IS DEPRECATED
.R[+:
  ENDIF                               :+][+:

ENDDEF emit-flag-text

.\" cmd-doc.tlib ends here \:+]