| What's new in this version: TeXShop 5.18
- Modern versions of Ghostscript do not process transparency operators in ps files unless the flag -dALLOWSPSTRANSPARENCY is added to the function call. In TeXShop 5.18, a preference item titled "Ghostscript Options" under the Typesetting tab can be checked to activate the flag. This activation only applies in two circumstances.
- When TeXShop opens a postscript file, it calls ps2pdf to convert the postscript to pdf and opens the pdf file. Without the flag, transparency will be ignored in the ps file. With the flag, it will be respected.
- When TeXShop typesets files in DVI mode, it runs TeX or LaTeX to create a dvi file, runs dvips to create a postscript file, converts the postscript file to pdf using ps2pdf, and displays the pdf file. Projects typeset in this way can use the package pstricks for extra typesetting effects, and pstricks can add transparency to illustrations. Typesetting will only preserve transparency if the flag is set.
- The flag requires Ghostscript 9.51 or higher. It has no effect when used with earlier versions of Ghostscript.
- The flag is added (in DVI mode) only if the user has not added "--distillerops" to the simpdftex preference settings. TeXShop does not want to interfere with users who are carefully controlling the Ghostscript flags themselves.
- This preference item should still work when users supply their own Ghostscript, possibly from macports or homebrew, but that has not been tested.
- Two sample files are provided for experimentation with the new setting. Select the TeXShop menu "Open ~/Library/TeXShop" and navigate to the folder New/Version-5.18. This folder contains two files which can be copied to your home directory: Transparency.ps and Transparency.tex. Open Transparency.ps in TeXShop. If the new item is not selected, the ruler in the illustration will cover the material underneath. If the new item is selected, the ruler will be partially transparent and show items underneath. Typeset the source file Transparency.tex to see the same change of behavior when typesetting in DVI mode.
- When new typesetting methods become available or older methods require new flags to operate properly, the changes are generally handled in TeXShop by creating new engine files. Herbert Schulz created such engines for transparency, available in ~/Library/TeXShop/Engines/Inactive/GhostscriptTransparencyEngines. The new preference item does not affect these engines, and the engines are more flexible than the preference setting, handling for instance versions of Ghostscript earlier than 9.51. Use Herbert's engines for full control. The new preference is for users who run into a problem and want to click a box for a quick solution.
TeXShop 5.16
- There are improvements in the German localization. The "Sharing" and "Mouse Mode" items in the toolbar are translated, and the "Split Window" item has been given a less ambiguous translation. A few translations were tweeked to add consistency and remove typos.
- A bug with the "Magnification" and "Page Number" items in single window toolbar is fixed. Previously, these items opened an empty preview window, a confusing action in single window mode.
TeXShop 5.15
- Some translations of toolbar items in various languages did not actually appear when TeXShop ran. This should be fixed.
- A number of German toolbar items were left in English, but should now appear in German
- The label tool now correctly appears in German in single window mode. The crash is gone.
- When using single window mode in English, selecting the magnifying glass tool made it impossible to select any other tool. As a workaround, users were told to hold down the Option key while selecting other items. The bug is now fixed and the workaround is no longer needed.
TeXShop 5.14
- TeXShop 5.14 fixes a crash bug in the German localization of TeXShop. This bug has been present for a long time and only affected single window mode. In that mode, TeXShop crashed when the user tried to customize the toolbar.
- The bug was caused by the "Labels" tool. The fix eliminates that tool, but only in German and only in single window mode.
- The user reporting this bug ran into another bug which had been reported earlier. In single window mode, selecting the magnifying glass makes it impossible to switch to other "mouse modes" like text selection and pdf selection. This problem occurs in English and a few other localizations, but there is an easy work around. Hold down the Option key while selecting other tools and then selection works.
- A new chapter titled "Working Around Bugs" has been added to the TeXShop manual listing this action. Sometimes it is easier to work around a bug than to fix it, and these cases will be listed in the new chapter. Let us hope that it remains short.
TeXShop 5.13
- The Preferences dialog has a button labeled "Set Default Values" at the bottom. Selecting this item changes all items in Preferences to their defaults when TeXShop is first opened. A bug in this command caused it to ignore reverting the source font or font size. This bug is fixed.
- After selecting "Set Default Values", the "Cancel" and "OK" buttons in Preferences work as usual, so selecting "Cancel" returns to the current defaults, while "OK" accepts the default values.
- Note that "Set Default Values" followed by "OK" removes any hidden preferences you may have set, so it should be used with caution. However, the new TeXShop Manual in TeXShop Help, added in version 5.12, has a list of all hidden preferences at the very end. The list is long, but you may be able to find a preference there that you set and then forgot.
- If TeXShop is configured to open all documents in Single Window mode, and the program is quit while windows are open, these windows will be restored the next time the program runs. However, TeXShop did not restore the position of the divider between source and preview views and the divider would be placed in the middle of the single window. Now TeXShop restores the position of the divider.
- In TeXShop Preferences under the Editor tab, the last three items in the Style box sometimes displayed as integers and sometimes as real numbers. The TeXShop Manual claimed that these items do not work and can be ignored. But in fact the items work after a restart of TeXShop.
- Now the items always display as integers and take integer values
- Moreover, setting an item causes an immediate change in any open source window, so users can experiment until they find satisfactory values. There is a small caveat. TeXShop only learns of changed values when the item is deactivated, so to see the result in open source windows, change a value and then click in a different box. It is tempting to instead push RETURN, but this accepts all changes and closes the Preferences window.
- After making changes in the Style fields, the "Cancel" and "OK" buttons in Preferences work as usual to reject or accept all changes. If Style changes are rejected, source windows return to their previous style.
- In the German localization, the "Parens Targets & Highlight Color" item in TeXShop Preferences under the Source tab was not hooked up correctly and misbehaved when used. This is fixed.
- A number of small changes in the German localization were made for greater consistency across the interface
TeXShop 5.12
- The folder ~/Library/TeXShop/Engines/Inactive/PreTeXt was revised and the three main PreTeXt engines were rewritten. Consequently, many more examples in mathbook can be typeset with TeXShop.
- The Help menu contains a new 180 page manual for TeXShop. This help manual can be printed if you want a hard copy, and it can be converted to a stand alone pdf file by selecting "Save as PDF" in the print dialog.
- The Help menu also contains a TeXShop Help Panel. This collection of web pages was the older way of documenting programs, but we stopped updating the panel around the release of Lion.
TeXShop 5.11
- Zheng-chao Han notified me of a bug when TeXShop typesets a source file stored in iCloud. To be honest, I had never used iCloud until this report. It was a pleasure to discover that TeXShop easily typesets files stored there. In version 5 of TeXShop, there is a new html preview window, which can be used to preview typesetting jobs which output html rather than pdf. But TeXShop would not open html files stored in iCloud, due to a space in one of the directory names in the full path to these files. This is fixed.
- Incidentally, TeXShop does not work well with the third party product Google Drive. The insertion cursor will randomly jump to the bottom of the page when editing source files on this system. I suspect that Google Drive does not understand automatic saving. The solution is to move source files from Google Drive to your personal machine before editing them, and move the changed versions back to Google Drive when you are done. I cannot fix this problem because I do not have access to Google Drive source code. But they can fix it because they have access to my code.
- Simon C. Leemann suggested changing the symbols for PageUp and PageDown in the various Preview Windows to up and down arrows rather than left and right chevron symbols. Done.
- Apple added support for tabbed windows in Cocoa, starting in macOS High Sierra. TeXShop adopted this feature and customized it slightly for LaTeX by defining a couple of magic comment lines about tabs, and adding a Preference Pane setting labeled "If Sync Opens a New Window, Open as Tab in Root Window."
- Later, Apple improved their tab support, making it possible to provide full support for tabs in TeXShop starting with version 4.72. Read the Changes section for version 4.72 for details. To turn on this full support, find the item "Open New Windows as Tabs" in TeXShop Preferences and in the associated pull-down menu select "Always".
- When choosing this item, the magic comment lines about tabs should not be used, and the setting "If Sync Opens a New Window, Open as Tab in Root Window" should not be selected. I should remove these features, but I hate to remove items which some people may still be using. Thanks to Mark Auer for pointing out that if both preference items just mentioned are selected, names of tabs can become permuted so the tab named "Chapter 1" can select source for "Chapter 2", etc.
- Mark Auer later reported another bug. If a tabbed window has a root file tab and tabs for various included chapter files, and if the project is typeset while showing the source for a particular chapter, the window switches to showing the root tab, even though the user is only interested in the chapter's source. Sadly, I could not reproduce this bug.
- Auer then sent me vast amounts of information about the bug. He made a movie showing it in action. He sent pictures of all of his TeXShop preference settings. He made a tiny example illustrating the problem. I looked and looked at all this information. Eventually I noticed that Mark wrote "! %TEX root = ./MyRoot.tex" while I wrote "! %TEX root = MyRoot.tex". Both are correct, but that extra "./" caused the problem. Both forms are now accepted. Thanks, Mark.
- Latexmk was updated to version 4.79. Note that TeXShop uses the version of latexmk in TeX Live if it is available.
TeXShop 5.10
- The preference items to set the document and console fonts were broken in the English localization of version 5.09. Now they are fixed.
TeXShop 5.09
- Marco Santi wanted a preference to set the font and size of text in the Macro Editor. There is already a preference to change the default font in the console. To avoid cluttering the Preference Dialog, version 5.09 allows users to also use this console font in the Macro Editor. Just check the box "Use Also for Macro Editor" under the Console Tab.
- Kurt Richard Todoroff reported an important bug that I could never reproduce. Just before typesettting concluded, his console would stop reporting output and the program would become unresponsive. Luckily, Todoroff knew exactly when this bug was introduced. Although he was using version 5.08, he told me that versions 5.00 and 5.01 typeset without problems but version 5.02 often failed.
- For the next several days, Todoroff tested versions of the program which I sent him. First I sent unlabeled programs A and B. He reported that A didn't work, but B worked fine. Program A was 5.02 and program B was 5.01. That test gave me confidence to proceed!
- Version 5.02 was a minor update which fixed a bug in "Highlight Current Line." I asked Todoroff to turn off "Highlight Current Line" in version 5.08 and the bug disappeared. I then replaced my fix of both "Highlight Current Line" and "Use Block Cursor" with a better fix and the problem went away.
- If you are curious, I'll say more. "Highlight Current Line" draws a light blue background under the line containing the insertion cursor. If the user clicks on a different line, this background must be erased, and then a background must be added under the new line. To erase the background of the old line, I originally erased the background of all lines in the visible portion of the source. But if the user scrolled so the original line was no longer on the screen and then clicked at a new spot, the old background would not be erased, and scrolling could later reveal two different current lines. In version 5.02, I fixed this by erasing the background color of the entire source text. This fix was very inefficient and bit me in the end. Now there is a much better fix.
TeXShop 5.08
- As reported in the version 5.03 changes, a user noticed that the insertion cursor -- the blinking vertical bar in the editor -- can occasionally vanish. The editor still knows where it is, so characters are inserted if you type. But the cursor is missing.
- Recently, the same user found a way to trigger this bug. If you type command-space, a spotlight search field appears. When this field is dismissed, the cursor has vanished. Knowing how to create the bug makes it easy to figure out how to get the cursor back. Just click in a blank area of the desktop and then in the source window, and the cursor will return. Clicking in another TeXShop window or some other program's window will also do the trick. I'm still working on eliminating the bug completely.
- When you open a file in TeXShop, the open dialog has a pull-down menu at the bottom allowing you to select the file's encoding. In Ventura, you must push the "Show Options" button to see this menu. If the menu is not used, TeXShop will use the default encoding set in TeXShop Preferences, which is almost always what you want. But if your colleagues send you a source with an unusual encoding, the pull-down menu is useful.
- Until recently, a similar menu appeared at the bottom of the save dialog. But it was seldom used because without it TeXShop saves files with the same encoding used to open them, as you'd expect.
- However, some users were tempted to use the menu to change file encodings. They would open a file using one encoding, and then save it using a different encoding. This is dangerous because characters available in one encoding but not in the other will be lost; since the file is overwritten in the process, these characters cannot be recovered. Therefore I removed the menu from the save dialog.
- Recently, Unicode UTF-8 has become the standard encoding. It has the advantage of preserving all characters. Internally the TeXShop editor uses unicode. The process described in the previous paragraph is less dangerous when converting to UTF-8, provided the file being converted was opened with the correct encoding. So in version 5.08 conversion returns, but in a way that is less likely to mislead users. In the Edit menu under the "Transformations" submenu, there is an item named "Change Encoding". When selected, a dialog appears allowing you to select a new encoding for the file. Nothing will happen until the file is saved, but it will then be saved with the new encoding.
- One user wrote that his eyesight is failing and he found it difficult to see the insertion cursor. He requested an optional block cursor. I'm sympathetic because I lost the central vision in one eye several years ago.
- Unfortunately, switching to a block cursor is not easy. In the Accessibility Pane of Apple's System Preferences, users can enlarge the standard cursor and change its color and outline color. But no such modifications are provided for the insertion cursor. Some programs provide a block cursor, but often they do not use Cocoa and rely on an open source library for editor support.
- In Cocoa's NSTextEdit the source text is a single string, even if a document is an entire book. The central algorithm of NSTextEdit displays this string in the editor. Every time the string contains a line feed, the editor switches to a separate line, but for long lines the editor must select a blank spot to make a soft line feed. When the user enters text, the entire algorithm must run again to modify the layout of lines further along in the string. Adding a block character to the string would thus involve massive modifications of this central Apple code.
- But of course TeXShop and other programs modify the display for syntax coloring and other reasons. This modification is done in a different way, using what Apple calls an "attributed string." An attributed string is a standard string with extra information for each character, listing its foreground color, background color, and other items. The layout code in NSTextEdit is not changed for attributed strings; the attributes are only used when drawing the string after line breaks have been determined.
- TeXShop already has a feature named "Highlight Current Line" which draws a light blue background beneath the entire line containing the insertion cursor. In TeXShop 4.08, this routine can be modified to draw a block cursor. The cursor colors the background of the two characters on either side of Apple's blinking insertion line.
- To turn on the feature, select the item "Use Block Insertion Character" in the TeXShop Source Menu. This item turns on "Highlight Current Line" if it is not currently on, but switches it to Block Cursor Mode. The item only affects the active document; any other document open at the time is not changed.
- Note that the Block Character colors the background of existing characters. Spaces are characters and their background can be drawn, but if no character is present at a spot, then the background cannot be colored. Thus when starting a brand new line, only the original insertion line is present until the first character is typed. After that, the block character highlights the background of the character left of the insertion line, but there is no character right of the line to highlight. When editing existing text, the characters on both sides are highlighted.
- It is a good idea to select a source font with fixed width characters if you intend to use the block cursor. Otherwise as you scroll over the characters in a line, the cursor's width will constantly change.
- Since the menu items "Highlight current line" and "Use Block Insertion Character" are related, a change in one sometimes changes the other. When "Use Block Insertion Character" is turned on, "Highlight current line" is automatically turned on as well. When "Highlight current line" is turned off, so is "Use Block Insertion Character."
- When "Use Block Insertion Character" is on and then turned off, "Highlight current line" remains on. So it is easy to switch back and forth between hightlighting the current line and showing the block insertion character: toggle "Use Block Insertion Character" off or on.
- If you want to use the block cursor on all files, turn it on in TeXShop Preferences using an item in the Misc1 tab. This item also makes it possible to modify the color and nature of the block cursor.
TeXShop 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 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:
- A pulldown menu in the Save Dialog allows users to change the extension of the saved file. This menu was out of sync by one element after the first four items. So if you selected an extension, you got the previous extension in the list. This is fixed.
- One user complained that the cursor occasionally vanishes and TeXShop must be restarted to get it back. I cannot reproduce this bug. The Cocoa APIs contain a class named NSCursor which has two relevant commands: [NSCursor hide] and [NSCursor unhide]. It is, of course, important that calls to these routines be paired up so the cursor is not left hidden at the end. XCode can search the complete TeXShop code base; the search revealed that these cursor routines are only called in TeXShop during the operation of the magnifying glass.
- My routine had extra code to insure that the routines were called in pairs, but the final unhide was not protected in the same way. I added that protection. I don't know if the extra code is necessary because I cannot reproduce the bug, but it cannot hurt.
TeXShop 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:
- The code to color the input line in the source window had a minor bug. If the user issued a "select All" command and then cancelled it by clicking in a source line, the selectAll coloring was cancelled in the visible region, but scrolling revealed traces of it in other text. Repaired.
- To fix a memory issue, TeXShop 5 refuses to open the magnifying glass if the pdf file has a magnification level above 250. One user complained, so there is now a hidden preference: defaults write TeXShop GlassMaxMagnification 300
- The default value is 250 and any choice above that is asking for trouble
TeXShop 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:
- When first writing a file to disk, a dialog allows you to choose the name and location of the file. The dialog has a pull-down menu allowing you to choose a file extension; the default extension is ".tex". This dialog now allows ".html" as an alternate extension.
- TeXShop has keyboard shortcuts to enlarge or shrink the source text. They are "command-plus" and "command-minus", but neither requires the shift key. Unfortunately, at some point in the past it became necessary to "select-all" before issuing these commands. This is no longer necessary and the shortcuts again work by themselves.
- A small number of users ran into a memory management problem in TeXShop. The program suddenly required a large amount of memory to run, up to 4 gigabytes.
- I converted TeXShop from manual memory management to "automatic reference counting" many years ago. In this system, memory management is mostly done automatically by the Apple API's. So while memory issues can appear, they are rare.
- This particular problem turned out to be triggered by selecting a high magnification for the preview window, and then using the magnifying glass. To protect against the problem, the magnifying glass will now only work when the magnification level of the preview image is below 250. Otherwise nothing will happen when you use the glass. If you want to inspect an area at very high magnification, use a pinch gesture to magnify as much as you like.
- An explanation may be useful. When TeXShop magnifies, it first constructs a hidden image of the entire active page of the pdf display. If the page being displayed has been highly magnified, only a small portion of the page will appear on the screen, but the offscreen image must contain that entire page, and that can require a gigantic amount of memory.
- 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 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:
- In version 5.0 of TeXShop the folder ~/Library/TeXShop/Engines/Inactive contains a subfolder named "html". This folder contains an engine named "html.engine". Drag this engine to the active area of the engines folder.
- It is then possible to both edit and preview html source files directly in TeXShop. TeXShop has always had the ability to open html source files and syntax color the file appropriately. Open such a file and select the html engine in the toolbar. After editing, type command-T to typeset. Immediately the source will open in TeXShop's new HTML Window, and you'll see a live web preview of your html code.
- To do this efficiently, it is useful to add a magic comment line to the top of the html file with the text
- % !TEX TS-program = html
- However, there is one tricky issue. The symbol % does not start a comment in html, so this magic line will confuse web browsers. The trick here is to surround the line with html comment symbols on lines immediately above and immediately below the magic comment. See the example file in the folder ~/Library/TeXShop/Engines/Inactive/html.
- If your Macros menu is up to date, there is a macro named "PreTeXt Header" which makes this very easy. Select a spot near the top of the file, click to determine where the macro will place new text, and choose the macro. It will add both comment signs and a magic engine sign, but the magic engine will be named "PreTeXt" because the macro was invented for a different purpose. Change "PreTeXt" to "html".
- The new html features have simplified my life. The Changes document you are currently reading was written in html and later converted to pdf. As a writer, I suffer the fatal flaw of using too many words; don't claim you didn't notice. The only way I can create documents is to write once, and then edit over and over, each time removing words. Version 5.00 of TeXShop makes this a breeze. Push the delete key, push command-T, and see the result.
- As we will see shortly, there are other TeX applications which require short stretches of html code. I tend to forget html commands and find myself looking them up on Google. For instance, I type a tag containing "bold", but the correct tag contains just "b".
- TeXShop 5.00 has a facility to help users like me. In the Help menu, there is a new item labeled "HTML Commands." This item brings up an html file listing appropriate tasks and the correct tags to implement the task. Each item also contains a short sample showing how the tag will actually be used. Unfortunately, this help document is written in html source code, so it is difficult to read. But the source can be typeset. Push command-T and you'll see a page that is easy to read.
- There is more. The help document can be edited and the changes will automatically be saved. So when you need a command not listed, look it up usig Google and then add that example to the help file. This facility is essential because the initial document provided in TeXShop doesn't list many commands.
- The actual source for the help document is contained in a new directory ~/Library/TeXShop/HTML, and the actual document is named "Help.html". This folder can also contain support files. It currently contains an image "topdot.jpg" used by Help.html and a few other support files, and you can add similar support files.
- When TeXShop is updated, Help.html and the various support files will not be touched, because you may have edited these items. But the HTML folder also contains a subfolder named "Inactive" and that folder will be updated. So more extensive help files may be provided in the future, which you can merge with your own additions to the default file. Since I'm not an html expert, I encourage users to contribute better initial Help.html files for this Inactive folder.
- There are many advantages in this new approach, but almost immediately you will notice that synctex does not work in either direction. In one direction, there is a sort of clumsy replacement. If you have a position in the HTML window and you want to jump to the corresponding position in the source, select a fairly long section of text in the pdf and then copy. This text should come from a single line of output. Then switch to the source and paste the result in the Find panel. This will usually bring you to the corresponding spot in the source. It may be possible to automatic this process so a single click does the same thing. I'm investigating. I have no idea how to sync in the other direction.
Another Important Example:
- TeX4ht is a program written by Eitan M. Gurari. It uses a standard LaTeX source file as input, but outputs an html file instead of a pdf file. In 2009, Gurari was preparing a talk for the TeX User Group conference about an extension which outputs braille, when he suddenly died. His TeX4ht project has been taken over by other volunteers and is being actively developed currently.
- Go to ~/Library/TeXShop/Engines/Inactive/TeX4ht. This folder contains an engine titled TeX4ht.engine. Make a copy of this engine and drag it to the active engines folder ~/Library/TeXShop/Engines. The TeX4ht folder also contains a subfolder titled Example. Make a copy of this entire folder and drag it to your home directory or another directory used for TeX projects. Inside this folder is a LaTeX file named Sample.tex. Open it in TeXShop 5.00. A Source Window and a pdf Preview Window will open. Look carefully at the source file and notice that the first line is a magic comment saying to typeset using the TeX4ht engine.
- Typeset
- Now alongside the pdf Preview Window there is an html Preview Window. The pdf window displays the output when typeset by pdfLaTeX. The html window displays the output when typeset by TeX4ht. This makes it easy to compare the results.
- Resize both windows. They behave differently.
- If you have a trackpad, resize both window contents with a finger gesture. Both resize. In particular, finger gestures can magnify the html image.
- Each document contains an active link at the end. Click these links. The pdf link causes Safari to open and display the new page. But the html link opens the linked page in the original html window, and the Back arrow can take you back to the original content.
- Add extra material to the source and typeset again. Notice that both windows are immediately updated. Neither window jumps to the top of the document when reloaded. For HTML, this is a major advantage over the old method of opening the output in Safari and clicking the reload icon when changes are made.
- Math4ht has many parameters controlling its operation. Originally it created a large number of small pictures for mathematical equations, and the web page displayed these pictures. It can also output MathML and many modern browsers can interprete these commands. An even nicer approach is to render mathematics using MathJax. This is the approach recommended by the American Mathematical Society and produces very acceptable typeset equations. Users will want to create their own engines to explore the advantages of these various approaches. The TeX4ht engine uses MathJax, but an alternate engine is also provided in Inactive/TeX4ht which uses MathML.
How Are HTML Engines Constructed:
There are exactly five new commands which can be added to engine scripts to implement features like those just presented:
- !TeX-noPreview
- !TEX-pdfPreview
- !TEX-htmlPreview
- !TEX-bothPreview
- !TEX-noConsole
- Each command starts with "!TEX". The little circle above is not part of the command.
- These are analogues of the magic comment lines used in TeXShop source, but there are a few differences. First, the lines can appear anywhere in an Engine file, because Engine files are short and it costs nothing to search the whole file. Second, the magic lines do not have to start at the beginning of a line; they can appear anywhere in the text. It is crucial, of course, that the lines look like comments to the shell interpreter. So for standard engines, each line should be prefaced with the # comment symbol. But engines can be interpreted by a variety of tools, and the comment symbol depends on the tool being used. That is why the actual magic comments can start anywhere on the page.
- The standard behavior of TeXShop still applies if an engine has none of these lines. After executing all lines of the engine, TeXShop looks in the document directory to see if there is a file with the same name as the source, but extension ".pdf". If so, it opens this pdf file in the Preview Window, unless the Option Key is depressed.
- If the line "!TeX-noPreview" is present, no preview window appears even if some of the other lines are also present.
- Otherwise if the lines "!TEX-pdfPreview" and or "!TEX-bothPreview" are present, TeXShop searches the document directory to see if there is a file with the same name as the source, but extension ".pdf". If so, it opens this pdf file in the Preview Window.
- If the lines "!TEX-htmlPreview" and or "!TEX-bothPreview" are present, TeXShop searches the document directory to see if there is a file with the same name as the source, but extension ".html". If so, it opens this html file in the HTML Window.
- The line "!TEX-noConsole" suppresses showing the console. It is unlikely that this line will be used with any engine except the one which processes html code.
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.
- 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
- 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
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 }
- 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 4.79
- Isao Sonobe updated OgreKit to version 2.1.12. This fixed a copy/paste bug in the ``Replace'' field of the panel. In addition, the font and font size used in the Find and Replace fields of the panel can be changed and the changes will be remembered even if TeXShop is quit and restarted. To modify these values, open the OgreKit Find Panel and then select the TeXShop menu /Source/Font/Show Fonts. The standard Font panel will open, allowing you to select a font and size. Do this for each field.
- Szilágyi Zsolt reported a curious bug when using the magnifying glass in single window mode. It is impossible to select any tools in the toolbar which are over the Preview half of the window. Thus it is not possible to switch from magnifying mode to text selection mode, and impossible to split the window. Tools on the other half of the window still work.
- This bug apparently first appeared in TeXShop 4.66. I spent some time trying to find the cause without success. I haven't given up, but the bug is not yet fixed.
- A day later, Zsolt reported an easy workaround. Hold down the option key while selecting tools, and then selection works. In particular, switching from magnifying mode to another action like text selection turns off the bug. But even if you want to stay in magnifying mode, you can proceed by using option while selecting other tools.
TeXShop 4.78
- The tags menu marks the locations in the source file for "chapter", "section", "subsection", and other commands. The command "part" has been added for very large book projects divided into parts, each with several chapters.
- I am not a TeXShop power user. If you watched me enter source text, you would loose all faith in the program. But there is one trick that I do use and recommend even for beginners. Although they can typeset using a menu command or a toolbar command, it is much easier to enter the keystroke command-T.
- This week, looking at the interface builder file defining the typeset menu, I found an additional menu item in the Typeset menu that doesn't appear when TeXShop runs. The item title is "Trash Aux & Typeset". That would have been very useful earlier this year when defective Aux files caused me to push the "Trash Aux Files" button in the console every time I wanted to typeset.
- It turns out that this menu item has been there all along. Open the typeset menu, but do not choose an item. Then push the Option key. Notice that the first item changes from "Typeset" to "Trash Aux & Typeset", and the keyboard shortcut changes from command-T to option-command-T. So typing option-command-T will call the TeXShop command to trash Aux and related files, and then typeset. |
