[ Direct Download: TeXShop 3 for Lion | Lion Source | TeXShop 2 | Version 2 Source ] [ Contact ]

TeXShop History

TeXShop Changes 4.73

The following changes were made:

TeXShop Changes 4.72

Version 4.71 was never released. The following changes were made in 4.72. Since I write the Changes document, I feel free to use it as my personal blog. The rest of the text for 4.72 has nothing to do with changes and can be skipped. It is a short essay about the evolution of macOS in the last twenty years. I used to believe that the great times for macOS were from 2000 to July of 2011. This covers the start of macOS through Snow Leopard. After that, the iPhone and iPad became dominant and smaller minor changes were made to macOS. I'm about to argue that this view is wrong.

When Apple bought NeXT, they obtained a method of programming called Cocoa. Programs written in Cocoa are broken into small pieces called "objects" described by "classes." Each object performs "methods," that is, small tasks that can be requested by other objects. Each object has "instance variables", which store values used by the object. Apple supplies the base classes and programmers add their own classes. A program is thus a cooperative endeavor between Apple and the author.

At the first developer conference about the new macOS, Apple announced that programs for it would be written in Cocoa. This announcement landed with a thud, and no significant company endorsed the system. So at the following conference, Apple introduced an alternate way to program called "Carbon," because, as they said, "Carbon is the basis of all life." Carbon was in fact the old system of programming the Mac, allowing old programs to be tweaked to run on the new system. Carbon was immediately endorsed by Microsoft, Adobe, and others, who said that Apple had finally come to its senses.

I went to some of those early developer conferences. Sessions about Carbon filled the enormous main hall to the brim, while sessions on Cocoa were given across the street and attended by 20 or 30 people who all seemed to know each other. Some Apple officials said that Cocoa was mainly for prototyping, and might transition from Objective C to Java.

Meanwhile, there was a dream in the minds of a few Apple engineers, not voiced publicly at the time. If everyone used Cocoa, then Apple could modify the base classes, and when the operating system was upgraded all programs on the Mac would get new features automatically, without even being recompiled. We aren't talking about minor cosmetic issues, but about major new abilities. However, a problem stood in the way known as the ``fragile base class problem.'' In an object oriented language, the base classes can be rewritten to optimize their operation. But new methods cannot be added to the base objects, and new instance variables cannot be added to them. This restriction more or less squashed the dream.

These problems affected all object oriented programming languages: C++, Objective Pascal, etc. However, Apple used an unusual language named Objective C, and in that language new methods can be added to the base classes. So half of the problem did not exist for Apple.

And then Apple engineers discovered a solution for the instance variable piece of the puzzle. But there was still a complication. Unlike other languages, Objective C requires ''runtime code" in the system, to assist the communication between objects. To fix the fragile base class program, Apple would have to modify this runtime code, and that would break all existing Cocoa applications.

Incidentally, this problem did not exist on the iPhone, which is programmed in Cocoa. Before Leopard, there were no iPhone programs. So Apple could fix Objective C on the phone before any programs were written for it.

Meanwhile, another transition was occurring in the world of computers. The processor used by the Macintosh was internally a 32-bit chip. By the time of macOS Tiger, Motorola was transitioning to a 64 bit chip. About the same time, Apple switched to Intel. The first Intel macs had 32 bit chips. But almost immediately, 64 bit chips became available and within a year, all Intel Macs had 64 bit processors. These processors could run both 32 bit and 64 bit programs, but at first all Mac programs were compiled for 32 bits so they could support a variety of machines. This meant that Apple could fix Objective C for 64 bit code, because at the time there were no programs written for the Mac using 64 bit Intel code.

After Snow Leopard, Apple did something that gave them a bad reputation for years. They very rapidly made old machines obsolete, so only machines with 64 bit processors could use the new system. As soon as this transition was finished, Apple returned to their older policy that new versions of macOS support most older machines.

Consequently, new versions of macOS only ran on 64 bit machines, the fragile base class problem was fixed on these machines, and all programs running on them in 64 bits had been compiled by code understanding the new runtime. The old dream was close to being realized.

But how about all those programs written in Carbon. Changing base classes would be irrelevant for them. That's another completely independent story. I'm going to tell it.

In the 2006 developer conference, Apple gave developers an initial beta of Leopard and announced that the system would be released in early 2007. The announcement included a series of slides describing features of the system, and one of the slides read "Full 64 Bit Support for both Cocoa and Carbon." So when the system appeared in 2007, developers could compile 64 bit versions of their applications.

However, Apple missed this release date. In January of 2007, Apple announced the iPhone. System engineers were pulled from macOS to work on completing the software for the phone, and Leopard was still unreleased when the 2007 developer conference opened. I went to both the 2006 and 2007 conferences, and the two conferences were almost identical: same keynotes, same slides, same sessions. This was one week before the release of the iPhone, but I didn't see a single iPhone at the conference.

There was one very significant slide difference. I'm ashamed that I didn't notice it during the keynote. The old slide for 64 bits now read "Full 64 Bit Support for Cocoa". After the keynote, there is a lunch break, and listening to engineers during that lunch, I gradually realized that Carbon was deprecated. Apple had been so successful that they no longer needed to pander to the big software companies and could push the programming environment they desired. Carbon applications continued to run until Catalina was released, but got no new features. This was a courageous decision by Apple, but it was also made possible by a secret fact.

During the first year after the iPhone was released, developers could not write programs for it. So in 2007, Apple knew something the rest of us didn't know. The iPhone was programmed in Cocoa.

I finally come to my point. As a result of this long development, the story of macOS from 2010 to 2020 is not at all a story of small tweaks. It is instead a story of astonishing improvement in the abilities of Macintosh applications caused by Apple revisions of the base classes. More people ought to know about this! Let me list some major steps taken.

For years, a standard request made by TeXShop users was that if they quit TeXShop and then restarted it, all the programs it was running when it was quit would load again, and their windows would be in exactly the positions they were in when the program quit. This seemed doable, but I never got around to doing it. Then one year I installed the beta for the new system and TeXShop got that feature automatically with not a single extra letter of code.

Recently I discovered the source code for the original version of TeXShop written in 2000. The program was very primitive, but it had a source window and a preview window and could typeset with TeX or LaTeX. I compiled it with the latest XCode and to my astonishment the code still compiled and the program was able to typeset latex documents. Even more remarkably, when I quit the program and restarted, all my documents reloaded and the windows appeared just where they had been before. In 2000, that feature was a distant dream. Now without any changes in my code the feature was there.

When Apple introduced the Retina display, programs written in Carbon didn't work because they expected much bigger dots. So Apple introduced a "compatibility mode"; the image they created was magnified by two before being displayed. Another way to say that is that for these programs, the Retina display was just an ordinary display. However, Cocoa programs worked because the base classes handled the needed modifications for much higher resolution.

Maybe the most astonishing change is "automatic saving." In this mode, you no longer have to save documents before quitting. The document is actually saved every few minutes while you work, but only the changes are saved, so the moments when saving occur are completely invisible. Documents are also saved when you close and at other important times. If you happen to erase a paragraph and then realize that you need it, you can issue the command "Revert To: Browse All Versions." A Time-machine display opens (even if you don't back up with Time machine) revealing old versions going back in time and you can go back, copy that paragraph, and paste it into the latest version. There are many other advantages of this system. I have never had a complaint about losing a file using it. But I would never dare to write such code myself; too scary.

Programmers have to write extra code to use automatic saving. Here is the complete TeXShop code to use this feature:

     + (BOOL) autosavesInPlace
          return YES;

Many features of a Cocoa program are created pictorially rather than by writing code. For instance, in the TeXShop source code there is a Menu object which defines the TeXShop menus and looks like a real menu. But if you compare the menu in this object to the actual menu shown when TeXShop runs, they are different. Why? Because as part of rewriting the base classes for automatic saving, Apple's base classes actually remove and add items in the menus. It's hard to believe that would actually work, but it does.

I've written this long essay because tabs in macOS are another example of a feature added by modifying the base classes. The additional code I wrote to obtain all the features summarized in the above changes document consist mainly of code to add the new preference item, but the actual code to activate the tabs is the routine given below, which is applied to four windows before they are opened:

   - (void)setTabBehavior: (NSWindow *) theWindow
       if (! atLeastSierra)
       NSInteger value = [SUD integerForKey:OpenAsTabsKey];
       switch (value) {
           case 0: break;
           case 1: theWindow.tabbingMode = NSWindowTabbingModePreferred; break;
           case 2: theWindow.tabbingMode = NSWindowTabbingModeDisallowed; break;
           default: break;

Don't tell me that Apple has just been tweaking the system for the last ten years!

TeXShop Changes 4.70

The following minor changes were made.

TeXShop Changes 4.69

The latest version of Sage simplifies the installation of Sage on the Macintosh. The Sage engine and corresponding documentation in ~/Library/TeXShop0/Engines/Inactive/Sage have been revised to reflect this change. It is no longer necessary to revise the Sage engine or the installation of sagetex after each Sage update.

In addition, the following relatively minor TeXShop changes have been made:

TeXShop Changes 4.68

There is new material in ~/Library/TeXShop/Engines/Inactive/Sage to support the latest release of Sage-Math. This material is mostly due to Herbert Schulz, who noticed the update and discovered that the Macintosh version broke several sample documents. His debugging led to a fix, both in the Macintosh version of the program and in our engines.

Latexmk was updated to version 4.75.

There are no TeXShop code changes. TeXShop should be ready for macOS Monterey when it is released.

TeXShop Changes 4.67

There are six important changes:

During Monterey testing, an initial switch to "Single Window Mode" displayed only the tool bar of the new window, without the two content regions. This proved to be a resizing problem, fixed by resizing the window appropriately. Once fixed, the bug did not recur. Users who run into this problem should resize.

TeXShop Changes 4.65 and 4.66

TeXShop 4.65 was never released.

There are eight changes in TeXShop 4.66. The first four are minor; the remaining four are more important, but only affect ConTeXt and External Editors:

TeXShop Changes 4.64

Latexmk is updated to version 4.73. Version 4.72b of latexmk, introduced in the previous version of TeXShop, had a serious bug causing long pauses when the program parsed the log file of certain book length projects. This is fixed.

TeXShop Changes 4.63

Three small changes are made in this minor update:

TeXShop Changes 4.62

This version fixes localization problems, particularly in the Help menu, introduced in version 4.61.

TeXShop Changes 4.61

This version changes the bibtex UTI from org.tug.bib to org.tug.tex.bibtex at the request of the BibDesk team. In addition, it adopts Apple's modern names for localized versions of the program, fixing some minor bugs in which text in strange scripts appears in occasional dialogs.

TeXShop Changes 4.60

The preference item "Open as Tab in Root Window" introduced in 4.59 is now off by default. Users who installed 4.59 may need to turn it off themselves. Most users will never need this feature.

In Apple's System Preferences under the General tab, there is an item labeled "Prefer tabs: in full screen when opening documents." The text in italics is a pull-down menu with three choices: "never", "in full screen", and "always". Users who have selected "always" should not select "Open as Tab in Root Window" because they already have the desired behavior. Moreover, the TeXShop item will interfere with the behavior given by this preference setting.

The System Preferences item changes the behavior of all Cocoa programs, while the TeXShop item only affects TeXShop. Moreover, the System Preferences item opens all source files as tabs in a single window, while the TeXShop item only opens source files associated with a given root as tabs in that root window.

TeXShop Changes 4.59

Version 4.59 has five changes:

TeXShop Changes 4.58

Version 4.58 is a relatively minor update to clean up a few issues which appeared over the holiday.

TeXShop Changes 4.57

Version 4.56 was released briefly and quickly withdrawn. Version 4.57 of TeXShop has a new version of OgreKit, 2.1.10, thanks to Isao Sonobe. The changes are Users will not notice the first item, which fixed debugging messages in XCode.

This should end the flurry of changes caused by Apple's Arm release, and I expect that TeXShop will remain unchanged through the holidays at least.

TeXShop Changes 4.55

The previous version, 4.54, fixed a bug when running on Sierra and High Sierra. After that fix, TeXShop could again run on macOS 10.12 and higher. The fix made no changes in the code; instead it replaced the Source Window in the English Interface Builder file with a copy of the German version, and then hooked up the connections for this object. Unfortunately, the window had several layers: a Split View, followed by two Scroll Views lying over two Clip Views, each containing a Text View. So some of the connections were not made.

That had rather dramatic consequences. Splitting the source window failed, various macros no longer worked, and Single Window mode failed. Thanks to rapid and detailed complaints from users, these problems were fixed by adding the missing connections. Version 4.55 is exactly what 4.54 was intended to be.

TeXShop Changes 4.54

Version 4.54 has two changes:

TeXShop Changes 4.53

Version 4.52 was never released. There are only two changes in 4.53, but the first is a big deal.

TeXShop Changes 4.51

This minor update has four changes:

TeXShop Changes 4.50

Versions 4.45 through 4.49 were never released. This version has the following changes:

TeXShop Changes 4.44

This version has four small changes:

TeXShop Changes 4.43

In an evening phone call, Louis M. Guenin pointed out that the Apple Find Bar in TeXShop doesn't behave like the similar Find Bar in Safari, TextEdit, and other Apple programs. In other programs, the entire window being searched darkens during a search and all instances of the phrase being searched stand out in white, with the active element in yellow.

The Find Bar is created by Cocoa with only a single line of TeXShop source code turning it on. It has an extra parameter called ``incrementalSearchingEnabled'' which TeXShop did not set. Now TeXShop sets the parameter.

There is a hidden preference to turn the feature off for users who dislike it:

     defaults write TeXShop IncrementalSearch NO

TeXShop has three search panels, the Apple Find Panel, the Apple Find Bar, and the OgreKit Find Panel. The choice among them is made in TeXShop Preferences and becomes active the next time TeXShop starts. The Apple Find Bar is the least intrusive, simply adding an extra search line at the top of the source window, but it is surprisingly powerful; users should give it a try. It supports "search and replace" once the word "replace" is checked, and there is a hidden pull down menu with other options, triggered by the symbol on the left side of the bar. And it fully supports Dark Mode.

TeXShop Changes 4.42

Version 4.42 has three small changes.

TeXShop Changes 4.41

Version 4.41 fixes minor engine problems caused by the elimination of the default ConTeXt menu item. Note that up to date ConTeXt engine files remain in 4.41; the version of ConTeXt in the menu was years out of date.

TeXShop Changes 4.40

There are two changes in version 4.40:

TeXShop Changes 4.39

James Crippen reported that in version 4.38, when the magnify tool is selected in the Preview window and the Source window is active, clicking in the content region of the Preview window magnifies but does not activate the window. This is fixed. Now the first click in the content region of an inactive Preview window activates that window, but an additional click is needed to magnify.

TeXShop Changes 4.38

The magnification glass code in 4.37 had bugs. With the glass active, it was impossible to scroll the pdf window with a track pad. Moreover, the window could not be resized, and the mouse-based scroll bar did not work; instead both actions triggered the magnifying glass.

These problems are fixed in 4.38.

The fixes should be sufficiently tested today to insure no future problems. But just in case, anyone with source code can return to the original version of the glass before 4.37 was released. On line 59 of globals.h, the code "#define IMMEDIATEMAGNIFY 0" occurs. Remove this line or comment it out and recompile.

TeXShop Changes 4.37

Version 4.35 fixed an important and long-standing bug. Version 4.36 was never released. Version 4.37 fixes two cosmetic bugs, which have annoyed me for some time. TeXShop should be ready for Catalina, so I anticipate several months of stability before further work is again required.

TeXShop Changes 4.35

Versions 4.32, 4.33, and 4.34 were never officially released. They were experimental versions as I attempted to understand the "sudden halt" bug.

The key feature of version 4.35 is that it contains a fix for the "sudden halt" bug. This is explained in detail at the end of this section. Version 4.35 has these additional changes:

The "sudden hang" problem is by far the most difficult debugging task I've faced in TeXShop history. You may want to stop reading here, because I'm about to recount the story leading to elimination of the bug. It turns out that someone else faced the same bug in 2006 and found a solution.

Around two years ago, a small number of users reported that occasionally during typesetting, output to the console abruptly stopped. This could happen in the middle of output, so the console output looked like this:

   Chapter 6.
   [65] [66 <./Cover.pdf> <./Mesh.pdf
   pdfTeX warning: /Library/TeX/texbin/pdflatex (file ./Mesh.pdf): PDF inclusion: 
   multiple pdfs with page group included in a single page
   >] [67] [68] [69

A few users believed that typesetting continued to the end of the document, but the majority stated that typesetting ended with this console output. I could not reproduce the bug. The first reports were for macOS Sierra, and continued with High Sierra and Mojave. When the bug occurred, users just typeset again and continued their work.

Gradually the bug reports became more urgent. Users reporting the bugs tended to be working on the last stages of a book with pdflatexmk, so they would change scattered pages throughout the document and then typeset, run makeindex, typeset, run bibtex, and typeset twice more in a run. In the end, some users ran into the problem every three or four jobs.

I ran across the bug very, very rarely in my work, perhaps three times in a two year span. This made it impossible to debug. Eventually, three users sent their complete projects and I could at last see the bug with regularity. Thanks to all three. At the time I got these projects, I was creating MacTeX-2019, and then learning how to notarize it and make the TeXLive command line programs adopt a hardened runtime, since Catalina will require these features. When that was done, I was invited to spend a day at the PreTeXt conference and got interested in modifying TeXShop so it could be used with PreTeXt. Only then, about two weeks before the 2019 TUG Conference in Palo Alto, did I have time to turn to the "sudden hang" bug. By that time, the document which displayed the bug most readily was a book by M. Tamer Özsu and Patrick Valduriez, and that became my standard debugging document. Thanks in particular to those authors.

Several people reporting the bug tried their own debugging, and discovered to their dismay that when TeXShop was run in XCode using the debugger, the bug did not occur. Gulp.

When TeXShop typesets, it uses a Cocoa object named NSTask to spawn an independent process which runs tex or latex. TeXShop uses NSTask to run several other TeX binaries, for instance to convert dvi files to pdf. My first suspicion was that these various NSTasks were interfering with each other, and I was inadvertently killing the TeX task in the middle of typesetting. To test this, I added a large number of NSLog statements to the TeXShop code and watched these in Apple's Console app during typesetting. These logs convinced me that no other Tasks ran during typesetting, so the initial guess was wrong. Moreover, the logs revealed that when typesetting abruptly halted, TeX reported that the terminationStatus was 13 or 141.

Then I turned to Google for an explanation of these numbers. But unfortunately, the first article I read said that programmers were allowed to number exceptions any way they pleased, so it would not be possible to decipher the numbers. For a few days, I gave up. Then I turned to Google again, and found that some programmers like small numbers for their own exceptions, and report (exception + 128) for system exceptions. Notice that 141 = 128 + 13. Aha.

More Google searching turned up an article listing standard exception numbers used in Linux and Unix programs, and exception 13 was listed as "SIGPIPE or 'Broken pipe', sometimes indicating an attempt to write to a pipe with no readers."

At this point, it helps to know more about how Cocoa programs run other independent programs. As mentioned earlier, Cocoa has an object called NSTask which abstracts this operation. To call a separate program, a programmer initializes several NSTask instance variables to point to a full path to the new program, to fix the environment variables, to determine the location of the file to be processed, and so forth. Then the programmer starts that task using the call [NSTask launch]. At that point, an entirely separate program begins running on the Macintosh.

In Unix, separate programs are completely independent. TeXShop knows nothing about TeX and TeX knows nothing about TeXShop. But sometimes these separate programs must communicate. For example, TeX needs to send a stream of information to the TeXShop console during typesetting. This communication is handled in Unix by creating a Pipe. You can imagine a Pipe as an area of memory which both programs are allowed to access; TeX can write to this memory area, and TeXShop can read from it. Cocoa has an object called NSPipe for creating and processing such a pipe.

Typical Unix programs have a very beautiful structure. They open three pipes when they run, called "standard input", "standard output", and "standard error." By default, standard input is connected to the keyboard, so anything typed on the keyboard will be sent to the program. By default, standard output is connected to the computer screen, so any information produced by the program will be sent to the screen. Ignore standard error for the moment. As an example, open Apple's Terminal program and type "cat". This runs a very simple program which accepts strings from standard input and outputs the string to standard output. Notice that everything you type flows to the screen. Type command-C to kill the program.

However, Unix has a simple method to connect standard input and standard output to different devices, like files. If the standard input of "cat" is connected to a file, then that program will output the file to the screen.

Unix also allows programs to be chained together, so standard output of the first program becomes standard input of the second program. In this way, complicated actions can be done by stringing simple programs together.

The information TeX sends to the console during typesetting is actually sent to its standard output. Occasionally, TeX will report an error and then stop. Users learn to type RETURN in the console at this moment. This RETURN is sent to TeX's standard input, where it tells TeX to ignore the error and continue typesetting.

So now we know that the "sudden halt" error occurs when the console suddenly stops writing data, and we know that the error is caused by a problem in a Pipe, and we know that data gets from TeX to TeXShop by flowing through the pipe called standard output. It is all beginning to make sense!

How exactly does data get from that Pipe into TeXShop. I remember very well the day in 2001 when I learned how to do that, because the method seemed magical. The first step is to attach to the standard output pipe another Cocoa object called a ReadHandle. The line of code that does that is

     self.readHandle = [self.outputPipe fileHandleForReading];

How does this readHandle work? It works sort of magically; we ask it to read from the Pipe and it does that and sends us the result. For instance, two methods we can call are "readDataToEndOfFile" and "readDataOfLength:".

The documentation for this object suggests that fairly complicated things are happening in the background. Here is part of this documentation: "When using a file handle object to communicate asynchronously with a socket, you must initiate the corresponding operations from a thread with an active run loop. Although the read, accept, and wait operations themselves are performed asynchronously on background threads, the file handle uses a run loop source to monitor the operations and notify your code appropriately. Therefore, you must call those methods from your application’s main thread".

But notice that the file operations just mentioned are not exactly what we want when sending information to the console. We don't want to wait until typesetting is over, and then send everything to the console at once. Instead, we want to send information to the console as TeX writes it out to the pipe. Here is when the real magic starts to occur. NSFileHandle objects have another call called "readInBackgroundAndNotify". This call causes the fileHandle to wait until data appears in the Pipe, and then read what is there (removing it from the Pipe) and then send a Notification to anyone who asks to see that data. Such "notifications" are a standard part of Cocoa programming. A procedure can register to see particular notifications when they are send, and then act upon them.

Early in TeXShop operation, the program runs the code

     [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(writeConsoleOutput:)
                 name:NSFileHandleReadCompletionNotification object:nil];
This says that whenever a ReadHandle has data waiting, TeXShop will receive the information in a method called writeConsoleOutput, and do with it whatever it wants to do. The current code looks something like this:
     - (void) writeConsoleOutput: (NSNotification *)aNotification {
         NSFileHandle *myFileHandle = [aNotification object];
         if (myFileHandle == self.readHandle) {
              NSData *myData = [[aNotification userInfo] objectForKey:@"NSFileHandleNotificationDataItem"];
              if ([myData length]) {
                    NSString *newOutput = [[NSString alloc] initWithData: myData encoding: NSUTF8StringEncoding];
                    NSRange theRange = [outputText selectedRange];
                    theRange.length = [newOutput length];
                    [outputText replaceCharactersInRange: [outputText selectedRange] withString: newOutput];
                    [outputText scrollRangeToVisible: [outputText selectedRange]];
              [self.readHandle readInBackgroundAndNotify];
Skipping the small details, this code says to ignore the notification unless it came from the ReadHandle associated with this particular document. In that case, it should obtain the Data which the handle read, and convert it to a string. If the string is not empty, it should be added to outputText, the text object in the Console Window.

Notice carefully that the procedure ends by calling ReadInBackgroundAndNotify again. So that call only asks the FileHandle to read once. If we want it to occur over and over, we need to call it after processing the data from the previous call.

Our detective story has reached the moment when the TeX User Group Summer Conference at Palo Alto began. So at the moment, I suspected a bug in readInBackgroundAndNotify or in writeConsoleOutput.

Two discoveries were made at the conference. First, I tried the sample Özsu and Valduriez document on Catalina and could not produce the bug. So maybe it was an Apple Bug which is fixed in Catalina. That would be good news. On the other hand, beta versions of macOS contain a lot of debugging code which is later removed, and our bug is hard to reproduce in a debugger. So another possibility was that when Catalina was released, the bug would suddenly show up there.

Second, on the first day of the conference I got email from Martin Hairer at Imperial College, London. He had run into the bug, had independently performed the analysis just discussed, and had decided that the problem was the routine "writeConsoleOutput" displayed earlier. I did not display the full TeXShop code when I displayed the code a few paragraphs ago; my routine also had code to parse the TeX output, looking for error messages. These messages were later used to create a "Goto Error" button. Hairer thought that the bug was caused by too much processing in "writeConsoleOutput" so that by the time "ReadInBackgroundAndNotify" was called, the Pipe was completely full. He sent a really beautiful fix. Rather than process the output in "writeConsoleOutput", he called "dispatch_async" to do the processing on a separate thread and then ReadInBackgroundAndNotify could be called immediately. This code was deeper than code I usually write; I glued it into TeXShop and crossed my fingers.

Unfortunately, both Hairer and I concluded a few hours later that this code does not really fix the bug. But the code remains in TeXShop 4.35 because I think it is much safer than my original code.

At any rate, I left the TUG conference convinced that our "sudden hang" bug is really an Apple bug, and I needed to report it to Apple. My experience is that developer support gives much better response if you send them a small application, together with source code, which exhibits the bug. So I knew that before writing Apple, I needed to create a very primitive form of TeXShop to send them. I spent labor day weekend writing that application.

I'm proud of the resulting small app. It had only five pages of source code and typesetting code was confined to a single page. It could read and write TeX files, and put up a source window, a preview window, and a console window. At the top of the source window were three objects: a Typeset button, a popup menu listing available typesetting engines, and a Kill Aux Files button. The program contained all engine files currently in TeXShop and thus could do any typesetting job that TeXShop now does.

When the program was completed on Labor Day in the U.S., I typeset the Özsu and Valduriez document and almost immediately got a "hang bug." This was good news, absolving TeXShop of most possible blame.

But before sending the code to Apple, I wanted to make sure that NSTask in the typesetting part used all the latest ideas, so Apple's wouldn't respond by saying I was using deprecated calls. For instance, I used Hairer's code for writeConsoleOutput . I also spent a little time Monday Evening reading Google to see if I could find other pages I hadn't yet read about NSTask.

This led to a page https://stackoverflow.com/questions/412562/execute-a-terminal-command-from-a-cocoa-app from 2011. This page contained a question about calling Terminal from a Cocoa App, and the answers all involved using NSTask to call Terminal and getting output back through a Pipe. Early answers suggested reading that Pipe with "readDataToEndOfFile" and later answers suggested instead the call "readInBackgroundAndNotify". I knew all of that. But then, about 2/3 of the way down the page, a user named Custos Mortem said:

     I'm surprised no one really got into blocking/non-blocking call issues
     For blocking/non-blocking call issues regarding NSTask read below:
          asynctask.m -- sample code that shows how to implement asynchronous 
          stdin, stdout, and stderr streams for processing data with NSTask
     Source code of asynctask.m is available at GitHub.
Here "asynctask.m" was a link to a page of code, also from around 2011. This code had an interesting routine I'll come to in a moment, and the following associated text:
        For "availableDataOrError:" see:
        - "NSTasks, NSPipes, and deadlocks when reading...",
        - "NSTask stealth bug in readDataOfLength!! :(",
Unhappily, both of these links were dead.

Later, Bruno Voisin taught me about an archive site which archives important dead pages, and I've managed to read both of these links. So I know that the crucial code in asynctask.m was actually written in 2006 by by Chris Suter, and described on CocoaBuilder.com. His code was then modified very slightly by Juan Leon.

So late Monday evening, I added this code to my small test program. The changes were minor. And then I tested the Özsu and Valduriez document and could not get a hang. The code on these pages, essentially due to Chris Suter, fixed the bug.

I hear you crying "enough history; what's the fix???"

The crucial call which reads the Pipe is

  [self.readHandle readInBackgroundAndNotify];
Something goes wrong during this read operation, but since it is done inside Cocoa, we have no chance to fix it. But actually, there is a slightly different call
       [self.readHandle waitForDataInBackgroundAndNotify];
This call again notifies us when data is waiting to be read, but this time it doesn't read it. So if we make this call, then we get to read the data ourselves, and if an exception occurs during the reading, we get a chance to fix it.

Both methods issue a Notification which calls writeConsoleOutput, listed above. The key difference will occur in the fourth line of the method. Originally this line reads

     NSData *myData = [[aNotification userInfo] objectForKey:@"NSFileHandleNotificationDataItem"];
which gets the data, already read, from the Notification object. The new code will replace this with
     NSData *myData = [self availableDataOrError: myFileHandle];
which calls a new routine to read the data. (We also need to replace the line "readInBackgroundAndNotify" at the end of the routine with "waitForDataInBackgroundAndNotify".

And now, at last, here is the new reading code by Chris Suter:

 -(NSData *) availableDataOrError: (NSFileHandle *)file {
    for (;;)
       @try {
          return [file availableData];
       } @catch (NSException *e) {
          if ([[e name] isEqualToString:NSFileHandleOperationException])
            if ([[e reason] isEqualToString: @"*** -[NSConcreteFileHandle availableData]: Interrupted system call"])
                 return nil;
   }  // for

TeXShop Changes 4.31

Versions 4.28, 4.29, and 4.30 were never released. Version 4.31 has the following changes:

TeXShop Changes 4.27

TeXShop 4.27 has four minor changes:

TeXShop Changes 4.26

TeXShop 4.26 has two minor changes:

TeXShop Changes 4.25

TeXShop 4.25 fixes an important memory leak. It fixes Applescript support, which broke a couple of months ago. And it continues the story of synchronizing with external editors started by TeXShop 4.24. Only people who configure TeXShop for an external editor will be interested in that third feature. But first, the memory leak, and applescript support.

If you do not use an external editor, you can stop reading here. Recall that TeXShop 4.24 and 4.25 have additional code for users of external editors. Both versions of TeXShop require some technical knowledge from users because they are concerned with activating the new features for as many editors as possible. Later versions of TeXShop will simplify the steps required of users, perhaps only requiring that they select an editor from a list in TeXShop Preferences.

When I was an undergraduate, my teacher claimed that Niels Bohr would say after a conversation ``We clearly don't understand this theory; let's write a paper about it.'' In that spirit, let me write about communication between independent programs on the Mac. In Unix, each program runs as a separate process with an independent address space, so direct communication is not easy and usually involves the Unix kernel.

One form of communication occurs when a program starts another program. It can then provide that second program with an unlimited number of parameters. GUI programs on the Mac are actually standard Unix programs in disguise, so they can be opened from the Terminal and additional parameters can be prescribed at that time. TeXShop doesn't use that ability, but it certainly calls programs like TeX, MakeIndex, XeTeX, etc., providing each with additional parameters. Some editors can also typeset; they call other programs in this way.

Shell scripts are a special case of this. When such a script first starts, it can retrieve the parameters used to call it, as $1, $2, $3, and so forth. Cocoa has a special class called NSTask for starting other programs, so communicating when new programs start is easy to implement on the Mac, and in particular communicating by starting shell scripts is easy.

Applescript is another form of communication between independent programs. Indeed, a major use of applescript is to make programs "scriptable", so they can be controlled by other pieces of code. Deep down inside, applescript implements special methods to make this communication between independent tasks possible. There are, however, two problems with applescript. The first is that it can be insecure, and in Mojave Apple started to address this problem by allowing programs to refuse to accept applescript communication. It is reasonable to fear future additional restrictions. (The second problem with Applescript may be my fault. I don't grok the language, and it doesn't grok me. So I waste hours and hours trying to make Applescript do something trivial, like pass more than one variable in a procedure.)

Notice that TextMate and BBEdit have another method of communicating with external programs. Each has an independent program in /usr/local/bin, which can ask the main program to perform certain tasks. I looked at the TextMate code. It called low level Unix socket commands; I admired it in the same way that I admired a 21 year old pianist who performed Liszt's Hungarian Rhapsody Number 6: fantastic, but something I could never do.

I once went to a NeXT developer conference, maybe the only one they held. At that conference, NeXT introduced "Distributed Objects", an easy way for independent programs to communicate on a NeXT. First, special "Connection Objects" established a connection between two programs. After that, one computer could run objects on the second machine and receive results back. The two programs could be running on the same machine, or different machines on a single ethernet network, or machines half way across the world. In the conference, NeXT showed slides containing the code necessary to establish such a connection. Each slide contained eight or ten lines of code.

This was in NeXTStep, which became OpenStep, and then Cocoa. So distributed objects are in Cocoa. I looked up the code recently. Every single routine in the API was deprecated.

However, there is a replacement, called XPC Services. I looked briefly at the code. It may be that this is the correct way to provide interconnection, particularly if AppleTalk has further restrictions. At the moment, I'm too lazy to proceed.

TeXShop Changes 4.24

Version 4.24 has three very minor changes:

TeXShop Changes 4.23

The changes in 4.23 are of two types. Some changes fix bugs in coloring and themes, and some fix bugs when NSTask is running latex and other TeX programs.

TeXShop Changes 4.22

Version 4.22 improves syntax coloring for footnotes and takes a first stab at fixing a typesetting bug. Unless version 4.22 is unstable, this will be the last version of TeXShop for several months because work is starting on MacTeX-2019.

TeXShop Changes 4.21

Version 4.21 is a minor release to clean up two syntax coloring bugs: Version 4.21 also includes an updated French translation by René Fritz of "TeXShop Tips and Tricks".

TeXShop Changes 4.20

Version 4.20 contains an updated "TeXShop Tips and Tricks" document by Herbert Schulz and fixes three annoying bugs:

TeXShop Changes 4.19

Version 4.19 cleans up three minor issues in 4.18:

TeXShop Changes 4.18

Version 4.17 was intended to remain the release version for several months. Two days after the release and out of the blue, I received four suggested code changes from Neil Sims, the Head of the Department of Mechanical Engineering at The University of Sheffield. Version 4.18 contains his changes and a minor extra bug fix. These changes are listed first. Sims' changes led to significant improvements in the underlying TeXShop code, and these improvements are explained at the end of this section for interested readers.

Aside: Each time I release TeXShop, I fear a complaint will arrive that the editor has become sluggish. Last summer I got exactly that complaint from an author writing a new physics textbook. He told me that it was painful to add new source text for his book, and sent the source to me. I typed a phrase, and then looked in horror as the letters I typed appeared on the screen at a rate of one every second.

This author's book was written in Hebrew, and he told me that most technical books in Israel are in English and don't run into this problem. At first I didn't understand the significance of this clue. Then by accident I changed the font used in TeXShop's source editor and completely fixed the problem. It turned out that the author was using a source font which did not contain Hebrew, but the Macintosh was intelligent and switched to a different font every time he typed in Hebrew. Since each LaTeX command was in English and the actual text was in Hebrew; the entire document had hundreds of thousands of font switches. Selecting a source font which contained both English and Hebrew fixed the problem.

Confession: TeXShop's editor must remain crisp and rapid, but for years there has been a dirty little secret within that editor. You might think that nothing much happens when you type a few letters into the editor, but you would be wrong. Every time new letters are about to enter the source, the NSText Cocoa class warns TeXShop and allows it to modify the letters. Then just after the letters appear, the class notifies TeXShop that it has added them. At these two moments, TeXShop is able to perform other tasks, and it is quite greedy using this power.

First, TeXShop must add syntax colors to the new characters. This cannot be done in isolation, since there is no way of knowing if the user is adding to a comment or finishing a TeX command. So TeXShop syntax colors the entire visible text on the screen after each new letter.

But in addition, the new letters may form a new tag. So every time a new letter is typed, the entire tags menu is reconstructed, which means that the entire source file must be read! As you'll guess, there are optimizations to speed this up. First, tag lines start with a backslash or comment sign. So TeXShop looks at the first character of each line and discards lines that could not contain tags. Second, the menu is constructed in "chunks". TeXShop studies 1000 characters at a time, and then pauses for .02 of a second to allow other things to happen. One of these other possible things is a new typed character, and in that case the menu construction starts from scratch.

Sims added an entirely new process to the list, which had to scan every word of the entire source to make his second popup menu. He hadn't optimized his code, so every time a new letter was added, TeXShop would have to read the entire source file a second time. So clearly I needed to optimize the label code, and I looked carefully at the tag code that I hadn't read for years. One interesting piece of code was added ten years ago by someone else just before the optimization to test the first letter of each line. That code read

      if 1
Said another way, it turned the optimization off!

Next I read Apple's documentation about PopupButtons, and discovered that such a button can notify the calling program when it is pressed, before it displays the menu. This suggested that TeXShop could postpone constructing the Tags and Labels popup menus until the user wants to use them, entirely removing those scary calls when entering text into the source. Experiments show that both menus are constructed rapidly. Thus in TeXShop 4.18 there a new Label tool from Neil Sims and both the Tags and Label popup menus are constructed on the fly when needed. Text entry should be much more efficient.

Some New Hidden Preferences, just in case: One lesson from the upgrades this summer is that things can go wrong and it is useful to protect users from new ideas. Therefore version 4.18 contains several hidden preference settings to switch back to old code if the new code causes problems.

Remarks on cocoAspell: Coco-Aspell is an alternate spell checker by Anton Leuski. Leuski's project allows users to replace Apple's own dictionaries with new dictionaries that can be made "LaTeX aware", while still using all the Apple spelling facilities. Leuski made the project open source recently; see https://github.com/leuski/cocoAspell,

I think of the project as the "gold standard" for TeX-aware spell checking. It has some minor problems. It can be difficult to install, and the latest commit to the open source project was August 5, 2017. Moreover, users must then use the dictionaries supplied with cocoAspell, rather than dictionaries by Apple or others. But it is my recommended approach.

TeXShop Changes 4.17

There are just two changes in 4.17:

TeXShop Changes 4.16

This version has several simple changes:

TeXShop Changes 4.15

In TeXShop 4.14, a file named TeXShop,scriptSuite and a program named ScriptRunner were inadvertently omitted from the TeXShop Application Bundle. This broke several Applescript macros. The missing files are again present in TeXShop 4.15.

TeXShop Changes 4.14

Version 4.14 is mainly about two small fixes:

TeXShop Changes 4.13

Version 4.13 fixes two small bugs in the Themes coloring system, and makes two other minor changes.

TeXShop Changes 4.12

TeXShop Changes 4.11

Versions 4.08, 4.09, 4.10, 4.11 are closely related, all dealing with Mojave issues. Read all of these change sections. The main purpose of 4.11 is to fix two Dark Mode problems on Mojave.

Users continue to complain that they cannot magnify source text with a keystroke. This is explained below, but to repeat, users must "Select All" first. So type

     command-A      command-=      command-=      etc.

Users also report that all but the first lines of paragraphs are indented. This is also explained below, but to repeat: To remove this feature, open TeXShop Preferences, select the Editor tab, and in the lower right corner change "Remaining Lines Paragraph Indent" from 30 to 0.

TeXShop Changes 4.10

TeXShop Changes 4.09

This version fixes a bug in the Theme Preference code of TeXShop 4.08. Apple's color picker has several modes, including options to choose colors using CMYK values or gray scale sliders. In version 4.08, TeXShop obtained colors from color wells, and asked these colors for their RGB values without first converting colors in other color spaces to RGB. Fixed.

In TeXShop 4.08 and 4.09, a slight change in the editor requires that users "Select All" before changing fonts or font sizes.

TeXShop Changes 4.08

This version of TeXShop works on Yosemite and above, but has been compiled on Mojave. The main purpose of the release is to fix TeXShop bugs when running on Mojave, and to support Dark Mode there. Here are the key details: There are additional features of TeXShop 4.08 that are not related to Mojave:

TeXShop Changes 4.02 - 4.07

Versions 4.02 - 4.04 of TeXShop were never released. Version 4.05, the original Mojave Beta, had a number of problems. Versions 4.06 - 4.07 were never released.

TeXShop Changes 4.01

Daniel Nowacki discovered that in some circumstances, most file menus could be disabled in Single Window Mode. This included Show Console, Show Log File, Close, Save, Print, Print Source, Convert Tiff, Abort Typesetting, and Trash AUX Files. The problem is fixed.

Other items in this menu are deliberately disabled in Single Window mode, like Duplicate, Rename, Move To, Revert To, and Page Setup. It is easy to work around these. But Daniel's expanded list was a real nuisance.

TeXShop Changes 4.00

There are three changes in TeXShop 4.00:

TeXShop Changes 3.99

There are two changes in TeXShop 3.99:

A user in Israel, Michael Gedalin, is writing a book in Hebrew using TeX. His source file often switches between English for TeX commands and Hebrew for the actual text. He complained that opening his source in TeXShop was slow and adding new text to the middle of the source file was very, very slow. Using either English or Hebrew, it was possible to type three words before any letters appeared on the screen.

Debugging this problem revealed an interesting cause. If the font used in the TeXShop editor contained both ASCII and Hebrew characters, there was no slowdown. But if the source font did not contain Hebrew characters, the Macintosh was smart enough to switch to a Hebrew font for Hebrew portions of the text. Unfortunately, this switch, repeated over and over in the text, was extremely slow.,

The lesson is clear. If you are writing in an unusual script, pick an editor source font which contains both ASCII characters and characters for your script. The Font Book, in Applications, lists for each font the scripts supported by that font.

TeXShop Changes 3.98

There are five changes in TeXShop 3.98:

TeXShop Changes 3.97

TeXShop 3.97 has a new preference setting determining whether the source editor is placed on the left or right side in Single Page mode.

Because work on MacTeX-2018 is beginning, TeXShop will not be further updated for several months.

TeXShop Changes 3.96

This version has one important change and several minor bug fixes:

TeXShop Changes 3.95

In High Sierra when previewing in "multipage mode", each typesetting job caused a flash in the Preview window before new material appeared. I found this behavior so disturbing that I didn't update to High Sierra until this week. TeXShop 3.94 completely fixed the problem. This fix was particularly significant because Apple revised the way they render pdf files and reported that the flash could not be repaired at their end. Without a TeXShop fix, we'd be stuck with the flash for years to come.

The fix worked by placing a picture of the old preview pdf over the Preview window just before switching to the new version of this pdf. The flash still occurred, but was hidden by the picture. One second later, the picture was removed, revealing the new pdf. The steps of placing a picture and later removing it were totally invisible to the user.

The fix had one small downside which I found barely noticeable: it caused a one second delay after typesetting before the new material appeared. This lost second caused several users to complain to me. A few of them used the preview in "single page mode," which does not have the flash bug. They complained of losing a second for no reason. Other users told me that they barely noticed the flash, but were annoyed every time they had to wait that additional second. Huh? Didn't notice the flash??!!

The only change in TeXShop 3.95 is additional preference settings to mollify these users. The program now has two hidden Preference settings. One turns the fix off. Note that the fix is only applied in High Sierra and above, so this setting only applies to those versions of macOS. To apply the fix, quit TeXShop, open Terminal in /Applications/Utilities, and type the following line:

     defaults write TeXShop FlashFix NO

However, I strongly recommend not applying this fix. Instead, experiment with the second fix, which reduces the delay before removing the picture of the old pdf. To apply the fix, quit TeXShop and type the following in Terminal:

     defaults write TeXShop FlashDelay 0.25
The value of the delay is measured in seconds and can be anything between 0.0 and 2.0. Other values are constrained to these values. If the delay is too short, the flash may still be visible, but on my High Sierra machine, a Mac Pro, the value 0.25 completely eliminates the flash and yet produces a delay of only 1/4 of a second, which is not noticeable to me. If this value works for most others, it may become the default in future versions of TeXShop.

If you still see the flash with this value, try 0.5. If you don't see a flash, but are still annoyed by the delay, try 0.01. If you complain of losing 1/100 of a second from your life every time you typeset, I will sympathize silently.

TeXShop Changes 3.93 and 3.94

Version 3.93 was never released. The main purpose of release 3.94 is to fix crucial bugs in TeXShop running on High Sierra. Here are the bugs:

After High Sierra was released, I dutifully noted these bugs and reported many of them to Apple developer support. Then I sat back and waited for fixes. The third entry was indeed fixed in High Sierra 10.13.2, but the other entries are still outstanding. However, unexpected behavior in a new version of Mac OS can have several causes. In some cases, TeXShop might have "shady code" which happened to work in earlier systems but was never really correct. In other cases, the problem could be an Apple bug. The most interesting situations occur when Apple rewrites code to improve the experience of most users, but that code breaks features of TeXShop and cannot be repaired.

All of the bugs above are fixed in TeXShop 3.94. Some of these fixes require new program logic. In these cases, the fix only runs on High Sierra and above, while the old code is still used on earlier systems to avoid problems on these systems.

Because these fixes solve almost all High Sierra problems, I intend to move over to that system immediately after TeXShop 3.94 is released.

There is one additional feature in 3.94. John Collins updated latexmk to version 4.54c, which fixes a problem with the previous version of latexmk. That version required a recent version of Perl and failed for users with an older version of OS X. The new version should work on all versions of OS X supported by TeXShop 3.94.

The rest of this report explains the fixes of the five bugs for those who are interested. Rather than taking them in order, I'll leave the most interesting case until last. The third item was indeed an Apple bug, and was recently fixed. The fourth item was fixed in TeXShop 3.91. I do not know if the cause was an Apple bug, so the workaround might eventually be removed or improved.

I found a workaround for the fifth bug. There are two useful pieces of information which could be placed in the second column of the search list. This column could display some of the surrounding text, or it could list the corresponding outline section. In High Sierra, TeXShop 3.94 shows surrounding text, and therefore avoids the bug. On earlier systems, TeXShop 3.94 shows the corresponding outline section if an outline is present, because those systems don't have this bug. But if no outline is present, TeXShop 3.94 shows surrounding text, rather than leaving the second column blank.

This brings us to the second bug, which was not an Apple bug at all but instead "shady code" in earlier versions of TeXShop. The Save Panel is mostly handled by Cocoa automatically. But programmers are allowed to provide an "accessory view" which will appear just above the buttons at the bottom, and extend features of the panel. If the programmer does not provide this accessory view, Apple provides one, showing a Popup Menu allowing the user to select the File Format of the saved file, which is essentially its extension.

TeXShop wants two Popup Menus in this view, one to choose the encoding of the file, and the other to choose its extension. Most users rightly ignore these popups, but they are useful in special cases. Creating an accessory view, and adding an "Encoding Popup Menu" are straightforward tasks. But Apple has already created the "File Format Popup Menu" and it is just a matter of grabbing their popup and adding it to our accessory view. Earlier versions of TeXShop contain ingenious code to do just that. Another word for "ingenious" is "shady." Unfortunately, the first reaction on rereading that code is "would that even work?" The answer is that it works in Sierra but not in High Sierra. It has been replaced with much more straightforward code. A Google search shows that other programmers faced the same problem and selected the straightforward approach rather than the shady one.

Finally, we come to the "flash after typesetting" bug, which was for me the most important problem. This problem turns out to be caused by a reworking of the Mac OS code to render pdf files. The new Apple code will render large documents with greater speed, but a consequence is an unavoidable flash if a pdf file is opened and immediately repositioned to the center of the document. Let's face it, that is an unusual operation unless you are editing and typesetting a TeX document. Unfortunately, the flash is a problem that Apple cannot solve.

However, TeXShop can solve the flash problem. Here's how that works. In Cocoa, "NSView" objects correspond to rectangular portions of the screen; these view objects know how to draw themselves. NSView objects can be layered, and in that case the top layer obscures lower layers unless the top layer is transparent.

After typesetting is complete and just before switching to the new version of the pdf file, TeXShop 3.94 takes a snapshot of the screen. It then creates a NSView exactly the size of the old pdf view in the Preview window, and places this view on top of the old view. The new view draws by showing the appropriate portion of the screen snapshot. Then the preview window is loaded with the new pdf view, which draws, flash and all. But we see nothing because the drawing is obscured by the NSView on top. Exactly one second later, the top NSView is removed, showing the new pdf underneath.

You might think that adding and removing this View would provide additional flashes, but such view manipulations have been a part of Cocoa since the beginning and the system is optimized to make such manipulations invisible.

This method depends strongly on the technique to get a snapshot of the screen. Many such techniques are available, but do not work well. For instance, I first tried a technique which obtained the pdf data to draw a portion of the screen. When this data was redrawn, font weights changed, and the screen became blurred for that one second interval. Google led me to the code now used to get that snapshot, and that open source code works like a charm. See the source for details.

There are a couple of possible problems with this fix, which users ought to know about. If you have several monitors, I do not know if the screen snapshot will provide the correct image. My High Sierra machine has only one monitor. I also don't know if one second is enough time to avoid the flash. It is for me, but my machine is quite fast. So in case of problems, please write.

TeXShop Changes 3.92

TeXShop Changes 3.90 and 3.91

Version 3.90 was never released. Version 3.91 has the following changes:

TeXShop Changes 3.89

Version 3.89 has the following changes:

TeXShop Changes 3.88

Version 3.88 has the following changes:

TeXShop Changes 3.87

The bug fix for Bibtex allowing citation keys with spaces turns out to be a bad idea. Bibtex documentation states that citation keys cannot have spaces, and the fix broke other user's Bibtex interaction. The fix has been removed. There are no other changes.

TeXShop Changes 3.86

TeXShop 3.86 fixes several minor issues reported by users since the release of 3.85. Most of these issues have been present for a long time.

TeXShop Changes 3.85

TeXShop 3.82 introduced "useTabs", an easy way to add tabs to projects with a root file and chapter files. TeXShop 3.84 added "useTabsWithFiles", a second method of adding tabs requiring a little more work for a lot more flexibility. Unhappily, the code for this second method broke the first method.


TeXShop 3.85 again activates both methods.

In High Sierra, tabs can be given special short names in place of the names of the files they represent. As the number of tabs increases, this becomes more and more useful. The second method of adding tabs has always supported these shorter names. A similar technique is provided in TeXShop 3.85 for the first method.

The magic line containing "useTabs" can be followed by an optional list of short names as in the example below:

% !TEX useTabs (one, two, , short name, five)
This additional parameter must be on the same line as "useTabs", but notice that single lines can wrap in the editor without adding a line feed. The short names are listed inside a pair of round brackets, and are separated by commas. White space at the beginning and end of a short name will be ignored, but a short name can contain more than one word, as in the above example. If the space between two commas is blank, the original name will be used for that file. If the list has fewer names than the number of tabs, original names will be used for the remaining tabs. If the list is longer than the number of tabs, names at the end will be ignored.

Version 3.85 runs on the original list of supported systems, including High Sierra. Tabs require Sierra and higher, and short names require High Sierra and higher. Short names can be input on Sierra, but they will be ignored on that system.

TeXShop 3.85 was compiled by XCode 8.3.3 running on Sierra. It runs fine on High Sierra, but the "short tab names" feature doesn't work there because XCode doesn't have API's for High Sierra. I tried compiling TeXShop on High Sierra using the beta copy of XCode provided for that system. The code worked fine in High Sierra and short tab names worked. But unfortunately, the resulting code had minor problems running on Sierra. The High Sierra version is available at the TeXShop web site at http://pages.uoregon.edu/koch/texshop/texshop.html.

The TeXShop 3.85 source code has one line commented out which must be activated to get short tab names on High Sierra. If you want to compile yourself on High Sierra, search the source file TSDocument.m for "High Sierra" and uncomment the following line of code

windowToTab.tab.title = self.includeFileShortNames[i];

TeXShop Changes 3.84

When version 3.82 of TeXShop was released, I said that it would be the final version of TeXShop until late fall. But bugs were discovered, so version 3.83 was released.

These versions of TeXShop created only half of the promised support for tabs, and I found that I couldn't stop in the middle. Version 3.84 completes tab support, and should finally be the last release until late fall. Note that tabs require Sierra or higher because Apple first added tab support in that version of macOS.

Tabs are not appropriate for all TeX projects. They work best on books and large articles with from five to fifteen chapters or divisions, each introduced with an \include command. Some authors prefer to divide their project into many more pieces, perhaps one file per section, and then associating a tab with each file would product unmanageably many tabs.

TeXShop has two mechanisms to enhance Sierra tab support. The first is very simple. Within the top 20 lines of the root file, add the line

% !TEX useTabs
When this command is given, TeXShop itself searches for \include files to associate with tabs; the mechanism should cover perhaps 70 percent of cases.

The second mechanism gives the user considerably more control over the tabs. Within the top 20 lines of the root file, add the line

% !TEX useTabsWithFiles
Below that, within the top 50 lines of the root file, add a line for each tab
% !TEX tabbedFile{chapter1/Introduction.tex} (One)
In this command, a path to the file shown in the tab is given in curly brackets. In the example, the path starts from the folder containing the project root file, but see more details below. Notice that the file extension must be included. That is because the second mechanism allows pdf, tiff, jpg, log, aux, and other files as tabs. Authors sometimes give source files long descriptive names, which makes the tab titles very long. The final piece of the above line in round brackets is optional, and gives a shorter tab name.

The optional short name will only be recognized in High Sierra, because it requires additional Apple API first made available there. Feel free to use the term in Sierra; it will cause no harm there, but will be ignored.

Finally, we list some technical details. The first mechanism searches for \include lines after \begin{document} in the body of the root file. It is common to list files without extensions, and in that case TeXShop adds the extension ".tex" when creating the tab. In the second mechanism, however, TeXShop will not change the extension given by the user, or add a missing extension, because tab files can have unusual types so the extensions provide crucial information. Both methods create at most 20 tabs and ignore lines which might create more of them. The "useTabs" mechanism only works if the root file has at most 20,000 characters, to avoid very long searches for \include lines in gigantic root files.

If a window with tabs is left open when TeXShop is closed, then the next time TeXShop is opened, macOS opens the window and recreates the tabs. The new tab mechanism recognizes this behavior and lets macOS do the job without itself creating tabs. However, macOS does not understand tabs made from pdf files, graphic files, and a few others, so some of the tabs may be missing. It is easy to get these tabs back. Close the document and then reopen it. This forces TeXShop to recreate the tabs, and then all tabs come back. Or open the missing files yourself and drag their windows to missing tabs. (This macOS behavior is not a bug; other features of TeXShop depend on it. We cannot have everything.)

Finally, a word about the path information between the curly brackets in the "tabbedFile" magic lines. Three types of path strings are recognized. The first are strings that start in the location of the root file. Examples include {chapter1.tex} and {Chapter1/Introduction.tex}. Longer strings of directories are allowed. When it sees this sort of string, TeXShop prepends the full path to the folder containing the root file.

Another possibility is a path starting at your home directory, like {~/Galois/Equations.tex}. Here ~ denotes the home directory, so this file is probably not in the project directory.

Finally, TeXShop recognizes full paths like {/Users/koch/Galois/Equations.tex}.

If you use still more Unix conventions, they may or may not work. No guarantees. Tests suggest that spaces are allowed in both directory names and file names, but I'm loathe to recommend them.

There are a few tricky points. The Finder often lists TeX source files without the ".tex" extension, but this extension is just hidden, not absent. It must be written as part of the tab file path. (During testing, I was confused by this point several times).

When TeXShop is asked to create a tab, it opens the file exactly as if a user had dragged the file icon to TeXShop and dropped it there. Then the window described in the tab is "tabbed." This creates a few surprising cases that look like bugs but aren't. For example, then TeXShop opens a dvi file, it actually converts the file to pdf using dvips and Ghostscript, and then opens the pdf file. So tabbing a dvi file will give a pdf file as a tab.

Here is another surprising case. Suppose that you are working on a project named "Galois.tex" and you earlier created a project named "Abel.tex". When you open Galois.tex, you want Abel.tex as a tab so you can refer to that source file as you write Galois. But if you drop the icon for Galois.tex on TeXShop, both Galois.tex and Galois.pdf will open in separate windows. Similarly dropping the icon for Abel.tex on TeXShop will open Abel.tex and Abel.pdf. After tabbing occurs, you'll have a tabbed window containing Galois.tex and Abel.tex, and you'll have Galois.pdf in a separate window. But you'll also have Abel.pdf in another window. The existence of this extra pdf file looks like a bug, but isn't.

This release of TeXShop was compiled by XCode 8.3.3 running on Sierra. It runs fine on High Sierra, but the "short tab names" feature doesn't work there because XCode doesn't have API's for High Sierra. I tried compiling TeXShop on High Sierra using the beta copy of XCode provided for that system. The code worked fine in High Sierra and short tab names worked. But unfortunately, the resulting code had minor problems running on Sierra. No doubt these will be fixed before the release of High Sierra.

Consequently, if you are beta testing High Sierra and want to use short tab names, you'll need to search the source file TSDocument.m for "High Sierra" and uncomment the following line of code

windowToTab.tab.title = self.includeFileShortNames[i];
Then compile on High Sierra.

TeXShop Changes 3.83

Murray Eisenberg discovered problems with the new "useTabs" feature and sent me his full source code to debug. This proved extremely useful! The problems I foresaw with this feature have not materialized, but Eisenberg's source revealed more elementary and embarrassing bugs, now fixed.

The only files which receive tabs are those loaded by \include{myfile} statements after \begin{document} in the root file. Here "myfile" can be a file name, partial path, or full path. Murray's document loaded chapters in a more complicated way, but was easily modified to meet this condition. It would be easy to extend TeXShop so an alternate method could also be used, in which the user lists files to be tabbed using "% !TEX fileForTab = " statements. This technique could assign files to tabs even if they aren't part of the source (for instances, tables of symbols), and could specifiy which chapters are tabbed for books with enormously many chapters. Write if you want this feature, which however will not appear until fall.

It is slightly possible that version 3.82 broke UTF-8 encoding in Japan and other far Eastern countries; the evidence is iffy at the moment. But if that happened, it is fixed in 3.83.

TeXShop Changes 3.82

After the release of MacTeX-2017 in May, I have been spending time on TeXShop dealing with bugs by other programmers which crashed TeXShop --- and TeXShop bugs which were my fault. Now I want to turn to new summer projects, so this should be the last TeXShop update until late fall. I'll return earlier only if significant new bugs are discovered.

This final summer release contains two features, one available only on Sierra and High Sierra, and the other only on High Sierra. We start with the High Sierra feature, which comes automatically to Cocoa applications without any new code by me.

TeXShop Changes 3.81

Version 3.81 fixes a small number of bugs in version 3.80:

TeXShop Changes 3.78 - 3.80

Versions 3.78 and 3.79 were never released. Version 3.80 has the following changes:

In addition to these changes, a small number of users ran into other issues running on macOS Sierra. Most users have had no trouble with Sierra, and find that it fixes a number of problems in the previous two or three systems, so these problems are rare:

First, a few users included the pstricks package in the header of their document, but used no features of this package and typeset with pdflatex. Usually pstricks requires TeX + DVI mode, so including it in the header of a pdflatex document is an error. But in Sierra, typesetting such a document with pdflatex created a pdf file that crashed PDFKit, Apple's pdf rendering code, and thus crashed TeXShop. This bug is fixed in High Sierra.

Second, some users writing beamer documents would typeset and scroll their document in TeXShop. A particular image in the middle of the document would create a glitch, and some following pages would be blank. Scrolling back up would give additional blank pages, even though they were correctly rendered earlier in the game. Eventually the document could crash TeXShop. This problem is caused by a PDFKit bug, and is fixed by Apple in High Sierra.

But in the meantime, we discovered that typesetting the same source with LuaLaTeX or XeLaTeX produces pdf files without problems. In addition, opening a defective pdf file with Adobe Acrobat Reader, and then saving that pdf file in Reader, produces a pdf file without problems.

One final problem occasionally occurs in Sierra. Many people use DropBox with TeXShop with no problems. A few of these users store their source files in the DropBox folder. A few of these folks report regular TeXShop crashes. In every case known to me, these crashes end when the TeX source files are removed from DropBox.

What is the explanation? I don't know, but I have suspicions. Recall that TeXShop uses Apple's Automatic Saving code, introduced in Lion. Thus the system can save the source at random times. A source file in DropBox can also be moved to the cloud at random times. What if both the Mac and DropBox want to make changes at the same time?

The Automatic Saving code is buried deep in Cocoa and isn't by me. The only piece of TeXShop code by me related to automatic saving says "turn automatic saving on."

Here's all I know about this problem.

But to repeat, many report no problems.

TeXShop Changes 3.76 - 3.77

Version 3.76 was never released. Version 3.77 has the following changes:

TeXShop Changes 3.75

There is only one change. In TeXShop 3.74 on Sierra 10.12.1, scrolling in the pdf window was jerky. This is fixed.

TeXShop Changes 3.74

TeXShop 3.74 fixes a small number of minor issues.

TeXShop Changes 3.72 and 3.73

TeXShop 3.72 finishes the task of preparing for macOS 10.12, Sierra. It also contains the changes listed below. The only change in TeXShop 3.73 is to improve the responsiveness of popUps when mousing over links.

TeXShop Changes 3.71

This version differs from 3.70 only in the German and Dutch localizations:

TeXShop Changes 3.69 and 3.70

Version 3.69 was never released. Version 3.70 has the following features.

TeXShop Changes 3.67 and 3.68

Version 3.67 was never released. The changes in version 3.68 are listed below:

TeXShop Changes 3.66

TeXShop Changes 3.65

This fixes a few problems introduced in 3.64:

TeXShop Changes 3.64

TeXShop 3.64 fixes a few problems with the Mac OS 10.12 (Sierra) beta. One change may be of independent interest. The most-often-requested new TeXShop feature is tabs in the source and preview windows. Sierra provides this feature automatically, without any additional TeXShop code. Creating these tabbed views is straightforward. Further details will be provided when Sierra is released.

TeXShop Changes 3.63

TeXShop 3.63 is an internal version, never released.

TeXShop Changes 3.62

TeXShop Changes 3.61

TeXShop Changes 3.60

TeXShop Changes 3.59

There are several small changes in TeXShop 3.59:

TeXShop Changes 3.58

Recent TeXShop versions have been released to fix or work around a series of El Capitan bugs, particularly in PDFKit. There are three major bugs:

When this bug occurs, it is fairly easy to obtain the missing image. With the blank page active, type command-shift-+ to zoom in and then acommand-shift-- to zoom back out. This causes the page to be displayed correctly.

However, it is better to insure that the blank page does not occur. Several instances of this bug were fixed in earlier releases. This release fixes three other cases:

Incidentally, all three bugs have been reported to Apple.

In addition, the following changes were made:

TeXShop Changes 3.57

TeXShop Changes 3.56

Debugging code accidentally left in version 3.55 caused a pause between typesetting and display of the new pdf. This is fixed.

TeXShop Changes 3.55

This version fixes two significant bugs when running in El Capitan:

TeXShop Changes 3.54

The Sparkle update mechanism was broken in 3.53. It is fixed in 3.54.

For some time, TeXShop has not contained the two movies which appear in the Help Menu. They are downloaded when the user requests them. This broke in 3.53, and is fixed in 3.54.

TeXShop Changes 3.53

El Capitan introduces a significant change for TeX users. The location /usr is no longer writeable, even by users with root privileges. Consequently, the symbolic link /usr/texbin has been relocated to /Library/TeX/texbin. This new link is automatically written by both MacTeX-2015 and BasicTeX-2015. If you updated to one of these, you have the link. Once the link exists, older versions of TeX like TeXLive-2013 also work fine.

GUI programs must be reconfigured to look for the new link. TeXShop 3.52 and later does this automatically.

For more information on TeX and El Capitan, see tug.org/mactex/elcapitan.html

TeXShop 3.53 includes the following changes:

TeXShop Changes 3.52

Many of the changes in version 3.52 prepare for OS X 10.11, El Capitan. In that system, the /usr/texbin link to the TeX binaries is replaced with a new link, /Library/TeX/texbin. Users who have installed MacTeX-2015 or BasicTeX-2015 already have this new link.

TeXShop Changes 3.51

TeXShop Changes 3.50

TeXShop Changes 3.49

TeXShop Changes 3.48.1

TeXShop Changes 3.48

TeXShop Changes 3.47

TeXShop Changes 3.46

TeXShop Changes 3.45.2

TeXShop Changes 3.45.1

TeXShop Changes 3.45

TeXShop Changes 3.44

Version 3.44 has the following changes

TeXShop Changes 3.43

Version 3.43 has the following changes

TeXShop Changes 3.42

Version 3.42 has the following changes

TeXShop Changes 3.40 and 3.41

Version 3.40 was never released. Version 3.41 has the following changes

TeXShop Changes 3.39

TeXShop Changes 3.38

TeXShop Changes 3.37

TeXShop Changes 3.36.2

TeXShop Changes 3.36.1

This version was released with version number 3.36.1 to test the operation of adding a final digit to the version number. In the future, this will be used for "silent updates" in which a minor problem is fixed in the first hours of a release. In the past we did not change the version number for such silent updates, but from now on we add a decimal digit to the end of the version in both the TeXShop home page and the program. We do not update change documents for minors updates. Source files are always updated at the same time as the program, even for minor updates.

TeXShop Changes 3.36

This is a minor update to clear up issues in the important version 3.35 release. It has the following changes:

TeXShop Changes 3.35

The step from TeXShop 2 to TeXShop 3 marked a significant boundary; version 3 has 64 bit code rather than 32 bit code and was compiled on Lion. The step from TeXShop 3.26 to TeXShop 3.35 marks a second significant boundary; version 3.35 uses Automatic Reference Counting rather than manual memory management and is compiled on Mavericks.

When Mavericks appeared a year ago, magnification code used in earlier TeXShop versions broke. It was replaced in 3.26 with code which worked on Mavericks, but not on earlier systems. TeXShop 3.26 used the older magnification code on older systems.

Later versions of TeXShop were compiled on Mavericks. Then the new magnification code worked on earlier systems, but the old magnification code broke. So TeXShop 3.35 uses the new magnification code on all systems. However, over the last couple of weeks testers discovered that this code leads to obscure crashes on Lion, but not on Mountain Lion and higher.

Consequently, in version 3.35, both magnification in the Preview window and selection of rectangular regions in the Preview window are disabled on Lion. Users of Lion should upgrade to Mountain Lion if at all possible, since these features will be active again. Users who cannot upgrade should consider moving to version 3.26 because the two disabled features work with that version. But version 3.26 will not be further upgraded and TeXShop Lion users will be stuck there in the same way that Snow Leopard users are stuck with TeXShop 2.

TeXShop 3.35 has the following additional changes:

TeXShop Changes 3.27 - 3.34

Versions 3.27 - 3.31 were never released. An experimental version of 3.32 had a limited release, and 3.33 was never released. Version 3.34 is the first regular release with these changes.

The most important feature of release 3.34 is that TeXShop's source code was revised to support ARC and the program was compiled using Automatic Reference Counting. Thus memory management is now done by the compiler rather than by hand. This should make the program much more stable.

Version 3.34 has the following additional changes:

TeXShop Changes 3.26

3.26 has the following fixes:

TeXShop Changes 3.25

TeXShop 3.25 contains the following fixes:

TeXShop Changes 3.24

There is only one change. The Sparkle upgrade mechanism in previous versions of the TeXShop 3 series does not work on Mavericks. This is fixed in 3.24.

TeXShop Changes 3.22 and 3.23

TeXShop 3.23 fixed one bug. In 3.22, if the user configured TeXShop to use an external editor and then set the hidden preference ExternalEditorTypesetAtStart to YES, the program crashed when opening a file. This is fixed in 3.23.

Version 3.22 has the following changes:

TeXShop Changes 3.19, 3.20, 3.21

Versions 3.19 and 3.20 were never released.

Version 3.21 has the following changes:

TeXShop Changes 3.18

Version 3.18 has only a single change:

TeXShop contains an obsolete sync method called Search Sync, and a modern replacement by Jerome Laurens called SyncTeX. In recent versions of TeXShop, the obsolete Search Sync from the Preview Window to the Source Window randomly hangs, making TeXShop unresponsive This was supposed to be fixed in version 3.17, but it wasn't. Unfortunately, when the modern SyncTeX cannot find a match, it calls the old Search Sync, so SyncTeX can indirectly hang as well.

It is silly to waste time on an obsolete method, so in TeXShop 3.18, Search Sync from the Preview Window to the Source Window is disabled and does nothing. Most users will notice no change. Users who misconfigured SyncTeX will lose synchronization.

Users should check that

TeXShop Changes 3.17

Version 3.17 has the following features:

TeXShop Changes 3.16

Version 3.16 has the following features:

TeXShop Changes 3.15

Version 3.15 has the following features:

TeXShop Changes 3.12 - 3.14

Versions 3.12 and 3.13 were never released. Some users downloaded beta copies of 3.12 to fix 3.11 bugs. Version 3.14 has the following features:

TeXShop Changes 3.11

TeXShop Changes 3.10

TeXShop Changes 3.09

TeXShop Changes 3.08

TeXShop Changes 3.07

TeXShop Changes 3.06

The changes in 3.06 are by Yusuke Terada.

In addition, Terada improved OgreKit 2.1.4 to make it more useful.

TeXShop Changes 3.05

TeXShop Changes 3.04

TeXShop Changes 3.03

TeXShop Changes 3.02

TeXShop Changes 3.00 and 3.01

TeXShop Changes 2.47

TeXShop Changes 2.46

TeXShop Changes 2.44 and 2.45

TeXShop Changes 2.42 and 2.43

TeXShop Changes 2.41

TeXShop 2.41 adds some new features.

TeXShop Changes 2.40

TeXShop 2.40 fixes a small number of minor bugs.

TeXShop Changes 2.39

TeXShop 2.39 fixes a significant bug for users who write in Hebrew and Arabic. In version 2.38, typesetting sometimes displaced diacritical marks left one character, even though the source looked correct. The problem was not in the typesetting, but instead in the source code, which was converted to an incorrect form when saved. This is fixed. See the explanation which follows.

TeXShop Changes 2.38

Version 2.38 contains some wonderful changes by Yusuke Terada, who made the changes at the request of employees in the company he works for in Tokyo. Most of Terada's changes are activated by new items in the TeXShop Preference Panel, which are turned off by default. So users need to turn these items on and experiment. You can easily return to the old behavior if desired. Here are Terada's changes:

In addition to the work of Terada, TeXShop 2.38 has the following changes:

TeXShop Changes 2.37

TeXShop 2.37 is an extremely minor upgrade.

TeXShop Changes 2.35 and 2.36

TeXShop Changes 2.34

TeXShop Changes 2.32 and 2.33

TeXShop Changes2.31

TeXShop Changes2.30

TeXShop Changes 2.27 - 2.29

Here are the changes:

TeXShop Changes 2.26

Version 2.26 is a minor upgrade to fix several bugs in 2.25. Here are the changes:

TeXShop Changes 2.21 - 2.25

Versions 2.21 - 2.24 were internal builds, never released. Here are the changes in them and version 2.25:

TeXShop Changes 2.19 - 2.20

Version 2.19 was an internal version, never released. Here are the changes in it and version 2.20:

For Users of Previous Versions

Changes in TeXShop 2.16 through 2.18

Versions 2.16 and 2.17 of TeXShop were constructed for test versions of MacTeX-2008, and released only to a few people testing that install package. Version 2.18 is now officially released on the TeXShop site. Here are the changes:

Changes in TeXShop 2.15

TeXShop 2.15 was an experimental release. It lived for a long time on my personal web page with a promise to migrate it to the usual TeXShop site. After the promise didn't materialize for several months, the link on my personal site was noticed by Version Tracker, and for several months that system pointed to the experimental 2.15 as the latest release. At last 2.15 has become "official" with the release of TeXShop 2.18.

Here is a list of new features:

Here are more details on each of these items.

Changes in TeXShop 2.14

Changes in TeXShop 2.13

Changes in TeXShop 2.12

Changes in TeXShop 2.10 Beta 10

Changes in TeXShop 2.10 Beta

The following change was made to TeXShop 2.09d

The following change was made to TeXShop 2.09c

The following change was made to TeXShop 2.09b

The following changes were made to TeXShop 2.09a

The following changes were made to TeXShop 2.09

The following change was made to TeXShop 2.08

The following change was made to TeXShop 2.07

The following changes were made to TeXShop 2.06

The following changes were made to TeXShop 1.43

Versions 1.42 and 2.05 add new features and fix several bugs:

New features in 2.05:

New features in 1.42 and 2.05:

Bugs fixed in 1.42 and 2.05:

Changes in 1.41 and 2.04

Changes in 2.03

Changes 1.40

Changes in 2.02

Changes in 1.39

Changes in 2.01

Changes in 1.38

New Features in 2.00

New Features in 2.00 and 1.37

Version 1.36 was never released

Version 1.35 adds new features and fixes several bugs:

Version 1.34 adds new features and fixes several bugs:

Version 1.33 adds new features and fixes several bugs:

Version 1.32 adds new features and fixes several bugs:

Version 1.31 adds new features and fixes several bugs:

Version 1.30 fixes several bugs.

Version 1.29 adds many new features and fixes several bugs.

Version 1.28 fixes some minor bugs in 1.27 and adds a few extra features:

The following changes were made in version 1.27:

The following changes were made in version 1.26:

The following changes were made in version 1.25:

The following changes were made in version 1.24:

The following change was made in version 1.23:

The following change was made in version 1.22:

The following changes were made in version 1.21:

The following changes were made in version 1.20:

The following changes were made in version 1.19:

The following changes were made in version 1.18:

The following changes were made in version 1.17:

The following changes were made in version 1.16:

The following changes were made in version 1.15:

The following changes were made in version 1.14:

The following changes were made in version 1.13:

The following changes were made in version 1.12:

The following changes were made in version 1.11:

The following changes were made in version 1.1:

Version 1.1 of TeXShop is accompanied by a new compilation of teTeX by Gerben Wierda. The new compilation has numerous bug fixes and improvements, including

The following changes were made in version 1.0:

The following changes were made in 1.0d6:

The following changes were made in 1.0d5:

The following changes were made in version 1.0d4: