1 [+: -*- Mode: nroff -*-
5 # cmd-doc.tlib -- Template for command line man/mdoc pages
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
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.
15 # The GNU Lesser General Public License, version 3 or later
16 # See the files "COPYING.lgplv3" and "COPYING.gplv3"
18 # The Modified Berkeley Software Distribution License
19 # See the file "COPYING.mbsd"
21 # These files have the following sha256 sums:
23 # 8584710e9b04216a394078dc156b781d0b47e1729104d666658aecef8ee32e95 COPYING.gplv3
24 # 4379e7444a0e2ce2b12dd6f5a52a27a4d02d39d247901d3285c88cf0d37f477b COPYING.lgplv3
25 # 13aa749a5b0a454917a944ed8fffc530b784f5ead522b1aacaf4ec8aa55a6239 COPYING.mbsd
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.
34 ;;# START-BUILDTREE-ISMS
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'
42 :+][+: # END-BUILDTREE-ISMS
44 (shell "CLexe=`echo ${AGexe} | sed 's@/autogen@/columns@'`
45 test -x \"${CLexe}\" || CLexe=`which columns`")
47 # END-INSTALL-ONLY-CODE :+][+:
49 (define down-prog-name (string-downcase! (get "prog-name")))
50 (define UP-PROG-NAME (get-up-name "prog-name"))
52 (define command-doc #t)
53 (define tmp-val (getenv "MAN_SECTION"))
54 (define man-sect (if (exist? "cmd-section") (get "cmd-section") "1"))
57 (define macro-name "")
59 (define fname-line "")
60 (define use-flags (exist? "flag.value"))
61 (define named-mode (not (or use-flags (exist? "long-opts") )))
63 (if (defined? 'tmp-val)
65 (set! man-sect tmp-val)))
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"
73 "the agman-cmd template only produces section 1, 5, 6 and 8 man pages")
75 (set! tmp-val (getenv "SECTION_NAME"))
76 (if (defined? 'tmp-val) (if (string? tmp-val)
77 (set! section-name tmp-val) ))
79 (define package-text "")
80 (define package+version (and (exist? "package") (exist? "version")))
82 (if (or (exist? "package") (exist? "version")) (begin
83 (set! package-text (string-append
85 (if package+version " (" "")
87 (if package+version ")" "") ))
90 (define name-to-fname (lambda (nm)
91 (string-tr (string-downcase nm) " " "-") ))
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) )))
100 (define home-rc-files (exist? "homerc"))
102 "\nSee \\fBOPTION PRESETS\\fP for configuration files.")
104 (define environ-init (exist? "environrc"))
106 "\nSee \\fBOPTION PRESETS\\fP for configuration environment variables.")
111 .Nm [+: prog-name :+]
112 .Nd [+: prog-title :+]
113 [+: INCLUDE "tpl-config.tlib" :+][+:#
115 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
117 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
119 DEFINE build-doc :+][+:
121 (if (not command-doc) (begin
122 (set! home-rc-files #f)
123 (set! home-rc-text "")
126 INVOKE doc-sections :+][+:
127 INVOKE ao-sections :+][+:
128 INVOKE assemble-sections :+][+:
132 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
133 .\" A S S E M B L E S E C T I O N S
135 .\" Emit the files for each section that was provided, and do conversions
137 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
139 DEFINE assemble-sections :+][+:
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.
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))
155 (if (not (defined? 'tmp-str))
156 (error (string-append "cannot locate " converter)))
159 cvt_prog=`cd \`dirname "$cvt_prog"\` >/dev/null && pwd
160 `/`basename "$cvt_prog"`
162 test -x "$cvt_prog" || die "'$cvt_prog' is not executable"
164 list='synopsis description options option-presets'
165 for f in $list ; do cat $f ; echo ; done
167 list='implementation-notes environment files examples exit-status errors
168 compatibility see-also conforming-to history authors copyright bugs
170 for f in $list ; do cat $f ; echo ; done > .end-doc
172 list=`ls -1 *`' .end-doc'
173 for f in $list ; do cat $f ; echo ; done
177 IF (exist? "doc-sub") :+][+:
178 (out-push-new (string-append tmp-dir "/.cmds")) :+][+:
181 IF (define field-name (get "sub-type" target-form))
182 (~~ target-form field-name) :+][+:
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)))
191 ENDFOR doc-sub :+][+:
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")
200 [+:(. egrep-prog):+] -v '^[ ]*$' .doc | $cvt_prog[+:
201 ENDIF doc-sub exists :+][+:
203 (shell (out-pop #t)) :+][+:
205 ENDDEF assemble-sections
207 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
208 .\" D O C S E C T I O N S
210 .\" Emit the files for each section that was provided.
211 .\" If multiple sections exist, they get glued together with ".Pp"
213 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
215 DEFINE doc-sections :+][+:
217 FOR doc-section :+][+:
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"))))
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") :+][+:
233 (out-push-new sec-file)
236 == "" :+][+: (error "unnamed doc-section") :+][+:
237 *==* " " :+].Sh "[+: (. sec-type) :+]"[+:
238 * :+].Sh [+: (. sec-type) :+][+:
242 (shell (string-append
244 "test -f ${fn} || die ${fn} not found from $PWD\n"
245 "${fn} <<\\_EndOfDocSection_ || die ${fn} failed in $PWD\n"
247 "\n_EndOfDocSection_"
250 CASE (emit "\n") sec-type :+][+:
252 (if home-rc-files (emit home-rc-text))
253 (set! home-rc-files #f) :+][+:
255 == ENVIRONMENT :+][+:
256 (if environ-init (emit environ-text))
257 (set! environ-init #f) :+][+:
263 ENDFOR doc-section :+][+:
267 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
268 .\" A O S E C T I O N S
270 .\" Emit the files for the sections that these templates augment,
271 .\" replace or conditionally replace
273 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
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" :+][+:
280 IF (or home-rc-files environ-init) :+][+:
281 INVOKE cond-section sec = "OPTION PRESETS" mode = "replace" :+][+:
283 IF (. home-rc-files) :+][+:
284 INVOKE cond-section sec = "FILES" mode = "append" :+][+:
287 IF (. environ-init) :+][+:
288 INVOKE cond-section sec = "ENVIRONMENT" mode = "append" :+][+:
292 ELSE section 5, not command :+][+:
293 INVOKE cond-section sec = "FILES" mode = "append" :+][+:
294 ENDIF section 5/not :+][+:
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" :+][+:
302 IF (exist? "copyright") :+][+:
303 INVOKE cond-section sec = "COPYRIGHT" mode = "alt" :+][+:
308 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
309 .\" C O N D I T I O N A L S E C T I O N
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:
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
321 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
323 DEFINE cond-section :+][+:
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))
332 (not (access? file-name R_OK)) :+][+:
334 INVOKE (sect-line-fname) :+][+:
336 ELSE file exists :+][+:
338 CASE (get "mode") :+][+:
341 INVOKE (sect-line-fname) :+][+:
344 (out-push-add file-name) :+][+:
345 INVOKE (string-append "append-" macro-name) :+][+:
348 (set! fname-line (shellf
349 "sed '1s/.Sh .*/.Pp/' %1$s ; rm -f %1$s" file-name)) :+][+:
350 INVOKE (sect-line-fname) :+][+:
353 (out-push-new) :+][+:
356 (error (sprintf "invalid section type: %s" (get "mode")))
361 ENDIF file existence/non-existence :+][+:
362 (out-pop) :+][+: # All paths open out :+][+:
365 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
366 .\" M K - D E S C R I P T I O N
367 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
369 DEFINE mk-description :+][+:
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."
379 (shell "sed 's/^$/.sp/' <<\\_EODesc_\n" (out-pop #t) "\n_EODesc_")
382 INVOKE append-description :+][+:
384 ENDDEF mk-description
386 .\" = = = = = = = = = = = = = = = = = =
387 .\" A P P E N D - D E S C R I P T I O N
388 .\" = = = = = = = = = = = = = = = = = = :+][+:
390 DEFINE append-description :+][+:
392 IF (= (get "main.main-type") "for-each"):+][+:
394 CASE main.handler-type :+][+:
395 ~* ^(name|file)|.*text \:+]
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,
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[+:
409 (error "the 'for-each' main has in invalid handler-type.") :+][+:
411 are blank lines or lines beginning with a '[+:
412 ?% comment-char "%s" "#" :+]' character.
415 ENDIF - "main" is of "for-each" type :+][+:
417 ENDDEF append-description
419 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
420 .\" M K - O P T I O N S
421 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
430 (define optname-from "A-Z_^")
431 (define optname-to "a-z--")
433 (define formatted-doc (exist? "option-format"))
435 (if formatted-doc (begin
437 (set! cvt-cmd (string-append (get "option-format") "2mdoc"))
440 (if (exist? "preserve-case")
442 (set! optname-from "_^")
443 (set! optname-to "--")
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 "-" "\\-" ))
451 (if (exist? "option-info")
452 (string-append ".Pp\n" (get "option-info") "\n") )
457 IF (not (exist? "documentation")) :+][+:
458 IF (exist? "aliases") :+][+:
459 INVOKE emit-alias-opt :+][+:
461 INVOKE emit-flag-text :+][+:
465 .Ss "[+: (get "descrip" "") :+]"[+:
466 (set! tmp-str (get "documentation" ""))
467 (if (> (string-length tmp-str) 3) (string-append
468 "\n" tmp-str "\n" )) :+][+:
473 .\" = = = = = = = = = = = = = = = = =
475 .\" = = = = = = = = = = = = = = = = =
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" )
486 Display usage information and exit.[+:#
488 .\" = = = = = = = = = = = = = = = = =
490 .\" = = = = = = = = = = = = = = = = = :+][+:
492 IF (not (exist? "no-libopts")) :+]
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" )
501 Pass the extended usage information through a pager.[+:
505 .\" = = = = = = = = = = = = = = = = =
506 .\" save and load configuration
507 .\" = = = = = = = = = = = = = = = = = :+][+:
509 IF (exist? "homerc") :+]
512 IF (not (exist? "disable-save")) :+][+:
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" )
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.
527 ENDIF saving not disabled :+][+:
529 (define tmp-val (get "load-opts-value" "<"))
530 (define tmp-str (if (exist? "long-opts") "Fl -" ""))
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" )
538 (string-append tmp-str "load-opts Ns = Ns Ar cfgfile , "
539 tmp-str "no-load-opts" )
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,
547 ENDIF (exist? "homerc")
549 .\" = = = = = = = = = = = = = = = = =
551 .\" = = = = = = = = = = = = = = = = = :+][+:
553 IF (exist? "version") :+]
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" )
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.[+:
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"
578 "\n_EndOfMdoc_" )) ) :+][+:
582 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
583 .\" M K - O P T I O N - P R E S E T S
584 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
586 DEFINE mk-option-presets \:+]
587 Any option that is not marked as \fInot presettable\fP may be preset
588 by loading values from [+:
590 :+]configuration ("RC" or ".INI") file(s)[+:
591 IF (. environ-init) :+] and values from
595 IF (. environ-init) :+]environment variables named:
597 \fB[+:(. UP-PROG-NAME):+]_<option-name>\fP or \fB[+:(. UP-PROG-NAME):+]\fP
600 IF (. home-rc-files) :+]
601 The environmental presets take precedence (are processed later than)
602 the configuration files.[+:
609 (get "rcfile" (string-append "." (get "prog-name") "rc")) )
610 (count "homerc") :+][+:
617 The file "\fI[+: (string-append (get "homerc") "/" rc-file)
618 :+]\fP" will be used, if present.[+:
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.[+:
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.[+:
637 ENDDEF mk-option-presets
639 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
640 .\" M K - E X I T - S T A T U S
641 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
643 DEFINE mk-exit-status \:+]
644 One of the following exit values will be returned:
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.") )
651 (define need-ex-noinput (exist? "homerc"))
652 (define need-ex-software #t)
654 (ag-fprintf 0 ".It 1 \" (EXIT_%s)\"\n%s\n"
655 (string->c-name! (string-upcase (get "exit-name[1]" "FAILURE")))
657 "The operation failed or the command syntax was not valid.")) :+][+:
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) ))
665 (set! tmp-str (get (sprintf "exit-name[%d]" (for-index)) "* unnamed *"))
666 (sprintf ".It %d \" (EXIT_%s)\"\n%s\n"
668 (string-upcase (string->c-name! tmp-str))
669 (get "exit-desc" "")) :+][+:
670 ENDFOR exit-desc :+][+:
672 (emit ".It 66 \" (EX_NOINPUT)\"
673 A specified configuration file could not be loaded.\n"))
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"))
680 (if (> (string-length fname-line) 1)
681 (emit fname-line)) :+]
685 ENDDEF mk-exit-status
687 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
688 .\" M K - A U T H O R S
689 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
691 DEFINE mk-authors :+][+:
693 (define remove-authors #t)
696 (if (exist? "copyright.author")
697 (stack-join ",\n" "copyright.author")
698 (stack-join ",\n" "copyright.owner") ))
700 (if (> (string-length tmp-val) 1)
701 (string-append tmp-val "\n")
702 (delete-file file-name))
708 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
710 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
712 DEFINE mk-bugs :+][+:
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) )
720 ENDDEF mk-bugs :+][+:
722 DEFINE append-bugs :+][+:
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") )
731 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
732 .\" M K - C O P Y R I G H T (+ licensing)
734 .\" This section is guaranteed to be the last section in the man page
735 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
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.[+:
746 (string-append "This program is released under the terms of "
747 (license-name (get "copyright.type")) ".") :+][+:
753 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
755 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
758 This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
764 .\" = = = = = APPEND TO IT: :+][+:
766 DEFINE append-notes :+]
768 This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
769 option definitions.[+:
773 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
774 .\" M K - E N V I R O N M E N T
775 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
777 DEFINE mk-environment :+][+:
778 INVOKE append-environment :+][+:
779 ENDDEF mk-environment
781 .\" = = = = = APPEND TO IT: :+][+:
783 DEFINE append-environment :+]
784 [+:(. environ-text) :+][+:
785 ENDDEF append-environment
787 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
789 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
791 DEFINE mk-files :+][+:
792 INVOKE append-files :+][+:
795 .\" = = = = = APPEND TO IT: :+][+:
797 DEFINE append-files :+]
798 [+:(. home-rc-text) :+][+:
801 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
802 .\" E M I T A L I A S O P T
803 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
805 DEFINE emit-alias-opt :+]
807 IF (exist? "value") :+][+:
808 IF (exist? "long-opts") \:+]
809 Fl [+:value:+] , Fl \-[+: name :+][+:
812 ENDIF (exist? "long-opts") :+][+:
814 ELSE value does not exist -- named option only :+][+:
816 IF (not (exist? "long-opts")) \:+]
819 Fl \-[+: (get "name") :+][+:
822 This is an alias for the \fI--[+: aliases :+]\fR option.[+:
823 IF (exist? "deprecated") :+]
826 NOTE: THIS OPTION IS DEPRECATED
829 ENDDEF emit-alias-opt
831 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
832 .\" E M I T F L A G T E X T
833 .\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
835 DEFINE emit-flag-text :+][+:
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")))
844 (set! opt-name (fix-optname opt-name))
845 (if (> (string-length dis-name) 0)
846 (set! dis-name (fix-optname dis-name)) )
848 (if (not (exist? "arg-type"))
850 (set! opt-arg (string-append "Ar "
851 (fix-optname (if (exist? "arg-name")
853 (string-downcase! (get "arg-type")) ))
859 IF (exist? "value") :+][+:
860 IF (exist? "long-opts") :+][+:
862 # * * * * * * * * * * * * * * * * * * * *
864 * The option has a flag value (character) AND
865 * the program uses long options
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 :+][+:
877 IF (exist? "disable") :+] , Fl -[+:(. dis-name):+][+:
882 # * * * * * * * * * * * * * * * * * * * *
884 * The option has a flag value (character) BUT
885 * the program does _NOT_ use long options
889 IF (exist? "arg-type") :+][+:
890 arg-optional Oo :+] [+:(. opt-arg):+] [+:
891 arg-optional Oc :+] [+:
893 ENDIF (exist? "long-opts") :+][+:
896 ELSE value does not exist -- named option only :+][+:
898 IF (not (exist? "long-opts")) :+][+:
900 # * * * * * * * * * * * * * * * * * * * *
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.
907 [+: (. opt-name) :+] [+:
908 IF (exist? "arg-type") :+] [+:
909 ? arg-optional ' Oo = Ns' ' Ns = Ns '
910 :+] [+:(. opt-arg) :+] [+:
911 arg-optional Oc :+] [+:
913 IF (exist? "disable") :+] , Fl -[+:(. dis-name):+][+:
918 # * * * * * * * * * * * * * * * * * * * *
920 * The option does not have a flag value (character).
921 * The program, instead, only accepts long options.
924 Fl -[+: (. opt-name) :+] [+:
926 IF (exist? "arg-type") :+][+:
927 arg-optional Oo :+] Ns = Ns [+:(. opt-arg):+] [+:
928 arg-optional Oc :+][+:
931 IF (exist? "disable")
932 :+], " Fl \-[+:(. dis-name):+]"[+:
936 [+: (get "descrip" "") :+].[+:
938 IF (exist? "min") :+]
939 This option is required to appear.[+:
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[+:
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[+:
958 IF (exist? "enabled") :+]
959 This option is enabled by default.[+:
962 IF (exist? "no-preset") :+]
963 This option may not be preset with environment variables
964 or in initialization (rc) files.[+:
967 IF (and (exist? "default") named-mode) :+]
968 This option is the default option.[+:
971 IF (exist? "equivalence") :+]
972 This option is a member of the [+:equivalence:+] class of options.[+:
975 IF (exist? "flags-must") :+]
976 This option must appear in combination with the following options:
977 [+: FOR flags-must ", " :+][+:flags-must:+][+:ENDFOR:+].[+:
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:+].[+:
986 IF (~* (get "arg-type") "key|set") :+]
987 This option takes a keyword as its argument[+:
989 IF (=* (get "arg-type") "set")
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
997 A single option will process a list of these values.[+:
1001 :+]. The argument sets an enumeration value that can
1002 be tested by comparing them against the option value macro.[+:
1007 The available keywords are:
1011 [+: (shellf "${CLexe} --indent='' --spread=1 -W50 <<_EOF_\n%s\n_EOF_"
1012 (join "\n" (stack "keyword")) ) :+]
1014 or their numeric equivalent.
1015 .in -4[+: (if (exist? "arg-default") "\n.sp" ) :+][+:
1017 ELIF (=* (get "arg-type") "num") :+]
1018 This option takes an integer number as its argument.[+:
1020 IF (exist? "arg-range") :+]
1023 is constrained to being:
1026 .na[+:FOR arg_range ", or" :+]
1030 case \"X${range}\" in
1032 echo \"less than or equal to\" `
1033 echo $range | sed 's/->//' ` ;;
1036 echo \"greater than or equal to\" `
1037 echo $range | sed 's/->.*//' ` ;;
1040 echo \"in the range \" `
1041 echo $range | sed 's/->/ through /' ` ;;
1044 echo exactly $range ;;
1046 X* ) echo $range is indeterminate
1051 ENDFOR arg-range :+]
1055 ENDIF arg-range exists :+][+:
1057 ENDIF arg-type key/set/num :+][+:
1059 IF (exist? "arg-default") :+]
1061 .[+: (. opt-arg) :+]
1064 [+: (join " + " (stack "arg-default" )) :+][+:
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") :+]
1073 NOTE: THIS OPTION IS DEPRECATED
1077 ENDDEF emit-flag-text
1079 .\" cmd-doc.tlib ends here \:+]