TeXShop for Mac

What's new in this version:

TeXShop 5.36
- In a document with over a thousand pages, the PageNumber box in the toolbar displays the number with a comma, as in 1,325. But users who want to go to a different page must enter the new page number without a comma. This makes it impossible to edit the existing number, say by changing 25 to 17 to go to page 1,317. This is fixed.
- Suppose a document has several pages of preliminary material before the main text begins. Perhaps these preliminary pages are numbered i, ii, iii, iv, v, ... and the main pages are numbered 1, 2, 3, 4, 5, ... Then entries in the PageNumber box will not be in sync with the actual page numbers in the text. The previous version of TeXShop introduced a fix for this problem, which required the user to insert a magic comment line and manually indicate the number of preliminary pages. The fix then numbered the preliminary pages 1#, 2#, 3#, ... and the main pages 1, 2, 3, ... Moreover, users could enter a number like 17 in the box to go to main page 17, and 2# in the box to go to the second preliminary page.
- This fix is still present in TeXShop 5.36, but the method of turning it on has been supplanted by a better method which does not require a magic comment line. The new method adds a macro to the source file which inserts an extra line in the console output and log file during typesetting. That line reads "Start of main material: 3." Here 3 is replaced with the page number of the first main page. TeXShop looks for this line during typesetting; if it occurs, the PageNumber is modified as in the old method. A big advantage is that as the preliminary material grows during editing, the fix automatically adjusts without user intervention.
- To activate this fix when using LaTeX and related engines, add the line write128{Start of main material: theReadonlyShipoutCounter.} to a spot in the source just after the main material is introduced.
- If instead you are using plain TeX or related engines, add the line write128{Start of main material: thepageno.} to a spot in the source just after the main material is introduced.
- TeXShop users need to find a way to remember these additional lines. Some may add items to the Macro menu, while others may modify their templates. It is also possible to add appropriate items to the Command Completion dictionary.
- After these lines have been added to the source, it is necessary to typeset to see changes in the PageNumber box. A lot of effort has gone into modifying the PageNumber whenever appropriate information is available in the log file. When TeXShop opens a new document, it checks to see if a log file is present, and if so it reads the log file to adjust the PageNumber box. If TeXShop is closed while documents are open, the documents will reappear the next time TeXShop starts with correct PageNumber entries.
- Suppose a situation I did not anticipate causes the new code to crash the program when reading an old document, even when the extra lines above have not been added to the source. In that case, write me immediately and I'll fix the problem. But in the meantime, you can fix the crash. Add the magic comment below to the top of the source. This comment completely cancels all of the new code, and the number 0 in the comment tells it to make no changes in the numbering. % !TEX numberingCorrection = 0 + current - desired
- Fixing Page Number boxes is a standard feature of pdf display programs like Preview, Skim, and Adobe Acrobat. These programs do not have access to the source file, and often work by parsing the table of contents information in the pdf file. TeXShop is a program for authors rather than a pdf display program, so it is natural for it to find the information to fix the Page Number box in the source file.
- Some users may prefer to view pdf files in TeXShop. If these users have access to the Log file associated with the pdf, they can get Number Box correction without using the source file. Just place the Log file in the same location as the pdf file, and TeXShop will automatically open and parse it, and adjust Page Numbers accordingly.
- This feature is even available if you do not have access to the Log file. For example, the Driver Manual for my car is a pdf file with two preliminary pages and then the main pages numbered 1, 2, 3, ... Using Apple's Text Edit in plain text mode, I created a small file with the same name as the pdf manual, but extension ".log". The complete contents of this file were Start of main material: 3.
- After this file was placed in the location of the manual, opening the manual in TeXShop provided PageNumber boxes with the correct numbering.


TeXShop 5.35
- Yusuke Terada reported a bug in "Trash AUX Files". When handling filenames containing Japanese diacritical marks, the "decomposed-form-string" and the "precomposed-form-string" might not match. Since Terada is a major TeXShop contributor, he provided a fix in the same report. Lucky me!
- Uwe Schmock complained that if the search field at the top of the preview window is used and the window is split, searching works in the top half of the window but not in the bottom half. This is fixed.
- Incidentally, searching in either half has a feature I only recently discovered. Suppose you want to search for a word like "number". You'll type this word in the toolbar's search field and push return to start searching. Then type command-G repeatedly to find additional occurrences of the word, or command-shift-G to search backward. The unexpected feature is the following. If you select a word like "hello" in the text before starting the search as above, then the search will start after this selection rather than at the beginning of the pdf document.
- The new TeXShop feature concerns documents which contain several pages of preliminary material before the main text begins. Suppose those preliminary pages are numbered i, ii, iii, iv, v, , ... and the main pages are numbered 1, 2, 3, 4, ... Then entries in TeXShop's PageNumber box in the toolbar will not be in sync with the actual page numbers in the text. TeXShop now has a magic comment line to fix this problem. The comment line reads % !TEX numberingCorrection = 0 + current - desired
- where "0" should be replaced by the number of preliminary pages in the document. Suppose, for example, that the document has three preliminary pages, and "0" is replaced with "3". Then in the PageNumber box in the toolbar, these pages will be listed as 1#, 2#, 3#, 1, 2, 3, 4, ...
- Consequently page numbers with a sharp sign list elements in the preface, and elements with plain numbers list the main pages and are in sync with the actual page numbers of these pages in the document. I experimented with changing the first list to i, ii, iii, iv, v, vi, ..., but these roman numerals quickly became large and overflowed the box. Moreover, using them in the reverse direction was awkward.
- As just hinted, this also works when using the PageNumber box in reverse to go to a particular page. Type a regular number to go to that exact page in the main text. Type something like 3# to go to the third page in the preface.
- This design will get out of sync if additional pages are added to the preliminary material. But most editing is done with the main text and sync problems are then relatively rare, caused for instance when a table of contents flows onto an extra page. TeXShop has a trick to make fixing this sort of problem easy. Suppose you suddenly notice that you are on page 72 of the actual text, but the PageNumber box contains 78. Return to the magic comment line, which might read % !TEX numberingCorrection = 3 + current - desired
- The end of this is a formula telling you how to fix the problem. Think of "current" as the current PageNumber entry, 78. Think of "desired" as the entry you want, 72. The above formula then reads 3 + 78 - 72 or 9. This is new number you should enter in the magic comment to replace the original 3.
- There is one final problem. Magic comment lines are read when TeXShop first opens a document, but TeXShop does not keep track of later changes to the lines. Thus editing the numberingCorrection line will not immediately fix page number synchronization. But the TeXShop Source menu has a new item named "Rescan Magic Comments" which will complete the process.


TeXShop 5.33
- When a new source file is first typeset, the output will appear in the Preview window scrolled to the top of the first page. Previously, it might be scrolled partly down this page.
- When a preview window is closed and later the document is typeset, the preview window will reappear scrolled to the top of the first page. Previously it might be scrolled to a position in the middle of the document.
- John Collin's latexmk has been updated to version 4.85.
- TeXShop was only possible because Apple provided developers with pre-built objects for crucial tasks: NSTextView for an editor, and PdfKit for a preview window. When the project started, I anxiously looked through the Pdf API's to see if Apple provided a routine to replace the old pdf file being displayed by a new version of the file; they did.
- Apple cannot anticipate or fully support all possible uses of their objects. When a new pdf is displayed in a window, it is always opened at the top of the file. If the view should be scrolled to a new position, I have to do that myself. But the API's assume that scroll bars are mostly manipulated by users, and provide only a vague "scroll region to visible" command for programmers to scroll the preview window. Moreover, if the programmer tries to scroll the pdf when it is opened, that scroll produces an annoying flash. I wrote Apple complaining about the flash, and they told me that there is nothing they can do to fix it. So I have to fix it at my end.
- When a LaTeX source file is opened, TeXShop reads the file and displays the text in a source window. Then it checks to see if a related pdf file is available. If so, TeXShop opens the pdf in a preview window using a routine I wrote named "showWithPath". Later when the user typesets, TeXShop switches from the original pdf to the new pdf using a routine I wrote named "reShowWithPath".
- The "showWithPath" code is straightforward and I have no problems revising it. But "reShowWithPath" is an entirely different matter and I dread having to even look at it. This is the piece of code that determines the scroll location of the old pdf, loads the new pdf, and then scrolls the new pdf to that same location. It also contains code which hides the screen for a fraction of a second so nobody sees the flash and then uncovers the screen before the user notices a pause and complains. All that scrolling is far from trivial because Apple doesn't provide code to do it automatically. If the user has eliminated part of the text before typesetting, the old scroll location may no longer occur and the code has to gracefully adjust. Just writing about "reShowWithPath" gives me the shivers, and having to modify it leads to nightmares. I hope I never have to touch it again.
- The bugs fixed in version 5.33 are related to these routines. If you receive the source code of a document from a friend and open it in TeXShop, there is no pdf file to display and so "showWithPath" is never called. When you typeset, TeXShop calls "reShowWithPath", but there is no previous version and thus no previous scroll position. In this special situation, the revised "reShowWithPath" just initializes the pdf and displays it without scrolling. That same situation occurs when you begin writing a new document in TeXShop and haven't yet typeset it.
- Each source document in TeXShop corresponds to an NSDocument object in computer memory. This object contains the source text and all the windows which might be needed to process it: source window, log window, console window, preview window, etc. If you close the source window, then all of this data is removed from computer memory. But if you close one of the auxiliary windows, like the preview window, it is removed from the screen, but all the data in NSDocument still exists in memory. If you typeset again, the preview window will reappear in its old position. This is not what users expect, since they believe that closing the window made it go away entirely. The final bug fix maintains that illusion by opening the window at its beginning, as though it were being opened for the first time.


TeXShop 5.32
- Version 5.32 fixes one bug. The following process will trigger the process for a few people but probably not you. Create a source window using the menu command "New". Enter one or two lines of text and then save the file using the menu command "Save As". Quit TeXShop and restart it again. Open the new source file. The file's name will be added to TeXShop's "Window" menu, but the corresponding source window will not appear. It seems that TeXShop has created a source file which it cannot display. This is an alarming bug.
- Here is the good news. There is nothing wrong with the file; it contains the correct text and can easily be opened using a trick. Even better, the bug only occurs if the user has selected "Syntax Color expl3 Code" in the TeXShop Source Window. This menu is a toggle which turns expl3 coloring on or off. When a window first opens, it is off. The only problem is that TeXShop has a hidden preference which turns the item on by default when windows are first opened: defaults write TeXShop expl3SyntaxColoring YES
- Only users who set this hidden preference are likely to see the bug.
- The bug has nothing to do with TeXShop's file saving code. It is a bug in TeXShop's syntax coloring code. When opening a source file, TeXShop syntax colors the source just before making the window visible. If the syntax coloring fails, the window is never made visible. TeXShop 5.32 fixes one step in the expl3 syntax coloring routine. After that, the routine does not fail and all windows open correctly.


TeXShop 5.31
- Version 5.31, released one day after the 5.30 release, fixes two bugs in that release. The first bug caused the Preview window to advance a page after each typesetting job in Single and Double Page modes. The second bug caused new projects to set magnification to 100 when initially typeset.


TeXShop 5.30
- Version 5.29 was never released. Version 5.30 fixes just one bug
- When TeXShop typesets a source file, it scrolls the pdf window of the new version to the spot visible in the preview window before typesetting. Consequently, the text shown after typesetting changes only slightly to show minor edits or new material added at the end. There are some exceptions. If the text starts with a table of contents covering several pages, and the aux file is deleted before typesetting, the output will jump several pages ahead after typesetting because the table of contents is missing and the document has fewer pages.A second typeset will restore the table of contents and return to the original spot.
- If material is removed from a document before typesetting and the new document has fewer pages, it is possible that the visible rectangle in the original document is beyond the end of the document after typesetting. In version 4.28 and some earlier versions, TeXShop would then set the page number on the pdf toolbar to a large negative number. Moreover, in fit-to-window mode it could change the magnification of the page actually shown to 100 so the view no longer filled the window. These bugs are fixed.



TeXShop 5.28
- A few subfolders of ~/Library/TeXShop/Engines/Inactive, including Arara and ConTeXt, were revised for this release
- TeXShop rewrites the Inactive folder whenever a new version of the program is released, but the rewrite is conservative, updating old files and adding new files and folders. No files or folders are ever removed, so the Inactive folder can become cluttered with irrelevant material. If you want only the latest version of this folder, move the Inactive folder to the desktop (do not move other folders). The next time TeXShop starts, it will recreate Inactive with the current default version.
- When TeXShop displays a preview file containing links and the user hovers the mouse over a link, a small window temporarily opens showing the linked area. This behavior can be toggled on or off using the menu item ``Link Popups'' in the Preview menu. By default, the behavior is on when a document is first opened, but this default can now be changed using a hidden preference: defaults write LinkPopups NO
- When TeXShop opens a source file, it checks the directory containing the file to see if it contains a file with the same name as the source but extension ".pdf". If so, TeXShop also opens the pdf file. If the user holds down the Option key while opening the file, the corresponding pdf file is not opened. This last behavior seems to have broken several years ago, but the feature works again.
- A very interesting bug was reported by Jeff Simmons. Later he discovered the exact cause of the bug and suggested an appropriate fix. When a macro begins with the words "--applescript direct", the applescript is run by TeXShop itself. But when a macro begins with "--applescript", the macro is run by a small auxiliary program in TeXShop. Simmons created and ran such a macro. Later he logged out of macOS and logged in as a different user. But when he tried to run a new "--applescript" macro as this second user, TeXShop instead ran the original macro.
- Because the auxiliary program is not TeXShop, TeXShop had to find a way to give it the applescript code it should run. Luckily, Unix provides a folder named tmp where programs can store temporary information. So TeXShop put the appropriate applescript program in tmp, and then gave the auxiliary program the name of this file. Since tmp may be used by many programs, knowing the name of the desired file is important.
- Then the author of TeXShop (and that would be me) made a stupid mistake. He always used the same name for the applescript file in tmp. As long as the same user ran applescript programs, there was no issue, because each new applescript file in tmp overwrote the previous one. But if a user logged out and then logged in as someone else, the new user did not have permission to overwrite the previous file, so the old file remained and ran.
- This is not a subtle mistake and Unix programmers are aghast after reading this explanation. But Simmons taught me an important lesson, and I'm grateful. By the way, it turns out that Apple has its own substitute for tmp and TeXShop now does the right thing. If you are a Cocoa programmer, please don't write me.


TeXShop 5.27
- If TeXShop is quit when files are open, the files appear in their old location the next time TeXShop starts. This behavior depends on the setting "Close windows when quitting an application" in the Desktop and Dock module of System Preferences. Restoring windows sometimes caused a long delay opening TeXShop after rebooting the Mac. This delay was caused by calling "scroll rect to visible" rather than "goto page" when preview window contents were scrolled to their old position. Apparently the first option caused the Mac to render all the pages of the document before opening it. The problem is fixed.
- John Collin's latexmk has been updated to version 4.83
- TeXShop can now syntax color expl3 code. See the chapter on expl3 in the TeXShop Manual, available in the TeXShop Help menu. According to a readme document from the LaTeX3 team, expl3 "provides the foundation on which new additions to the LaTeX kernel and other advanced extensions are built. The commands provided are not intended for use at the document level." By default, TeXShop syntax colors as usual, but if a new menu item is toggled on, it also syntax colors any expl3 code in the source.


TeXShop 5.25
- As in earlier versions of TeXShop, if you hover the mouse over a link in the Preview window, a small window opens showing the text at the linked location; this window remains open for five seconds and then vanishes. There is a new menu item in the Preview menu called "Link Popups", suggested by Uwe Schmock. This menu is a toggle turning the hover behavior on or off. When it is on, the menu item is checked.
- If you click in the contents of the Preview window while the Control key is down, a contextual menu opens. The "Link Popups" item is also in this contextual menu.
- The details of the small window created by hovering over a link can be changed by holding down any combination of three modifier keys before moving a mouse to the link. These modifying keys have been changed so their names give a mnemonic for the effect they create. The SHIFT key shifts the small window to appear above the link, rather than below it. The COMMAND key commands that a bigger window with larger text be displayed. The OPTION key selects the optional behavior that the small window will remain on the screen until the mouse moves. (If a user forgets to push the option key, it can be pushed later; if it is down at the five second mark, the window will remain open.)
- Latexmk by John Collins was upgraded to version 4.82a.
- The Edit menu contains an item named "Experiment". Select a section of tricky source text, perhaps a complicated series of mathematical equations. Then select the item. A new small window appears, showing the selected source. This window contains a "Typeset" button. Pushing that button produces a second small window showing the typeset output. It is then possible to experiment with the tricky source without modifying the actual document source, until the experiment produces the correct result. Copy the corrected source back to the document.
- This item works by creating a new source file for the experiment. The new source contains everything in the main document header up to but not including begin{document}, followed by begin{document}, the experimental source, and end{document}.
- This even works if the header is the root document of a project, and the experimental source comes from one of the included files. However, previous versions of TeXShop assumed that begin{document} was in this root document. Otherwise the Experiment menu item did nothing.
- This TeXShop code has been slightly revised. If begin{document} is not in the root document, then the entire root document is used rather than everything up to but not including begin{document}. The Experiment menu item may therefore work for a few additional projects.
- The code implementing "switch views" in a Preview window that has not been split was completely rewritten for TeXShop 5.25. In version 5.23, there was noticeable creep of the two views as the views were switched over and over. This creep is gone and the views are now stable.
- Recall how "Switch Views" works. Scroll the Preview window to an interesting spot. Press Option-2 to select this spot, i.e., view. Scroll to a second interesting spot or view. Now Option-2 switches between these two views. Either view can be scrolled when it is active and the scrolled position replaces the original position for that view.
- In version 5.23, the two views were also the two views seen if the window was split. This is no longer the case. If either view is split, that view will become the top view in the split window, and the bottom view will show an entirely independent third position. If the window is then unsplit, and Option-2 is used to switch to the alternate view in the full window, and then the window is split again, the alternate view will be the top view in the split window and the bottom view will be the same bottom view seen earlier.
- Thus combining our two full views with splitting windows allows us to work with three independent portions of the pdf file.
- Any "Display Format" and "Magnification" change made to a Preview Window affects both views. Thus if the window is changed to Double MultiPage mode and later switched with Option-2, the new view will also be in Double MultiPage mode.
- Finally, substantial efforts were made to improve the "split window" feature in the Preview window. This feature is difficult to modify because users have many ways to change how it works, and improving it for one group of users can makes it worse for a different group of users. Users can split the window vertically or horizontally, they can move the bar separating the two pieces, they can scroll either piece, they can change the display format and magnification of the pieces, they can switch the two pieces. These users may be working on multiple window mode with separate source and preview windows, or single window mode with source and preview in separate halves of a single window. And after all these changes are made and the window is unsplit, users expect to be back to one normal window without any surprises.
- A few users told me that as soon as something unexpected happened when splitting a window, they stopped using the feature for fear that the underlying pdf file would be damaged. So a word of reassurance is in order. None of these display modifications are written back to the pdf file. They only affect how TeXShop displays the file. If TeXShop does something strange, the file is perfectly safe. Retreat to full window mode and proceed as if nothing happened. If you like, write me to explain the surprise behavior. Then relax.
- A major complaint has been "display creep." A user splits the window, works in this mode for a while, then unsplits and expects to be exactly back where they started, only to discover that the text crept up or down by several lines. These users then cycle through split/unsplit cycles several times and noticed that each produces a further creep. A major effort has gone into eliminating these creeps. The program isn't perfect, but it is better than before.
- The "creep problem" depends on display mode. In single page or double page modes, it is not a problem. The more common modes are multipage and double multipage modes, and there creep can occur. An effort was made to reduce the problem in these two modes.
- If the Option key is held down when a window is split, the split is vertical. This mode actually works as expected, provided you know what to expect. When a window is split, the original single full window's contents are placed in the left vertical side. Since vertical sections are narrower than before, more pages are shown. The original unsplit page is at the bottom of this display rather than the top. This is by design. Similarly when the window is unsplit, the bottom portion of the left side will become the new single window. This is also by design. If the left side is scrolled during the split phase, the new material at the bottom of the left side will become the full window after unsplitting.
- If the option key is not held down when a window is split, the split is horizontal and the original window's contents are placed in the top half. This is the point where major creeping occurred. To fix the problem, the behavior of unsplitting such a window has changed slightly. In version 5.25, TeXShop remembers the position of the window just before it was split, and that location returns when the window is unsplit. While the window is split, the top can be scrolled elsewhere. But when the window is unsplit, this new position will not expand to the full window; instead the window will return to its original position.
- However, it is easy to scroll the top to a new position that is "permanent." Temporarily unsplit the window, scroll to the new position, and split again. The old bottom half did not change, but the top half is at a new position and that position will be remembered and returned to the next time the window is unsplit.
- Note that this new behavior only affects horizontal splitting in Multipage or Double Multipage modes.
- As in earlier versions of TeXShop, the lower and upper versions of the display can be switched by typing Option-2. This is rarely done, mainly in the situation where the user wants the lower half of the split window to become the full window when it is unsplit. But our "creep fix" cannot be applied in this case because the lower half was never in full page mode, and thus TeXShop does not have a full page mode to remember and return to. So in this very special case, the old code from TeXShop 5.24 is used when the window is unsplit. Consequently, Option-2 may produce slight creep, but since it is rarely used, that should not matter.
- Two special variations have been added to the split window command in horizontal mode. Most users should ignore these variations, but one or two users may find them helpful. If the shift and control keys are held down when the Split Window menu is selected or the corresponding tool is checked, the window is forced to split so the lower and upper views are the same size. If just the shift key is held down in the same situation, the two views are forced to have the same size and they contain the same material. The first of these variations may be useful for users who rarely move the split bar and never change the magnification of either view. These users probably already have a stable situation without creep. In those rare cases when they do move the split bar (and pay with additional creep), the option takes them back to the stable situation. The second variation was created for a user who lectures directly from a screen showing typeset course notes. He typically shows a full window view of the notes. But when he comes to a theorem, he splits the screen using the second variation. The theorem remains in the upper view, so students can refer back to it and recall the assumptions required for the conclusion. Meanwhile the lower view can be scrolled to show examples and then key steps of the proof.


TeXShop 5.24
- After a document is typeset, the new pdf file is loaded into the Preview Window, replacing the old version. This pdf must be scrolled to the exact spot shown before typesetting, so only edited items change and the document does not slowly creep up and down, or abruptly shift. Apple's PDFKit routines do not have a call making this task easy, so improving preview behavior has been a constant struggle over the years. In the last versions of TeXShop (in multipage and double multipage display modes) the image was very stable unless only a small portion of the upper page was shown and most of the screen displayed the following page. In that case, after typesetting the lower page jumped to fill the entire window. It was possible to predict exactly when this jump would occur. Slowly scroll the Preview window while looking at the "Page Number" item in the tool bar. When only about 1/3 of the top page is visible, the page number will suddenly jump to the next page. After that, typesetting will cause the undesirable jump.
- This problem is fixed in TeXShop 5.24. I do not know exactly why my fix works, but several users have confirmed that it does. Don't look a gift horse in the mouth.
- Incidentally, large changes made in the beginning of a document before it was scrolled to the current position and then typeset cause jumps which are unavoidable. This typically happens if a document has a table of contents. If a user kills the aux file and then typesets, the table of contents will vanish and the typeset document will jump ahead by several pages. Typesetting again creates the table of contents and the document jumps back to the expected place.
- When the TeXShop icon is in the dock and TeXShop is running, holding the mouse button down over the program icon brings up a contextual menu listing several possible actions. This menu is created by Apple with no TeXShop code involved. But it is possible for programmers to add items to the menu, and some Apple programs like TextEdit add a "New Document" item. So does TeXShop in version 5.24.
- TeXShop now contains latexmk version 4.82 by John Collins. Latexmk is also in TeX Live, and TeXShop will use that copy if it is available. Otherwise TeXShop will default to its internal copy of latexmk.
- The "About TeXShop" dialog contained the line "Copyright 2001-2023, Richard Koch". The year 2023 has been replaced by 2024.


TeXShop 5.23
- If your Macintosh is appropriately configured and you close TeXShop with a project open on the screen, that project will reappear when TeXShop is restarted, with the windows in the same positions they were in just before TeXShop quit. Until recently this happened instantly, but in the last several versions of TeXShop there was a delay before the old windows reappeared. This turns out to be an error on my part, and it is fixed.
- The package hyperref can create links from one portion of a document to another. For instance, each entry in the table of contents can become a link to that item in the text, and any reference to a theorem proved earlier can be followed by a link to the actual statement of the theorem. These links are active in the Preview window, so clicking on a link takes you to the corresponding linked spot in the text.
- Hovering over such links will bring up a small view of the linked text without moving the scroll bar. This is convenient if you are proofreading a series of linked items. For instance, hovering over a section number in the table of contents will display the beginning of that section in the text. Normally the popup is on screen for four seconds and then disappears. If the Shift key is down at the end of these four seconds, the popup will remain on the screen until the mouse moves. For a larger version of the popup, hold down the Option key before hovering over the link. (In previous versions of TeXShop, the Option key played both of these roles.)
- This facility is enhanced in version 5.23 of TeXShop due to Uwe Schmock's request. Normally the popup is shown just below the link in the text. But sometimes the author will want to compare what comes right after the link to the information in the popup. In that case, hold down the Command key before activating the popup. The popup window will then appear just above the link. This trick can be combined with the Shift and Option key tricks mentioned in the previous paragraph.
- TeXShop has a Macro facility which makes it possible for users to write applescripts to control common procedures. This impressive Macro facility and the Macro Editor were added to TeXShop long ago by Mitsuhiro Shishikura. The current expert in applescripts is Michael Sharpe, who wrote the wonderful document "Notes on Applescript in TeXShop" in the TeXShop Help Menu.
- TeXShop provides a number of constants that can be used in Applescripts it runs. These are listed in section 5 of Sharpe's manual. Examples are #FILEPATH#, #PDFPATH#, #DVIPATH#, #PSPATH#. The first provides the full path to the TeX source file, which might be /Users/koch/Documents/Fourier/Fourier.tex. Others give full paths to the pdf file, dvi file, etc., in the same folder. One missing constant sometimes requested is #FOLDERPATH#, which would give a full path to the folder containing these files, rather than individual files in the folder. In the example just quoted, it would give /Users/koch/Documents/Fourier/. I recently discovered a request made four years ago on stackoverflow for such a constant, together with several later requests. Version 5.23 of TeXShop finally provides this missing constant.
- In the TeXShop manual (which is typeset with XeLaTeX), I activated hyperref with the LaTeX command
- usepackage[colorlinks=true, pdfstartview=FitV, linkcolor=blue,
- citecolor=blue, urlcolor=blue, hyperfigures=true]{hyperref}
- Uwe Schmock pointed out that adding "bookmarksnumbered" to this command would number the chapters and sections shown in the TeXShop drawer. As we will see, that proves to be a useful change for the manual and may be a useful change for your documents as well. Just change the command to
- usepackage[colorlinks=true, pdfstartview=FitV, linkcolor=blue,
- citecolor=blue, urlcolor=blue, hyperfigures=true, bookmarksnumbered]{hyperref}
- A new item was added to the Windows menu, "Switch Views". This item is only active if the Preview Window is active. If the Preview Window has been split, the item interchanges the top and bottom views. When the window is later unsplit, the top portion becomes the full contents of the window. Using "Switch Views" before unsplitting brings the bottom portion to the full window.
- The "Switch Views" menu item also works when the Preview Window is active and unsplit, and this use case may prove to be more important than the original reason for introducing the command. Suppose you want to work on two related portions of a document. In TeXShop's Preview Window, do not split the view. Instead, just scroll to one of the two interesting portions of your document. Then select "Switch Views" and scroll to a second related section of the document. You can now switch between these two portions using the Window menu "Switch Views", which has a keyboard shortcut Option-2.
- So your document can have two active portions and you can switch between them with Option-2. Although "Switch Views" does not work in the Source window, you can easily edit and revise the two related portions of your document because sync works between the two Preview views and the source file. Suppose text in one of the two portions needs revision. Sync from that text to the source, edit the source, and retypeset.
- The new command is not perfect. The two views may creep gradually when switched, so a little adjustment with the scroll bar might be needed after switching views. The creep depends on window size and monitor size and may be acceptable for some configurations and not acceptable for others. Perhaps we can improve the feature in later TeXShop versions.
- A long time ago, a different keystroke sequence was introduced to switch the views of a split preview window. That keystroke sequence has been removed in Version 5.23 because the new menu item is easy to find and use.
- TeXShop configures the way documents are displayed using two preference items, which it calls "Display Format" and "Magnification". Typical display formats are Single Page, Double Page, Multipage, Double Multipage. Typical magnification items are Fit to Window, Actual Size, and Fixed Magnification. These items can be selected in TeXShop Preferences, and then affect Preview windows when they first open.
- After a document is open, the two preference items can be changed for a particular Preview window using items in the Preview menu. These choices are temporary while the document is being used, but revert back to the default choices for new documents.
- When the window is not split, the Preview menu's submenu items "Magnification" and "Display Format" affect the document as a whole, and thus both views simultaneously. So if you change the magnification of the current view, and later use "Switch Views", the second view will also use the new magnification level. If you switch to "Double Page" mode in the current view and later use "Switch Views", the second view will also be in Double Page mode.
- When the Preview window is split so both views are shown simultaneously, "Magnification" and "Display Format" changes made to the top view affect the entire document as above. Thus if the window is later unsplit, this changes will hold in the entire document, and also apply after "Switch Views" is used.
- However, when the Preview window is split so both views are shown simultaneously, "Magnification" and "Display Format" changes made to the bottom view will only apply to that portion of the split window, and only as long as the window remains split. This slight design inconsistency makes it possible for a user working with two sections of the document to temporarily magnify the bottom section and inspect fine details without propagating that magnification change to the rest of the interface.
- An interesting and rather complicated interaction occurs when the Preview window is split and the drawer for this window is open. To describe this interaction, we introduce a concept well-known to Macintosh programmers, but perhaps not to users. Suppose your Macintosh is in use and you type on the keyboard. How does the Macintosh know where to send those keystrokes? Which window should receive them? Which view of a split view? If the drawer of a window is open, should the keystroke go to the drawer or the window?
- It turns out that at any moment the Macintosh has selected a "first responder". This is the object that first learns of keystrokes. The first responder is the beginning of a chain of more and more general objects. If the first responder is the drawer attached to a window, the keystroke goes to that drawer. But if the drawer cannot use the keystroke, it passes down the chain to the next object, which might be the view associated with that drawer. If the view in turn cannot use the keystroke, it passes further down the chain, perhaps to the window containing the view. If this window cannot use the keystroke, then the keystroke is lost and does nothing.
- The first responder will change as a user works. Often this happens when the user clicks on a different view. In the example just given, if the window has a split view and the user clicks on the top view, then that view becomes first responder. Then keystrokes never reach the drawer, but instead pass from the top view to the full window. -All of this is complicated and often works ``automatically'' without even the programmer knowing the details of these responder chains.
- Consider now the following example. Suppose a preview window is active and contains two split views and an open drawer. Suppose the drawer is showing the various chapters of a document, and these chapters are numbered. If you select the second chapter of your document in the drawer, the top view will scroll to the start of this second chapter, and the drawer will mark the second chapter in blue. That blue mark indicates that the drawer is still the first responder.
- It turns out that numbered drawer contents respond to keyboard shortcuts. If you type Option-1, the drawer will select the first chapter. If you type Option-2 followed by Option-0, the drawer will select chapter 20. Type Option-UpArrow to select the first item and Option-DownArrow to select the last item. Type Option-1.5 to select Chapter 1, Section 5. If chapter 3 is selected, Option-RightArrow will open sub-levels and Option-LeftArrow will close sub-levels. Although these keystrokes select drawer items, it is still necessary to click these items to make the associated view scroll to them.
- But how do we select items displayed in the bottom view? To do that, click in the bottom view. Notice that the blue selection bands in the drawer change to gray bands. So the drawer is no longer first responder; instead the bottom view is first responder. This action made another invisible change. It sent a message to the drawer's contents linking them to the second view. Now chapters and sections can be selected in the second view.
- There is a final interesting interaction. Select a chapter in the drawer and type Option-2. This command does not switch the two views, because the first responder is the drawer rather than the Preview Window. Instead it selects chapter 2 in the drawer. But if we click in either view, then that view becomes first responder rather than the drawer. So if we type Option-2, this keystroke will not go to the drawer, but rather to the view just clicked. That view does not understand Option-2, so it passes it on down to the Preview Window. The Preview Window does understand Option-2 as a shortcut for "Switch Views" and switches the views.
- Pdf documents can be encrypted and password-protected by Apple's Preview, or the commercial version of Adobe Acrobat. Such documents can still be opened by TeXShop and other pdf viewers. When the document is opened a window appears, but instead of showing the document, the window contains a text field where the user can type the password. After the user types that password, the document opens.
- TeXShop does not contain a single line of code to make this happen. The initial page with a password entry field is created and managed by Apple, and the document is then decrypted when read from disk by Apple. TeXShop was not even recompiled to make this happen. Instead one day an update to macOS appeared and TeXShop got the feature for free. This is the glory of Cocoa (and Swift).
- Uwe Schmock wrote me after he distributed password-protected notes for his students. He discovered a small number of problems when TeXShop views a password-protected file. These problems are fixed in version 5.23 of TeXShop.
- The first problem was that the contents of the drawer were empty when such a document was displayed. The reason is that TeXShop initialized the drawer before Apple began decrypting the file. This bug is fixed.
- The second problem was that when splitting the document horizontally or vertically, the position of the splitting bar was severely limited. This bug was caused because Apple applied constraints to the views displaying the two pieces, but TeXShop does not use constraints to position subviews. This problem is also fixed.
- A final problem is that students must remember the password of a file that they intend to read often. Many students save a short document on the computer listing passwords required in this way, but that certainly makes the password system less secure. Apple has a system to solve this problem. When the user types a password, Apple offers to save it in their keychain, which is encrypted. Unfortunately, Apple does not make that offer when opening a password protected pdf file. Perhaps in the future, ...
- In the meantime, students might employ a trick to make passwords easier to use with commonly read encrypted documents. In the Macro menu, select "Open Macro Editor". An editor appears. Select "New Item" and give the item an easy name. Then enter the following code:
- --Applescript direct
- tell application "System Events" to keystroke "password"
- tell application "System Events" to keystroke return
- Replace the text "password" inside the quotation marks with the actual password. Save the macro. When the text field appears asking for a password, select this macro.
- There will be one problem. MacOS does not allow Applescripts to control the computer in this manner without permission. So when the macro is first run, an error message will appear. Sometimes, but not always, Apple will open System Settings to the spot where the appropriate permission can be given. That spot is the Privacy & Security module of System Preferences, and the item "Automation" in this item. A special item for TeXShop can be created and given permission to control "System Events".


TeXShop 5.22
- If the user removes a folder from ~/Library/TeXShop and then runs TeXShop, the folder will be recreated with default contents. Curiously, this did not apply to the folder ~/Library/TeXShop/Engines/Inactive, but now it does. Before this change, a user could remove ~/Library/TeXShop/Engines and that entire folder would be recreated, including the Inactive subdirectory, but that technique destroyed any special engines the user might have created.
- When new versions of TeXShop are introduced, most folders in ~/Library/TeXShop are not changed because these folders store files created and edited by the user. But the Inactive folder is updated because users should have the latest versions of these items. This update adds new files and folders and modifies existing files and folders, but it does not remove files or folders no longer needed. I'm thinking of changing this behavior so Inactive is completely "cleaned up", but that is a more drastic step that needs to be carefully considered. In the meantime, users can accomplish that complete cleanup by removing the Inactive folder and letting TeXShop recreate it.
- The Typst program was recently updated to version 0.9.0, and Jeroen Scheerder updated the material in ~/Library/TeXShop/Engines/Inactive/Typst for the new version. If you are already using Typst in TeXShop, go to this location. An early section in the document "AboutTypst.pdf" explains how to download and install Typst. Follow these instructions to obtain the new version. The last section of this document explains how to move the contents of the "Advanced" folder into appropriate places. Scheerder revised the contents of "Advanced", so move the revised folders into the same spots.
- Version 5.20 added a preference item to activate transparency when calling Ghostscript. That item adds a flag to Ghostscript calls, but the flag is only relevant on recent versions of Ghostscript. So TeXShop checked the version of Ghostscript and did not add the flag if the version being used was not recent enough. This check involved calling a shell script that was incompetently written (by me) and failed in Sonoma. The script has been rewritten and the bug is fixed on Sonoma.
- In version 4.61, the bibtex UTI was changed from org.tug.bib to org.tug.tex.bibtex at the request of the BibDesk team. But not all data structures were changed, breaking the creation of new bibtex files from within TeXShop. This bug was not noticed until now. It is fixed.
- Version 5.03 of TeXShop included an example program explaining how to create interactive documents using tex4ht. The source code for such a document is ordinary latex. When typeset by pdflatex, the result is a static pdf file. But when typeset by tex4ht, the result is a web page with interactive content. The sample document is in ~/Library/TeXShop/New/Demo.
- Since tex4ht can output MathJax calls, the mathematical formulas on the web pages it creates are essentially perfect. But the illustrations are sometimes distorted. Recently I read a brief note by Michal Hoftich, who maintains tex4ht, explaining how to fix this problem. So TeXShop 5.22 installs a new folder, ~/Library/TeXShop/New/Demo-Additions-5.22, containing a Read-Me file explaining the very simple modification to the Demo document which fixes illustrations. These Read-Me changes can be made in the same manner to other documents typeset by tex4ht.


TeXShop 5.21
- Jeroen Scheerder improved the support of Typst by using the Packages system now under construction in that project. Packages are similar to style and class files in the LaTeX world; they extend the capabilities of the typesetting system. Scheerder separated each sample program provided in TeXShop 5.20 into a package and a template. The package is hidden away in ~/Library/Application Support/typst and the template is available in the TeXShop templates pulldown in the source window. This makes it possible to start a new project by selecting an initial template and adding material to it. The templates can be edited by users to fit their precise requirements.
- If a source project opened an html window in TeXShop, and the source was then closed without first closing the html window, TeXShop would sometimes crash. This is fixed.
- The Chinese localization in 5.20 had one item translated by Google rather than the official localizer. This is fixed.
- A small number of Interface Builder connections led to objects that no longer exist. This caused cautionary items in the log file, although TeXShop ran fine. The connections are gone and the log entries no longer appear.
- The log file complained that "unarchiving safe plist type 'NSString' occurred" and warned that this would be disallowed in the future. This is fixed and the log entry is gone.


TeXShop 5.20
- Some people complained that line numbers in the source file are too small to read. A new preference under the "Source" tab allows users to choose between small and large line numbers.
- The Typst project by Martin Haug and Laurenz Mädje is a complete rewrite of both the input language and the typesetting abilities of TeX and LaTeX. See https://typst.app for details. A TeXShop user, Jeroen Scheerder, recently created an engine file that allows TeXShop to typeset Typst sources. Version 5.20 of TeXShop contains that engine in ~/Library/TeXShop/Engines/Inactive/Typst. This folder also contains simple typst source files, called templates, and instructions explaining how to download and install typst. Thus users can easily experiment with Typst using TeXShop.
- Typst source files have extension ".typ". This file extension was added to the list of extensions that TeXShop is willing to create and open, and to the list of file types that TeXShop can typeset. Moreover, source files with extension ".typ" can be added to ~/Library/TeXShop/Templates and then will appear in the Templates pulldown menu in the source window.
- Version 5.18 of TeXShop contains a preference which adds a flag whenever Ghostscript is called telling the program to process transparency operators. This flag is understood by Ghostscript 9.51 and later, so TeXShop has code which checks the version of Ghostscript running, and does not add the flag when the version is earlier than 9.51. But very shortly after the release of TeXShop 5.18, Matthias Schmidt read that code and discovered that it did nothing because it was deactivated by a line of debugging code I forgot to remove. I silently fixed the bug and most people updating to version 5.18 received a version without this bug. Since the bug was minor, I decided not to release a new version just to fix it. It is fixed for everyone in version 5.20.
- The TeXShop manual was updated slightly to describe the changes in version 5.20. Uwe Schmock has also improved the manual and some of his changes are in the latest version.
- Max Horn runs an important web site which may be unknown to most TeXShop users. The site is https://github.com/TeXShop/TeXShop and contains the source code for most versions of TeXShop since the program began. While the Horn site was under construction, I sent him old sources obtained by turned on computers that had last run twenty years ago; they started right up! That is how I found the original sources for the earliest TeXShop, which are linked from the the main TeXShop page, https://pages.uoregon.edu/koch/texshop/texshop.html.
- I am ashamed to admit that git remains a mystery to me. So Horn has access to valuable information I know nothing about. Here's an example. Horn recently reported that the 5.18 sources suddenly contained a complete copy of the final program. That was 90 megs of useless information. Sure enough, a copy had accidentally been saved in the wrong spot. This problem was immediately fixed on the web, but I'm gradually digesting a list from Horn of other elements in the current sources that are probably no longer relevant.


TeXShop 5.18
- Modern versions of Ghostscript do not process transparency operators in ps files unless the flag -dALLOWSPSTRANSPARENCY is added to the function call. In TeXShop 5.18, a preference item titled "Ghostscript Options" under the Typesetting tab can be checked to activate the flag. This activation only applies in two circumstances.
- When TeXShop opens a postscript file, it calls ps2pdf to convert the postscript to pdf and opens the pdf file. Without the flag, transparency will be ignored in the ps file. With the flag, it will be respected.
- When TeXShop typesets files in DVI mode, it runs TeX or LaTeX to create a dvi file, runs dvips to create a postscript file, converts the postscript file to pdf using ps2pdf, and displays the pdf file. Projects typeset in this way can use the package pstricks for extra typesetting effects, and pstricks can add transparency to illustrations. Typesetting will only preserve transparency if the flag is set.
- The flag requires Ghostscript 9.51 or higher. It has no effect when used with earlier versions of Ghostscript.
- The flag is added (in DVI mode) only if the user has not added "--distillerops" to the simpdftex preference settings. TeXShop does not want to interfere with users who are carefully controlling the Ghostscript flags themselves.
- This preference item should still work when users supply their own Ghostscript, possibly from macports or homebrew, but that has not been tested.
- Two sample files are provided for experimentation with the new setting. Select the TeXShop menu "Open ~/Library/TeXShop" and navigate to the folder New/Version-5.18. This folder contains two files which can be copied to your home directory: Transparency.ps and Transparency.tex. Open Transparency.ps in TeXShop. If the new item is not selected, the ruler in the illustration will cover the material underneath. If the new item is selected, the ruler will be partially transparent and show items underneath. Typeset the source file Transparency.tex to see the same change of behavior when typesetting in DVI mode.
- When new typesetting methods become available or older methods require new flags to operate properly, the changes are generally handled in TeXShop by creating new engine files. Herbert Schulz created such engines for transparency, available in ~/Library/TeXShop/Engines/Inactive/GhostscriptTransparencyEngines. The new preference item does not affect these engines, and the engines are more flexible than the preference setting, handling for instance versions of Ghostscript earlier than 9.51. Use Herbert's engines for full control. The new preference is for users who run into a problem and want to click a box for a quick solution.


TeXShop 5.16
- There are improvements in the German localization. The "Sharing" and "Mouse Mode" items in the toolbar are translated, and the "Split Window" item has been given a less ambiguous translation. A few translations were tweeked to add consistency and remove typos.
- A bug with the "Magnification" and "Page Number" items in single window toolbar is fixed. Previously, these items opened an empty preview window, a confusing action in single window mode.


TeXShop 5.15
- Some translations of toolbar items in various languages did not actually appear when TeXShop ran. This should be fixed.
- A number of German toolbar items were left in English, but should now appear in German
- The label tool now correctly appears in German in single window mode. The crash is gone.
- When using single window mode in English, selecting the magnifying glass tool made it impossible to select any other tool. As a workaround, users were told to hold down the Option key while selecting other items. The bug is now fixed and the workaround is no longer needed.


TeXShop 5.14
- TeXShop 5.14 fixes a crash bug in the German localization of TeXShop. This bug has been present for a long time and only affected single window mode. In that mode, TeXShop crashed when the user tried to customize the toolbar.
- The bug was caused by the "Labels" tool. The fix eliminates that tool, but only in German and only in single window mode.
- The user reporting this bug ran into another bug which had been reported earlier. In single window mode, selecting the magnifying glass makes it impossible to switch to other "mouse modes" like text selection and pdf selection. This problem occurs in English and a few other localizations, but there is an easy work around. Hold down the Option key while selecting other tools and then selection works.
- A new chapter titled "Working Around Bugs" has been added to the TeXShop manual listing this action. Sometimes it is easier to work around a bug than to fix it, and these cases will be listed in the new chapter. Let us hope that it remains short.


TeXShop 5.13
- The Preferences dialog has a button labeled "Set Default Values" at the bottom. Selecting this item changes all items in Preferences to their defaults when TeXShop is first opened. A bug in this command caused it to ignore reverting the source font or font size. This bug is fixed.
- After selecting "Set Default Values", the "Cancel" and "OK" buttons in Preferences work as usual, so selecting "Cancel" returns to the current defaults, while "OK" accepts the default values.
- Note that "Set Default Values" followed by "OK" removes any hidden preferences you may have set, so it should be used with caution. However, the new TeXShop Manual in TeXShop Help, added in version 5.12, has a list of all hidden preferences at the very end. The list is long, but you may be able to find a preference there that you set and then forgot.
- If TeXShop is configured to open all documents in Single Window mode, and the program is quit while windows are open, these windows will be restored the next time the program runs. However, TeXShop did not restore the position of the divider between source and preview views and the divider would be placed in the middle of the single window. Now TeXShop restores the position of the divider.
- In TeXShop Preferences under the Editor tab, the last three items in the Style box sometimes displayed as integers and sometimes as real numbers. The TeXShop Manual claimed that these items do not work and can be ignored. But in fact the items work after a restart of TeXShop.
- Now the items always display as integers and take integer values
- Moreover, setting an item causes an immediate change in any open source window, so users can experiment until they find satisfactory values. There is a small caveat. TeXShop only learns of changed values when the item is deactivated, so to see the result in open source windows, change a value and then click in a different box. It is tempting to instead push RETURN, but this accepts all changes and closes the Preferences window.
- After making changes in the Style fields, the "Cancel" and "OK" buttons in Preferences work as usual to reject or accept all changes. If Style changes are rejected, source windows return to their previous style.
- In the German localization, the "Parens Targets & Highlight Color" item in TeXShop Preferences under the Source tab was not hooked up correctly and misbehaved when used. This is fixed.
- A number of small changes in the German localization were made for greater consistency across the interface


TeXShop 5.12
- The folder ~/Library/TeXShop/Engines/Inactive/PreTeXt was revised and the three main PreTeXt engines were rewritten. Consequently, many more examples in mathbook can be typeset with TeXShop.&