Changes

If you install "ConTeXt Suite" or want to use "TeXLive" in parallel with "ConTeXt Suite"s you have to create new engines TeXShop is a good editor for "TeXShop", so that you can run your versions all variants of "TeX and ConTeXt" directly from within "TeXShop".It offers:

==== Setting* 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-Up 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 Single User 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 users user's ''Library '' folder of the users HOME user's home folder. They are installed first when the user runs TexShop TeXShop for the first time. * 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 executable and press Enter: chmod 755 ~/Library/TeXShop/Engines/ConTeXt2021.engineYou 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 useAlternatePathThen, 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 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 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:<ol><li> Make sure that you are using the latest ConTeXt release</li><li> Make sure that you are using TeXShop v4.66 or later</li><li> Add the following “magic lines” at the start of your source document:<pre>% !TEX useAlternatePath% !TEX useConTeXtSyncParser</pre></li> <li>Make sure that your document generates a <code>.synctex</code> file. Your source should contain this line:<pre>\setupsynctex[state=start,method=min]</pre>or this:<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. 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>% !TEX TS-program = ConTeXt2021% !TEX useAlternatePath% !TEX useConTeXtSyncParser \setupsynctex[state=start,method=min] \starttextSed ut perspiciatis unde omnis iste natus error sit voluptatemaccusantium doloremque laudantium, totam rem aperiam, eaqueipsa quae ab illo inventore veritatis et quasi architectobeatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatemquia voluptas sit aspernatur aut odit aut fugit, sed quiaconsequuntur magni dolores eos qui ratione voluptatem sequinesciunt. Neque porro quisquam est, qui dolorem ipsum quiadolor sit amet, consectetur, adipisci velit, sed quia nonnumquam eius modi tempora incidunt ut labore et dolore magnamaliquam quaerat voluptatem. Ut enim ad minima veniam, quisnostrum exercitationem ullam corporis suscipit laboriosam, nisiut aliquid ex ea commodi consequatur? Quis autem vel eum iurereprehenderit qui in ea voluptate velit esse quam nihilmolestiae consequatur, vel illum qui dolorem eum fugiat quovoluptas nulla pariatur?\stoptext</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 each 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.

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 which ever whichever encoding you wish. You can, also, set the file encoding when it a document is saved. TeXShop will automatically recognize the file encoding of existing files and use that when saving the file.

* Make TeXshop use utf-8 as its standard encoding for filesStart TeXShop. Choose the TeXShop-* Go to ''Preferences >Preferences Menu In the dialog window that comes up look for Encodings Field Source'', and choose ''Unicode (UTF-8 Close )'' from the drop-down menu in the Dialog window''Encoding'' group.