.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SDFGET 1"
.TH SDFGET 1 "2023-08-02" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
sdfget \- Documentation Extraction Utility
.SH "PURPOSE"
.IX Header "PURPOSE"
\&\fIsdfget\fR extracts documentation embedded in source code.
.SH "USAGE"
.IX Header "USAGE"
.Vb 7
\& usage  : sdfget [\-h[help]] [\-o[out_ext]]
\&         [\-l[log_ext]] [\-O[out_dir]]
\&         [\-f formatting_filename] [\-g[get_rule]]
\&         [\-r[rpt_file]] [\-s scope] [\-i]
\&         [\-v[verbose]] file ...
\&purpose: extract documentation embedded in source code
\&version: 2.000    (SDF 2.001)
.Ve
.PP
The options are:
.PP
.Vb 11
\& Option       Description
\& \-h           display help on options
\& \-o           output file extension
\& \-l           log file extension
\& \-O           output to input file\*(Aqs (or explicit) directory
\& \-f           filename to use when formatting the output
\& \-g           rule to use to get documentation
\& \-r           report file
\& \-s           scope of documentation to be extracted
\& \-i           only output lines not extracted
\& \-v           verbose mode
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \-h option provides help. If it is specified without a parameter, a
brief description of each option is displayed. To display the
attributes for an option, specify the option letter as a parameter.
.PP
By default, generated output goes to standard output. To direct output
to a file per input file, use the \-o option to specify an extension
for output files. If the \-o option is specified without a parameter,
an extension of \fIout\fR is assumed.
.PP
Likewise, error messages go to standard error by default. Use the \-l
option to create a log file per input file. If the \-l option is
specified without a parameter, an extension of \fIlog\fR is assumed.
.PP
By default, generated output and log files are created in the current
directory. Use the \-O option to specify an explicit output directory.
If the \-O option is specified without a parameter, the input file's
directory is used.
.PP
The \-f option can be used to specify a filename to use when formatting
the output. This is useful when the text is coming from the standard
input stream.
.PP
The \fIget-rule\fR nominates the formatting of the embedded documentation
to be extracted. All currently defined get-rules assume the
documentation is in comment blocks in one of the following formats:
.PP
.Vb 3
\& >>section_title1::
\& text of section 1, line 1
\& text of section 1, line ..
\&
\& >>section_title2::
\& text of section 2, line 1
\& text of section 2, line ..
\& >>END::
\&
\& >>section_title3:: text of section 3
.Ve
.PP
The first form is most commonly used. In this format, the text in a
section extends until the end of the current \*(L"comment block\*(R" or the
start of the next section, whichever comes first. The second form
(i.e. explicitly specifying where the section ends) is useful if you
wish to add some normal comments (i.e. non-documentation) which you do
not want extracted. If the text is short, the third form can be used.
Regardless of the format, if a section is found which is already
defined, the text of the section is concatenated onto the existing
text. This permits the documentation for each entity to be specified
immediately above where it is defined in the source code.
.PP
The \-g option specifies the \fIget-rule\fR to use. The available
get-rules differ on the prefix expected at the front of each line as
shown below.
.PP
.Vb 7
\& Rule                              Prefix
\& perl                              #
\& cpp                               //
\& c                                 * or /*
\& fortran                           c (with 5 preceding spaces)
\& eiffel                            \-\-
\& bat                               rem
.Ve
.PP
Within C code, a trailing space is required after the characters
above. For other languages, a trailing space is optional. Within
\&\s-1FORTRAN\s0 code, the \*(L"c\*(R" character must be preceded by exactly 5 spaces.
For other languages, zero or more whitespace characters are permitted
before the characters above.
.PP
For example, embedded documentation within C code looks like:
.PP
.Vb 4
\& /* >>Purpose::
\&  * This library provides a high level interface
\&  * to commonly used network services.
\&  */
.Ve
.PP
If the \-g option is not specified, \fIperl\fR is the default get-rule. If
the \-g option is specified without a parameter, the extension in
lowercase of the filename (or the \fIformatting filename\fR if the text
is coming from standard input) is used to guess the get_rule as shown
below.
.PP
.Vb 6
\& Rule                              Extensions
\& cpp                               cpp, c++, cc, hpp, hpp, h, java, idl
\& c                                 c
\& fortran                           fortran, for, f77, f
\& eiffel                            eiffel, ada
\& bat                               bat, cmd
.Ve
.PP
A report filename can be specified using the \-r option. If the name
doesn't include an extension, sdg is assumed. Reports provide a
mechanism for:
.IP "\(bu" 4
selectively extracting sections, and
.IP "\(bu" 4
rudimentary reformatting (e.g. to \fI\s-1SDF\s0\fR)
.PP
If no report is specified, all sections are output in the following
format:
.PP
.Vb 2
\& section_title1
\& section_text1
\&
\& section_title2
\& section_text2
.Ve
.PP
If \-r is specified on its own, \fIdefault.sdg\fR is assumed. This report
selects the set of sections (within the \fI\s-1SDF\s0\fR documentation
standards) which form the user documentation and formats them into
\&\fI\s-1SDF\s0\fR. Details on the report format are specified below. Reports are
searched for in the current directory, then in the \fIstdlib\fR directory
within \s-1SDF\s0's library directory.
.PP
The \-s option can be used to specify the scope of the documentation to
be extracted. (This is an experimental feature and may change so most
users should avoid using it.)
.PP
The \-i option outputs only those lines which the get-rule did not
match. This option is useful for extracting non-documentation from a
file to give just the code.
.PP
\&\fBNote: \fRThe \-r option is ignored if \-i is specified.
.PP
The \-v option enables verbose mode. This is useful for seeing which
rule is being used for each file.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To extract the user documentation from a \fI\s-1SDF\s0\fR application written in
\&\*(C+ (\fIxyz\fR, say) and save it into \fIxyz.sdf\fR:
.PP
.Vb 1
\&      sdfget \-gcpp \-r \-osdf xyz.cpp
.Ve
.SH "LIMITATIONS AND FUTURE DIRECTIONS"
.IX Header "LIMITATIONS AND FUTURE DIRECTIONS"
It would be nicer if the get-rule was always guessed from the filename
extension but changing the default from perl could break existing
scripts. Therefore, get-rule guessing must be explicitly enabled by
specifging the \-g option without a parameter.