texexec



texexec(1)                          ConTeXt                         texexec(1)




NAME

       texexec - ConTeXt and PDF auxiliary program and batch processor



SYNOPSIS

       texexec [ OPTION ...  ] FILE [ ...  ]



DESCRIPTION

       texexec is a Perl script that provides several functions:

       o      Process  a  TeX  file.  This includes performing as many runs as
              necessary of  tex(1),  texutil(1),  and  metapost(1).    Options
              allow  you  to  select  the output format, the pages to process,
              paper size, and so forth.

       o      Create new ConTeXt formats (with --format).

       o      Post-process existing  PDF  files,  including  merging  multiple
              files, and extracting and rearranging pages within a file (simi-
              lar to the functions provided by psnup(1) and pdfmerge(1)).

       o      Extract or strip documentation from  com{ConTeXt}  source  files
              (using texutil(1)).

       o      Run  METAPOST  (mpost(1))  to  generate  figures  from  METAPOST
              source.

       o      Produce ‘‘proof sheets´´ of figures used  in  a  ConTeXt  source
              file.




OPTIONS

       All  switches  are  specified  in  full,  but can be abbreviated to the
       shortest unique string.   Thus, --ver works the same as --verbose.



General Options

       --alone
              Avoid  calling  other  programs  when  possible.   For  example,
              --alone  will  prevent texexec from using fmtutil(1) to generate
              formats (which can be handy when tracing installation problems).

       --environment=ENVIRONMENT
              Specify  a  ConTeXt ENVIRONMENT to use when processing the file.
              This option can be useful when converting from non-ConTeXt  file
              formats  where  no environment or layout settings are present in
              the file.

       --help [ SWITCH ]
              Produce a summary of switches and arguments.  Many switches have
              additional  information  that  can  be  seen by typing ‘‘texexec
              --help optvar(SWITCH)´´.

       --interface=LANGUAGE
              Specify the language ConTeXt should use to communicate with you.
              Options are


              en     US English

              nl     Dutch

              de     German

              uk     British English

              cz     Czech

              it     Italian

       --once Process  a  file  once and only once.  (By default, texexec pro-
              cesses the file as many times as necessary to sort out all  ref-
              erences, typeset METAPOST code, and so forth.)

       --output=DRIVER
              Specify  the  output  DRIVER  for  use with \special primitives.
              Defaults to the setting in the local cont-sys.tex file, but  can
              be set to one of


              pdftex Native pdftex(1) code

              dvips  For dvips(1) (the default)

              dvipsone
                     For dvipsone

              dviwindo
                     For dviwindo, the oldest ConTeXt drivers

              dviview
                     For dviview (experimental)


              There  may  be  other supported drivers -- check the most recent
              ConTeXt documentation.

       --pages=PAGENUMBERLIST
              Specify the pages or page range to appear in  the  output  file.
              PAGENUMBERLIST may be the keyword odd or even; one or more pages
              separated by commas (x,y); or a page range in the form :z.

       --passon=STRING
              Pass additional  command-line  switches  and  arguments  to  the
              tex(1) process run by texexec.

              For  example,  the MikTeX TeX system (for DOS/Windows) can embed
              information in the DVI file that will allow you to find the line
              in  a  source code file corresponding to the line in the typeset
              output.  It uses a switch  called  ‘‘--src´´  to  activate  this
              functionality, and can be used from texexec as


                   texexec --passon="--src" somefile


              The double quotes (") are required to prevent texexec from using
              the switch itself.

       --program
              The name of the TeX program to use (tex(1), by default).

       --result=FILENAME
              Allows you to change the  basename  of  the  output  file.   See
              --mode for an example.

       --runs=NUMBER
              Specify the number of runs to perform on a file.  Overrides tex-
              exec´s calculations.

       --silent
              Suppress diagnostic and progress messages.

       --suffix=SUFFIX
              Specify the suffix of the output file.

       --tex=PROGRAMNAME
              Allows you specify the program to use instead of tex(1).  Useful
              for  trying  different  versions of tex(1) installed on the same
              machine.

       --texutil
              Force a run of texutil(1).

       --verbose
              Output diagnostic information, including the  contents  of  tex-
              exec.ini.




Processing ConTeXt Source Files

       Including specifying paper sizes, formats, and so forth.


       --arrange
              Don´t  perform  page rearrangements (e.g., for producing a book-
              let) until the last run.

       --batch
              Process the file in batch mode -- continue to typeset the  docu-
              ment  after  finding  errors.  More imformation about batch mode
              can be found in Donald E. Knuth´s TeXbook.

       --bodyfont
              The name of a font to preload for use in setting the body of the
              text.

       --centerpage
              Center the document image on the page.

       --color
              Turn  on  color  mode.   Color  mode can also be set by commands
              embedded in the document.  These commands override  the  --color
              option.

       --convert=FORMAT
              Convert the input file to ConTeXt format from FORMAT before pro-
              cessing.  In most cases, this conversion will result  in  a  TeX
              file.  Currently supported input FORMATs are xml and sgml.

       --dvi  Shortcut for --output=dvi.

       --fast Typeset  the  document(s)  as  fast  as possible without causing
              problems.

       --final
              Perform a final run without skipping anything.  This  option  is
              typically used with --fast.

       --language=LANGUAGE
              Set  the  language  for  hyphenation.   Can be specified in your
              source file.  Options are the same as those for --interface.

       --mode=MODELIST
              Allows you to change the mode (page size and resolution) of  the
              output file.


                   texexec --pdf --mode=A4     --result=pdftex-a pdftex-t
                   texexec --pdf --mode=letter --result=pdftex-l pdftex-t
                   texexec --pdf --mode=screen --result=pdftex-s pdftex-t


              Here  the  mode switch tells ConTeXt to obey the mode directives
              in the layout specifications.  The --result flag allows  you  to
              rename the output file.

       --noarrange
              Ignore arrangement commands in the source file.

       --paper=KEY
              For  typesetting multiple pages on a single piece of paper.  KEY
              can be a4a3 (for printing A4 pages on A3  paper)  or  a5a4  (for
              printing  A5 pages on A4 paper).  The actual layout of the pages
              is specified with the --print switch.

       --pdf  Shorthand for --output=pdftex.

       --print=KEY
              Specify the layout of the final output.  KEY can be up,  result-
              ing  in 2 pages per sheet, double sided, or down, resulting in 2
              rotated pages per sheet, double sided.  Use the  --paper  switch
              to specify the original page and sheet size.




Creating ConTeXt Format Files

       --format=FORMATFILE
              Specify  a  FORMATFILE  to  use  when typesetting.  texexec will
              prepend the string cont-  to the name you give, so you can  type
              plain instead of cont-plain, as in


                   texexec --format=plain --program=pdftex somefile


       --make Generate a ConTeXt format file.



Postprocess PDF Files

       --combination=ROWS*COLS
              Specify  the number of pages to show on a single page.  Use with
              --pdfcombine.

       --pdfarrange
              For rearranging pages in PDF files.


                   texexec --pdfarrange --paper=a5a4 --print=up foo.pdf


              This command creates an A5 booklet  from  a  PDF  file  foo.pdf.
              --pdfarrange is used in conjunction with the following switches:

       --paperoffset
              Adjust the space between the edge of the pages and the beginning
              of the text block.

       --backspace
              Adjust the inside (‘‘gutter´´) margins.

       --topspace
              Adjust the top and bottom margin.

       --markings
              Add crop marks.

       --addempty=PAGES
              Add  empty  pages  after  the pages specified in PAGES.  (Useful
              for, among other things, adding blank pages  after  a  table  of
              contents.)

       --textwidth=WIDTH
              Set  the  width of the original text.  Specifying this parameter
              with a single-sided original will allow ConTeXt  to  adjust  the
              page layout for double-sided output, producing much more attrac-
              tive results.

              With the --pdfarrange flag, specifying more than one  file  will
              result  in  all of the files being combined in the final result,
              allowing you to add title pages, decorated part separators,  and
              so forth.

              You can also do more complex manipulations, such as adding addi-
              tional text to the page by setting up a small file  with  layout
              definitions and a simple figure insertion loop.

       --pdfcombine
              Combine  multiple pages.  Requires you to specify the --combina-
              tion switch.

       --pdfselect
              Extract pages from a file.  Use in combination with the --selec-
              tion switch, as in

              texexec --pdfselect --paper=S6 --selection=1,9,14 file-1

              which  extracts  pages  1, 9, and 14 from file-1.pdf, and places
              them in texexec.pdf (the default output filename  if  an  output
              file isn´t specified).

              See --pdfarrange for other options.

       --selection=PAGES
              Specify  pages  to  be affected by another option.  See --pdfar-
              range and --pdfselect for examples.



Extract or Strip Out Documentation

       --listing
              Produce a typeset version of the source code in FILE.   You  can
              specify the form of the output file, as in
              texexec --listing --pdf readme.now

              which  will  produce a PDF file called texexec.pdf.  Without the
              --pdf flag, texexec will produce a DVI file.

              See also --backspace and --topspace.

       --module
              Create documentation for ConTeXt, MetaPost (see  mpost(1)),  and
              Perl  modules.  Converts the documentation to ConTeXt format and
              then typesets  that  documentation.   See  texutil(1)  for  more
              information about the format of the documentation strings.



Process METAPOST Figures

       --mpformat
              The name of a MetaPost format file.

       --mptex
              Strips out and typesets TeX code embedded in a MetaPost file.

       --nomp Do not run MetaPost, even if needed.

       --nomprun
              Do not run mpost(1) on embedded MetaPost code.



Producing Proof Sheets of Figures

       --figures=ALTERNATIVE
              Specify  one  of  three options to produce a document containing
              the images used in the source file:


              a      A proof sheet with additional  information  provided  for
                     each figure

              b      A proof sheet with the graphics only

              c      One  figure per page, with the page clipped to the bound-
                     ing box of the figure

                     See also --paperoffset, which allows you  to  specify  an
                     offset to be added to the page, as in


                          texexec --figures=c --paperoffset=.5cm *.pdf
                          *.png *.jpg



              texexec  uses  texutil(1)  to obtain the list of figures to pro-
              cess.



USAGE

       o      Each ConTeXt user interface (language) has its own format.   The
              following  command  generates two formats, one using the English
              interface for typesetting in English, and one for Dutch:


                   texexec --make en nl


              By default, the language used for typesetting matches the  user-
              interface  language (set with --interface.  It´s possible to use
              one language for typesetting and another for messages by  chang-
              ing  the  relevant settings in cont-usr.tex, but these languages
              can also be changed on the command line with a command such as

              texexec --make --language=pl,cz,sk --bodyfont=plr en

              That command generates a ConTeXt format  file  with  an  English
              user  interface,  and the main language set to Polish (pl).  The
              default body font is the Polish version of Computer Modern Roman
              (plr).  Czech and Slovak hyphenation patterns are also loaded so
              that Czech and Slovak text included in a  source  file  will  be
              typeset properly (cz and sk).

       o      When  the appropriate formats are present, a file can be typeset
              by typing


                   texexec test


              texexec tries to determine what interface it should use to type-
              set test.tex by looking for a line such as


                   % interface=en tex=pdfetex output=pdftex


              at  the  top  of  the file (i.e., on the very first line).  This
              line is equivalent to TeX´s format line, ‘‘&FORMAT´´).

              By default, texexec will produce a DVI  file.   The  --pdf  flag
              tells  texexec  to  produce a PDF file, instead (by running pdf-
              tex(1)).  You can also be more specific about what drivers  tex-
              exec should use, by specifying a command line such as


                   texexec --output=dvips,acrobat test


              which  specifies  the  use  of  the  dvips  driver (which is the
              default), combined with the use of Acrobat-specific PDF instruc-
              tions.

              After  an  error-free run, texexec will run texutil(1) to deter-
              mine whether additional runs of tex(1)  (or  pdftex(1))  or  any
              utility  programs (e.g., bibtex(1), makeindex(1)) are necessary.
              You can suppress these additional runs by specifying the  --once
              or --runs flags:


                   texexec --once test
                   texexec --runs=2 test




INITIALIZATION

              When  starting,  texexec  first  looks for the file texexec.ini,
              which specifies the location of various programs and  configura-
              tion  files,  and  specifies the programs to use.  The --verbose
              flag causes texexec to print the information in  texexec.ini  to
              the terminal and the log file.

              texexec  requires  Perl.  On Unix and Unix-like systems, no spe-
              cial steps have to be  taken  to  get  texexec  to  work  beyond
              installing  Perl and having the perl(1) binary in your path.  On
              Windows systems, however, you may need to  run  Perl  by  typing
              commands such as ‘‘perl texexec.pl optvar(ARGS)´´.

              The  fpTeX  distribution comes with a program called runperl.exe
              that can be copied and renamed to texexec.exe.   You  will  also
              have  to  rename  a  copy  to texutil.exe (see texutil(1)).  The
              teTeX and fpTeX distributions, at least, should perform the nec-
              essary  steps  as  part of their installation sequence -- if you
              have problems, however, you may need to follow the advice  given
              here.

              The file texexec.rme contains default configuration information.
              If no file texexec.ini  exists  (in  TEXMF/context/config/,  you
              should  copy  texexec.rme  to  that  directory  and rename it to
              texexec.ini.  Make any necessary changes to this file to reflect
              the layout of programs and directories on your system.


ENCODINGS

              Some languages require specific character encodings to represent
              their alphabets (beyond the basic ASCII encoding).  Although you
              can  use  TeX  commands  to  represent these characters, such as
              ‘‘\.z´´, it´s easier to use a text editor that  includes  direct
              support  for  these characters and let ConTeXt translate them to
              the necessary TeX commands.  For some languages,  this  approach
              can  also  improve  the  performance  of TeX´s hyphenation algo-
              rithms.

              ConTeXt supports several of the most  commonly  used  encodings.
              Check  the  files  beginning with enco-, lang-, and font- in the
              ConTeXt distribution for more information.

              web2c distributions (such as teTeX) support a mechanism  to  map
              document  encodings  to ConTeXt´s internal encoding, font encod-
              ings, and hyphenation patterns.   texexec  provides  a  document
              option and a command-line flag to pass the necessary information
              to tex(1) or pdftex(1).  You can add lines such as


                   %& --translate-file=cp1250pl

              or


                   % --translate=cp1250pl


              to the beginning of your document, or  specify  the  --translate
              flag on the command line, as


                   texexec --translate=il2pl somefile


              Note  that using language-specific encodings will make your file
              less portable than using ASCII.  It  may  not  be  possible  for
              other people to typeset your documents on their systems.


FILES

       TEXMF/context/config/texexec.ini
              TeXExec configuration file

       TEXMF/context/config/texexec.rme
              TeXExec configuration file defaults



SEE ALSO

              bibtex(1),   dvips(1),  fmtutil(1),  makeindex(1),  metapost(1),
              mpost(1), pdfetex(1), pdfmerge(1), pdftex(1), perl(1), psnup(1),
              tex(1), texshow(1), texutil(1).

              The TeXExec manual, mtexexec.pdf.

              The TeXExec configuration README files:

       o      TEXMF/context/config/texexec.rme

       o      TEXMF/context/perltk/texexec.rme

              Donald E. Knuth´s The TeXbook.


AUTHOR

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

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



ConTeXt                          October 2000                       texexec(1)

Man(1) output converted with man2html