.TH "yodlverbinsert" "1" "1996\-2021" "yodl_4\&.03\&.03" "Your Own Document Language"

.PP 
.SH "NAME"
yodlverbinsert \- Generate verb\-sections from parts of a file
.PP 
.SH "SYNOPSIS"
\fByodlverbinsert\fP [OPTIONS] \fI[marker] file\fP
.PP 
.SH "DESCRIPTION"

.PP 
\fBVerbinsert\fP is a simple \fBC++\fP support program that is used for generating
\fIverb()\fP\-sections in \fBYodl\fP files using sections of
existing files\&. The files from which sections are included are usually \fBC\fP
or \fBCpp\fP source files, accepting either \fI//\fP or \fI/*\fP\-style comment\&. See
the \fBEXAMPLES\fP section for illustrations\&.
.PP 
\fBVerbinsert\fP offers the possibility to indent both the initial \fIverb\fP\-statement
and the inserted file contents\&. Furthermore, an additional empty line may be
inserted before the first line that is actually inserted\&.
.PP 
Blank lines at the beginning and end of files are ignored\&.
.PP 
.IP o 
\fImarker\fP
.br 
The argument \fImarker\fP must start in \fIfile\fP\(cq\&s first column en must
either start as a standard \fBC\fP or \fBC++\fP comment: \fI//\fP or \fI/*\fP must be
used\&. Following that, the remainder of the argument is used as a label, e\&.g\&.,
\fI//label\fP, \fI/*label*/\fP\&. Except for the first two characters and their
locations, and the last two characters of a \fBC\fP\-style marker, no special
restrictions are imposed upon the label\-names\&. A labeled section ends at the
next \fI//=\fP (for labels starting with \fI//\fP) or at the next \fI/**/\fP
(for labels starting  with \fI/*\fP)\&. Like the markers, the end\-markers must
also start in the first columns of lines\&.
.IP 
Alternatively, pairs of \fI//+label\fP, or \fI/*+label*/\fP can be used\&. For
such markers, copying starts at the first line following the first occurrence
of the label, and ends when the label is encountered again\&.  When these
markers are used any additionally encountered marker\-line is simply ignored,
and not written to the output stream\&.  This allows labeled sections to be
nested\&.
.IP 
.IP o 
\fIfile\fP
.br 
The argument \fIfile\fP must be an existing file\&.

.PP 
\fBVerbinsert\fP writes its selected section to its standard output stream\&.
.PP 
When files contain identical marker sections then the contents of each of
these marker sections is included in the generated \fIverb\fP\-section\&. This
allows the inclusion of non\-consecutive lines of source files in a \fIverb\fP
section\&.
.PP 
.SH "OPTIONS"
The default values of options are listed with each of the options between
square brackets\&. The defaults were chosen so that \fByodlverbinsert\fP performs the behavior
of an earlier version of this program, which was not distributed with \fBYodl\fP\&.
.IP o 
\fB\-a\fP
.br 
Process all lines of \fIfile\fP (except initial and trailing blank
lines)\&. The argument \fImarker\fP must not be specified\&.
.IP o 
\fB\-A\fP
.br 
Same as the \fI\-a\fP option, but ignoring all lines that can be considered 
\fIyodlverbinsert\fP (end) marker\-lines\&. 
.IP o 
\fB\-k\fP
.br 
Keep the newlines after 
.nf 
 and before 
.fi 
\&. These newlines result in extra
empty lines before the first and after the last source code lines\&. Starting
with version 4\&.02\&.00 these lines are removed by default\&.
.IP o 
\fB\-n\fP
.br 
Immediately following the indentation: lines are prefixed by numbers,
occupying 2 columns, followed by a colon and a blank\&.
.IP o 
\fB\-N\fP
.br 
Do not write a newline immediately following \fIverb\fP\-statement\(cq\&s
open\-parenthesis\&. By default it is written, causing an additional line to be
inserted before the first line that\(cq\&s actually inserted from a file\&.
.IP o 
\fB\-s\fP \fInSpaces\fP [0]
.br 
start each line that is written into the \fIverb\fP\-section with
\fInSpaces\fP additional blanks\&.
.IP o 
\fB\-S\fP \fInSpaces\fP [8]
.br 
prefix the \fIverb\fP of the \fIverb\fP\-section by \fInSpaces\fP additional
blanks\&.
.IP o 
\fB\-t\fP \fInTabs\fP [0]
.br 
start each line that is written into the \fIverb\fP\-section with
\fInTabs\fP additional tab characters\&. If both \fI\-s\fP and \fI\-t\fP are specified,
the tabs are inserted first\&.
.IP o 
\fB\-T\fP \fInTabs\fP [0]
.br 
prefix the \fIverb\fP of the \fIverb\fP\-section by \fInTabs\fP additional
tab characters\&. If both \fI\-S\fP and \fI\-T\fP are specified, the tabs are inserted
first\&.

.PP 
.SH "EXAMPLE"

.PP 
Assume the file \fIdemo\fP contains the following text:
.nf 

preceding text

//+nest
//one
one 1

//=

/*two*/

    two

/**/
//+nest

trailing text
    
.fi 

.PP 
Then the following commands write the shown output to the program\(cq\&s
standard output:
.IP o 
\fIyodlverbinsert //one demo\fP
.br 
.nf 
        verb(
one 1
)

.fi 
.IP o 
\fIyodlverbinsert \-N //one demo\fP
.br 
.nf 
        verb(one 1
)

.fi 
.IP o 
\fIyodlverbinsert \-n \-s4 \(cq\&/*two*/\(cq\& demo\fP
.br 
.nf 
        verb(
        1: two
)

.fi 

.IP 
.IP o 
\fIyodlverbinsert \-n //+nest\(cq\& demo\fP
.br 
.nf 
        verb(
 1: one 1
 2:
 3:
 4:
 5:     two
)

.fi 

.PP 
.SH "SEE ALSO"

.PP 
\fByodl\fP(1), 
\fByodlbuiltins\fP(7), 
\fByodlconverters\fP(1), 
\fByodlletter\fP(7), 
\fByodlmacros\fP(7), 
\fByodlmanpage\fP(7),
\fByodlpost\fP(1), 
\fByodlstriproff\fP(1), 
\fByodltables\fP(7)\&.
.PP 
.SH "BUGS"

.PP 
\-
.PP 
.SH "AUTHOR"

.PP 
Frank B\&. Brokken (f\&.b\&.brokken@rug\&.nl),