manpagez: man pages & more
man soelim(1)
Home | html | info | man
soelim(1)                   General Commands Manual                  soelim(1)


Name

       soelim - recursively interpolate source requests in roff or other text
       files


Synopsis

       soelim [-Crt] [-I dir] [input-file ...]

       soelim --help

       soelim -v
       soelim --version


Description

       GNU soelim is a preprocessor for the groff(7) document formatting
       system.  soelim works as a filter to eliminate source requests in
       roff(7) input files; that is, it replaces lines of the form ".so
       included-file" within each text input-file with the contents of
       included-file, recursively.  By default, it writes lf requests as well
       to record the name and line number of each input-file and
       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 (-r) or supplied in TeX comments instead
       (-t).  In the absence of input-file arguments, soelim reads the
       standard input stream.  Output is written to the standard output
       stream.

       If the name of a macro-file contains a backslash, use \\ or \e to embed
       it.  To embed a space, write "\ " (backslash followed by a space).  Any
       other escape sequence in macro-file, including "\[rs]", prevents soelim
       from replacing the source request.

       The dot must be at the beginning of a line and must be followed by "so"
       without intervening spaces or tabs for soelim to handle it.  This
       convention allows source requests to be "protected" from processing by
       soelim, for instance as part of macro definitions or "if" requests.

       There must also be at least one space between "so" and its macro-file
       argument.  The -C option overrides this requirement.

       The foregoing is the limit of soelim's understanding of the roff
       language; it does not, for example, replace the input line
              .if 1 .so otherfile
       with the contents of otherfile.  With its -r option, therefore, soelim
       can be used to process text files in general, to flatten a tree of
       input documents.

       soelim was designed to handle situations where the target of a roff
       source request requires a preprocessor such as eqn(1), pic(1),
       refer(1), or tbl(1).  The usual processing sequence of groff(1) is as
       follows.

                 input        sourced
                 file          file
                   |             |
                   v             v
               preprocessor --> troff --> postprocessor
                                             |
                                             v
                                          output
                                           file

       That is, files sourced with "so" are normally read only by the
       formatter, troff.  soelim is not required for troff to source files.

       If a file to be sourced should also be preprocessed, it must already be
       read before the input file passes through the preprocessor.  soelim,
       normally invoked via groff's -s option, handles this.

                 input
                 file
                   |
                   v
                 soelim --> preprocessor --> troff --> postprocessor
                   ^                                     |
                   |                                     v
                sourced                               output
                 file                                  file


Options

       --help displays a usage message, while -v and --version show version
       information; all exit afterward.

       -C     Recognize an input line starting with .so even if a character
              other than a space or newline follows.

       -I dir Search the directory dir path for input- and included-files.  -I
              may be specified more than once; each dir is searched in the
              given order.  To search the current working directory before
              others, add "-I ." at the desired place; it is otherwise
              searched last.

       -r     Write files "raw"; do not add lf requests.

       -t     Emit TeX comment lines starting with "%" indicating the current
              file and line number, rather than lf requests for the same
              purpose.

       If both -r and -t are given, the last one specified controls.


See also

       groff(1)

groff 1.23.0                      2 July 2023                        soelim(1)

groff 1.23.0 - Generated Sat Dec 23 09:16:09 CST 2023
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.