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 119DEFINE build-doc :+][+: 120 121(if (not command-doc) (begin 122 (set! home-rc-files #f) 123 (set! home-rc-text "") 124) ) :+][+: 125 126INVOKE doc-sections :+][+: 127INVOKE ao-sections :+][+: 128INVOKE assemble-sections :+][+: 129 130ENDDEF 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 139DEFINE 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#:+] 148cvt_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:+]' 159cvt_prog=`cd \`dirname "$cvt_prog"\` >/dev/null && pwd 160 `/`basename "$cvt_prog"` 161cd $tmp_dir 162test -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[+: 177IF (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 :+][+: 199ELSE \:+] 200[+:(. egrep-prog):+] -v '^[ ]*$' .doc | $cvt_prog[+: 201ENDIF doc-sub exists :+][+: 202 203(shell (out-pop #t)) :+][+: 204 205ENDDEF 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 215DEFINE doc-sections :+][+: 216 217FOR 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 263ENDFOR doc-section :+][+: 264 265ENDDEF 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 275DEFINE 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 302IF (exist? "copyright") :+][+: 303 INVOKE cond-section sec = "COPYRIGHT" mode = "alt" :+][+: 304ENDIF :+][+: 305 306ENDDEF 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 323DEFINE 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 :+][+: 363ENDDEF cond-section 364 365.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 366.\" M K - D E S C R I P T I O N 367.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 368 369DEFINE 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 384ENDDEF mk-description 385 386.\" = = = = = = = = = = = = = = = = = = 387.\" A P P E N D - D E S C R I P T I O N 388.\" = = = = = = = = = = = = = = = = = = :+][+: 389 390DEFINE append-description :+][+: 391 392IF (= (get "main.main-type") "for-each"):+][+: 393 394 CASE main.handler-type :+][+: 395 ~* ^(name|file)|.*text \:+] 396.Pp 397This program will perform its function for every file named on the command 398line or every file named in a list read from stdin. The arguments or input 399names must be pre\-existing files. The input list may contain comments, 400which[+: 401 402 !E \:+] 403.Pp 404This program will perform its function for every command line argument 405or every non\-comment line in a list read from stdin. 406The 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 415ENDIF - "main" is of "for-each" type :+][+: 416 417ENDDEF append-description 418 419.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 420.\" M K - O P T I O N S 421.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 422 423DEFINE 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 456FOR 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 :+][+: 471ENDFOR 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 486Display 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 501Pass the extended usage information through a pager.[+: 502 503ENDIF no no-libopts 504 505.\" = = = = = = = = = = = = = = = = = 506.\" save and load configuration 507.\" = = = = = = = = = = = = = = = = = :+][+: 508 509IF (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 523Save the option state to \fIcfgfile\fP. The default is the \fIlast\fP 524configuration file listed in the \fBOPTION PRESETS\fP section, below. 525The 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 542Load options from \fIcfgfile\fP. 543The \fIno-load-opts\fP form will disable the loading 544of earlier config/rc/ini files. \fI\-\-no-load-opts\fP is handled early, 545out of order.[+: 546 547ENDIF (exist? "homerc") 548 549.\" = = = = = = = = = = = = = = = = = 550.\" version 551.\" = = = = = = = = = = = = = = = = = :+][+: 552 553IF (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 565Output version of program and exit. The default mode is `v', a simple 566version. The `c' mode will print copyright information and `n' will 567print the full copyright notice.[+: 568ENDIF :+] 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 580ENDDEF mk-options 581 582.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 583.\" M K - O P T I O N - P R E S E T S 584.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 585 586DEFINE mk-option-presets \:+] 587Any option that is not marked as \fInot presettable\fP may be preset 588by 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) :+] 601The environmental presets take precedence (are processed later than) 602the 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' :+] 617The file "\fI[+: (string-append (get "homerc") "/" rc-file) 618:+]\fP" will be used, if present.[+: 619 620 == "" :+][+: 621 622 * :+] 623The \fIhomerc\fP file is "\fI[+:homerc:+]\fP", unless that is a directory. 624In that case, the file "\fI[+: (. rc-file) :+]\fP" 625is searched for within that directory.[+: 626 ESAC :+][+: 627 628 * :+] 629The \fIhomerc\fP files are [+: 630 FOR homerc ", " :+][+: 631 IF (last-for?) :+]and [+: 632 ENDIF :+]"\fI[+: homerc :+]\fP"[+: ENDFOR :+]. 633If any of these are directories, then the file \fI[+: (. rc-file) :+]\fP 634is searched for within those directories.[+: 635 ESAC :+][+: 636 637ENDDEF mk-option-presets 638 639.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 640.\" M K - E X I T - S T A T U S 641.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 642 643DEFINE mk-exit-status \:+] 644One 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 659FOR 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" "")) :+][+: 670ENDFOR exit-desc :+][+: 671(if need-ex-noinput 672 (emit ".It 66 \" (EX_NOINPUT)\" 673A specified configuration file could not be loaded.\n")) 674 675(if need-ex-software 676 (emit ".It 70 \" (EX_SOFTWARE)\" 677libopts had an internal operational error. Please report 678it 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 685ENDDEF mk-exit-status 686 687.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 688.\" M K - A U T H O R S 689.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 690 691DEFINE 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 706ENDDEF mk-authors 707 708.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 709.\" M K - B U G S 710.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 711 712DEFINE 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 720ENDDEF mk-bugs :+][+: 721 722DEFINE 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 729ENDDEF 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 737DEFINE mk-copyright \:+] 738Copyright (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[+: 751ENDDEF mk-copyright 752 753.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 754.\" M K - N O T E S 755.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 756 757DEFINE mk-notes \:+] 758This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP 759option definitions. 760[+: 761 762ENDDEF mk-notes 763 764.\" = = = = = APPEND TO IT: :+][+: 765 766DEFINE append-notes :+] 767.Pp 768This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP 769option definitions.[+: 770 771ENDDEF append-notes 772 773.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 774.\" M K - E N V I R O N M E N T 775.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 776 777DEFINE mk-environment :+][+: 778 INVOKE append-environment :+][+: 779ENDDEF mk-environment 780 781.\" = = = = = APPEND TO IT: :+][+: 782 783DEFINE append-environment :+] 784[+:(. environ-text) :+][+: 785ENDDEF append-environment 786 787.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 788.\" M K - F I L E S 789.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 790 791DEFINE mk-files :+][+: 792 INVOKE append-files :+][+: 793ENDDEF mk-files 794 795.\" = = = = = APPEND TO IT: :+][+: 796 797DEFINE append-files :+] 798[+:(. home-rc-text) :+][+: 799ENDDEF append-files 800 801.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 802.\" E M I T A L I A S O P T 803.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 804 805DEFINE 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 :+] 822This is an alias for the \fI--[+: aliases :+]\fR option.[+: 823 IF (exist? "deprecated") :+] 824.sp 825.B 826NOTE: THIS OPTION IS DEPRECATED 827[+: 828 ENDIF :+][+: 829ENDDEF emit-alias-opt 830 831.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 832.\" E M I T F L A G T E X T 833.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+: 834 835DEFINE 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") :+] 939This option is required to appear.[+: 940 ENDIF :+][+: 941 942 IF (exist? "max") :+] 943This 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") :+] 951The \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") :+] 959This option is enabled by default.[+: 960 ENDIF :+][+: 961 962 IF (exist? "no-preset") :+] 963This option may not be preset with environment variables 964or in initialization (rc) files.[+: 965 ENDIF :+][+: 966 967 IF (and (exist? "default") named-mode) :+] 968This option is the default option.[+: 969 ENDIF :+][+: 970 971 IF (exist? "equivalence") :+] 972This option is a member of the [+:equivalence:+] class of options.[+: 973 ENDIF :+][+: 974 975 IF (exist? "flags-must") :+] 976This option must appear in combination with the following options: 977[+: FOR flags-must ", " :+][+:flags-must:+][+:ENDFOR:+].[+: 978 ENDIF :+][+: 979 980 IF (exist? "flags-cant") :+] 981This 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") :+] 987This option takes a keyword as its argument[+: 988 989 IF (=* (get "arg-type") "set") 990 991:+] list. Each entry turns on or off 992membership bits. The bits are set by name or numeric value and cleared 993by preceding the name or number with an exclamation character ('!'). 994They can all be cleared with the magic name \fInone\fR and they can all be set 995with 996.IR all . 997A single option will process a list of these values.[+: 998 999 ELSE 1000 1001:+]. The argument sets an enumeration value that can 1002be tested by comparing them against the option value macro.[+: 1003 1004 ENDIF 1005 1006:+] 1007The 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 1014or their numeric equivalent. 1015.in -4[+: (if (exist? "arg-default") "\n.sp" ) :+][+: 1016 1017 ELIF (=* (get "arg-type") "num") :+] 1018This option takes an integer number as its argument.[+: 1019 1020 IF (exist? "arg-range") :+] 1021The value of 1022.[+:(. opt-arg):+] 1023is constrained to being: 1024.in +4 1025.nf 1026.na[+:FOR arg_range ", or" :+] 1027[+: (shellf " 1028range='%s' 1029 1030case \"X${range}\" in 1031X'->'?* ) 1032 echo \"less than or equal to\" ` 1033 echo $range | sed 's/->//' ` ;; 1034 1035X?*'->' ) 1036 echo \"greater than or equal to\" ` 1037 echo $range | sed 's/->.*//' ` ;; 1038 1039X?*'->'?* ) 1040 echo \"in the range \" ` 1041 echo $range | sed 's/->/ through /' ` ;; 1042 1043X?* ) 1044 echo exactly $range ;; 1045 1046X* ) echo $range is indeterminate 1047esac" 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") :+] 1060The default 1061.[+: (. opt-arg) :+] 1062for 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 1073NOTE: THIS OPTION IS DEPRECATED 1074[+: 1075 ENDIF :+][+: 1076 1077ENDDEF emit-flag-text 1078 1079.\" cmd-doc.tlib ends here \:+] 1080