93
edits
Changes
Jump to navigation
Jump to search
Also, make <li>Make sure that your document enables the generation of the generates a <code>.synctex</code> file. Your source should contain this line: <pre>\setupsynctex[state=start,method=min]</pre>
<pre>\setupsynctex[state=start]</pre></li><li>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:<pre>TeXShop -> Preferences -> Engines -> Alternate path == /Users/<username>/Applications/context-osx-64/tex/texmf-osx-64/bin </pre><i><b>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.</b></i></li></ol>You may find that you need to quit and restart TeXShop to get it to take account of changes you make to the above.
Re-formatted synctex instructions to make them clearer and stressed the importance of setting the alternate path preferences entry.
= TeXShop =
TeXShop is a good Editor editor for all variants of TeX and ConTeXt. It offers:
* syntax highlighting;
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:
* Go into ''TeXShop > Engines > Inactive > ConTeXt-Sync''. Move or copy the file <code>ConTeXt2021.engine</code> 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 executble executable and press Enter:
chmod 755 ~/Library/TeXShop/Engines/ConTeXt2021.engine
You may close the terminal.
Then, typeset your document. You do not need to select the correct engine from the drop-down menu when <code>% !TEX TS-program</code> 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 between Source and PDF ===== As of July 2021, ConTeXt provides support , through its Swiss-army knife <code>mtxrun</code> 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
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 this feature, make syncing:<ol><li> Make sure that you are using the latest ConTeXt release, and add </li><li> Make sure that you are using TeXShop v4.66 or later</li><li> Add the following additional “magic line” lines” at the start of your source document: <pre>% !TEX useAlternatePath% !TEX useConTeXtSyncParser</pre></li>
or this:
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:
</nowiki>
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 your projecteach included file. That is done by adding yet another “magic line” to all included sources:
% !TEX root = <MAIN>.tex
where <code><MAIN>.tex</code> 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 <code>.tex</code> file in TeXShop, rather than the <code>.pdf</code> file. TeXShop will open the PDF anyway, but by choosing the <code>.tex</code> 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 <code>mtxrun</code>. 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 <code>mtxrun</code>'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 <code>mtxrun</code> is to blame. So, it is recommended to verify that by invoking <code>mtxrun</code> directly. For instance, if <code>test.tex</code> is the name of the minimal example above, then a terminal session may go like this (<code>$</code> is the shell prompt: it must not be typed):
<nowiki>
$ 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
</nowiki>
Now, a file called <code>test.synctex</code> should exist. Test ConTeXt's synctex script for forward syncing:
<nowiki>
$ mtxrun --script synctex --find --file=test.tex --line=12 --direct test.synctex
page=1 llx=354 lly=178 urx=423 ury=193
</nowiki>
The output shows the page in PDF to jump to and the bounding box of the region to highlight. Then, test backward syncing:
<nowiki>
$ mtxrun --script synctex --report --page=1 --x=350 --y=180 --console test.synctex
"test.tex" 11 0
</nowiki>
The output shows the source path, the line number (<code>11</code>), and a tolerance (<code>0</code>), which will be positive if the input coordinate is slightly outside any bounding box recorded in the <code>.synctex</code> file.
If <code>mtxrun</code> 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 <code>% !TEX root</code> directive (the space between <code>%</code> and <code>!</code> 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=====
