Adding upstream version 1.23.0.upstream/1.23.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 456 insertions, 0 deletions

diff --git a/src/preproc/soelim/soelim.1.man b/src/preproc/soelim/soelim.1.man
new file mode 100644
index 0000000..4a1c042
--- /dev/null
+++ b/src/preproc/soelim/soelim.1.man
@@ -0,0 +1,456 @@
+'\" p
+.TH @g@soelim @MAN1EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+@g@soelim \- recursively interpolate source requests in
+.I roff
+or other text files
+.
+.
+.\" ====================================================================
+.\" Legal Terms
+.\" ====================================================================
+.\"
+.\" Copyright (C) 1989-2020 Free Software Foundation, Inc.
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
+.\" this manual under the conditions for verbatim copying, provided that
+.\" the entire resulting derived work is distributed under the terms of
+.\" a permission notice identical to this one.
+.\"
+.\" Permission is granted to copy and distribute translations of this
+.\" manual into another language, under the above conditions for
+.\" modified versions, except that this permission notice may be
+.\" included in translations approved by the Free Software Foundation
+.\" instead of in the original English.
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_soelim_1_man_C \n[.cp]
+.cp 0
+.
+.\" Define fallback for groff 1.23's MR macro if the system lacks it.
+.nr do-fallback 0
+.if !\n(.f           .nr do-fallback 1 \" mandoc
+.if  \n(.g .if !d MR .nr do-fallback 1 \" older groff
+.if !\n(.g           .nr do-fallback 1 \" non-groff *roff
+.if \n[do-fallback]  \{\
+.  de MR
+.    ie \\n(.$=1 \
+.      I \%\\$1
+.    el \
+.      IR \%\\$1 (\\$2)\\$3
+.  .
+.\}
+.rr do-fallback
+.\" Man pages are seldom preprocessed with pic(1).
+.mso pic.tmac
+.
+.
+.\" ====================================================================
+.\" Definitions
+.\" ====================================================================
+.
+.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
+.el   .ds tx TeX
+.
+.
+.\" ====================================================================
+.SH Synopsis
+.\" ====================================================================
+.
+.SY @g@soelim
+.RB [ \-Crt ]
+.RB [ \-I
+.IR dir ]
+.RI [ input-file\~ .\|.\|.]
+.YS
+.
+.
+.SY @g@soelim
+.B \-\-help
+.YS
+.
+.
+.SY @g@soelim
+.B \-v
+.
+.SY @g@soelim
+.B \-\-version
+.YS
+.
+.
+.\" ====================================================================
+.SH Description
+.\" ====================================================================
+.
+GNU
+.I soelim \" GNU
+is a preprocessor for the
+.MR groff @MAN7EXT@
+document formatting system.
+.
+.I @g@soelim
+works as a filter to eliminate source requests in
+.MR roff @MAN7EXT@
+input files;
+that is,
+it replaces lines of the form
+.RB \[lq] .so
+.IR included-file \[rq]
+within each text
+.I input-file
+with the contents of
+.IR included-file ,
+recursively.
+.
+By default,
+it writes
+.B lf
+requests as well to record the name and line number of each
+.I input-file
+and
+.IR included-file ,
+so that any diagnostics produced by later processing can be accurately
+traced to the original input.
+.
+Options allow this information to be suppressed
+.RB ( \-r )
+or supplied in \*[tx] comments instead
+.RB ( \-t ).
+.
+In the absence of
+.I input-file
+arguments,
+.I @g@soelim
+reads the standard input stream.
+.
+Output is written to the standard output stream.
+.
+.
+.PP
+If the name of a
+.I macro-file
+contains a backslash,
+use
+.B \[rs]\[rs]
+or
+.B \[rs]e
+to embed it.
+.
+To embed a space,
+write
+.RB \[lq] \[rs]\~ \[rq]
+(backslash followed by a space).
+.
+Any other escape sequence in
+.IR macro-file ,
+including
+.RB \[lq] \[rs][rs] \[rq],
+prevents
+.I @g@soelim
+from replacing the source request.
+.
+.
+.PP
+The dot must be at the beginning of a line and must be followed by
+.RB \[lq] so \[rq]
+without intervening spaces or tabs for
+.I @g@soelim
+to handle it.
+.
+This convention allows source requests to be \[lq]protected\[rq] from
+processing by
+.IR @g@soelim ,
+for instance as part of macro definitions or
+.RB \[lq] if \[rq]
+requests.
+.
+.
+.PP
+There must also be at least one space between
+.RB \[lq] so \[rq]
+and its
+.I macro-file
+argument.
+.
+The
+.B \-C
+option overrides this requirement.
+.
+.
+.PP
+The foregoing is the limit of
+.IR @g@soelim 's
+understanding of the
+.I roff
+language;
+it does not,
+for example,
+replace the input line
+.
+.RS
+.EX
+\&.if 1 .so otherfile
+.EE
+.RE
+.
+with the contents of
+.IR otherfile .
+.
+With its
+.B \-r
+option,
+therefore,
+.I @g@soelim
+can be used to process text files in general,
+to flatten a tree of input documents.
+.
+.
+.PP
+.I soelim \" generic
+was designed to handle situations where the target of a
+.I roff \" generic
+source request requires a preprocessor such as
+.MR @g@eqn @MAN1EXT@ ,
+.MR @g@pic @MAN1EXT@ ,
+.MR @g@refer @MAN1EXT@ ,
+or
+.MR @g@tbl @MAN1EXT@ .
+.
+The usual processing sequence of
+.MR groff @MAN1EXT@
+is as follows.
+.
+.\" Does this groff installation use a command prefix?  In installed
+.\" pages, this comparison will not look like it needs to be dynamically
+.\" decided.
+.\"
+.\" This is done so that the box sizes (in the pic(1) diagram) and arrow
+.\" alignments (in the text alternative) can remain fixed.
+.if !'@g@'\%' \{\
+In the diagrams below,
+the traditional names for
+.I soelim
+and
+.I troff
+are used;
+on this system,
+the GNU versions are installed as
+.I @g@soelim
+and
+.IR @g@troff .
+.\}
+.
+.
+.PP
+.ie t \{\
+.PS
+.ps 10
+.vs 12
+box invisible width 0.5 height 0.4 "input" "file";
+move to last box .bottom;
+down;
+arrow 0.3;
+box invisible width 0.8 height 0.2 "preprocessor";
+move to last box .right
+right;
+arrow 0.3;
+A: box invisible width 0.35 height 0.2 "troff";
+move to last box .top;
+up;
+move 0.3;
+box invisible width 0.6 height 0.4 "sourced" "file";
+line <- up 0.3 from A.top;
+move to A.right;
+right;
+arrow 0.3;
+box invisible width 0.85 height 0.2 "postprocessor";
+move to last box .bottom;
+down;
+arrow 0.3;
+box invisible width 0.5 height 0.4 "output" "file"
+.ps
+.vs
+.PE
+.\}
+.el \{\
+.EX
+          input        sourced
+          file          file
+            \[bv]             \[bv]
+            \[da]             \[da]
+        preprocessor \[an]\[->] troff \[an]\[->] postprocessor
+                                      \[bv]
+                                      \[da]
+                                   output
+                                    file
+.EE
+.\}
+.PP
+That is,
+files sourced with
+.RB \[lq] so \[rq]
+are normally read
+.I only
+by the formatter,
+.IR @g@troff .
+.
+.I @g@soelim
+is
+.I not
+required for
+.I @g@troff
+to source files.
+.
+.
+.PP
+If a file to be sourced should also be preprocessed,
+it must already be read
+.I before
+the input file passes through the preprocessor.
+.
+.IR @g@soelim ,
+normally invoked via
+.IR groff 's
+.B \-s
+option,
+handles this.
+.
+.
+.PP
+.ie t \{\
+.PS
+.ps 10
+.vs 12
+box invisible width 0.5 height 0.4 "input" "file";
+move to last box .bottom;
+down;
+arrow 0.3;
+A: box invisible width 0.5 height 0.2 "soelim";
+line <- 0.3;
+box invisible width 0.5 height 0.4 "sourced" "file";
+move to A.right;
+right;
+arrow 0.3;
+box invisible width 0.8 height 0.2 "preprocessor";
+arrow 0.3;
+box invisible width 0.35 height 0.2 "troff";
+arrow 0.3
+box invisible width 0.85 height 0.2 "postprocessor";
+move to last box .bottom;
+down;
+arrow 0.3;
+box invisible width 0.5 height 0.4 "output" "file"
+.ps
+.vs
+.PE
+.\}
+.el \{\
+.EX
+          input
+          file
+            \[bv]
+            \[da]
+          soelim \[an]\[->] preprocessor \[an]\[->] troff \[an]\[->] \
+postprocessor
+            \[ua]                                     \[bv]
+            \[bv]                                     \[da]
+         sourced                               output
+          file                                  file
+.EE
+.\}
+.
+.
+.\" ====================================================================
+.SH Options
+.\" ====================================================================
+.
+.B \-\-help
+displays a usage message,
+while
+.B \-v
+and
+.B \-\-version
+show version information;
+all exit afterward.
+.
+.
+.TP
+.B \-C
+Recognize an input line starting with
+.B .so
+even if a character other than a space or newline follows.
+.
+.TP
+.BI \-I\~ dir
+Search the directory
+.I dir
+path for
+.I input-
+and
+.I included-files.
+.
+.B \-I
+may be specified more than once;
+each
+.I dir
+is searched in the given order.
+.
+To search the current working directory before others,
+add
+.RB \[lq] "\-I .\&" \[rq]
+at the desired place;
+it is otherwise searched last.
+.
+.
+.TP
+.B \-r
+Write files \[lq]raw\[rq];
+do not add
+.B lf
+requests.
+.
+.
+.TP
+.B \-t
+Emit \*[tx] comment lines starting with
+.RB \[lq] % \[rq]
+indicating the current file and line number,
+rather than
+.B lf
+requests for the same purpose.
+.
+.
+.PP
+If both
+.B \-r
+and
+.B \-t
+are given,
+the last one specified controls.
+.
+.
+.\" ====================================================================
+.SH "See also"
+.\" ====================================================================
+.
+.MR groff @MAN1EXT@
+.
+.
+.\" Clean up.
+.rm tx
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_soelim_1_man_C]
+.do rr *groff_soelim_1_man_C
+.
+.
+.\" Local Variables:
+.\" fill-column: 72
+.\" mode: nroff
+.\" End:
+.\" vim: set filetype=groff textwidth=72: