mk

mk - a LaTeX maker

Synopsis

    mk - a LaTeX maker

    Usage: mk [options] [file]

    mk-specific options:
        -C, --Clean             Remove all unnecessary files generated by latex and bibtex
        -c, --clean             Same, except for the pdf or postscript files
            --ps                Generate postscript version of document (default: pdf)
            --edit=STRING       use STRING as the file to be edited
        -w, --[no-]warn         After a successful run, print warnings found in the log file

    vpp-related options:
        -b, --batch=STRING      run in batch using STRING for print command
        -p, --printer=STRING    print to printer named STRING
        -d, --doublesided       printer is double sided
            --[no-]view         do [not] view the document
            --[no-]print        do [not] offer printing interaction

    General options:
        -r, --rc=STRING         use STRING as an rc file
        -V, --version           print version and exit
        -v, --[no-]verbose      be [not] verbose (quiet is the default)
            --[no-]check        do [not] check the availability of executables
        -h, --help              print this help and exit

    Defaults:
    --no-warn --print --view --no-verbose --no-check main

    Required gems (gem install <gem name> -r):
      rubygems term-ansicolor

    Required other programs:
      CTAN: latex pdflatex vpp texi2dvi scriptingutils.rb

Copyright

Copyright (C) 2009 Wybo Dekker (wybo@servalys.nl)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see www.gnu.org/licenses.

Introduction

mk is a Ruby script that, in close collaboration with vpp, is helpful in the cyclic process of editing, viewing, and printing a latex document. Having an existing latex document, say main.tex (see the section ‘Locating the source’ for the creation of new documents and for other extensions than .tex), you run mk by typing:

    mk main

or, since main happens to be mk‘s default filename:

    mk

Now, if main.tex is a valid latex source, mk compiles it, including any table of contents, indices, bibliography references, included files, and so on and vpp takes over and displays the resulting PDF or, with the —ps option, PostScript output. When you leave the viewer you will see a prompt:

    vpp command (h for help):

If you are satisfied with the displayed output, you can now decide to print all or part of your document (see the section ‘Page selection’), or you can simply quit by typing ‘q’. On the other hand, if you decide that you want to change the source and have another try, you can edit the source by typing ‘e’ to get back to mk and (re)edit your source. After saving your work and leaving your editor, another compilation and display cycle will be performed, based on the new source.

Essentially, mk uses texi2dvi for compilation. texi2dvi always runs TeX at least once, even though this may be unnecessary. Therefore, TeX will be run with the —recorder option, which reports all the target‘s dependencies in a .fls file. In every cycle, mk analyses the .fls and the tex and bibtex log files to see if a compilation is needed. When errors have occurred, mk uses the log files to find out which file has to be edited, and at which line. This can also be an \input-ed file, a style file, or any other file on which the target depend. However, files in the TEXMFMAIN tree are excluded.

Page selection

As said in the introduction, after a successful compilation and display of the resulting PDF or PostScript output, the user is prompted with:

    vpp command (h for help):

on typing ‘h’ vpp displays examples of possible commands:

Examples of print commands:

    5       to print page 5
    5-      to print pages 5 through the end
    5-7     to print pages 5, 6 and 7
    -7      to print the first 7 pages
    5-7,19- to print pages 5, 6, 7 and 19 through the end
    a       to print the whole document
    -       to print the whole document
    a x3    to print 3 copies of the document
    x3      the same
    5 x3    to print 3 copies of page 5
    t       print the whole document two sided
    t 2-    print two sided starting at page 2
    b       to print the whole document as an a5 size booklet
    b -12   to print the first 12 pages as an a5 size booklet

Other commands:

    e       (if called by mk) edit the tex source and rerun mk
    c       (if called by mk) rerun mk
    v       (re)view the ps/pdf file
    oxyz    send pdf output to file xyz.pdf instead of printer
    pxyz    print to printer xyz
    dx      tell vpp printer is doublesided (x=t) or singlesided (x=f)
    h       display this help
    ?       display this help
    q       quit

With these examples, no further explanation should be necessary, except that, when twosided (‘t’) or booklet (‘b’) printing is selected for a single-sided printer, printing will be performed in two shifts, one for the front side and one for the backside. Between the shifts, another prompt appears:

    printer ready? then turn stack and type return

You will have to arrange your printer such that, with the printed sides up, the first page printed will be at the bottom of the stack, and the last page printed will be on top. Normally you will then have your output come out the back of your printer. ‘Turn the stack’ then means: rotate it over the long side of the paper and feed it back into the printer for the other side to be printed.

For further information on vpp, look in its manpage by typing

    vpp -h

or read the vpp documentation.

Locating the source

mk locates the latex source in several steps: (here the source extension .tex is supposed, but .ltx, .drv and .dtx will also be tried)

1. If you supply no arguments, the file main.tex in the current directory is assumed.
2. If you supply an argument (say myfile), mk adds a .tex extension if it isn‘t there and looks for myfile.tex in the current directory.
3. If myfile.tex is not found in the current directory, mk looks in the ‘alternate directory’ (say /Documents) if you have defined one (see the section ‘RC files’).
4. If the source was not found in /Documents, mk thinks that you may have a subdirectory myfile in /Documents where the source may live under the name main.tex
5. If that file is not there, mk now concludes that the source does not yet exist and reports this, telling at the same time which files have been tried.
6. Finally, if all the above did not lead to a source file, mk dies.

The TeX format to be used

mk will try to find out what TeX format is is needed to compile the source. The most straightforward way to tell mk what format to use is to insert a comment line with one of the following (case-insensitive) strings on a single line:

    %!pdflatex:: forces _pdflatex_ or, with the <tt>--ps</tt> option, _latex_
    %!latex::    forces _latex_ (and sets the <tt>--ps</tt> option)
    %!xelatex::  forces _xelatex_
    %!xetex::    forces _xetex_

If none of these is found, mk looks for a \usepackage{fontspec} or \RequirePackage{fontspec} and, if found, uses xelatex. The \usepackage may have options, but the must be on one line.

If still no decision could be made, mk looks for \documentclass and chooses pdflatex or, with the —ps option, latex

Finally, if no match was found, pdftex is assumed or, with the —ps option, tex.

Options

mk comes with several options. Before evaluating any options, mk will try to read a system rc file, a user rc file, and, finally an rc file in the current directory. The default values for most options can be set in these files. See the section ‘RC files’ for more information.

You can also set option defaults in an alias. For example:

    alias mk='mk -no-verbose'

  mk --batch '2-3 x3' test

RC files and customization

Unless the environment variable NORC has been set, three rc files are executed, if they exist, before reading the command line options, in the following order:

You can use these rc files to set the default values for the options, by setting the global Ruby Perl variable named after the long version of the options. For example:

    @verbose = true # run in verbose mode

So if you usually like mk to work in verbose mode, you can indicate so in your rc file and change your mind in some cases by using the —no-verbose option.

Other variables, not having a corresponding command line option, that can be set in the rc files, and their default values, are:

  mk myfile

  @warnings_to_skip=[
    'Package hyperref Warning: Token not allowed in a PDFDocEncoded string',
    'Package array Warning: Column [XY] is already defined on '
  ]

TeXWorks and mk

mk can can be used for one-click typesetting:

  edit -> preferences -> Typesetting
  add a new tool `mk' and give it three parameters:
  --noview
  --noprint
  $basename
  Deselect "Auto-hide output panel unless errors occur"

mk runs pdflatex with the —synctex=1 option, so you will be able to jump betwee source and pdf-ouput.

Bugs

Currently, mk is only available for unix.

Required files