This package has been deprecated

Author message:

This project has not been maintained since mid 2016. Consider other options like Overleaf or latexmk :)

TeXgo

---

• --watch functionality not yet implemented.

---

This CLI utility simplifies use of LaTeX by streamlining compilation and providing easy-to-use watch/rebuild functionality.

It works for basic LaTeX projects and outputs only the resultant PDF file, using the standard set of commands:

pdflatex myfile.tex
bibtex myfile
pdflatex myfile.tex
pdflatex myfile.tex

It skips the bibtex command if no .bib file is supplied or found in the project's root.

This is the only LaTeX use case the author has had to deal with so far, which is his attempt at explaining why that's all that's supported. If you've other use cases, such as needing to deal with postscript or other output files, please contact the author and/or possibly consider contributing some code.

Installation

This script is built using Node.js, and can be installed using npm.

npm install -g texgo

Usage Summary

Navigate to the root directory for your LaTeX project and:

texgo

This'll try finding the main .tex and .bib file, run the compilation and leave you with only the output .pdf (keeping all of the other clutter away for you).

Optionally configure with .texgorc or ~/.config/texgo. Commit the .texgorc to version control and share, then all anybody needs to do is texgo!

Consider bringing Docker into the mix, so nobody even needs to worry about installing LaTeX!

Detailed Usage

---

texgo --help
texgo -h

The help commands provide a useful, quick summary of usage. This README, however, is a more thorough and explained form of documentation.

Each of the options covered below can be provided via configuration, on a global, per-project or mixed basis, allowing you to simply execute texgo once configured.

---

This package assumes any required LaTeX commands and resources are available to the user executing the command, unless you decide to use Docker (as described in the Using Docker section below).

Enter the root directory of your LaTeX project and execute one of:

texgo # to simply compile the document once -
      # works without extra parameters if there's only one `.tex` file in the root directory.
texgo main.tex # to specify which is the main `.tex` file.

texgo --watch # to compile once, and then watch for changes such to compile responsively.
texgo -w # is the same as above.
texgo -w main.tex # is again needed if there are multiple `.tex` files to choose from.

A .bib file must also be specified if more than one happen to be present in the root directory:

texgo --bib main.bib
texgo -w -b main.bib main.tex # is the same as above,
                              # but also watching and specifying a main `.tex` file.

You can also execute TeXgo from elsewhere by specifying the root directory explicitly:

texgo --dir ../myproject
texgo -d ../myproject -w # is the same as above, with watching.

# You mustn't prefix the start `.tex` file if there is one -
# it will be located relative to the specified root directory.
texgo -d ../myproject -w main.tex

• --watch will fail without --force if the output file already exists on its first compilation - after the first compilation it will be fine to overwrite itself without --force.

Output

The output PDF file will by default be written to a file in the root directory, with the same name as the main .tex file, but of course with .pdf as its extension instead. This can be changed by providing an additional option:

texgo --output ../output/myproject.pdf
texgo -o ../output/myproject.pdf # which is the same as above -
                                 # the invocation will fail because it will _not_ overwrite that file.

texgo --force -o ../output/myproject.pdf # however, will overwrite an existing output file.
texgo -f -o ../output/myproject.pdf -w main.tex # is the same as above, with watching and a main file.

Using Docker

TeXgo can be used without having LaTeX installed on the host system with thanks to Docker.

Basically, instead of attempting to run the LaTeX compilation scripts on the host system, TeXgo can use Docker to pull down a Docker image with LaTeX installed, and use the commands within that instead.

This shifts the requirement from having LaTeX installed and available on your system, to having Docker installed and available on your system. Docker would then pull down a LaTeX image, which takes time. Once pulled, future invocations would of course operate much faster.

The main benefit here is portability. If working with a complex LaTeX build which involves many additional packages (outside of texlive-full), other users may have trouble compiling your document. If you're able to shift that complexity into a Dockerfile, then anybody can simply type texgo and know they're getting exactly the same results as you.

Prerequisites:

If you can successfully run this command (without sudo), then you should be good to go:

docker run --rm hello-world

Use TeXgo with Docker:

# Use the default image: `tianon/latex:latest`.
texgo --docker
texgo -D # is the same as above.

# Specify your own Docker image.
# `myImages/latex:lite` is fictional - replace with yours.
texgo --docker --image myImages/latex:lite
texgo -D -I myImages/latex:lite # is the same as above.

About the Docker image..

The default Docker image used is tianon/latex:latest, because it's dead simple and contains texlive-full, which should work for almost everybody. It also happens to currently (2016/07/04) be the most popular LaTeX repository.

Unfortunately, texlive-full isn't small, so that image weighs in at ~4Gb... For that reason, it may be wise to docker pull tianon/latex:latest beforehand (because the pull subcommand provides more information - you might think something's going wrong when run tries to pull it (because it doesn't show a progress bar)).

Alternatively, you can roll your own, more light-weight LaTeX Dockerfile starting from texlive-base or texlive-latex-recommended, and only add in the things you need to get your project compiling. That Dockerfile can operate locally, as long as it's tagged appropriately.

Thanks to...

blang/latex-docker for partial inspiration.

Configuration

To avoid having to specify parameters like --output (and possibly even --force if you're so willing) many times, this utility supports provision of configuration files as per the rc package.

This can be considered as the default configuration, which acts as if no parameters were provided:

dir=
main=
bib=
output=
force=
docker=
image=

Here's an example configuration, which can be automatically loaded if written a file named .texgorc in the current directory, wherever that may be:

dir=../myproject
main=main.tex
bib=main.bib
output=../output/myproject.pdf

; Any non-blank value will enable the force option.
force=1

Now you can simply execute texgo or texgo -w and your configuration will be picked up and used.

As briefly mentioned, this worked because a file named .texgorc was present in the directory that the texgo command was being executed. The rc package describes many other ways to provide such a configuration file (i.e. in ~/.config/texgo or specified via --config).

• Any options specified as part of the command will take precedence over those found in configuration files.
• Configuration is loaded when the command is initially executed, so it won't be automatically updated if changed during a texgo --watch.

Using Docker

If you wanted to use Docker across your system, instead of installing LaTeX yourself, you could use ~/.config/texgo to avoid typing --docker and --image many times:

docker=1

; If you need to use a custom image.
image=myImages/latex:lite

If you had a particular project which had a custom LaTeX installation/configuration, you could try to create a Dockerfile and replicate that installation, and then include that in the project's .texgorc.

This means you could reformat your computer or come back in a year's time, and still get up and running without missing a beat, or share the project with someone else and not worry about them not having correct dependencies, or configuring TeXgo - all they'd have to do is type texgo!

Caveats and Assumptions

• The set of executed compilation commands is not modifiable.
• Does not support bibliography packages that require commands other than bibtex to function.
• If a --dir is specified which is not the current directory, it will not be checked for RC files.
• If LaTeX tries to relatively refer to files outside of the root directory of the project, it will not find those files. This is because the root directory is copied to and used from a temporary location.
• Only supports output of the single resultant PDF.
• The compiled PDF is expected to have the same filename as the main .tex file, but of course with the appropriate file extension.