"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tcllib/apps/tcldocstrip.man" (13 Nov 2019, 6300 Bytes) of package /linux/misc/ds9.8.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 [comment {-*- tcl -*- doctools manpage}]
    2 [manpage_begin tcldocstrip n 1.0]
    3 [see_also docstrip]
    4 [keywords .dtx]
    5 [keywords conversion]
    6 [keywords docstrip]
    7 [keywords documentation]
    8 [keywords LaTeX]
    9 [keywords {literate programming}]
   10 [keywords markup]
   11 [keywords source]
   12 [copyright {2005 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
   13 [titledesc {Tcl-based Docstrip Processor}]
   14 [moddesc   {Textprocessing toolbox}]
   15 [category  {Documentation tools}]
   16 [description]
   17 [para]
   18 
   19 The application described by this document, [syscmd tcldocstrip], is a
   20 relative of [syscmd docstrip], a simple literate programming tool for
   21 LaTeX.
   22 
   23 [para]
   24 
   25 [syscmd tcldocstrip] is based upon the package [package docstrip].
   26 
   27 [subsection {USE CASES}]
   28 
   29 [syscmd tcldocstrip] was written with the following three use cases in
   30 mind.
   31 
   32 [para]
   33 [list_begin enumerated]
   34 [enum]
   35 Conversion of a single input file according to the listed guards into
   36 the stripped output. This handles the most simple case of a set of
   37 guards specifying a single document found in a single input file.
   38 
   39 [enum]
   40 Stitching, or the assembly of an output from several sets of guards,
   41 in a specific order, and possibly from different files. This is the
   42 second common case. One document spread over several inputs, and/or
   43 spread over different guard sets.
   44 
   45 [enum]
   46 Extraction and listing of all the unique guard expressions and guards
   47 used within a document to help a person which did not author the
   48 document in question in familiarizing itself with it.
   49 
   50 [list_end]
   51 
   52 [subsection {COMMAND LINE}]
   53 
   54 [list_begin definitions]
   55 
   56 [call [cmd tcldocstrip] [arg output] [opt options] [arg input] [opt [arg guards]]]
   57 
   58 This is the form for use case [lb]1[rb]. It converts the [arg input]
   59 file according to the specified [arg guards] and options. The result
   60 is written to the named [arg output] file.
   61 
   62 Usage of the string [const "-"] as the name of the output signals that
   63 the result should be written to [const stdout]. The guards are
   64 document-specific and have to be known to the caller. The
   65 [arg options] will be explained later, in section [sectref OPTIONS].
   66 
   67 [list_begin arguments]
   68 
   69 [arg_def path output in]
   70 
   71 This argument specifies where to write the generated document. It can
   72 be the path to a file or directory, or [const -].
   73 
   74 The last value causes the application to write the generated
   75 documented to [const stdout].
   76 
   77 [para]
   78 
   79 If the [arg output] does not exist then [lb]file dirname $output[rb]
   80 has to exist and must be a writable directory.
   81 
   82 [arg_def path inputfile in]
   83 
   84 This argument specifies the path to the file to process. It has to
   85 exist, must be readable, and written in [term docstrip] format.
   86 
   87 [list_end]
   88 [para]
   89 
   90 [call [cmd tcldocstrip] [opt options] [arg output] ([opt options] [arg input] [arg guards])...]
   91 
   92 This is the form for use case [lb]2[rb]. It differs from the form for
   93 use case [lb]1[rb] by the possibility of having options before the
   94 output file, which apply in general, and specifying more than one
   95 inputfile, each with its own set of input specific options and guards.
   96 
   97 [para]
   98 
   99 It extracts data from the various [arg input] files, according to the
  100 specified [arg options] and [arg guards], and writes the result to the
  101 given [arg output], in the order of their specification on the command
  102 line. Options specified before the output are global settings, whereas
  103 the options specified before each input are valid only just for this
  104 input file. Unspecified values are taken from the global settings, or
  105 defaults. As for form [lb]1[rb] using the string [const "-"] as output
  106 causes the application to write to stdout.
  107 
  108 Using the string [const "."] for an input file signals that the last
  109 input file should be used again. This enables the assembly of the
  110 output from one input file using multiple and different sets of
  111 guards, without having to specify the full name of the file every
  112 time.
  113 
  114 [call [cmd tcldocstrip] [option -guards] [arg input]]
  115 
  116 This is the form for use case [lb]3[rb].
  117 
  118 It determines the guards, and unique guard expressions used within the
  119 provided [arg input] document. The found strings are written to
  120 stdout, one string per line.
  121 
  122 [list_end]
  123 
  124 [subsection OPTIONS]
  125 
  126 This section describes all the options available to the user of the
  127 application, with the exception of the option [option -guards]. This
  128 option was described already, in section [sectref {COMMAND LINE}].
  129 
  130 [para]
  131 [list_begin options]
  132 [opt_def -metaprefix string]
  133 
  134 This option is inherited from the command [cmd docstrip::extract]
  135 provided by the package [package docstrip].
  136 
  137 [para]
  138 
  139 It specifies the string by which the '%%' prefix of a metacomment line
  140 will be replaced. Defaults to '%%'. For Tcl code this would typically
  141 be '#'.
  142 
  143 [opt_def -onerror mode]
  144 
  145 This option is inherited from the command [cmd docstrip::extract]
  146 provided by the package [package docstrip].
  147 
  148 [para]
  149 
  150 It controls what will be done when a format error in the [arg text]
  151 being processed is detected. The settings are:
  152 
  153 [list_begin definitions]
  154 [def [const ignore]]
  155 Just ignore the error; continue as if nothing happened.
  156 
  157 [def [const puts]]
  158 Write an error message to [const stderr], then continue processing.
  159 
  160 [def [const throw]]
  161 Throw an error. [var ::errorCode] is set to a list whose first element
  162 is [const DOCSTRIP], second element is the type of error, and third
  163 element is the line number where the error is detected. This is the
  164 default.
  165 [list_end]
  166 
  167 [opt_def -trimlines bool]
  168 
  169 This option is inherited from the command [cmd docstrip::extract]
  170 provided by the package [package docstrip].
  171 
  172 [para]
  173 
  174 Controls whether [emph spaces] at the end of a line should be trimmed
  175 away before the line is processed. Defaults to [const true].
  176 
  177 [opt_def -preamble text]
  178 [opt_def -postamble text]
  179 [opt_def -nopreamble]
  180 [opt_def -nopostamble]
  181 
  182 The -no*amble options deactivate file pre- and postambles altogether,
  183 whereas the -*amble options specify the [emph user] part of the file
  184 pre- and postambles. This part can be empty, in that case only the
  185 standard parts are shown. This is the default.
  186 
  187 [para]
  188 
  189 Preambles, when active, are written before the actual content of a
  190 generated file. In the same manner postambles are, when active,
  191 written after the actual content of a generated file.
  192 
  193 [list_end]
  194 
  195 [vset CATEGORY docstrip]
  196 [include ../modules/doctools2base/include/feedback.inc]
  197 [manpage_end]