134
edits
Changes
Jump to navigation
Jump to search
Add a section about bug reporting
* 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 Hans 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 does not work, 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 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, and the other necessary magic lines, as explained above.
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=====
