--- /dev/null
+[+: -*- Mode: nroff -*-
+
+ AutoGen5 template man
+
+## cmd-doc.tlib -- Template for command line man/mdoc pages
+##
+## Time-stamp: "2011-03-04 11:08:00 bkorb"
+##
+## This file is part of AutoOpts, a companion to AutoGen.
+## AutoOpts is free software.
+## AutoOpts is Copyright (c) 1992-2011 by Bruce Korb - all rights reserved
+##
+## AutoOpts is available under any one of two licenses. The license
+## in use must be one of these two and the choice is under the control
+## of the user of the license.
+##
+## The GNU Lesser General Public License, version 3 or later
+## See the files "COPYING.lgplv3" and "COPYING.gplv3"
+##
+## The Modified Berkeley Software Distribution License
+## See the file "COPYING.mbsd"
+##
+## These files have the following md5sums:
+##
+## 43b91e8ca915626ed3818ffb1b71248b COPYING.gplv3
+## 06a1a2e4760c90ea5e1dad8dfaac4d39 COPYING.lgplv3
+## 66a5cedaf62c4b2637025f049f9b826f COPYING.mbsd
+
+# Produce a man page for section 1, 6 or 8 commands. Which is
+# selected via: -DMAN_SECTION=n. "n" may have a suffix, if desired.
+# These sections have default section names that may be overridden
+# with -DSECTIN_NAME=XX, also passed to the autogen invocation.
+#
+:+][+:
+
+(define down-prog-name (string-downcase! (get "prog-name")))
+(define UP-PROG-NAME (get-up-name "prog-name"))
+
+(define tmp-val (getenv "MAN_SECTION"))
+(define man-sect (if (exist? "cmd-section") (get "cmd-section") "1"))
+
+(if (defined? 'tmp-val)
+ (if (string? tmp-val)
+ (set! man-sect tmp-val)))
+
+(define section-name
+ (if (=* man-sect "1") "User Commands"
+ (if (=* man-sect "6") "Games"
+ (if (=* man-sect "8") "System Management"
+ (error
+ "the agman-cmd template only produces section 1, 6 and 8 man pages")
+))))
+(set! tmp-val (getenv "SECTION_NAME"))
+(if (defined? 'tmp-val) (if (string? tmp-val)
+ (set! section-name tmp-val) ))
+
+(define package-text "")
+(define package+version (and (exist? "package") (exist? "version")))
+
+(if (or (exist? "package") (exist? "version")) (begin
+ (set! package-text (string-append
+ (get "package")
+ (if package+version " (" "")
+ (get "version")
+ (if package+version ")" "") ))
+) )
+
+(define name-to-fname (lambda (nm)
+ (string-tr (string-downcase sec-type) " " "-") ))
+
+(make-tmp-dir)
+
+(define home-rc-files (exist? "homerc"))
+(define home-rc-text
+ "\nSee \\fBOPTION PRESETS\\fP for configuration files.")
+
+(define environ-init (exist? "environrc"))
+(define environ-text
+ "\nSee \\fBOPTION PRESETS\\fP for configuration environment variables.")
+
+(emit (head-line))
+(dne ".\\\" ") :+][+:#
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" B U I L D D O C
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE build-doc :+][+:
+
+INVOKE doc-sections :+][+:
+INVOKE ao-sections :+][+:
+
+(out-push-new (string-append tmp-dir "/.assemble")) \:+]
+
+cat_n_rm() {
+ test -f ${tmp_dir}/$1 || return 0
+ grep -E -v '^[ ]*$' ${tmp_dir}/$1
+ rm -f ${tmp_dir}/$1
+}
+for f in synopsis description options option-presets
+do cat_n_rm $f ; done
+test -f ${tmp_dir}/name && rm -f ${tmp_dir}/name
+
+for f in implementation-notes environment files examples exit-status \
+ compatibility notes see-also conforming-to history authors bugs
+do cat_n_rm $f ; done > ${tmp_dir}/.fini
+
+set -- ${tmp_dir}/*
+test -f "$1" && grep -E -v '^[ ]*$' $*
+cat ${tmp_dir}/.fini
+[+: (out-pop)
+ (shell ". ${tmp_dir}/.assemble") :+][+:
+
+ENDDEF build-doc
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" D O C S E C T I O N S
+.\"
+.\" Emit the files for each section that was provided.
+.\"
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE doc-sections :+][+:
+
+FOR doc-section :+][+:
+
+ CASE
+ (define sec-type (string-upcase (get "ds-type")))
+ (define sec-name (name-to-fname sec-type))
+ (out-push-new (string-append tmp-dir "/" sec-name))
+ (define cvt-fn (find-file (string-append
+ (get "ds-format" "man") "2mdoc")))
+ (if (not (defined? 'cvt-fn))
+ (error (sprintf "Cannot locate converter for %s"
+ (get "ds-format" "man"))))
+ sec-type :+][+:
+
+ *==* " " :+]
+.Sh "[+: (. sec-type) :+]"[+:
+ == "" :+][+:
+ * :+]
+.Sh [+: (. sec-type) :+][+:
+ ESAC :+]
+[+:
+ (shell (string-append
+ "fn='" cvt-fn "'\n"
+ "test -f ${fn} || die ${fn} not found from $PWD\n"
+ "${fn} <<\\_EndOfDocSection_ || die ${fn} failed in $PWD\n"
+ (get "ds-text")
+ "\n_EndOfDocSection_"
+ )) :+][+:
+
+ CASE (. sec-type) :+][+:
+ == FILES :+][+:
+ (if home-rc-files (emit home-rc-text))
+ (set! home-rc-files #f) :+][+:
+
+ == ENVIRONMENT :+][+:
+ (if environ-init (emit environ-text))
+ (set! environ-init #f) :+][+:
+ ESAC :+][+:
+
+ (out-pop)
+ :+][+:
+
+ENDFOR doc-section :+][+:
+
+ENDDEF doc-sections
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" A O S E C T I O N S
+.\"
+.\" Emit the files for the sections that these templates augment,
+.\" replace or conditionally replace
+.\"
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE ao-sections :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/synopsis"))
+ (not (access? tmp-val R_OK)) :+][+:
+ (out-push-new tmp-val) :+][+:
+ INVOKE synopsis :+][+:
+ (out-pop) :+][+:
+ENDIF :+][+:
+
+
+
+IF (set! tmp-val (string-append tmp-dir "/description"))
+ (access? tmp-val R_OK) :+][+:
+ (out-push-add tmp-val) :+][+:
+ELSE :+][+:
+ (out-push-new tmp-val) :+][+:
+ INVOKE description :+][+:
+ENDIF :+][+:
+
+IF (= (get "main.main-type") "for-each"):+][+:
+
+ CASE main.handler-type :+][+:
+ ~* ^(name|file)|.*text :+]
+.Pp
+This program will perform its function for every file named on the command
+line or every file named in a list read from stdin. The arguments or input
+names must be pre\-existing files. The input list may contain comments,
+which[+:
+
+ !E :+]
+.Pp
+This program will perform its function for every command line argument
+or every non\-comment line in a list read from stdin.
+The input list comments[+:
+
+ * :+][+:
+ (error "the 'for-each' main has in invalid handler-type.") :+][+:
+ ESAC \:+]
+ are blank lines or lines beginning with a '[+:
+ ?% comment-char "%s" "#" :+]' character.
+[+:
+
+ENDIF - "main" exists :+][+:
+(out-pop) :+][+:
+
+
+INVOKE options :+][+:
+INVOKE implementation-notes :+][+:
+INVOKE environment :+][+:
+INVOKE examples :+][+:
+INVOKE compatibility :+][+:
+INVOKE see-also :+][+:
+INVOKE standards :+][+:
+INVOKE history :+][+:
+INVOKE authors :+][+:
+INVOKE bugs :+][+:
+
+IF (or home-rc-files environ-init) :+][+:
+
+ INVOKE option-presets :+][+:
+
+ENDIF :+][+:
+
+(define sec-fmt "\n.Sh %s%s")
+
+(if environ-init
+ (begin
+ (set! tmp-val (string-append tmp-dir "/environment"))
+ (if (access? tmp-val R_OK)
+ (begin
+ (out-push-add tmp-val)
+ (emit environ-text)
+ )
+ (begin
+ (out-push-new tmp-val)
+ (ag-fprintf 0 sec-fmt "ENVIRONMENT" environ-text)
+ ) )
+ (out-pop)
+) )
+
+(if home-rc-files
+ (begin
+ ;; XXX: Will /files conflict with a FILES stanza?
+ (set! tmp-val (string-append tmp-dir "/files"))
+ (if (access? tmp-val R_OK)
+ (begin
+ (out-push-add tmp-val)
+ (emit home-rc-text)
+ )
+ (begin
+ (out-push-new tmp-val)
+ (ag-fprintf 0 sec-fmt "FILES" home-rc-text)
+ ) )
+ (out-pop)
+) ) :+][+:
+
+ENDDEF ao-sections
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" D E S C R I P T I O N
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE description :+]
+.Sh DESCRIPTION
+[+:
+
+ (if (exist? "prog-man-descrip")
+ (join "\n.Pp\n" (stack "prog-man-descrip"))
+ (if (exist? "detail")
+ (join "\n.Pp\n" (stack "detail"))
+ "There is no description for this command."
+ ) ) :+]
+[+:
+ENDDEF description
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" O P T I O N S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE options
+
+:+][+:
+
+(set! tmp-val (string-append tmp-dir "/options"))
+(out-push-new tmp-val)
+
+(define opt-arg "")
+(define dis-name "")
+(define opt-name "")
+(define optname-from "A-Z_^")
+(define optname-to "a-z--")
+(define cvt-cmd "")
+(define formatted-doc (exist? "option-doc-format"))
+
+(if formatted-doc (begin
+ (out-push-new)
+ (set! cvt-cmd (string-append (get "option-doc-format") "2mdoc"))
+) )
+
+(if (exist? "preserve-case")
+ (begin
+ (set! optname-from "_^")
+ (set! optname-to "--")
+) )
+
+(define fix-optname (lambda (o_nm) (begin
+ (set! o_nm (string-tr o_nm optname-from optname-to))
+ (set! o_nm (string-substitute o_nm "-" "\\-" ))
+ o_nm )))
+
+:+]
+.Sh OPTIONS[+:
+(if (exist? "option-info")
+ (string-append "\n.Pp\n" (get "option-info") "\n") )
+:+]
+.Bl -tag[+:
+
+FOR flag :+][+:
+
+ IF (exist? "documentation") :+]
+.Ss "[+: (string-substitute (get "descrip") "-" "\\-") :+]"[+:
+ ELSE :+][+:
+ INVOKE emit-flag-text :+][+:
+ ENDIF :+][+:
+ENDFOR flag
+
+.\" = = = = = = = = = = = = = = = = =
+.\" help option
+.\" = = = = = = = = = = = = = = = = =
+
+:+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: (get "help-value" "?") :+][+:
+ (if (exist? "long-opts") " , \" \\-\\-help\"") :+][+:
+ ELSE :+][+:
+ (if (exist? "long-opts") "\\-\\-") :+]help[+:
+ ENDIF :+]
+Display usage information and exit.[+:#
+
+.\" = = = = = = = = = = = = = = = = =
+.\" more-help option
+.\" = = = = = = = = = = = = = = = = = :+][+:
+
+ IF (not (exist? "no-libopts")) :+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% more-help-value "%s" "!" :+][+:
+ IF (exist? "long-opts") :+] , " \-\-more-help"[+: ENDIF :+][+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+: ENDIF :+]more-help[+:
+ ENDIF :+]
+Pass the extended usage information through a pager.[+:
+
+ENDIF no no-libopts
+
+.\" = = = = = = = = = = = = = = = = =
+.\" save and load configuration
+.\" = = = = = = = = = = = = = = = = = :+][+:
+
+IF (exist? "homerc") :+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% save-opts-value "%s" ">"
+ :+] " [\fIrcfile\fP][+:
+ IF (exist? "long-opts") :+]," " \-\-save-opts" "[=\fIrcfile\fP][+:
+ ENDIF :+]"[+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+:
+ ENDIF :+]save-opts "[=\fIrcfile\fP]"[+:
+ ENDIF :+]
+Save the option state to \fIrcfile\fP. The default is the \fIlast\fP
+configuration file listed in the \fBOPTION PRESETS\fP section, below.
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% load-opts-value "%s" "<"
+ :+] " \fIrcfile\fP[+:
+ IF (exist? "long-opts")
+ :+]," " \-\-load-opts" "=\fIrcfile\fP," " \-\-no-load-opts[+:
+ ENDIF :+]"[+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+:
+ ENDIF :+]load-opts "=\fIrcfile\fP," " \-\-no-load-opts"[+:
+ ENDIF :+]
+Load options from \fIrcfile\fP.
+The \fIno-load-opts\fP form will disable the loading
+of earlier RC/INI files. \fI\-\-no-load-opts\fP is handled early,
+out of order.[+:
+ENDIF (exist? "homerc")
+
+.\" = = = = = = = = = = = = = = = = =
+.\" version
+.\" = = = = = = = = = = = = = = = = = :+][+:
+
+IF (exist? "version") :+]
+.It [+:
+
+ IF (. use-flags) :+]\-[+: ?% version-value "%s" "v"
+ :+] " [{\fIv|c|n\fP}][+:
+ IF (exist? "long-opts") :+]," " \-\-version" "[=\fI{v|c|n}\fP][+:
+ ENDIF :+]"[+:
+ ELSE :+][+:
+ IF (exist? "long-opts") :+]\-\-[+:
+ ENDIF :+]version "[=\fI{v|c|n}\fP]"[+:
+ ENDIF :+]
+Output version of program and exit. The default mode is `v', a simple
+version. The `c' mode will print copyright information and `n' will
+print the full copyright notice.[+:
+ENDIF :+]
+.El
+[+:
+
+(if formatted-doc
+ (shell (string-append
+ "fn='" (find-file cvt-cmd)
+ "'\ntest -f ${fn} || die '" cvt-cmd " not found'\n"
+ "${fn} <<\\_EndOfMdoc_ || die ${fn} failed in $PWD\n"
+ (out-pop #t)
+ "\n_EndOfMdoc_" )) ) :+][+:
+
+ (out-pop) :+][+:
+
+ENDDEF options
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" O P T I O N P R E S E T S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE option-presets :+][+:
+
+(set! tmp-val (string-append tmp-dir "/option-presets"))
+(out-push-new tmp-val)
+
+:+]
+.Sh "OPTION PRESETS"
+Any option that is not marked as \fInot presettable\fP may be preset
+by loading values from [+:
+ IF (. home-rc-files)
+ :+]configuration ("RC" or ".INI") file(s)[+:
+ IF (. environ-init) :+] and values from
+[+:
+ ENDIF :+][+:
+ ENDIF :+][+:
+ IF (. environ-init) :+]environment variables named:
+.nf
+ \fB[+: (. UP-PROG-NAME) :+]_<option-name>\fP or \fB[+: (. UP-PROG-NAME) :+]\fP
+.fi
+.ad[+:
+ IF (. home-rc-files) :+]
+The environmental presets take precedence (are processed later than)
+the configuration files.[+:
+ ENDIF :+][+:
+ ELSE :+].[+:
+ ENDIF :+][+:
+
+ CASE
+ (define rc-file
+ (get "rcfile" (string-append "." (get "prog-name") "rc")) )
+ (count "homerc") :+][+:
+
+ == "0" :+][+:
+ == "1" :+][+:
+
+ CASE homerc :+][+:
+ ~~ '\.|\$HOME' :+]
+The file "\fI[+: (string-append (get "homerc") "/" rc-file)
+:+]\fP" will be used, if present.[+:
+ * :+]
+The \fIhomerc\fP file is "\fI[+:homerc:+]\fP", unless that is a directory.
+In that case, the file "\fI[+: (. rc-file) :+]\fP"
+is searched for within that directory.[+:
+ ESAC :+][+:
+
+ * :+]
+The \fIhomerc\fP files are [+:
+ FOR homerc ", " :+][+:
+ IF (last-for?) :+]and [+:
+ ENDIF :+]"\fI[+: homerc :+]\fP"[+: ENDFOR :+].
+If any of these are directories, then the file \fI[+: (. rc-file) :+]\fP
+is searched for within those directories.[+:
+ ESAC :+][+:
+
+(out-pop) :+][+:
+
+ENDDEF option-presets
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" I M P L E M E N T A T I O N N O T E S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE implementation-notes :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/implementation-notes"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "IMPLEMENTATION NOTES"
+[+: (out-pop) :+][+:
+ENDIF implementation-notes :+][+:
+
+ENDDEF implementation-notes
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" E N V I R O N M E N T
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE environment :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/environment"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "ENVIRONMENT"
+[+: (out-pop) :+][+:
+ENDIF environment :+][+:
+
+ENDDEF environment
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" E X A M P L E S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE examples :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/examples"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "EXAMPLES"
+[+: (out-pop) :+][+:
+ENDIF examples :+][+:
+
+ENDDEF examples
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" E X I T S T A T U S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE exit-status :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/exit-status"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "EXIT STATUS"
+[+: (out-pop) :+][+:
+ENDIF exit-status :+][+:
+
+ENDDEF exit-status
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" C O M P A T I B I L I T Y
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE compatibility :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/compatibility"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "COMPATIBILITY"
+[+: (out-pop) :+][+:
+ENDIF compatibility :+][+:
+
+ENDDEF compatibility
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" S E E A L S O
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE see-also :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/see-also"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "SEE ALSO"
+[+: (out-pop) :+][+:
+ENDIF see-also :+][+:
+
+ENDDEF see-also
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" S T A N D A R D S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE standards :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/standards"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "STANDARDS"
+[+: (out-pop) :+][+:
+ENDIF standards :+][+:
+
+ENDDEF standards
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" H I S T O R Y
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE history :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/history"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "HISTORY"
+[+: (out-pop) :+][+:
+ENDIF history :+][+:
+
+ENDDEF history
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" A U T H O R S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE authors :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/authors"))
+ (out-push-new tmp-val)
+ (set! tmp-val (get "copyright.author" (get "copyright.owner")))
+ (> (string-length tmp-val) 0) :+]
+.Sh AUTHORS
+[+: (. tmp-val) :+][+:
+
+ (set! tmp-val (get "copyright.eaddr" (get "eaddr")))
+ (if (> (string-length tmp-val) 0)
+ (string-append "\n.br\nPlease send bug reports to: " tmp-val) ) :+][+:
+
+ CASE copyright.type :+][+:
+ = gpl :+]
+.Pp
+Released under the GNU General Public License.[+:
+ = lgpl :+]
+.Pp
+Released under the GNU General Public License with Library Extensions.[+:
+ = bsd :+]
+.Pp
+Released under the Free BSD License.[+:
+ * :+][+:
+ IF (exist? "copyright.text")
+ :+]
+.Pp
+.nf
+.na
+[+: copyright.text :+]
+.fi
+.ad[+:
+ ELIF (exist? "copyright.date") :+]
+.Pp
+Released under an unspecified copyright license.[+:
+ ENDIF :+][+:
+ ESAC :+][+:
+ENDIF copyright author/owner :+]
+.Pp
+This manual page was \fIAutoGen\fP-erated from the \fB[+: prog-name :+]\fP
+option definitions.[+:
+
+(out-pop) :+][+:
+
+ENDDEF authors
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" B U G S
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE bugs :+][+:
+
+IF (set! tmp-val (string-append tmp-dir "/bugs"))
+ (out-push-new tmp-val)
+
+:+]
+.Sh "BUGS"
+[+: (out-pop) :+][+:
+ENDIF bugs :+][+:
+
+ENDDEF bugs
+
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
+.\" E M I T F L A G T E X T
+.\" = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = :+][+:
+
+DEFINE emit-flag-text :+][+:
+
+ (if (exist? "enable")
+ (set! opt-name (string-append (get "enable") "-" (get "name")))
+ (set! opt-name (get "name")) )
+ (if (exist? "disable")
+ (set! dis-name (string-append (get "disable") "-" (get "name")))
+ (set! dis-name "") )
+
+ (set! opt-name (fix-optname opt-name))
+ (if (> (string-length dis-name) 0)
+ (set! dis-name (fix-optname dis-name)) )
+
+ (if (not (exist? "arg-type"))
+ (set! opt-arg "")
+ (set! opt-arg (string-append "\\fI"
+ (fix-optname (if (exist? "arg-name")
+ (get "arg-name")
+ (string-downcase! (get "arg-type")) ))
+ "\\fP" ))
+ )
+
+:+]
+.It [+:
+ IF (exist? "value") :+][+:
+ IF (exist? "long-opts") :+][+:
+
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option has a flag value (character) AND
+ * the program uses long options
+ *
+ \:+]
+ \-[+:value:+][+:
+ IF (not (exist? "arg-type")) :+] ", " -\-[+:
+ ELSE :+] " [+:(. opt-arg):+], " \-\-[+:
+ ENDIF :+][+: (. opt-name) :+][+:
+ IF (exist? "arg-type") :+][+:
+ ? arg-optional " [ =" ' "=" '
+ :+][+: (. opt-arg) :+][+:
+ arg-optional " ]" :+][+:
+ ENDIF :+][+:
+ IF (exist? "disable") :+], " \fB\-\-[+:(. dis-name):+]\fP"[+:
+ ENDIF :+][+:
+
+ ELSE :+][+:
+
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option has a flag value (character) BUT
+ * the program does _NOT_ use long options
+ *
+ \:+]
+ \-[+:value:+][+:
+ IF (exist? "arg-type") :+][+:
+ arg-optional "[" :+] "[+:(. opt-arg):+][+:
+ arg-optional '"]"' :+][+:
+ ENDIF " :+][+:
+ ENDIF :+][+:
+
+
+ ELSE value does not exist -- named option only :+][+:
+
+ IF (not (exist? "long-opts")) :+][+:
+
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option does not have a flag value (character).
+ * The program does _NOT_ use long options either.
+ * Special magic: All arguments are named options.
+ *
+ \:+]
+ [+: (. opt-name) :+][+:
+ IF (exist? "arg-type") :+] [+:
+ ? arg-optional " [ =" ' "=" '
+ :+][+:(. opt-arg):+][+:
+ arg-optional "]" :+][+:
+ ENDIF:+][+:
+ IF (exist? "disable") :+], " \fB[+:(. dis-name):+]\fP"[+:
+ ENDIF :+][+:
+
+
+ ELSE :+][+:
+ # * * * * * * * * * * * * * * * * * * * *
+ *
+ * The option does not have a flag value (character).
+ * The program, instead, only accepts long options.
+ *
+ \:+]
+ \-\-[+: (. opt-name) :+][+:
+
+ IF (exist? "arg-type") :+] "[+: #" :+][+:
+ arg-optional "[" :+]=[+:(. opt-arg):+][+:
+ arg-optional "]" :+]"[+: #" :+][+:
+ ENDIF :+][+:
+
+ IF (exist? "disable")
+ :+], " \fB\-\-[+:(. dis-name):+]\fP"[+:
+ ENDIF :+][+:
+ ENDIF :+][+:
+ ENDIF :+]
+[+: (string-substitute (get "descrip") "\\" "\\\\") :+].[+:
+
+ IF (exist? "min") :+]
+This option is required to appear.[+:
+ ENDIF :+][+:
+
+ IF (exist? "max") :+]
+This option may appear [+:
+ IF % max (= "%s" "NOLIMIT")
+ :+]an unlimited number of times[+:ELSE
+ :+]up to [+: max :+] times[+:
+ ENDIF:+].[+:
+ ENDIF:+][+:
+
+ IF (exist? "disable") :+]
+The \fI[+:(. dis-name):+]\fP form will [+:
+ IF (exist? "stack-arg")
+ :+]clear the list of option arguments[+:
+ ELSE :+]disable the option[+:
+ ENDIF :+].[+:
+ ENDIF:+][+:
+
+ IF (exist? "enabled") :+]
+This option is enabled by default.[+:
+ ENDIF :+][+:
+
+ IF (exist? "no-preset") :+]
+This option may not be preset with environment variables
+or in initialization (rc) files.[+:
+ ENDIF :+][+:
+
+ IF (and (exist? "default") named-mode) :+]
+This option is the default option.[+:
+ ENDIF :+][+:
+
+ IF (exist? "equivalence") :+]
+This option is a member of the [+:equivalence:+] class of options.[+:
+ ENDIF :+][+:
+
+ IF (exist? "flags-must") :+]
+This option must appear in combination with the following options:
+[+: FOR flags-must ", " :+][+:flags-must:+][+:ENDFOR:+].[+:
+ ENDIF :+][+:
+
+ IF (exist? "flags-cant") :+]
+This option must not appear in combination with any of the following options:
+[+: FOR flags-cant ", " :+][+:flags-cant:+][+:ENDFOR:+].[+:
+ ENDIF :+][+:
+
+
+ IF (~* (get "arg-type") "key|set") :+]
+This option takes a keyword as its argument[+:
+
+ IF (=* (get "arg-type") "set")
+
+:+] list. Each entry turns on or off
+membership bits. The bits are set by name or numeric value and cleared
+by preceding the name or number with an exclamation character ('!').
+They can all be cleared with the magic name \fInone\fR and they can all be set
+with
+.IR all .
+A single option will process a list of these values.[+:
+
+ ELSE
+
+:+]. The argument sets an enumeration value that can
+be tested by comparing them against the option value macro.[+:
+
+ ENDIF
+
+:+]
+The available keywords are:
+.in +4
+.nf
+.na
+[+: (shellf "${CLexe:-columns} --indent='' --spread=1 -W50 <<_EOF_\n%s\n_EOF_"
+ (join "\n" (stack "keyword")) ) :+]
+.fi
+or their numeric equivalent.
+.in -4[+: (if (exist? "arg-default") "\n.sp" ) :+][+:
+
+ ELIF (=* (get "arg-type") "num") :+]
+This option takes an integer number as its argument.[+:
+
+ IF (exist? "arg-range") :+]
+The value of [+:(. opt-arg):+] is constrained to being:
+.in +4
+.nf
+.na[+:FOR arg_range ", or" :+]
+[+: (shellf "
+range='%s'
+
+case \"X${range}\" in
+X'->'?* )
+ echo \"less than or equal to\" `
+ echo $range | sed 's/->//' ` ;;
+
+X?*'->' )
+ echo \"greater than or equal to\" `
+ echo $range | sed 's/->.*//' ` ;;
+
+X?*'->'?* )
+ echo \"in the range \" `
+ echo $range | sed 's/->/ through /' ` ;;
+
+X?* )
+ echo exactly $range ;;
+
+X* ) echo $range is indeterminate
+esac"
+
+(get "arg-range") )
+:+][+:
+ ENDFOR arg-range :+]
+.fi
+.in -4[+:
+
+ ENDIF arg-range exists :+][+:
+
+ ENDIF arg-type key/set/num :+][+:
+
+ IF (exist? "arg-default") :+]
+The default [+: (. opt-arg) :+] for this option is:
+.ti +4
+ [+: (join " + " (stack "arg-default" )) :+][+:
+ ENDIF :+]
+.sp
+[+:
+ (if (exist? "doc")
+ (string-substitute (get "doc") "\\" "\\\\")
+ "This option has not been fully documented." ) :+][+:
+ IF (exist? "deprecated") :+]
+.sp
+.B
+NOTE: THIS OPTION IS DEPRECATED
+.R[+:
+ ENDIF :+][+:
+
+ENDDEF emit-flag-text
+
+.\" cmd-doc.tlib ends here \:+]
projects / thirdparty / ntp.git / commitdiff
