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

TeXShop History

TeXShop Changes 5.04

Developers were given a preliminary version of macOS Ventura 13.1 around November 10, 2022. TeXShop has a serious bug when run on that system. The bug is fixed in TeXShop 5.04, and users should upgrade now to avoid the bug when Ventura 13.1 is released.

The bug is dramatic. If you open a new source window and enter some text, and then attempt to close the window, the window remains and becomes a zombie.When you quit TeXShop and open it again, the window reappears. There is no way to get rid of it.

This dramatic behavior has a trivial cause. TeXShop adds a menu to the Save Dialog allowing users to set the encoding of the saved file. In all recent versions of TeXShop, the code creating this menu has one bad line which did nothing on earlier systems, but stops the Save Dialog from opening in Ventura 13.1. That bad line of code is no longer in TeXShop 5.04.

I took this opportunity to entirely remove the encoding pull-down menu from the Save Dialog. It is still present in the Open Dialog because a user could receive a file from a colleague with an unusual encoding and want to open that particular file. If a user then edits the file and saves it, the encoding used to open the file is also used to save it, so an encoding menu isn't needed in the Save Dialog.

If you use the Save Dialog's encoding menu for other reasons, you can bring it back with a new hidden preference setting:

     defaults write TeXShop EncodingMenuInSaveDialog YES

The encoding menu in the Save Dialog is typically used in one of two cases. The first is when a brand new file is saved and the user doesn't want to use the default encoding set in Preferences. In this case, a user could add a magic comment line setting the encoding to the unusual value and achieve the same result. The other case is when users are trying to convert a file from one encoding to another. That kind of conversion is tricky; opening a file in one encoding and saving in another can fail and lose information. Removing the encoding menu from the Save Dialog removes the temptation to act without careful planning.

TeXShop Changes 5.03

After the release of version 5.02, a few small problems emerged, particularly in the demo program. I made corrections on my web page without changing the version number, so if you downloaded early, you might have small flaws and if you downloaded later, you don't. Two larger problems were reported and fixed the same way.

Now that the program is stable, it is time to bring everyone up to date. I do not expect further TeXShop updates for a couple of months, fingers crossed. Here are the two important bugs:

TeXShop Changes 5.02

TeXShop 5.01 came with a demo source file and support document explaining how to create web projects with interactive elements using TeXShop 5 and TeX4ht. Within days of releasing the program, I discovered a much better way to create these documents. In the new method, the interactive pieces of the document, which are written in html, can be written directly in the source code for TeX4ht, and the resulting web page can be read linearly with interactive elements following other text in the main document.

The demo source and support document have been revised to reflect this discovery. That is the main reason that TeXShop 5.02 has been released. As before, after installation go to ~/Library/TeXShop/New and copy the Demo folder to your home directory or another place you store TeX source files. When you have time, open this folder and follow the instructions inside.

Two other issues are addressed:

TeXShop Changes 5.01

Recall that ~/Library/TeXShop stores user configuration files: templates, typesetting engines, macros, etc. Because users will modify the contents of most folders, TeXShop does not rewrite them during updates. But a few folders are rewritten. Users can edit typesetting engines, so ~/Library/TeXShop/Engines is not modified. But Engines/Inactive is a collection of alternate engines, and that folder is completely rewritten each time you update TeXShop so it contains the very latest versions of these unused engines.

If you think a folder is out of date, you can throw it away or move it to the desktop. The next time TeXShop runs, it will rewrite that folder using default values.

On rare occasions it is advisable to modify a file in a folder whose contents you can edit. In those cases, the required modification is described in "About This Release" in the TeXShop Help Menu. Theoretically users will read "About This Release" every time they upgrade the program. Usually it will say that no changes are needed.

One special folder, ~/Library/TeXShop/New, is completely rewritten each time TeXShop is updated. For several years I kept old material in that folder, just in case. In version 5.01 I cleaned that folder and it now contains only two folders required for version 5.01 and explained in "About This Release".

Now on to other issues. The following changes were made:

TeXShop 5.00 and 5.01 contain new features to facilitate the creation of classroom material which combines the clear logical treatment of a set of pdf notes with the interactive features of a rough and tumble classroom and web experience: experiments, movies, question and answer sessions, and the like. You won't notice these changes unless I point them out. So I constructed an example project and an elaborate document that explains how that project was created. I'm hoping that most TeXShop users will read that document and work their way through the example project.

The example adds about a megabyte to the size of TeXShop, but the elaborate document explaining it has lot of pictures and size almost 10 megabytes. Where could I put it? I decided to put it in ~/Library/TeXShop/New. This increases the size of the TeXShop download by about 10 megabytes. But in a few months after the example has been distributed, it will be removed from New and we'll be back to the old download size.

I recommend that after installing TeXShop 5.01, you go to TeXShop's "TeXShop menu" and select "Open ~/Library/TeXShop." Open the "New" folder and copy the complete folder named "Demo" to your home directory or another place you save TeX projects.

When you have a little time, go to that Demo folder. Read the short file "Preparing-for-the-Demo". The last paragraph will explain what to do next. Good luck.

TeXShop Changes 5.00

Version 5.00 is a major new release of TeXShop. But when typesetting traditional documents, there are no changes. Most users will see nothing new until they read this document.

Rather than immediately explaining the new features, I'll demonstrate one addition. Make sure a document is open in TeXShop or an empty source window created by the "New" menu item is visible. In the Preview menu, there is an item labeled "Show HTML Window". Select this item. A window will appear looking like a Safari window and displaying HTML content.

The Apple API's used by TeXShop contain a class called WKWebKitView which implements a web view for any standard Macintosh program. The new HTML Window in TeXShop was created that way. Notice that the links in this page are active, so while the HTML code for the initial page is contained in TeXShop, it is easy to get to web pages that are live on the web. Toolbar arrows allow you to move back and forth between pages. Almost all web features are active in this window.

A URL field at the top of the new window allows you to navigate to any web page you like. Unlike Safari, this field does not do Google searches, and it is very strict about syntax, so if the URL you type is not precisely correct, nothing may happen. The toolbar also contains a Search Field, but it is not currently active and will be activated in a future version of TeXShop.

The HTML Window behaves like the Source and Preview windows. Move it to a reasonable position, probably on the right side of the screen, give it a reasonable size, and then choose the menu item "Save HTML Window Position." After that, the window will always appear in the selected position.

In TeXShop Preferences under the Preview tab, there are new items for the HTML Window. If you fill in the "Home URL" item with the URL of a significant web page, that page will appear rather than the TeXShop default page when selecting "Show HTML Window".

All this is well and good, but Safari does the same thing with much more support in the interface. So what's the point?

A Short Essay on NSDocument

TeXShop is constructed using the NSDocument class in the Cocoa APIs. It has a nib file containing all the graphical elements used by a typical document, and source code files which process that document. When I program TeXShop I imagine that it only opens and processes one document at a time; thus the text in the source window will always be the source for that document, and the view in the preview window will always be the pdf for that document. All of the extra code to handle multiple documents is provided automatically by Cocoa.

When a new document is opened, all of the objects in the NSDocument nib file for that document are instantiated at once. Some are shown and many are hidden away to be used later on. These objects include a source window, a preview window, a console window, a log window, a window with two panes for single window mode, and an extra graphics window in case the user opens a tiff, jpeg, or png file. The key new feature in version 5.00 of TeXShop is that the document nib file also contains an html window which can show live html content. Thus if a typesetting engine produces html files rather than pdf files, the html file can be previewed directly in TeXShop.

Recall that "Show HTML Window" opens a default HTML Window. This is not a global window available for common use by all documents. Instead it is the particular HTML window assigned to the active document. To verify this assertion, close all documents and notice that the "Show HTML Window" menu item is grayed out. If you have two open documents, activate "Show HTML Window" twice, once when each document is active. Notice that you get two HTML windows. They will appear at the same spot, but you can separate them.

An Example which Finally Illustrates the Point of All This:

Another Important Example:

How Are HTML Engines Constructed?

TeX User Group Conferences

Next I claim the privilege of interrupting this change document to write a blog post. Apologies.

The TeX User Group (TUG) was founded in 1980, shortly after the appearance of TeX. It publishes a journal, TUGboat, three times a year and creates the distribution TeX Live, which works on almost all computer platforms. TeX Live is created in collaboration with similar TeX User Groups in other countries. TUG holds an annual meeting each year, sometimes in the U.S. and sometimes abroad.

In 2001 after MacOS X was released, I was invited to speak at the national TUG conference in Delaware by Wendy McKay; TUG offered to pay my way. I knew almost nothing about TUG, but imagined a conference of 2,000 users. We would meet in a large auditorium and listen to talks on solving common typesetting issues. Perhaps 100 Mac people would be there, excited to hear anything about MacOS X. When I got to Delaware, I discovered that there were 45 people at the conference and almost every one was on the program. They paid their own way. I sheepishly refunded the travel money back to TUG. There were only three or four Mac folks, but they all became significant in my life.

Wendy worked for Jerrold Marsden at CalTech. Marsden was a leading authority in classical mechanics, and is the author of many well known mathematical textbooks. He used a Macintosh to write mathematics very rapidly, and invited TeX experts to CalTech to solve TeX problems. Among these was Ross Moore from Australia, who was also at the Delaware conference. He knows more deep facts about LaTeX than anyone I know, and has often spoken at TUG conferences. He is currently working on accessibility for pdf documents written with LaTeX. Hans Hagen, author of ConTeXt, was also at Delaware.

Delaware had a special honored guest, Hàn Thế Thành. His pdftex program added code to Knuth's TeX which output pdf files rather than dvi files. His project was absolutely crucial for TeXShop because otherwise I'd have to make a dvi viewer, far beyond my capabilities.

Thành came from Vietnam and his pdftex work was part of his PhD thesis from Masaryk University, Brno, Czech Republic. He talked about that thesis at the conference, beginning with a detailed image of a page from the Gutenberg bible. This remarkably beautiful page had absolutely straight right margins. But when you measured with a ruler, they turned out not to be straight; instead commas and periods were pushed slightly into the margin, creating the illusion of a straight side. In his thesis, Thành added that ability to pdfTeX and pdfLaTeX.

I began my talk in Delaware by installing TeX onto a new MacOS X machine using Gerben Wierda's installer. In the process, the Finder crashed and I spent ten seconds restarting it. After the talk, a participant said to me "I'm not interested in your program, but it is amazing that you could restart the Finder without rebooting the machine."

I have been to many TUG conferences. In Hawaii, the organizers pulled us out to look at the sunset because Mercury was visible close to the horizon. A few days later they pulled us out at noon because on that one day at that one time, the Sun was directly overhead. In a recent conference at Palo Alto, I met my collaborator Yusuke Terada, from Japan, for the first time. Shortly after we met, I looked over his shoulder at another participant, and asked Terada "do you know who that is?" It was Donald Knuth.

Already in Delaware, there were talks about XML. The speakers directly typed XML code during their talks, and the indentation grew and grew until it was two pages right of the original margin. It took me several years to understand the goal of these talks. XML is easily parsed by computers and LaTeX is not. Authors submit papers to publishers already formatted in a personal way, but the publishers need to reformat these articles to conform to the standard of a journal or book series. This can be done automatically by computers if the paper is in XML, but requires work by hand for articles in LaTeX. All well and good, but I stopped paying attention to XML talks.

There were also pessimistic talks by famous figures in the TeX world, predicting that TeX would be dead in another five years. Most of these talks were from England, and I gradually realized that many speakers had jobs in the Open University system. For these jobs, they didn't want to produce static articles, but rather interactive documents allowing students to input information and try experiments. Their students had iPads and other portable machines and worked remotely. HTML web documents were much more useful than static LaTeX documents. Eventually I stopped listening to these talks as well.

In my little corner of the world, TeX had created a revolution. Our mathematics department used to employ three secretaries to type mathematical manuscripts. They are gone. Today if you go into a mathematician's office, there will be a computer running LaTeX and a chalk board. Research is done with these two devices and immediately typeset and sent to collaborators in Europe. All of our PhD students use TeX for quizzes and exams, and when we hired younger hot shots as Assistant Professors, they required graduate students to submit homework written in LaTeX. If research articles in some other field must be in Microsoft Word, that's their problem, not mine.

Covid and Reconsidering TUG Talks

Then Covid hit. Luckily I'm retired, but I watched my mathematical colleagues switch to remote teaching with only a week's notice. I don't know how they did it. Gradually I realized that those pessimistic talks contained an important message.

Some of my colleagues at the University of Oregon switched to PreTeXt to write lecture notes; I'll describe that project in a moment, but suffice it to say that one goal of that project is to allow authors to write interactive material which can be accessed over the web. Authors write using XML. Perhaps I should have listened to those talks after all.

Here's my "dream setup for the future." A faculty member would write lecture notes in LaTeX. These notes would be typeset by an engine which outputs both pdf and html. The pdf document would contain the course in final polished form, so students could look back at the clear logical direction of the lectures. The html document would contain interactive material: movies, questions with student input, etc., so students would be actively involved, even if working remotely.

The HTML Preview window has been added to support software that already exists, but even more to encourage new software which makes things easier for authors.

Maybe PreTeXt will be the answer for interactive documents. Maybe an extended version of TeX4ht will be the tool of choice. Maybe projects not yet invented will rise to the top. It is likely that several solutions will ultimately emerge.

PreTeXt, a Project Worth Keeping an Eye On:

At the 2014 TUG conference in Portland, Oregon, I heard a talk by Robert Beezer of the University of Puget Sound on Mathbook XML. A former PhD student of mine named Tom Judson was converting a textbook he had published into the new interactive XML format. I talked to Beezer, but the conversation soon switched to a description of how Beezer and Judson met, which was via very serious bicycling in France.

A couple of years later, I found myself in a group of alumni of the University of Oregon, wearing suits and talking about possible donations. As rapidly as possible, I retreated to the mathematics building where people wearing jeans talked about mathematics. One of the faculty members there asked if I knew anything about PreTeXt, a way of writing interactive mathematics that he and other faculty were using. I didn't, but I looked it up on the internet. Turns out, Beezer's project had been renamed.

PreTeXt is an interesting project. The central idea is that authors enter formatting commands using a special form of XML. But mathematics is entered in standard LaTeX form, so writing documents is quite straightforward and not nearly as verbose as documents entirely in XML. The source is then translated into other formats using XSL. In this way, PDF, HTML, EPUB and other versions can be created automatically from the source. All of this is described very clearly on the web site https://pretextbook.org

In 2019, I spent a considerable amount of time revising TeXShop so it would be useful in this project. I added some new engines for PreTeXt, provided appropriate syntax coloring for XML documents, and made other changes.

In the Covid years I lost track of the project. When I recently returned, I discovered that several changes have been made in the PreTeXt project and TeXShop's PreTeXt engines no longer worked. So the material in ~/Library/TeXShop/Engines/Inactive/PreTeXt has been completely revised for version 5.00 of TeXShop. A new engine is included which shows the PreTeXt source in the Source Window and the HTML output in the HTML window. This means that interactive features can be tested while the source is being written. Another engine provides the PDF Preview in one window and HTML Preview in a second window so the two can be compared.

An enormous advantage of PreTeXt over similar projects is that substantial effort is devoted to interactive elements. It is all well and good to argue that html output allows interaction, but this is only useful if authors have easy access to many different ways to interact with readers; these cannot be scattered over the internet, but must be gathered together and curated by someone.

PreTeXt is a good example of a project which creates html files containing interactive elements. But it is a complicated project. To give it a try, go to the folder mentioned in the previous paragraph and read the document "PreTeXt with TeXShop", which explains how to download the project and typeset several example files provided in the download.

Another Look at TeX4ht

When writing this version of TeXShop, I used a small one page document to test TeX4ht. Then one night I woke up in the middle of the night and thought "I need to test a real document." So I picked a 35 page set of lecture notes with lots of png and jpeg illustrations, tables, and extensive mathematics and added just one line saying "typeset me with TeX4ht". I hesitated briefly thinking "this may crash the program, or else it will take a long, long time to typeset." Then I pushed the typeset button.

Typesetting took only a few seconds, two windows appeared on the screen, one contained pdf output supplied by pdflatex and one contained html output supplied by TeX4ht. This HTML view had illustrations, mathematics, tables, everything. Amazing.

An hour later, I realized that the "iftex" package makes it possible to write source with different outcomes in the pdf and html windows. So I added "\usepackage{iftex}" to the header and wrote the following source text:

	\ifpdf
	     We'll include a static image, but in the browser you can see a movie here.
	\else
	     To understand this point, run the following movie
	\fi

The two preview windows had different text at that point.

My dream system requires more. In the html window, I want to write html code. So I need a new directive. Let us call it "beginHTML". Typical source code would then be

	\ifpdf
	     Here is the initial frame of a movie illustrating this point %and then code to display a jpg
	\else
	     \beginHTML
	       -- html code to embed an actual movie --
	     \endHTML
	\fi

At this point, Karl Berry called my attention to the \HCode command in TeX4ht. Sure enough, it worked. For example, the following code fragment typesets fine:

	\ifpdf
		Here is the initial frame of a movie.
	\else
		\HCode{
		-- a piece of html code; in this Changes document, the code is interpreted by html 
		-- and you will see the result rather than the source code! --
		Rather than  explaining  the new features, I'll demonstrate. Here's a link:
		 Slides: Dirac's Belt Trick, Quaternions, and the iPad  }
	\fi

But HCode has severe limitations. It can only accept a single paragraph, and TeX4ht itself embeds the text in a tag pair of p's. Only html source which can be embedded in a paragraph will be accepted. I could not, for instance, display a graphic this way. I may not entirely understand HCode, so some of these things may be possible.

Later I discovered that I could open the html file generated by TeX4ht and just copy/paste straight html code from various of my web pages into the output. This always worked fine, and I could do the more complicated tasks I desire.

This suggests that TeX4ht could be modified by adding a new command similar to HCode, say HFullCode. This command would directly insert the material between { and } into the html document. It would not surround the insertion with a tag pair of p's and would preserve line breaks. I don't know if this is possible or will be done.

However, there is an alternate way to provide interactive html content. Since TeX4ht projects can contain links, the pieces of interactive content can be placed on separate html pages. And since TeXShop supports authoring and Web preview of such separate pages, writing them could be part of a single workflow.

Of course links could also be embedded in the pdf file, but this feels psychologically wrong. Students should think of the pdf as the polished final version of a course, to be read like an article or book. Students should think of the html version as an interactive document, asking questions, trying experiments, teaching how mathematics is actually created. Reading it would be a typical web experience, where it is natural to follow links to further material.

One major problem is that interactive content will often contain mathematical equations. So those extra html pages need to contain mathematics. For author sanity those mathematical equations should be input using LaTeX notation and rendered using MathJax. The MathJax web site seems to suggest that this is possible, but I don't yet understand the details.

So let my final word repeat an earlier sentiment. Maybe PreTeXt will be the answer for interactive documents. Maybe TeX4ht will be the tool of choice. Maybe projects not yet invented will rise to the top, and several solutions will ultimately emerge.

Epilogue:

Version 5.00 of TeXShop introduces two new features. First, TeXShop can display isolated web pages directly within the program using "Show HTML Window." And second, TeXShop can preview html output of engines exactly as it now previews pdf output. The first of these is a sort of trick with limited utility, and the second is the key new ability.

I can imagine use cases of the first feature. Suppose you are writing a document which is a response to a currently active web page. You could load this web page with "Show HTML Window" to make it constantly available as you write, freeing Safari for random browsing.

However, there is an important difference between the way TeXShop opens PDF documents and the way it opens Web pages. When TeXShop opens a PDF file, it appears in an independent window on the screen, not tied to any project currently being edited. But when TeXShop opens a Web page, it uses a window from the active project. This is the same window that the project will use if it has to preview html output. When you use TeXShop for conventional LaTeX projects, it is fine to open an occasional active Web page with "Show HTML Window". But if you use TeXShop for projects which directly create html output, using "Show HTML Window" is not a good idea.

TeXShop Changes 4.80 - 4.99

Versions 4.80 - 4.99 were never released.

TeXShop Changes 4.79

Two issues are addressed:

TeXShop Changes 4.78

Marco Santi suggested the first two features below:

TeXShop Changes 4.77

The following issues are addressed:

TeXShop Changes 4.76

TeXShop 4.75 changed the behavior of Preview in "double page" and "double-multipage" modes. This proved to be controversial and is fixed in version 4.76. If your default display environment is "multipage", none of these changes matter to you.

TeXShop uses Apple's PDFKit to display pdf files. This kit has two properties named "displaysRTL" and "displaysAsBook" which change double page behavior. Both are booleans. Most scripts are written from left to right, and setting displaysRTL to NO causes the pages to also flow from left to right. Scripts like Arabic and Hebrew are written from right to left and setting displaysRTL to YES causes the pages to also flow from right to left. In TeXShop 4.75, the "Page One on Left" and "Page One on Right" preferences set this property. This also holds for 4.76, but the items are renamed "Pages Flow Left to Right" and "Pages Flow Right to Left."

Version 4.75 ignored displaysAsBook, although earlier versions usually set it to YES. When it is YES, the first page is shown by itself and the remaining pages are shown as double pages. By convention, there are an odd number of pages in a book before the actual content begins, so this causes the left and right pages to appear as they would if a user opened the actual book.

In version 4.76, displaysAsBook is set to YES by default and the initial page appears by itself. Just in case, a hidden preference setting named "DisplayAsBook" is included, and users who dislike the single page can get rid of it by issuing the following command in Terminal:

     defaults write TeXShop DisplayAsBook NO

In addition, two new special comment lines are provided so the property can be set on a document by document basis. These overrule the defaults and turn book display mode on or off for that document.

     % !TEX bookDisplay
     % !TEX standardDisplay
 

In Japan, text can be written horizontally or vertically. When it is written vertically, pages should appear from right to left. Therefore we also provide special comment lines to set "displaysRTL" on a document by document basis:

     % !TEX PageDirectionL2R
     % !TEX PageDirectionR2L
 

TeXShop Changes 4.75

This release fixes two minor bugs and should be stable until the release of macOS Ventura in the fall.

TeXShop Changes 4.74

The following minor bug fixes were made:

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)
           return;
    
       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:
        ADDED
        For "availableDataOrError:" see:
        - "NSTasks, NSPipes, and deadlocks when reading...",
        http://dev.notoptimal.net/2007/04/nstasks-nspipes-and-deadlocks-when.html
        - "NSTask stealth bug in readDataOfLength!! :(",
        http://www.cocoabuilder.com/archive/cocoa/173348-nstask-stealth-bug-in-readdataoflength.html#173647
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"])
              {
                 continue;
              }
                 return nil;
           }
          @throw;
      }
   }  // 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
       return;
  
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.

Grrr.

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: