diff options
Diffstat (limited to 'src/preproc/soelim/soelim.1.man')
| -rw-r--r-- | src/preproc/soelim/soelim.1.man | 456 |
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: |