From Wiki
Revision as of 17:31, 14 December 2021 by BruceH2020 (talk | contribs) (Re-formatted synctex instructions to make them clearer and stressed the importance of setting the alternate path preferences entry.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


TeXShop is a good editor for all variants of TeX and ConTeXt. It offers:

  • syntax highlighting;
  • a viewer for your typeset PDFs;
  • two-way synchronisation (SyncTeX) between source and PDF;
  • templates (and you can create your own);
  • command completion;
  • multiple file encodings.

Here, only a summary of the main configuration relevant to ConTeXt is provided. This should get you up and running, but for more detailed documentation, refer to TeXShop > Help > Changes. Also, check the stuff inside ~/Library/TeXShop/, in particular, the folders Engines/Inactive/ConTeXt-Sync, and ExternalEditorScripts if you plan to use TeXShop as a previewer for an external editor.

If you have installed MacTeX (the TeX Live distribution for macOS), you may start typesetting right away. If TeXShop was installed with MacTeX, you may find it in the /Applications/TeX folder; otherwise, it will likely be in your /Applications folder. Open a ConTeXt document with TeXShop, choose the ConTeXt (LuaTeX) engine from the drop-down menu in the toolbar of the source window, and typeset!

Most likely, though, you will want to use the most up to date ConTeXt release (see Installation). For that, you need to perform the following one-time set up:

  • In the Finder, Option-click on the Go menu and select Library (this menu entry may not be visible if you do not keep Option pressed while clicking). TeXShop installs support files for every user in the folder TeXShop in the user's Library folder of the user's home folder. They are installed first when the user runs TeXShop for the first time.
  • Go into TeXShop > Engines > Inactive > ConTeXt-Sync. Move or copy the file ConTeXt2021.engine into the Engines folder.
  • Close and reopen TeXShop. The new ConTeXt2021 engine should now appear in the toolbar drop-down menu.
  • Open Terminal.app, then type the following to make the engine executable and press Enter:
chmod 755 ~/Library/TeXShop/Engines/ConTeXt2021.engine

You may close the terminal.

  • Back in TeXShop, go to Preferences > Engine and adjust the Alternate Path text field to point to the full path of your local ConTeXt installation.

Now, every time you edit a ConTeXt document and want to use your local installation instead of MacTeX's, add the following “magic lines” right at the beginning of your source document:

% !TEX TS-program = ConTeXt2021
% !TEX useAlternatePath

Then, typeset your document. You do not need to select the correct engine from the drop-down menu when % !TEX TS-program is used: TeXShop will pick up the engine specified in the source. Verify in the Console window that the correct ConTeXt distribution is used for typesetting.

Syncing between Source and PDF

As of July 2021, ConTeXt provides support, through its Swiss army knife mtxrun script, for getting the filename and line corresponding to a certain spot in a PDF document, and for getting the PDF coordinates (page number + bounding box) corresponding to a given line in a source file. Type this in a terminal window to get some information about this nifty feature:

mtxrun --script synctex --help

Editors can exploit this feature to provide smooth syncing between source code and PDF.

TeXShop v4.66 and later has adopted ConTeXt's syncing method. When this method is enabled (see the “magic line” below), Cmd-clicking somewhere in the preview window jumps to the source window and highlights the corresponding line. Vice versa, Cmd-clicking somewhere in a source window jumps to, and highlights, the corresponding spot in the preview.

To enable syncing:

  1. Make sure that you are using the latest ConTeXt release
  2. Make sure that you are using TeXShop v4.66 or later
  3. Add the following “magic lines” at the start of your source document:
    % !TEX useAlternatePath
    % !TEX useConTeXtSyncParser
  4. Make sure that your document generates a .synctex file. Your source should contain this line:

    or this:

  5. Make sure the TeXShop preferences setting “alternate path” is set to the path to your LMTX installation. A typical example for an Intel-based Mac is:
    TeXShop -> Preferences -> Engines -> Alternate path == /Users/<username>/Applications/context-osx-64/tex/texmf-osx-64/bin 

    If you do not do this or get this wrong then the editor will fail to sync from source to PDF or back without any error message.

You may find that you need to quit and restart TeXShop to get it to take account of changes you make to the above.

Then, typeset your document and try Cmd-clicking either in the source or in the preview. This is a minimal example that allows you to test syncing within TeXShop:

% !TEX TS-program = ConTeXt2021
% !TEX useAlternatePath
% !TEX useConTeXtSyncParser


Sed ut perspiciatis unde omnis iste natus error sit voluptatem
accusantium doloremque laudantium, totam rem aperiam, eaque
ipsa quae ab illo inventore veritatis et quasi architecto
beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem
quia voluptas sit aspernatur aut odit aut fugit, sed quia
consequuntur magni dolores eos qui ratione voluptatem sequi
nesciunt. Neque porro quisquam est, qui dolorem ipsum quia
dolor sit amet, consectetur, adipisci velit, sed quia non
numquam eius modi tempora incidunt ut labore et dolore magnam
aliquam quaerat voluptatem. Ut enim ad minima veniam, quis
nostrum exercitationem ullam corporis suscipit laboriosam, nisi
ut aliquid ex ea commodi consequatur? Quis autem vel eum iure
reprehenderit qui in ea voluptate velit esse quam nihil
molestiae consequatur, vel illum qui dolorem eum fugiat quo
voluptas nulla pariatur?

Syncing works even with complex documents made of several source files. Backward syncing (from PDF to source) works without any additional settings. To make forward syncing work (i.e., jumping from an included source to the PDF), you need to tell TeXShop which is the “root” document of each included file. That is done by adding yet another “magic line” to all included sources:

% !TEX root = <MAIN>.tex

where <MAIN>.tex is the name of your root source. If your included files are in a different folder, you need to specify the correct (relative) path to the root document. Refer to TeXShop's documentation to learn more about this and the other “magic lines”.

TeXShop still supports an old syncing method, which is based on Jérôme Laurens's SyncTeX, but using that for ConTeXt is not recommended any longer, so how to use that will not be explained in this document. Just note that the Sync Method preference in Preferences > Typesetting is not relevant for the new syncing method described above; it is strongly recommended that it is set to SyncTeX (TeX ≥ 2010) anyway.

Syncing with an External Editor

TeXShop can be used as a previewer for an external editor. If you want to edit your source files in a different editor, go to TeXShop > Preferences > Source, and check Configure for External Editor. Then, close and reopen TeXShop.

Detailed instructions about configuring TeXShop to synchronise with an external editor are provided in TeXShop > Help > Changes and in the documents located in the ~/Library/TeXShop/Engines/Inactive/ConTeXt-Sync and ~/Library/TeXShop/ExternalEditorScripts folders—so such instructions will not be repeated here, also because they depend on which editor you are using.

The following are a few things you may want to keep in mind if you use an external editor. They certainly apply to TeXShop v4.66; more recent releases may have rectified some of the issues or improved the user experience:

  • TeXShop v4.66 does not (yet) support forward syncing from an included source. Forward syncing is supported for the root source document of a document consisting of many source files or for a single-source document, though.
  • For syncing to work with an external editor, make sure that only one preview window (the preview of the document you are currently editing) is opened in TeXShop; otherwise, syncing may not work. Depending on the editor, you may also need to keep only one source window open in your editor.
  • If syncing with an external editor still does not appear to work, and you are sure that you have followed the instructions and your configuration is correct, make sure that the relevant “magic lines” appear in your source document and try typesetting your document once from within TeXShop, by selecting the menu entry Typeset > Typeset (the PDF of your document must be opened in TeXShop, of course). Then, try syncing again. If syncing in one direction does not work, try syncing in the other direction first.
  • Even if Configure for External Editor is checked in your preferences, always open the .tex file in TeXShop, rather than the .pdf file. TeXShop will open the PDF anyway, but by choosing the .tex file, it may have an opportunity to parse the “magic lines” of the source code and configure itself correctly for ConTeXt (provided that your source file contains the relevant magic lines!).

Syncing is Buggy: To Whom Should I Report It?

The new ConTeXt syncing in TeXShop works by invoking ConTeXt's command-line tool mtxrun. This has two advantages:

  • it simplifies the code required in TeXShop to deal with synchronisation;
  • it allows ConTeXt's developers to continue improving synchronisation independently, and TeXShop can automatically benefit from such improvements (as long as mtxrun's interface does not change).

There is one drawback: if something breaks, who is to blame?

If Cmd-clicking somewhere has an effect, e.g., TeXShop jumps somewhere but perhaps not at the right spot, it is more likely that mtxrun is to blame. So, it is recommended to verify that by invoking mtxrun directly. For instance, if test.tex is the name of the minimal example above, then a terminal session may go like this ($ is the shell prompt: it must not be typed):

$ cd <path to test.tex source directory>
$ export PATH=~/context-osx-64/tex/texmf-osx-64/bin:$PATH  # Make sure ConTeXt beta is used (Intel macOS executable)
$ mtxrun --script context --autogenerate test.tex

Now, a file called test.synctex should exist. Test ConTeXt's synctex script for forward syncing:

$ mtxrun --script synctex --find --file=test.tex --line=12 --direct test.synctex

page=1 llx=354 lly=178 urx=423 ury=193

The output shows the page in PDF to jump to and the bounding box of the region to highlight. Then, test backward syncing:

$ mtxrun --script synctex --report --page=1 --x=350 --y=180 --console test.synctex
"test.tex" 11 0

The output shows the source path, the line number (11), and a tolerance (0), which will be positive if the input coordinate is slightly outside any bounding box recorded in the .synctex file.

If mtxrun output looks accurate enough, then probably TeXShop is at fault; otherwise, report the issue to ConTeXt's mailing list.

If, on the other hand, Cmd-clicking somewhere has no effect whatsoever, then TeXShop might be at fault. But since the configuration for synchronisation is not trivial, be sure to double-check everything explained above before reporting an issue to TeXShop's author. In particular, if you are working with a complex document consisting of many files, make sure that each one has a % !TEX root directive (the space between % and ! is mandatory in magic lines) and the other necessary magic lines. Make also sure that you are typesetting with a sufficiently recent ConTeXt release.

If you have configured TeXShop to use an external editor, be sure to (re)read TeXShop's documentation: although syncing with an external editor works (with some limitation for complex documents), you may have to work a bit harder than necessary to convince TeXShop to synchronise with your editor. See the remarks above.

Making UTF-8 Default File Encoding

ConTeXt uses UTF-8 as its default encoding, so it is best to make this the default encoding for your files. You can also choose whichever encoding you wish. You can also set the file encoding when a document is saved. TeXShop will automatically recognize the file encoding of existing files and use that when saving the file.

To make TeXshop use utf-8 as its standard encoding for files, proceed as follows:

  • Start TeXShop.
  • Go to Preferences > Source, and choose Unicode (UTF-8) from the drop-down menu in the Encoding group.
Creating an Engine for TeXShop

Actually, engine is somewhat misleading. In TeXShop an engine is a script that contains commands that are use to typeset your documents. TeXShop comes with many engines set up to run TeX, LaTeX, Xe(La)TeX and ConTeXt MKII and MKIV that have been installed via MacTeX.

If you want to use ConTeXt Suite you will have to create an TeXShop-engine.

If you have not run TeXShop start it so that the support files for TeXShop are installed for you.

Since in the newer versions of MacOS the users Library-folder is hidden and not accessible from within TeXShop we will use the terminal for simplicity reasons. If you wish you can access the your Library-folder from the Finder and navigate to the Engines-folder inside of the TeXShop-folder inside your Library-folder and choose a ConTeXt-engine.

  • Start the Terminal you will find it in the Utility-folder in the Applications-folder
  • Find your username is, if you do not know it already.

    The command whoami will output your user name.

  • Open the standard MKIV engine for TeXShop enter
open -a TeXShop $HOME/Library/TeXShop/Engines/ConTeXt\ \(LuaTeX\).engine

This will open the file in TeXShop and switch to TeXShop

  • Save the engine with a new Name "ConTeXt Suite":
 option click on the File menu 
 choose "Save As …"
 change (LuaTeX) in the Name field to Suite
 hit return
  • Change the set path line to:
set path= (/Users/username/context/tex/texmf-osx-64/bin  $path /usr/local/bin)
If you installed in a different location then change /Users/username/context/ to the location where you
installed ConTeXt standalone. Do not forget to change username in the line above to your actual username!! 
  • Save the file again
use either the file menu or cmd-s
  • close the window
use either the file menu or cmd-w

You can know use your new engine by choosing it from the Pop-up Menu of your document window.

If you want other options or use MKII then create a new engine and change the line containing mtxrun accordingly.

In the manual for TeXShop you can find instructions for making your engine the the default engine or how to have TeXShop use your engine no matter which engine is set on a file by file basis.

Setting-Up TeXShop for ConTeXt Suite System-Wide Installation

Making a decent tutorial for setting-up TeXShop for a ConTeXt Suite system-wide installation is kind of difficult, because TeXShop installs support files for each user which become unique to each user after it has been started for the first time by the user. The problem is how get the needed engine/s for the ConTeXt Suite into the user support files.

You can put the engine in into the application bundle of TeXShop, so that it will be installed for every user the first time they run TeXShop or a new version of TeXShop is run. Of course you have to the engine into the application bundle of each update to TeXShop!

  • Start TeXShop
  • create a new document

use the File-Menu or use cmd-N

  • save the engine
 use the File-Menu or use cmd-S
 In the dialog window change the name of the file to ConTeXt Suite.engine or whatever!
 In the lower part of the dialog change the file format to Plain Text
  • enter the following content into the document:
 set path= (/Users/quayjay/context/tex/texmf-osx-64/bin  $path /usr/local/bin)
 mtxrun --script context --autogenerate --synctex=1 "$1"
  • Save the engine

use the File-Menu or use cmd-S

  • Quit TeXShop
  • Open 2 windows in the finder
  • In one window and navigate to where you saved the engine
  • In the other window navigate to the Applications-folder and to where TeXShop was installed.
If you installed via MacTeX you will find it in Applications->TeX->TexShop

  • Open the folder containing the default engines for TeXShop

press: shift-cmd-G in the dialog enter: TeXShop.app/Contents/Resources/TeXShop/Engines

  • copy the engine from the other window using 'option'-drag
 You will be ask for an administrator password: enter it!
  • close the windows

'IMPORTANT:' The newly created engine will not be installed if a user has already run TeXShop! If a user has already run TeXShop then the newly created engine must copied to their Engine-folder inside of their TeXShop-folder inside their Library-folder!!

Do not forget that you have to also copy your own copy of the newly created engine to your own Engine-folder!!