|
| 1 | +# Getting Started: Build Your First Document |
| 2 | + |
| 3 | +Now that [you’ve installed Tectonic][install], let’s create and build your first |
| 4 | +[document]. |
| 5 | + |
| 6 | +[install]: ./install.md |
| 7 | +[document]: ../ref/documents.md |
| 8 | + |
| 9 | +**Important:** *From here on out, this [Getting Started][gs-index] guide will |
| 10 | +use what we call the [“V2” interface][v2cli] to the Tectonic program. The V2 |
| 11 | +interface coexists with, but has a fairly different approach than, the [“V1” |
| 12 | +interface][v1cli]. We are gradually migrating from V1 to V2. Neither interface |
| 13 | +(V1 or V2) is the same as the one exposed by classic TeX tools such as |
| 14 | +`pdflatex`.* |
| 15 | + |
| 16 | +[gs-index]: ./index.md |
| 17 | +[v2cli]: ../ref/v2cli.md |
| 18 | +[v1cli]: ../ref/v1cli.md |
| 19 | + |
| 20 | + |
| 21 | +## Create a new document |
| 22 | + |
| 23 | +The Tectonic [V2 interface][v2cli] has a “multitool” structure similar to that |
| 24 | +of other powerful tools such as [git] and [cargo]. To create a new document, we |
| 25 | +use a [`new`][cli-new] subcommand that looks like this: |
| 26 | + |
| 27 | +```sh |
| 28 | +$ tectonic -X new myfirstdoc |
| 29 | +``` |
| 30 | + |
| 31 | +[git]: https://git-scm.com/ |
| 32 | +[cargo]: https://doc.rust-lang.org/cargo/ |
| 33 | +[cli-new]: ../v2cli/new.md |
| 34 | + |
| 35 | +This will create a new [Tectonic workspace][workspace] directory named |
| 36 | +`myfirstdoc` containing a file `Tectonic.toml` and a sub-directory named `src`. |
| 37 | +Enter this new directory in your command prompt. |
| 38 | + |
| 39 | +[workspace]: ../ref/workspaces.md |
| 40 | + |
| 41 | +```sh |
| 42 | +$ cd myfirstdoc |
| 43 | +``` |
| 44 | + |
| 45 | +**Note:** *The `-X` flag activates the V2 interface. Don’t forget it! Eventually |
| 46 | +it will become unnecessary and you’ll just be able to write `tectonic new`, but |
| 47 | +that changeover hasn’t happened yet.* |
| 48 | + |
| 49 | + |
| 50 | +## Basic document source structure |
| 51 | + |
| 52 | +The source code to your document is stored in the `src` subdirectory of your new |
| 53 | +document. Check it out: |
| 54 | + |
| 55 | +```sh |
| 56 | +$ ls src |
| 57 | +``` |
| 58 | + |
| 59 | +You’ll see three files that were created by the [`new`][cli-new] command: |
| 60 | + |
| 61 | +- `_preamble.tex` |
| 62 | +- `index.tex` |
| 63 | +- `_postamble.tex` |
| 64 | + |
| 65 | +These files are pre-populated with extremely basic contents following this |
| 66 | +suggested source structure: |
| 67 | + |
| 68 | +- The “preamble” file should contain all of your (La)TeX initialization |
| 69 | + boilerplate, up to and including the LaTeX `\begin{document}` command. |
| 70 | +- The “index” file contains all of your actual document content, without any of |
| 71 | + the annoying boilerplate. When you create a new Tectonic document, it just |
| 72 | + contains the text `Hello, world.` |
| 73 | +- The “postamble” file should contain all of your cleanup code, starting with |
| 74 | + the LaTeX `\end{document}` command. There will almost never need to be any |
| 75 | + other content in this file. |
| 76 | + |
| 77 | +When Tectonic builds your document, it processes these files in the order listed |
| 78 | +above, so all three of them need to be available. But the breakdown suggested |
| 79 | +above is only a suggestion, nothing more. If you want all of your boilerplate |
| 80 | +and content to be in a single file, we recommend putting it all in `index.tex` |
| 81 | +and making your preamble and postamble be empty. |
| 82 | + |
| 83 | +The motivation for this separation is partially stylistic, but not entirely so. |
| 84 | +In the future, we anticipate that there might be different ways to build the |
| 85 | +same document that invoke different preamble or postamble contents. |
| 86 | + |
| 87 | + |
| 88 | +## Building your document |
| 89 | + |
| 90 | +To compile your document, run: |
| 91 | + |
| 92 | +```sh |
| 93 | +$ tectonic -X build |
| 94 | +``` |
| 95 | + |
| 96 | +If you haven’t run Tectonic on your computer before, this command will take a |
| 97 | +minute or two as it downloads the support files that it needs and generates the |
| 98 | +LaTeX “format file” storing the default macro collection. Tectonic will cache |
| 99 | +these files and avoid downloading them again. Test it out by running the build |
| 100 | +again: |
| 101 | + |
| 102 | +```sh |
| 103 | +$ tectonic -X build |
| 104 | +``` |
| 105 | + |
| 106 | +This time the command should finish much more quickly, with no messages about |
| 107 | +downloading files. The output PDF document will be placed at the path |
| 108 | +`build/default/default.pdf` relative to your document directory: |
| 109 | + |
| 110 | +```sh |
| 111 | +$ ls -l build/default/ |
| 112 | +``` |
| 113 | + |
| 114 | +If you’re familiar with traditional TeX engines, you’ll have noticed that |
| 115 | +Tectonic’s “user experience” is substantially different from those engines: |
| 116 | + |
| 117 | +1. Tectonic doesn’t print out the usual chatter — unless there’s an error. |
| 118 | +2. Tectonic automatically reruns the TeX stage until its output stabilizes. |
| 119 | +3. By default, Tectonic doesn’t write out intermediate files such as |
| 120 | + (`texput.aux`, `texput.log`). |
| 121 | +4. You ought not have seen this yet, but if you make a mistake in your TeX, |
| 122 | + Tectonic will quit with an error message, rather than asking you to type `X2` |
| 123 | + or whatever. |
| 124 | + |
| 125 | +We hope that you’ll agree that these changes make for a program that is much |
| 126 | +more pleasant to use than the traditional tools. |
0 commit comments