texutil



TEXUTIL(1)                                                          TEXUTIL(1)



texutil(1)                          CONTEXT                         texutil(1)




NAME

       texutil - ConTeXt auxiliary program



SYNOPSIS

       texutil [ OPTION... ] FILENAME[...]



DESCRIPTION

       When  processing a source file, ConTeXt (via texexec(1)) saves informa-
       tion (including table of contents, tables of figures and tables,  index
       entries,  cross-references)  in a ‘‘utility file´´ called FILENAME.tui.
       After each successful run, this utility file is postprocessed by  texu-
       til to organize the information for the next run.

       texutil performs a number of useful functions:


       o      Postprocessing  references,  including  sorting  index  and list
              entries (with --references)

       o      Extracting documentation and other  types  of  information  from
              ConTeXt source files (with --documents)

       o      Logfile analysis (with --logfile)

       o      Collecting information about graphic files to help with typeset-
              ting (with --figures)

       o      Converting EPS files to a PDF format suitable for  inclusion  in
              PDF   files  generated  with  pdftex(1)  (with  ----epspage  and
              --epstopdf)



OPTIONS

       All switches are specified here in full, but can be abbreviated to  the
       shortest  unique  string.  Thus, --ver works the same as --verbose pro-
       vided that there is no other flag beginning with ‘‘ver´´.



General Options

       --help Print a usage summary to stdout.

       --interface=LANGUAGECODE
              Specify the language for messages.   One  of  en  (English),  de
              (German), or nl (Dutch).  The default language is English.

       --outputfile=FILENAME
              Specify the name of the output file.

       --purge [ BASENAME ]
              Delete  temporary  files.   Specifying an optional BASENAME will
              only affect the temporary files that begin with that BASENAME.

       --silent
              Redirects stdout to the  log  file  (texutil.log,  by  default).
              When  used with --verbose, a summary is printed to stdout, while
              any other output is written to the log file.

              For example,


                   texutil --figures --silent --verbose somefile.png


              will output something like


                   n=somefile.png t=png x=0bp y=0bp w=443bp h=591bp


              to stdout, placing other output into texutil.log.  This informa-
              tion can be piped into another program for further processing.

       --type=SUFFIX
              Specify the SUFFIX of the file you want texutil to process.

       --verbose
              Print diagnostic messages to the screen.



Postprocessing References

       The  --references  flag  instructs texutil to process information about
       cross-references, index entries, and other data requiring more than one
       pass to process in the ConTeXt utility file.

       Index  and  sorted  list  entries  are sorted before being written out;
       redundant index entries are removed.

       texutil is called automatically by  texexec(1)  during  its  processing
       runs  unless  you  specify otherwise.  texutil can also be run by hand,
       using the form


            texutil --references FILENAME


       This command would cause texutil to load the utility file FILENAME.tui,
       sort  and  convert  the contents of that file, and write the results to
       FILENAME.tuo.

       Options specific to this mode are:

       --ij   Sort ‘‘IJ´´ as ‘‘Y´´.  Often used when processing files  written
              in Dutch.

       --high Convert  ‘‘high´´  ASCII  values  into  equivalent TeX commands.
              This switch is provided for backward compatibility.

       --quotes
              Take tex(1) accent commands  into  consideration  when  sorting.
              (Otherwise,  quotes are considered to be boundary characters for
              strings.)

       --tcxpath=PATH
              Specify path to tcx filter files for translating between  encod-
              ings.



Extracting Information from ConTeXt Source Files

       ConTeXt  source  files  often contain documentation (see USAGE for more
       information  about  the  format)  or  other  information  that  can  be
       extracted by texutil when called with the --documents flag:


            texutil --documents FILENAME


       This  command  produces  a file called FILENAME.ted from a ConTeXt file
       called FILENAME.tex.

       The --sources flag does the opposite: Documentation lines are  stripped
       out of the output, which is written to a file called FILENAME.tes.

       Historically,  ConTeXt source files included other forms of information
       -- such as syntax definitions, macro definitions, and editor  templates
       -- that can be extracted with the following flags:


       --infos
              Extract TeXEdit macro information (tex->tud -- see USAGE)

       --setups
              Extract ConTeXt syntax definitions (tex->texutil.tus)

       --templates
              Extract TeXEdit editor templates (tex->tud)



Analyzing Log Files

       Calling  texutil with the --logfile option allows you to extract infor-
       mation about problems with your ConTeXt source file from the  log  file
       produced during a texexec(1) run.

       You can specify what information texutil should report with the follow-
       ing options:

       --box  Extract information about overfull boxes.  By default, this flag
              will  cause texedit to report both horizontal and vertical over-
              full boxes.  If you´re only interested  in  one  kind,  you  can
              specify --hbox or --vbox instead.

       --criterium=SIZE
              Exclude  reports  about boxes that are less than SIZE points too
              large.

       --unknown
              Extract messages about missing references or figures.



Gathering Information about Figures

       The --figures flag tells texutil to generate information about  one  or
       more  (non-EPS)  graphics files for use in typesetting.  Called as, for
       example,


            texutil --figures *.png *.tif


       texutil will scan the current directory for  PNG  and  TIFF  files  and
       extract  some  useful  information  about  their  sizes  and types.  By
       default, this information is stored in a file called texutil.tuf, which
       is  consulted  by  ConTeXt when typesetting a page with a non-EPS image
       file -- see the example given for the --silent flag for an alternative.

       This  flag is especially useful when you plan to typeset a file of pre-
       views of graphic files -- see the discussion of the --figures  flag  in
       the texexec(1) manpage.



Converting EPS Files for PDF Inclusion

       texutil  can  also convert EPS files to PDF format for inclusion in PDF
       files generated with pdftex(1) or pdfetex(1).


       --epspage
              Adjust the bounding box of an EPS file to the dimensions of  the
              output  page.   This option also removes some redundant informa-
              tion and marks files as converted  so  that  they  will  not  be
              affected by subsequent runs.

       --epstopdf
              Calls  gs(1) to convert the specified EPS graphic files into PDF
              format.



USAGE


Embedded Documentation Format

       Documentation lines included in ConTeXt source files can  be  specified
       by beginning lines with the following strings:

       %C     Copyright information

       %D     Documentation lines

       %I     TeXEdit information lines (mostly in Dutch)

       %M     Macro code needed to processs the documentation

       %S     ‘‘Suppressed´´ lines

       The  same  forms  can  be  used for Perl scripts, except that the ‘‘%´´
       characters are replaced by ‘‘#´´ characters.  See the source for  texu-
       til for an example.



SEE ALSO

       gs(1), pdfetex(1), pdftex(1), texexec(1), texshow(1).

       Web page: <http://www.pragma-ade.com/>



AUTHOR

       This  manpage  was  written  by C.M. Connelly <c@eskimo.com> and Tobias
       Burnus <burnus@gmx.de>.  It is based on the texutil manual  written  by
       Hans Hagen <pragma@wxs.nl>.

       The    PDF   manual   and   texutil   itself   can   be   obtained   at
       <http://www.pragma-ade.com/pragma-ade/texutil.htm>.



ConTeXt                          October 2000                       texutil(1)

Man(1) output converted with man2html