mdoc-synopsis.tlib revision 290001 
1[+: autogen5 template man :+][+: 
2DEFINE mk-synopsis                          :+][+:
3  (out-push-new file-name)                 \:+]
4.Sh SYNOPSIS
5.Nm[+:
6
7  IF (. use-flags)                          :+][+:
8    IF (exist? "long-opts")                 :+]
9.\" Mixture of short (flag) options and long options
10.Op Fl flags
11.Op Fl flag Op Ar value
12.Op Fl \-option-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
13[+: ELSE no long options:                   :+]
14.Op Fl flags
15.Op Fl flag Op Ar value
16[+: ENDIF
17                                            :+][+:
18  ELIF (exist? "long-opts")
19                                            :+]
20.Op Fl \-option-name
21.Op Fl \-option-name Ar value
22[+:
23
24  ELIF  (not (exist? "argument"))           :+]
25.Op Ar option\-name Ar value
26.Pp
27All arguments are named options.
28[+:
29  ENDIF                                     :+][+:
30
31  IF (exist? "argument")                    :+][+:
32    argument                                :+][+:
33
34    IF (exist? "reorder-args")              :+]
35.Pp
36Operands and options may be intermixed.  They will be reordered.
37[+: ENDIF                                   :+][+:
38
39  ELIF (or (exist? "long-opts") use-flags)
40
41:+]
42.Pp
43All arguments must be options.
44[+:
45
46  ENDIF                                     :+][+:
47
48  IF (exist? "main")                        :+][+:
49  CASE main.main-type                       :+][+:
50  == shell-process                          :+]
51.Pp
52This program will emit text that is expected to be evaluated by
53a Bourne-compatible shell, thus digesting the options for the script.[+:
54
55  == shell-parser                           :+]
56.Pp
57This program is designed to produce output suitable for inclusion
58into a shell script that will parse the options described.[+:
59
60  == for-each                               :+]
61.Pp
62The operands that this program operates on may be specified either
63on the command line or read from standard input, one per line.
64In that input, leading and trailing white space is stripped,
65blank lines are ignored[+:
66
67    IF (define comment-char (get "comment-char" "#"))
68       (> (string-length comment-char) 1)  \:+]
69 and lines beginning with the character
70.I [+: (substring comment-char 1 0):+]
71are treated as comments[+:
72    ENDIF :+].[+:
73
74    IF (exist? "interleaved")               :+]
75Options may be interleaved with operands both on the command
76line and when operands are read from standard input.[+:
77    ENDIF  interleaved
78
79:+]
80Standard input may not be a terminal.[+:
81
82  ESAC  main-type                           :+][+:
83  ENDIF  main exists                        :+]
84.Pp
85[+:
86
87FOR explain   "\n.Pp\n"                     :+][+:
88  (get "explain" "")                        :+][+:
89ENDFOR                                      :+][+:
90
91(out-pop)                                   :+][+:
92ENDDEF mk-synopsis                          :+]
93