contrib/ntp/sntp/ag-tpl/0-old/cmd-doc.tlib

   1 [+: -*- Mode: nroff -*-
   2
   3   AutoGen5 template man
   4
   5 # cmd-doc.tlib -- Template for command line man/mdoc pages
   6 #
   7 #  This file is part of AutoOpts, a companion to AutoGen.
   8 #  AutoOpts is free software.
   9 #  Copyright (C) 1992-2013 Bruce Korb - all rights reserved
  10 #
  11 #  AutoOpts is available under any one of two licenses.  The license
  12 #  in use must be one of these two and the choice is under the control
  13 #  of the user of the license.
  14 #
  15 #   The GNU Lesser General Public License, version 3 or later
  16 #      See the files "COPYING.lgplv3" and "COPYING.gplv3"
  17 #
  18 #   The Modified Berkeley Software Distribution License
  19 #      See the file "COPYING.mbsd"
  20 #
  21 #  These files have the following sha256 sums:
  22 #
  23 #  8584710e9b04216a394078dc156b781d0b47e1729104d666658aecef8ee32e95  COPYING.gplv3
  24 #  4379e7444a0e2ce2b12dd6f5a52a27a4d02d39d247901d3285c88cf0d37f477b  COPYING.lgplv3
  25 #  13aa749a5b0a454917a944ed8fffc530b784f5ead522b1aacaf4ec8aa55a6239  COPYING.mbsd
  26
  27 # Produce a man page for section 1, 5, 6 or 8 commands.  Which is
  28 # selected via: -DMAN_SECTION=n.  "n" may have a suffix, if desired.
  29 # These sections have default section names that may be overridden
  30 # with -DSECTIN_NAME=XX, also passed to the autogen invocation.
  31 #
  32 :+][+:
  33
  34    ;;# START-BUILDTREE-ISMS
  35    ;;
  36    (shell "CLexe=${AGexe%/agen5/*}/columns/columns
  37   test -x \"${CLexe}\" || {
  38     CLexe=${AGexe%/autogen}/columns
  39     test -x \"${CLexe}\" || die 'columns program is not findable'
  40   }")
  41
  42 :+][+: # END-BUILDTREE-ISMS
  43
  44 (shell "CLexe=`echo ${AGexe} | sed 's@/autogen@/columns@'`
  45        test -x \"${CLexe}\" || CLexe=`which columns`")
  46
  47 # END-INSTALL-ONLY-CODE :+][+:
  48
  49 (define down-prog-name (string-downcase! (get "prog-name")))
  50 (define UP-PROG-NAME   (get-up-name "prog-name"))
  51
  52 (define command-doc    #t)
  53 (define tmp-val        (getenv "MAN_SECTION"))
  54 (define man-sect       (if (exist? "cmd-section") (get "cmd-section") "1"))
  55 (define file-name      "")
  56 (define sect-name      "")
  57 (define macro-name     "")
  58 (define tmp-str        "")
  59 (define fname-line     "")
  60 (define use-flags      (exist? "flag.value"))
  61 (define named-mode     (not (or use-flags (exist? "long-opts") )))
  62
  63 (if (defined? 'tmp-val)
  64     (if (string? tmp-val)
  65         (set! man-sect tmp-val)))
  66
  67 (define section-name
  68    (if (=* man-sect "1") "User Commands"
  69    (if (=* man-sect "5") "File Formats"
  70    (if (=* man-sect "6") "Games"
  71    (if (=* man-sect "8") "System Management"
  72    (error
  73     "the agman-cmd template only produces section 1, 5, 6 and 8 man pages")
  74 )))))
  75 (set! tmp-val (getenv "SECTION_NAME"))
  76 (if (defined? 'tmp-val) (if (string? tmp-val)
  77     (set! section-name tmp-val) ))
  78
  79 (define package-text "")
  80 (define package+version (and (exist? "package") (exist? "version")))
  81
  82 (if (or (exist? "package") (exist? "version")) (begin
  83   (set! package-text (string-append
  84         (get "package")
  85         (if package+version " (" "")
  86         (get "version")
  87         (if package+version ")" "") ))
  88 ) )
  89
  90 (define name-to-fname (lambda (nm)
  91     (string-tr (string-downcase nm) " " "-") ))
  92
  93 (define sect-line-fname (lambda () (begin
  94     (out-push-new file-name)
  95     (emit (string-append ".Sh \"" sect-name "\"\n"))
  96     (string-append "mk-" macro-name) )))
  97
  98 (make-tmp-dir)
  99
 100 (define home-rc-files (exist? "homerc"))
 101 (define home-rc-text
 102   "\nSee \\fBOPTION PRESETS\\fP for configuration files.")
 103
 104 (define environ-init  (exist? "environrc"))
 105 (define environ-text
 106   "\nSee \\fBOPTION PRESETS\\fP for configuration environment variables.")
 107
 108 (emit (head-line))
 109 (dne ".\\\"  ")                       :+]
 110 .Sh NAME
 111 .Nm [+: prog-name                     :+]
 112 .Nd [+: prog-title                    :+]
 113 [+: INCLUDE "tpl-config.tlib"         :+][+:#
 114
 115 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 116 .\"  B U I L D   D O C
 117 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 118
 119 DEFINE build-doc                      :+][+:
 120
 121 (if (not command-doc) (begin
 122     (set! home-rc-files #f)
 123     (set! home-rc-text "")
 124 )   )                                 :+][+:
 125
 126 INVOKE doc-sections                   :+][+:
 127 INVOKE ao-sections                    :+][+:
 128 INVOKE assemble-sections              :+][+:
 129
 130 ENDDEF build-doc
 131
 132 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 133 .\"  A S S E M B L E   S E C T I O N S
 134 .\"
 135 .\" Emit the files for each section that was provided, and do conversions
 136 .\"
 137 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 138
 139 DEFINE assemble-sections    :+][+:
 140
 141 (out-push-new)
 142
 143 :+][+:
 144 #.\" Insert the sections in the prescribed order
 145 #.\" Ensure a newline between them all.  We strip blank lines,
 146 #.\" so extra blank lines get removed.
 147 #:+]
 148 cvt_prog='[+:
 149
 150     (define target-form   (if man-page "man" "mdoc"))
 151     (define source-form   (get "option-format" "texi"))
 152     (define converter     (string-append source-form "2" target-form ))
 153     (set! tmp-str (find-file converter))
 154
 155     (if (not (defined? 'tmp-str))
 156         (error (string-append "cannot locate " converter)))
 157     tmp-str
 158 :+]'
 159 cvt_prog=`cd \`dirname "$cvt_prog"\` >/dev/null && pwd
 160          `/`basename "$cvt_prog"`
 161 cd $tmp_dir
 162 test -x "$cvt_prog" || die "'$cvt_prog' is not executable"
 163 {
 164     list='synopsis description options option-presets'
 165     for f in $list ; do cat $f ; echo ; done
 166     rm -f $list name
 167     list='implementation-notes environment files examples exit-status errors
 168         compatibility see-also conforming-to history authors copyright bugs
 169         notes'
 170     for f in $list ; do cat $f ; echo ; done > .end-doc
 171     rm -f $list
 172     list=`ls -1 *`' .end-doc'
 173     for f in $list ; do cat $f ; echo ; done
 174     rm -f $list
 175 } 1>.doc 2>/dev/null
 176 [+:
 177 IF (exist? "doc-sub")       :+][+:
 178   (out-push-new (string-append tmp-dir "/.cmds")) :+][+:
 179   FOR doc-sub               :+][+:
 180
 181     IF (define field-name (get "sub-type" target-form))
 182        (~~ target-form field-name)  :+][+:
 183
 184        (set! field-name (get "sub-name"))
 185        (define rep-string (string-append "<<" field-name ">>"))
 186        (emit (string-substitute (get "sub-text") rep-string (get field-name)))
 187        "\n"
 188
 189     :+][+:  ENDIF           :+][+:
 190
 191   ENDFOR doc-sub            :+][+:
 192
 193   (out-pop)
 194   (define post-proc-cmd (string-append
 195           (get "doc-sub-cmd" "sed -f %s %s") " | "
 196           egrep-prog " -v '^[   ]*$' | $cvt_prog"))
 197   (sprintf post-proc-cmd ".cmds" ".doc")
 198   :+][+:
 199 ELSE                       \:+]
 200 [+:(. egrep-prog):+] -v '^[     ]*$' .doc | $cvt_prog[+:
 201 ENDIF doc-sub exists        :+][+:
 202
 203 (shell (out-pop #t))        :+][+:
 204
 205 ENDDEF assemble-sections
 206
 207 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 208 .\"  D O C   S E C T I O N S
 209 .\"
 210 .\" Emit the files for each section that was provided.
 211 .\" If multiple sections exist, they get glued together with ".Pp"
 212 .\" between them.
 213 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 214
 215 DEFINE doc-sections                   :+][+:
 216
 217 FOR doc-section                       :+][+:
 218   IF
 219     (define sec-type (string-upcase (get "ds-type")))
 220     (define sec-name (name-to-fname sec-type))
 221     (define cvt-fn (find-file (string-append
 222          (get "ds-format" "man") "2mdoc")))
 223     (if (not (defined? 'cvt-fn))
 224         (error (sprintf "Cannot locate converter for %s"
 225                (get "ds-format" "man"))))
 226
 227     (define sec-file (string-append tmp-dir "/" sec-name))
 228     (access? sec-file R_OK)           :+][+:
 229         (out-push-add sec-file)
 230         (emit ".Pp\n")                :+][+:
 231
 232   ELSE :+][+: CASE
 233     (out-push-new sec-file)
 234     sec-type :+][+:
 235
 236     == ""    :+][+: (error "unnamed doc-section") :+][+:
 237     *==* " " :+].Sh "[+: (. sec-type)             :+]"[+:
 238     *        :+].Sh [+: (. sec-type)              :+][+:
 239     ESAC     :+][+:
 240   ENDIF :+]
 241 [+:
 242     (shell (string-append
 243       "fn='" cvt-fn "'\n"
 244       "test -f ${fn} || die ${fn} not found from $PWD\n"
 245       "${fn} <<\\_EndOfDocSection_ || die ${fn} failed in $PWD\n"
 246       (get "ds-text")
 247       "\n_EndOfDocSection_"
 248     ))                                :+][+:
 249
 250     CASE (emit "\n") sec-type         :+][+:
 251     == FILES                          :+][+:
 252         (if home-rc-files (emit home-rc-text))
 253         (set! home-rc-files #f)       :+][+:
 254
 255     == ENVIRONMENT                    :+][+:
 256         (if environ-init (emit environ-text))
 257         (set! environ-init #f)        :+][+:
 258     ESAC                              :+][+:
 259
 260     (out-pop)
 261     :+][+:
 262
 263 ENDFOR doc-section                    :+][+:
 264
 265 ENDDEF doc-sections
 266
 267 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 268 .\"  A O   S E C T I O N S
 269 .\"
 270 .\" Emit the files for the sections that these templates augment,
 271 .\" replace or conditionally replace
 272 .\"
 273 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 274
 275 DEFINE ao-sections              :+][+:
 276   IF (. command-doc)            :+][+:
 277     INVOKE cond-section  sec = "OPTIONS"       mode = "replace"       :+][+:
 278     INVOKE cond-section  sec = "EXIT STATUS"   mode = "insert"        :+][+:
 279
 280     IF (or home-rc-files environ-init)                                :+][+:
 281       INVOKE cond-section   sec = "OPTION PRESETS" mode = "replace"   :+][+:
 282
 283       IF (. home-rc-files)                                            :+][+:
 284         INVOKE cond-section sec = "FILES"          mode = "append"    :+][+:
 285       ENDIF                                                           :+][+:
 286
 287       IF (. environ-init)                                             :+][+:
 288         INVOKE cond-section sec = "ENVIRONMENT"    mode = "append"    :+][+:
 289       ENDIF                                                           :+][+:
 290     ENDIF                                                             :+][+:
 291
 292   ELSE  section 5, not command  :+][+:
 293     INVOKE cond-section sec = "FILES"          mode = "append"        :+][+:
 294   ENDIF  section 5/not          :+][+:
 295
 296   INVOKE cond-section  sec = "SYNOPSIS"        mode = "alt"           :+][+:
 297   INVOKE cond-section  sec = "DESCRIPTION"     mode = "append"        :+][+:
 298   INVOKE cond-section  sec = "AUTHORS"         mode = "alt"           :+][+:
 299   INVOKE cond-section  sec = "BUGS"            mode = "append"        :+][+:
 300   INVOKE cond-section  sec = "NOTES"           mode = "append"        :+][+:
 301
 302 IF (exist? "copyright")                                               :+][+:
 303   INVOKE cond-section   sec = "COPYRIGHT"      mode = "alt"           :+][+:
 304 ENDIF                                                                 :+][+:
 305
 306 ENDDEF ao-sections
 307
 308 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 309 .\"  C O N D I T I O N A L   S E C T I O N
 310 .\"
 311 .\" Figure out what to do for AutoOpts required sections, depending on "mode"
 312 .\" In all cases, if the file does not exist, invoke the "mk" macro to create
 313 .\" a new file.  If it does exist, then:
 314 .\"
 315 .\" alt       Alternate -- emit no text
 316 .\" replace   throw away any pre-existing file.
 317 .\" append    invoke the "append" macro to emit additional text
 318 .\" insert    save the current contents, replacing the .Sh line with .Pp.
 319 .\"           invoke the "mk" macro then emit the saved text
 320 .\"
 321 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 322
 323 DEFINE cond-section                     :+][+:
 324
 325   IF
 326      (set! sect-name   (string-upcase! (string-substitute
 327                        (get "sec") "-" " " )))
 328      (set! macro-name  (string-downcase! (string-substitute
 329                        sect-name " " "-" )))
 330      (set! file-name   (string-append tmp-dir "/" macro-name))
 331
 332      (not (access? file-name R_OK))     :+][+:
 333
 334      INVOKE (sect-line-fname)           :+][+:
 335
 336   ELSE file exists                      :+][+:
 337
 338      CASE (get "mode")                  :+][+:
 339
 340      ==  replace                        :+][+:
 341          INVOKE (sect-line-fname)       :+][+:
 342
 343      ==  append                         :+][+:
 344          (out-push-add file-name)       :+][+:
 345          INVOKE (string-append "append-" macro-name) :+][+:
 346
 347      ==  insert                         :+][+:
 348          (set! fname-line (shellf
 349            "sed '1s/.Sh .*/.Pp/' %1$s ; rm -f %1$s" file-name)) :+][+:
 350          INVOKE (sect-line-fname)       :+][+:
 351
 352      ==  alt                            :+][+:
 353          (out-push-new)                 :+][+:
 354
 355      *                                  :+][+:
 356          (error (sprintf "invalid section type: %s" (get "mode")))
 357
 358      :+][+:
 359      ESAC                               :+][+:
 360
 361   ENDIF file existence/non-existence    :+][+:
 362   (out-pop) :+][+: # All paths open out :+][+:
 363 ENDDEF cond-section
 364
 365 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 366 .\"  M K - D E S C R I P T I O N
 367 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 368
 369 DEFINE mk-description                   :+][+:
 370
 371    (out-push-new)
 372    (emit
 373      (if (exist? "prog-man-descrip")
 374          (stack-join "\n.Pp\n" "prog-man-descrip")
 375          (if (exist? "detail")
 376              (stack-join "\n.Pp\n" "detail")
 377              "There is no description for this command."
 378    ) )   )
 379    (shell "sed 's/^$/.sp/' <<\\_EODesc_\n" (out-pop #t) "\n_EODesc_")
 380
 381    :+][+:
 382    INVOKE append-description            :+][+:
 383
 384 ENDDEF mk-description
 385
 386 .\" = = = = = = = = = = = = = = = = = =
 387 .\"  A P P E N D - D E S C R I P T I O N
 388 .\" = = = = = = = = = = = = = = = = = = :+][+:
 389
 390 DEFINE append-description               :+][+:
 391
 392 IF (= (get "main.main-type") "for-each"):+][+:
 393
 394   CASE main.handler-type                :+][+:
 395   ~* ^(name|file)|.*text               \:+]
 396 .Pp
 397 This program will perform its function for every file named on the command
 398 line or every file named in a list read from stdin.  The arguments or input
 399 names must be pre\-existing files.  The input list may contain comments,
 400 which[+:
 401
 402   !E                                   \:+]
 403 .Pp
 404 This program will perform its function for every command line argument
 405 or every non\-comment line in a list read from stdin.
 406 The input list comments[+:
 407
 408   *                                     :+][+:
 409   (error "the 'for-each' main has in invalid handler-type.") :+][+:
 410   ESAC                                 \:+]
 411  are blank lines or lines beginning with a '[+:
 412   ?% comment-char "%s" "#" :+]' character.
 413 [+:
 414
 415 ENDIF - "main" is of "for-each" type    :+][+:
 416
 417 ENDDEF append-description
 418
 419 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 420 .\"  M K - O P T I O N S
 421 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 422
 423 DEFINE mk-options
 424
 425 :+][+:
 426
 427 (define opt-arg       "")
 428 (define dis-name      "")
 429 (define opt-name      "")
 430 (define optname-from  "A-Z_^")
 431 (define optname-to    "a-z--")
 432 (define cvt-cmd       "")
 433 (define formatted-doc (exist? "option-format"))
 434
 435 (if formatted-doc (begin
 436     (out-push-new)
 437     (set! cvt-cmd (string-append (get "option-format") "2mdoc"))
 438 )   )
 439
 440 (if (exist? "preserve-case")
 441    (begin
 442       (set! optname-from "_^")
 443       (set! optname-to   "--")
 444 )  )
 445
 446 (define fix-optname (lambda (o_nm) (begin
 447    (set! o_nm (string-tr o_nm optname-from optname-to))
 448    (set! o_nm (string-substitute o_nm "-" "\\-" ))
 449    o_nm )))
 450
 451 (if (exist? "option-info")
 452     (string-append ".Pp\n" (get "option-info") "\n") )
 453 \:+]
 454 .Bl -tag[+:
 455
 456 FOR flag                              :+][+:
 457   IF (not (exist? "documentation"))   :+][+:
 458     IF (exist? "aliases")             :+][+:
 459       INVOKE emit-alias-opt           :+][+:
 460     ELSE                              :+][+:
 461       INVOKE emit-flag-text           :+][+:
 462     ENDIF                             :+][+:
 463
 464   ELSE                                :+]
 465 .Ss "[+: (get "descrip" "") :+]"[+:
 466 (set! tmp-str (get "documentation" ""))
 467 (if (> (string-length tmp-str) 3) (string-append
 468     "\n" tmp-str "\n" ))              :+][+:
 469
 470   ENDIF                               :+][+:
 471 ENDFOR flag
 472
 473 .\" = = = = = = = = = = = = = = = = =
 474 .\"  help option
 475 .\" = = = = = = = = = = = = = = = = =
 476
 477 :+]
 478 .It [+:
 479   (define tmp-val (get "help-value" "\\&?"))
 480   (if (and use-flags (> (string-length tmp-val) 0))
 481       (string-append "Fl " tmp-val
 482             (if (exist? "long-opts") " , Fl -help" "") )
 483       (string-append (if (exist? "long-opts") "Fl -" "") "help" )
 484   )  \:+]
 485
 486 Display usage information and exit.[+:#
 487
 488 .\" = = = = = = = = = = = = = = = = =
 489 .\"  more-help option
 490 .\" = = = = = = = = = = = = = = = = = :+][+:
 491
 492   IF (not (exist? "no-libopts")) :+]
 493 .It [+:
 494   (define tmp-val (get "more-help-value" "\\&!"))
 495   (if (and use-flags (> (string-length tmp-val) 0))
 496       (string-append "Fl " tmp-val
 497             (if (exist? "long-opts") " , Fl -more-help" "") )
 498       (string-append (if (exist? "long-opts") "Fl -" "") "more-help" )
 499   )       \:+]
 500
 501 Pass the extended usage information through a pager.[+:
 502
 503 ENDIF no no-libopts
 504
 505 .\" = = = = = = = = = = = = = = = = =
 506 .\"  save and load configuration
 507 .\" = = = = = = = = = = = = = = = = = :+][+:
 508
 509 IF (exist? "homerc") :+]
 510 .It [+:
 511
 512   IF (not (exist? "disable-save"))    :+][+:
 513
 514   (define tmp-val (get "save-opts-value" ">"))
 515   (if (and use-flags (> (string-length tmp-val) 0))
 516       (string-append "Fl " tmp-val " Oo Ar cfgfile Oc"
 517             (if (exist? "long-opts")
 518                 " , Fl -save-opts Oo Ns = Ns Ar cfgfile Oc" ) "")
 519       (string-append (if (exist? "long-opts") "Fl -" "")
 520             "save-opts Oo Ns = Ns Ar cfgfile Oc" )
 521   )       \:+]
 522
 523 Save the option state to \fIcfgfile\fP.  The default is the \fIlast\fP
 524 configuration file listed in the \fBOPTION PRESETS\fP section, below.
 525 The command will exit after updating the config file.
 526 .It [+:
 527   ENDIF  saving not disabled          :+][+:
 528
 529   (define tmp-val (get "load-opts-value" "<"))
 530   (define tmp-str (if (exist? "long-opts") "Fl -" ""))
 531
 532   (if (and use-flags (> (string-length tmp-val) 0))
 533       (string-append "Fl " tmp-val " Ar cfgfile"
 534          (if (exist? "long-opts")
 535              (string-append " , " tmp-str "load-opts Ns = Ns Ar cfgfile"
 536                             " , " tmp-str "no-load-opts" )
 537              "") )
 538       (string-append tmp-str "load-opts Ns = Ns Ar cfgfile , "
 539                      tmp-str "no-load-opts" )
 540   )       \:+]
 541
 542 Load options from \fIcfgfile\fP.
 543 The \fIno-load-opts\fP form will disable the loading
 544 of earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,
 545 out of order.[+:
 546
 547 ENDIF (exist? "homerc")
 548
 549 .\" = = = = = = = = = = = = = = = = =
 550 .\"  version
 551 .\" = = = = = = = = = = = = = = = = = :+][+:
 552
 553 IF (exist? "version") :+]
 554 .It [+:
 555
 556   (define tmp-val (get "version-value" "v"))
 557   (if (and use-flags (> (string-length tmp-val) 0))
 558       (string-append "Fl " tmp-val " Op Brq Ar v|c|n"
 559             (if (exist? "long-opts")
 560                 "  Fl -version Op Brq Ar v|c|n" ) "")
 561       (string-append (if (exist? "long-opts") "Fl -" "")
 562             "version Op Brq Ar v|c|n" )
 563   )       \:+]
 564
 565 Output version of program and exit.  The default mode is `v', a simple
 566 version.  The `c' mode will print copyright information and `n' will
 567 print the full copyright notice.[+:
 568 ENDIF                                 :+]
 569 .El
 570 [+:
 571
 572 (if formatted-doc
 573     (shell (string-append
 574     "fn='" (find-file cvt-cmd)
 575     "'\ntest -f ${fn} || die '" cvt-cmd " not found'\n"
 576     "${fn} <<\\_EndOfMdoc_ || die ${fn} failed in $PWD\n"
 577     (out-pop #t)
 578     "\n_EndOfMdoc_" )) )           :+][+:
 579
 580 ENDDEF mk-options
 581
 582 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 583 .\"  M K - O P T I O N - P R E S E T S
 584 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 585
 586 DEFINE mk-option-presets              \:+]
 587 Any option that is not marked as \fInot presettable\fP may be preset
 588 by loading values from [+:
 589   IF (. home-rc-files)
 590     :+]configuration ("RC" or ".INI") file(s)[+:
 591     IF (. environ-init) :+] and values from
 592 [+:
 593     ENDIF                             :+][+:
 594   ENDIF                               :+][+:
 595   IF (. environ-init) :+]environment variables named:
 596 .nf
 597   \fB[+:(. UP-PROG-NAME):+]_<option-name>\fP or \fB[+:(. UP-PROG-NAME):+]\fP
 598 .fi
 599 .ad[+:
 600     IF (. home-rc-files)              :+]
 601 The environmental presets take precedence (are processed later than)
 602 the configuration files.[+:
 603     ENDIF                             :+][+:
 604   ELSE                                :+].[+:
 605   ENDIF                               :+][+:
 606
 607   CASE
 608     (define rc-file
 609        (get "rcfile" (string-append "." (get "prog-name") "rc")) )
 610     (count "homerc")                  :+][+:
 611
 612   == "0"                              :+][+:
 613   == "1"                              :+][+:
 614
 615     CASE homerc                       :+][+:
 616     ~~ '\.|\$HOME'                    :+]
 617 The file "\fI[+: (string-append (get "homerc") "/" rc-file)
 618 :+]\fP" will be used, if present.[+:
 619
 620     == ""                             :+][+:
 621
 622     *                                 :+]
 623 The \fIhomerc\fP file is "\fI[+:homerc:+]\fP", unless that is a directory.
 624 In that case, the file "\fI[+: (. rc-file) :+]\fP"
 625 is searched for within that directory.[+:
 626     ESAC                              :+][+:
 627
 628   *                                   :+]
 629 The \fIhomerc\fP files are [+:
 630     FOR homerc ", "                   :+][+:
 631       IF (last-for?)                  :+]and [+:
 632       ENDIF :+]"\fI[+: homerc :+]\fP"[+: ENDFOR :+].
 633 If any of these are directories, then the file \fI[+: (. rc-file) :+]\fP
 634 is searched for within those directories.[+:
 635   ESAC                                :+][+:
 636
 637 ENDDEF mk-option-presets
 638
 639 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 640 .\"  M K - E X I T - S T A T U S
 641 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 642
 643 DEFINE mk-exit-status                \:+]
 644 One of the following exit values will be returned:
 645 .Bl -tag
 646 [+:
 647 (ag-fprintf 0 ".It 0 \" (EXIT_%s)\"\n%s\n"
 648     (string->c-name! (string-upcase (get "exit-name[0]" "SUCCESS")))
 649     (get "exit-desc[0]" "Successful program execution.") )
 650
 651 (define need-ex-noinput  (exist? "homerc"))
 652 (define need-ex-software #t)
 653
 654 (ag-fprintf 0 ".It 1 \" (EXIT_%s)\"\n%s\n"
 655     (string->c-name! (string-upcase (get "exit-name[1]" "FAILURE")))
 656     (get "exit-desc[1]"
 657     "The operation failed or the command syntax was not valid.")) :+][+:
 658
 659 FOR exit-desc (for-from 2)            :+][+:
 660   (if (= (for-index) 66)
 661       (set! need-ex-noinput  #f)
 662       (if (= (for-index) 70)
 663           (set! need-ex-software #f) ))
 664
 665   (set! tmp-str (get (sprintf "exit-name[%d]" (for-index)) "* unnamed *"))
 666   (sprintf ".It %d \" (EXIT_%s)\"\n%s\n"
 667     (for-index)
 668     (string-upcase (string->c-name! tmp-str))
 669     (get "exit-desc" ""))             :+][+:
 670 ENDFOR exit-desc                      :+][+:
 671 (if need-ex-noinput
 672     (emit ".It 66 \" (EX_NOINPUT)\"
 673 A specified configuration file could not be loaded.\n"))
 674
 675 (if need-ex-software
 676     (emit ".It 70 \" (EX_SOFTWARE)\"
 677 libopts had an internal operational error.  Please report
 678 it to autogen-users@lists.sourceforge.net.  Thank you.\n"))
 679
 680 (if (> (string-length fname-line) 1)
 681     (emit fname-line))                :+]
 682 .El
 683 [+:
 684
 685 ENDDEF mk-exit-status
 686
 687 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 688 .\"  M K - A U T H O R S
 689 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 690
 691 DEFINE mk-authors                     :+][+:
 692
 693   (define remove-authors #t)
 694
 695   (set! tmp-val
 696       (if (exist? "copyright.author")
 697           (stack-join ",\n" "copyright.author")
 698           (stack-join ",\n" "copyright.owner") ))
 699
 700   (if (> (string-length tmp-val) 1)
 701       (string-append tmp-val "\n")
 702       (delete-file file-name))
 703
 704   :+][+:
 705
 706 ENDDEF mk-authors
 707
 708 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 709 .\"  M K - B U G S
 710 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 711
 712 DEFINE mk-bugs                        :+][+:
 713
 714     (set! tmp-val (get "copyright.eaddr" (get "eaddr")))
 715     (if (> (string-length tmp-val) 1)
 716         (string-append "Please send bug reports to: " tmp-val "\n")
 717         (delete-file file-name) )
 718     :+][+:
 719
 720 ENDDEF mk-bugs                        :+][+:
 721
 722 DEFINE append-bugs                    :+][+:
 723
 724     (set! tmp-val (get "copyright.eaddr" (get "eaddr")))
 725     (if (> (string-length tmp-val) 1)
 726         (string-append "\n.Pp\nPlease send bug reports to: " tmp-val "\n") )
 727     :+][+:
 728
 729 ENDDEF append-bugs
 730
 731 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 732 .\"  M K - C O P Y R I G H T  (+ licensing)
 733 .\"
 734 .\"  This section is guaranteed to be the last section in the man page
 735 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 736
 737 DEFINE mk-copyright                    \:+]
 738 Copyright (C) [+: copyright.date        :+] [+:
 739   (get "copyright.owner" (get "copyright.author" (get "copyright.eaddr")))
 740   :+] all rights reserved.
 741 [+: CASE (get "copyright.type")         :+][+:
 742     = note  :+][+: (get "copyright.text") :+][+:
 743     == ''   :+]This program has an unspecified license.[+:
 744
 745     *       :+][+:
 746     (string-append "This program is released under the terms of "
 747             (license-name (get "copyright.type")) ".")    :+][+:
 748
 749   ESAC      :+]
 750 [+:
 751 ENDDEF mk-copyright
 752
 753 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 754 .\"  M K - N O T E S
 755 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 756
 757 DEFINE mk-notes                       \:+]
 758 This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
 759 option definitions.
 760 [+:
 761
 762 ENDDEF mk-notes
 763
 764 .\" = = = = = APPEND TO IT:           :+][+:
 765
 766 DEFINE append-notes                   :+]
 767 .Pp
 768 This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
 769 option definitions.[+:
 770
 771 ENDDEF append-notes
 772
 773 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 774 .\"  M K - E N V I R O N M E N T
 775 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 776
 777 DEFINE mk-environment                 :+][+:
 778   INVOKE  append-environment          :+][+:
 779 ENDDEF mk-environment
 780
 781 .\" = = = = = APPEND TO IT:           :+][+:
 782
 783 DEFINE append-environment             :+]
 784 [+:(. environ-text)                   :+][+:
 785 ENDDEF append-environment
 786
 787 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 788 .\"  M K - F I L E S
 789 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 790
 791 DEFINE mk-files                       :+][+:
 792   INVOKE  append-files                :+][+:
 793 ENDDEF mk-files
 794
 795 .\" = = = = = APPEND TO IT:           :+][+:
 796
 797 DEFINE append-files                   :+]
 798 [+:(. home-rc-text)                   :+][+:
 799 ENDDEF append-files
 800
 801 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 802 .\"  E M I T   A L I A S   O P T
 803 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 804
 805 DEFINE emit-alias-opt                   :+]
 806 .It [+:
 807   IF (exist? "value")                   :+][+:
 808     IF (exist? "long-opts")            \:+]
 809  Fl [+:value:+] , Fl \-[+: name         :+][+:
 810     ELSE                               \:+]
 811  Fl [+:value:+][+:
 812     ENDIF  (exist? "long-opts")         :+][+:
 813
 814   ELSE  value does not exist -- named option only  :+][+:
 815
 816     IF (not (exist? "long-opts"))      \:+]
 817  [+: name :+][+:
 818     ELSE                               \:+]
 819  Fl \-[+: (get "name")                   :+][+:
 820     ENDIF                               :+][+:
 821   ENDIF                                 :+]
 822 This is an alias for the \fI--[+: aliases :+]\fR option.[+:
 823   IF (exist? "deprecated")            :+]
 824 .sp
 825 .B
 826 NOTE: THIS OPTION IS DEPRECATED
 827 [+:
 828   ENDIF                               :+][+:
 829 ENDDEF emit-alias-opt
 830
 831 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
 832 .\"  E M I T   F L A G   T E X T
 833 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
 834
 835 DEFINE emit-flag-text                 :+][+:
 836
 837   (if (exist? "enable")
 838       (set! opt-name (string-append (get "enable") "-" (get "name")))
 839       (set! opt-name (get "name")) )
 840   (if (exist? "disable")
 841       (set! dis-name (string-append (get "disable") "-" (get "name")))
 842       (set! dis-name "") )
 843
 844   (set! opt-name (fix-optname opt-name))
 845   (if (> (string-length dis-name) 0)
 846       (set! dis-name (fix-optname dis-name)) )
 847
 848   (if (not (exist? "arg-type"))
 849       (set! opt-arg "")
 850       (set! opt-arg (string-append "Ar "
 851             (fix-optname (if (exist? "arg-name")
 852                 (get "arg-name")
 853                 (string-downcase! (get "arg-type"))  ))
 854             ))
 855   )
 856
 857 :+]
 858 .It [+:
 859   IF (exist? "value")                   :+][+:
 860     IF (exist? "long-opts")             :+][+:
 861
 862           # * * * * * * * * * * * * * * * * * * * *
 863           *
 864           *  The option has a flag value (character) AND
 865           *  the program uses long options
 866           *
 867           \:+]
 868  Fl [+:value:+][+:
 869       IF (not (exist? "arg-type"))      :+] , Fl -[+:
 870       ELSE  :+] [+:(. opt-arg):+] , Fl -[+:
 871       ENDIF :+][+: (. opt-name)         :+] [+:
 872       IF (exist? "arg-type")            :+][+:
 873               ? arg-optional Oo Ns = Ns
 874               :+] [+:  (. opt-arg)      :+] [+:
 875               arg-optional Oc           :+][+:
 876       ENDIF                             :+][+:
 877       IF (exist? "disable") :+] , Fl -[+:(. dis-name):+][+:
 878       ENDIF                             :+][+:
 879
 880     ELSE                                :+][+:
 881
 882           # * * * * * * * * * * * * * * * * * * * *
 883           *
 884           *  The option has a flag value (character) BUT
 885           *  the program does _NOT_ use long options
 886           *
 887           \:+]
 888  Fl [+:value:+] [+:
 889       IF (exist? "arg-type")            :+][+:
 890             arg-optional Oo     :+] [+:(. opt-arg):+] [+:
 891             arg-optional Oc     :+] [+:
 892       ENDIF "                           :+][+:
 893     ENDIF  (exist? "long-opts")         :+][+:
 894
 895
 896   ELSE  value does not exist -- named option only  :+][+:
 897
 898     IF (not (exist? "long-opts"))       :+][+:
 899
 900           # * * * * * * * * * * * * * * * * * * * *
 901           *
 902           *  The option does not have a flag value (character).
 903           *  The program does _NOT_ use long options either.
 904           *  Special magic:  All arguments are named options.
 905           *
 906           \:+]
 907  [+: (. opt-name) :+] [+:
 908       IF (exist? "arg-type")            :+] [+:
 909          ? arg-optional ' Oo = Ns' ' Ns = Ns '
 910          :+] [+:(. opt-arg)              :+] [+:
 911          arg-optional Oc                :+] [+:
 912       ENDIF:+][+:
 913       IF (exist? "disable") :+] , Fl -[+:(. dis-name):+][+:
 914       ENDIF                             :+][+:
 915
 916
 917     ELSE                                :+][+:
 918           # * * * * * * * * * * * * * * * * * * * *
 919           *
 920           *  The option does not have a flag value (character).
 921           *  The program, instead, only accepts long options.
 922           *
 923           \:+]
 924  Fl -[+: (. opt-name) :+] [+:
 925
 926       IF (exist? "arg-type") :+][+:
 927             arg-optional Oo :+] Ns = Ns [+:(. opt-arg):+] [+:
 928             arg-optional Oc :+][+:
 929       ENDIF                             :+][+:
 930
 931       IF (exist? "disable")
 932         :+], " Fl \-[+:(. dis-name):+]"[+:
 933       ENDIF                             :+][+:
 934     ENDIF                               :+][+:
 935   ENDIF                                 :+]
 936 [+: (get "descrip" "") :+].[+:
 937
 938   IF (exist? "min")                     :+]
 939 This option is required to appear.[+:
 940   ENDIF                                 :+][+:
 941
 942   IF (exist? "max") :+]
 943 This option may appear [+:
 944     IF % max (= "%s" "NOLIMIT")
 945       :+]an unlimited number of times[+:ELSE
 946       :+]up to [+: max :+] times[+:
 947     ENDIF:+].[+:
 948   ENDIF:+][+:
 949
 950   IF (exist? "disable")               :+]
 951 The \fI[+:(. dis-name):+]\fP form will [+:
 952     IF (exist? "stack-arg")
 953           :+]clear the list of option arguments[+:
 954     ELSE  :+]disable the option[+:
 955     ENDIF :+].[+:
 956   ENDIF:+][+:
 957
 958   IF (exist? "enabled")               :+]
 959 This option is enabled by default.[+:
 960   ENDIF                               :+][+:
 961
 962   IF (exist? "no-preset")             :+]
 963 This option may not be preset with environment variables
 964 or in initialization (rc) files.[+:
 965   ENDIF                               :+][+:
 966
 967   IF (and (exist? "default") named-mode) :+]
 968 This option is the default option.[+:
 969   ENDIF                               :+][+:
 970
 971   IF (exist? "equivalence")           :+]
 972 This option is a member of the [+:equivalence:+] class of options.[+:
 973   ENDIF                               :+][+:
 974
 975   IF (exist? "flags-must")            :+]
 976 This option must appear in combination with the following options:
 977 [+: FOR flags-must ", " :+][+:flags-must:+][+:ENDFOR:+].[+:
 978   ENDIF                               :+][+:
 979
 980   IF (exist? "flags-cant")            :+]
 981 This option must not appear in combination with any of the following options:
 982 [+: FOR flags-cant ", " :+][+:flags-cant:+][+:ENDFOR:+].[+:
 983   ENDIF                               :+][+:
 984
 985
 986   IF (~* (get "arg-type") "key|set") :+]
 987 This option takes a keyword as its argument[+:
 988
 989     IF (=* (get "arg-type") "set")
 990
 991 :+] list.  Each entry turns on or off
 992 membership bits.  The bits are set by name or numeric value and cleared
 993 by preceding the name or number with an exclamation character ('!').
 994 They can all be cleared with the magic name \fInone\fR and they can all be set
 995 with
 996 .IR all .
 997 A single option will process a list of these values.[+:
 998
 999     ELSE
1000
1001 :+].  The argument sets an enumeration value that can
1002 be tested by comparing them against the option value macro.[+:
1003
1004     ENDIF
1005
1006 :+]
1007 The available keywords are:
1008 .in +4
1009 .nf
1010 .na
1011 [+: (shellf "${CLexe} --indent='' --spread=1 -W50 <<_EOF_\n%s\n_EOF_"
1012             (join "\n" (stack "keyword"))  )   :+]
1013 .fi
1014 or their numeric equivalent.
1015 .in -4[+: (if (exist? "arg-default") "\n.sp" ) :+][+:
1016
1017   ELIF (=* (get "arg-type") "num")    :+]
1018 This option takes an integer number as its argument.[+:
1019
1020     IF  (exist? "arg-range")          :+]
1021 The value of
1022 .[+:(. opt-arg):+]
1023 is constrained to being:
1024 .in +4
1025 .nf
1026 .na[+:FOR arg_range ", or"            :+]
1027 [+: (shellf "
1028 range='%s'
1029
1030 case \"X${range}\" in
1031 X'->'?*  )
1032   echo \"less than or equal to\" `
1033     echo $range | sed 's/->//' ` ;;
1034
1035 X?*'->'  )
1036   echo \"greater than or equal to\" `
1037     echo $range | sed 's/->.*//' ` ;;
1038
1039 X?*'->'?* )
1040   echo \"in the range \" `
1041     echo $range | sed 's/->/ through /' ` ;;
1042
1043 X?* )
1044   echo exactly $range ;;
1045
1046 X* ) echo $range is indeterminate
1047 esac"
1048
1049 (get "arg-range") )
1050 :+][+:
1051       ENDFOR arg-range :+]
1052 .fi
1053 .in -4[+:
1054
1055     ENDIF  arg-range exists           :+][+:
1056
1057   ENDIF  arg-type key/set/num         :+][+:
1058
1059   IF (exist? "arg-default")           :+]
1060 The default
1061 .[+: (. opt-arg) :+]
1062 for this option is:
1063 .ti +4
1064  [+: (join " + " (stack "arg-default" )) :+][+:
1065   ENDIF                               :+]
1066 .sp
1067 [+:
1068  (if (exist? "doc") (string-substitute (get "doc" "") "\n\n" "\n.sp\n")
1069      "This option has not been fully documented." ) :+][+:
1070   IF (exist? "deprecated")            :+]
1071 .sp
1072 .B
1073 NOTE: THIS OPTION IS DEPRECATED
1074 [+:
1075   ENDIF                               :+][+:
1076
1077 ENDDEF emit-flag-text
1078
1079 .\" cmd-doc.tlib ends here \:+]