"Fossies" - the Fresh Open Source Software Archive

Member "SAOImageDS9/tcllib/apps/dtplite.man" (13 Nov 2019, 14068 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 dtplite n 1.0.5]
    3 [see_also {docidx introduction}]
    4 [see_also {doctoc introduction}]
    5 [see_also {doctools introduction}]
    6 [keywords conversion]
    7 [keywords docidx]
    8 [keywords doctoc]
    9 [keywords doctools]
   10 [keywords HTML]
   11 [keywords manpage]
   12 [keywords markup]
   13 [keywords nroff]
   14 [keywords TMML]
   15 [copyright {2004-2013 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
   16 [titledesc {Lightweight DocTools Markup Processor}]
   17 [moddesc   {Documentation toolbox}]
   18 [category  {Documentation tools}]
   19 [description]
   20 [para]
   21 
   22 The application described by this document, [syscmd dtplite], is the
   23 successor to the extremely simple [syscmd mpexpand]. Influenced in its
   24 functionality by the [syscmd dtp] doctools processor it is much more
   25 powerful than [syscmd mpexpand], yet still as easy to use; definitely
   26 easier than [syscmd dtp] with its myriad of subcommands and options.
   27 
   28 [para]
   29 
   30 [syscmd dtplite] is based upon the package [package doctools], like
   31 the other two processors.
   32 
   33 [subsection {USE CASES}]
   34 
   35 [syscmd dtplite] was written with the following three use cases in
   36 mind.
   37 
   38 [para]
   39 [list_begin enumerated]
   40 [enum]
   41 Validation of a single document, i.e. checking that it was written in
   42 valid doctools format. This mode can also be used to get a preliminary
   43 version of the formatted output for a single document, for display in
   44 a browser, nroff, etc., allowing proofreading of the formatting.
   45 
   46 [enum]
   47 Generation of the formatted documentation for a single package,
   48 i.e. all the manpages, plus a table of contents and an index of
   49 keywords.
   50 
   51 [enum]
   52 An extension of the previous mode of operation, a method for the easy
   53 generation of one documentation tree for several packages, and
   54 especially of a unified table of contents and keyword index.
   55 
   56 [list_end]
   57 
   58 [para]
   59 
   60 Beyond the above we also want to make use of the customization
   61 features provided by the HTML formatter. It is not the only format the
   62 application should be able to generate, but we anticipiate it to be
   63 the most commonly used, and it is one of the few which do provide
   64 customization hooks.
   65 
   66 [para]
   67 
   68 We allow the caller to specify a header string, footer string, a
   69 stylesheet, and data for a bar of navigation links at the top of the
   70 generated document.
   71 
   72 While all can be set as long as the formatting engine provides an
   73 appropriate engine parameter (See section [sectref OPTIONS]) the last
   74 two have internal processing which make them specific to HTML.
   75 
   76 [subsection {COMMAND LINE}]
   77 
   78 [list_begin definitions]
   79 
   80 [call [cmd dtplite] [option -o] [arg output] [opt options] [arg format] [arg inputfile]]
   81 
   82 This is the form for use case [lb]1[rb]. The [arg options] will be
   83 explained later, in section [sectref OPTIONS].
   84 
   85 [list_begin arguments]
   86 
   87 [arg_def path output in]
   88 
   89 This argument specifies where to write the generated document. It can
   90 be the path to a file or directory, or [const -].
   91 
   92 The last value causes the application to write the generated
   93 documented to [const stdout].
   94 
   95 [para]
   96 
   97 If the [arg output] does not exist then [lb]file dirname $output[rb]
   98 has to exist and must be a writable directory.
   99 
  100 The generated document will be written to a file in that directory,
  101 and the name of that file will be derived from the [arg inputfile],
  102 the [arg format], and the value given to option [option -ext] (if
  103 present).
  104 
  105 [arg_def (path|handle) format in]
  106 
  107 This argument specifies the formatting engine to use when processing
  108 the input, and thus the format of the generated document. See section
  109 [sectref FORMATS] for the possibilities recognized by the application.
  110 
  111 [arg_def path inputfile in]
  112 
  113 This argument specifies the path to the file to process. It has to
  114 exist, must be readable, and written in [term doctools] format.
  115 
  116 [list_end]
  117 [para]
  118 
  119 [call [cmd dtplite] [const validate] [arg inputfile]]
  120 
  121 This is a simpler form for use case [lb]1[rb]. The "validate" format
  122 generates no output at all, only syntax checks are performed. As such
  123 the specification of an output file or other options is not necessary
  124 and left out.
  125 
  126 [call [cmd dtplite] [option -o] [arg output] [opt options] [arg format] [arg inputdirectory]]
  127 
  128 This is the form for use case [lb]2[rb]. It differs from the form for
  129 use case [lb]1[rb] by having the input documents specified through a
  130 directory instead of a file. The other arguments are identical, except
  131 for [arg output], which now has to be the path to an existing and
  132 writable directory.
  133 
  134 [para]
  135 
  136 The input documents are all files in [arg inputdirectory] or any of
  137 its subdirectories which were recognized by [cmd fileutil::fileType]
  138 as containing text in [term doctools] format.
  139 
  140 [call [cmd dtplite] [option -merge] [option -o] [arg output] [opt options] [arg format] [arg inputdirectory]]
  141 
  142 This is the form for use case [lb]3[rb]. The only difference to the
  143 form for use case [lb]2[rb] is the additional option [option -merge].
  144 
  145 [para]
  146 
  147 Each such call will merge the generated documents coming from
  148 processing the input documents under [arg inputdirectory] or any of
  149 its subdirectories to the files under [arg output]. In this manner it
  150 is possible to incrementally build the unified documentation for any
  151 number of packages. Note that it is necessary to run through all the
  152 packages twice to get fully correct cross-references (for formats
  153 supporting them).
  154 
  155 [list_end]
  156 
  157 [subsection OPTIONS]
  158 
  159 This section describes all the options available to the user of the
  160 application, with
  161 
  162 the exception of the options [option -o] and [option -merge]. These
  163 two were described already, in section [sectref {COMMAND LINE}].
  164 
  165 [para]
  166 [list_begin options]
  167 [opt_def -exclude string]
  168 
  169 This option specifies an exclude (glob) pattern. Any files identified
  170 as manpages to process which match the exclude pattern are
  171 ignored. The option can be provided multiple times, each usage adding
  172 an additional pattern to the list of exclusions.
  173 
  174 [opt_def -ext string]
  175 
  176 If the name of an output file has to be derived from the name of an
  177 input file it will use the name of the [arg format] as the extension
  178 by default. This option here will override this however, forcing it to
  179 use [arg string] as the file extension. This option is ignored if the
  180 name of the output file is fully specified through option [option -o].
  181 
  182 [para]
  183 
  184 When used multiple times only the last definition is relevant.
  185 
  186 [opt_def -header file]
  187 
  188 This option can be used if and only if the selected [arg format]
  189 provides an engine parameter named "header". It takes the contents of
  190 the specified file and assign them to that parameter, for whatever use
  191 by the engine. The HTML engine will insert the text just after the tag
  192 [const <body>].
  193 
  194 If navigation buttons are present (see option [option -nav] below),
  195 then the HTML generated for them is appended to the header data
  196 originating here before the final assignment to the parameter.
  197 
  198 [para]
  199 
  200 When used multiple times only the last definition is relevant.
  201 
  202 [opt_def -footer file]
  203 
  204 Like [option -header], except that: Any navigation buttons are ignored,
  205 the corresponding required engine parameter is named "footer", and the
  206 data is inserted just before the tag [const </body>].
  207 
  208 [para]
  209 
  210 When used multiple times only the last definition is relevant.
  211 
  212 [opt_def -style file]
  213 
  214 This option can be used if and only if the selected [arg format]
  215 provides an engine parameter named "meta". When specified it will
  216 generate a piece of HTML code declaring the [arg file] as the
  217 stylesheet for the generated document and assign that to the
  218 parameter. The HTML engine will insert this inot the document, just
  219 after the tag [const <head>].
  220 
  221 [para]
  222 
  223 When processing an input directory the stylesheet file is copied into
  224 the output directory and the generated HTML will refer to the copy, to
  225 make the result more self-contained. When processing an input file we
  226 have no location to copy the stylesheet to and so just reference it as
  227 specified.
  228 
  229 [para]
  230 
  231 When used multiple times only the last definition is relevant.
  232 
  233 [opt_def -toc path]
  234 
  235 This option specifies a doctoc file to use for the table of contents
  236 instead of generating our own.
  237 
  238 [para]
  239 
  240 When used multiple times only the last definition is relevant.
  241 
  242 [opt_def -pre+toc "label path|text"]
  243 [opt_def -post+toc "label path|text"]
  244 
  245 This option specifies additional doctoc files (or texts) to use in
  246 the navigation bar.
  247 
  248 [para] Positioning and handling of multiple uses is like for options
  249 [option -prenav] and [option -postnav], see below.
  250 
  251 [opt_def -nav "label url"]
  252 [opt_def -prenav "label url"]
  253 
  254 Use this option to specify a navigation button with [arg label] to
  255 display and the [arg url] to link to. This option can be used if and
  256 only if the selected [arg format] provides an engine parameter named
  257 "header". The HTML generated for this is appended to whatever data we
  258 got from option [option -header] before it is inserted into the
  259 generated documents.
  260 
  261 [para]
  262 
  263 When used multiple times all definitions are collected and a
  264 navigation bar is created, with the first definition shown at the left
  265 edge and the last definition to the right.
  266 
  267 [para] The url can be relative. In that case it is assumed to be relative
  268 to the main files (TOC and Keyword index), and will be transformed for
  269 all others to still link properly.
  270 
  271 [opt_def -postnav "label url"]
  272 
  273 Use this option to specify a navigation button with [arg label] to
  274 display and the [arg url] to link to. This option can be used if and
  275 only if the selected [arg format] provides an engine parameter named
  276 "header". The HTML generated for this is appended to whatever data we
  277 got from option [option -header] before it is inserted into the
  278 generated documents.
  279 
  280 [para]
  281 
  282 When used multiple times all definitions are collected and a
  283 navigation bar is created, with the last definition shown at the right
  284 edge and the first definition to the left.
  285 
  286 [para] The url can be relative. In that case it is assumed to be relative
  287 to the main files (TOC and Keyword index), and will be transformed for
  288 all others to still link properly.
  289 
  290 [list_end]
  291 
  292 [subsection FORMATS]
  293 
  294 At first the [arg format] argument will be treated as a path to a tcl
  295 file containing the code for the requested formatting engine. The
  296 argument will be treated as the name of one of the predefined formats
  297 listed below if and only if the path does not exist.
  298 
  299 [para]
  300 
  301 [emph {Note a limitation}]: If treating the format as path to the tcl
  302 script implementing the engine was sucessful, then this script has to
  303 implement not only the engine API for doctools, i.e.
  304 
  305 [term doctools_api], but for [term doctoc_api] and [term docidx_api]
  306 as well. Otherwise the generation of a table of contents and of a
  307 keyword index will fail.
  308 
  309 [para]
  310 
  311 List of predefined formats, i.e. as provided by the
  312 package [package doctools]:
  313 
  314 [para]
  315 [list_begin definitions]
  316 
  317 [def [const nroff]]
  318 
  319 The processor generates *roff output, the standard format for unix
  320 manpages.
  321 
  322 [def [const html]]
  323 
  324 The processor generates HTML output, for usage in and display by web
  325 browsers. This engine is currently the only one providing the various
  326 engine parameters required for the additional customaization of the
  327 output.
  328 
  329 [def [const tmml]]
  330 
  331 The processor generates TMML output, the Tcl Manpage Markup Language,
  332 a derivative of XML.
  333 
  334 [def [const latex]]
  335 
  336 The processor generates LaTeX output.
  337 
  338 [def [const wiki]]
  339 
  340 The processor generates Wiki markup as understood by [syscmd wikit].
  341 
  342 [def [const list]]
  343 
  344 The processor extracts the information provided by [cmd manpage_begin].
  345 [see_also {docidx introduction}]
  346 [see_also {doctoc introduction}]
  347 [see_also {doctools introduction}]
  348 [keywords conversion]
  349 [keywords docidx]
  350 [keywords doctoc]
  351 [keywords doctools]
  352 [keywords HTML]
  353 [keywords manpage]
  354 [keywords markup]
  355 [keywords nroff]
  356 [keywords TMML]
  357 
  358 This format is used internally to extract the meta data from which
  359 both table of contents and keyword index are derived from.
  360 
  361 [def [const null]]
  362 
  363 The processor does not generate any output. This is equivalent to
  364 [const validate].
  365 
  366 [list_end]
  367 
  368 [subsection {DIRECTORY STRUCTURES}]
  369 
  370 In this section we describe the directory structures generated by the
  371 application under [arg output] when processing all documents in an
  372 [arg inputdirectory]. In other words, this is only relevant to the use
  373 cases [lb]2[rb] and [lb]3[rb].
  374 
  375 [list_begin definitions]
  376 
  377 [def "[lb]2[rb]"]
  378 
  379 The following directory structure is created when processing a single
  380 set of input documents.  The file extension used is for output in
  381 HTML, but that is not relevant to the structure and was just used to
  382 have proper file names.
  383 
  384 [example {
  385     output/
  386         toc.html
  387         index.html
  388         files/
  389             path/to/FOO.html
  390 }]
  391 
  392 The last line in the example shows the document
  393 generated for a file FOO located at
  394 
  395 [example {
  396     inputdirectory/path/to/FOO
  397 }]
  398 
  399 [def "[lb]3[rb]"]
  400 
  401 When merging many packages into a unified set of documents the
  402 generated directory structure is a bit deeper:
  403 
  404 [example {
  405     output
  406         .toc
  407         .idx
  408         .tocdoc
  409         .idxdoc
  410         .xrf
  411         toc.html
  412         index.html
  413         FOO1/
  414             ...
  415         FOO2/
  416             toc.html
  417             files/
  418                 path/to/BAR.html
  419 }]
  420 
  421 Each of the directories FOO1, ... contains the documents generated for
  422 the package FOO1, ... and follows the structure shown for use case
  423 [lb]2[rb]. The only exception is that there is no per-package index.
  424 
  425 [para]
  426 
  427 The files [file .toc], [file .idx], and [file .xrf] contain the
  428 internal status of the whole output and will be read and updated by
  429 the next invokation. Their contents will not be documented. Remove
  430 these files when all packages wanted for the output have been
  431 processed, i.e. when the output is complete.
  432 
  433 [para]
  434 
  435 The files [file .tocdoc], and [file .idxdoc], are intermediate files
  436 in doctoc and docidx markup, respectively, containing the main table
  437 of contents and keyword index for the set of documents before their
  438 conversion to the chosen output format.
  439 
  440 They are left in place, i.e. not deleted, to serve as demonstrations
  441 of doctoc and docidx markup.
  442 
  443 [list_end]
  444 
  445 [vset CATEGORY doctools]
  446 [include ../modules/doctools2base/include/feedback.inc]
  447 [manpage_end]