% !TEX TS-program = htlatex
\documentclass[11pt, oneside]{amsart}
\usepackage{geometry}                % See geometry.pdf to learn the layout options. There are lots.
\geometry{letterpaper}                   % ... or a4paper or a5paper or ... 
%\geometry{landscape}                % Activate for for rotated page geometry
\usepackage[parfill]{parskip}    % Activate to begin paragraphs with an empty line rather than an indent
\usepackage{graphicx}
\usepackage{amssymb}
\usepackage{epstopdf}
\usepackage{url}
\DeclareGraphicsRule{.tif}{png}{.png}{`convert #1 `dirname #1`/`basename #1 .tif`.png}

\title{TUG-GUI-Applications}
\author{Richard Koch}
\date{\today}                                           % Activate to display a given date or no date

\begin{document}
\maketitle
\section{GUI Applications}
This is the portion of the TUG documentation which deals with making the GUI Applications package.

{\bf Warning:} It is important that the folders in which packages are built live on the hard disk rather than an external
disk. Building constructs folders named ``root'' which are copies of material to be installed. This root folder and its
contents are often owned by root. But material on an external drive is owned by the user instead.

A clean package file will contain
\begin{itemize}
\item ``apps'' folder with programs and documentation to be installed in /Applications/TeX
\item Files ``buildPackage.sh'' and ``buildDVDpackage.sh''
\item Files ``background.jpg'', ``License.rtf'', ``ReadMe.rtf'', ``Welcome.rtf''
\item ``TeX-Source'' folder containing LaTeX source files for the documentation in apps 
\item ``scripts'' and ``scriptsDVD' folders, each  containing ``postinstall''; these ``postinstall'' files are different
\item GUIApplicationsBuild and GUIApplicationsDVDBuild projects for Packagemaker
\item ``TUG'' folder with this document
\item Files ``signPackage.sh'' and ``signDVDPackage.sh''
\end{itemize}


\section{OverView}

This package installs BibDesk, LaTeXiT, TeX Live Utility, TeXShop, and TeXworks in /Applications/Utilities. It installs the spell checker
Excalibur. It also installs
brief documentation for new features in that year's TeX Live. All these pieces are added to the apps folder before building. They are  moved
to root/Applications/TeX by buildPackage.sh. Notice that buildPackage.sh must be edited if file names change or documentation
is added or removed.

\section{Programs in Apps}

To save space, the ``apps'' directory in the Build documentation tree only contains documentation, but does not contain GUI
applications. Thus before building, it is necessary to add Applications to this directory. The following is a list of these
applications, and of web sites where the current versions can be obtained:

\begin{itemize}
\item BibDesk, available at \url{http://bibdesk.sourceforge.net/}
\item Excalibur-4.0.7, available at \url{http://excalibur.sourceforge.net/}. This is a folder named ``Excalibur-4.0.7''  containing the
Excalibur program, Excalibur-manual.pdf, gpl-2.0.pdf, Read Me.txt, and Standard Dictionary.
\item LaTeXiT, available at \url{http://chachatelier.fr/programmation/latexit_en.php}
\item TeX Live Utility, available at \url{http://mactlmgr.googlecode.com/}
\item TeXShop, available at \url{http://pages.uoregon.edu/texshop/} The folder contains three programs named TeXShop-Leopard,
TeXShop-Lion, and TeXShop-Lion-NoMovie. The first is the latest program in the 2.** series, the second is the latest
program in the 3.** series, and the third is the second with the two movies removed.
The first is a universal binary, and the second has 64 bit code and requires Lion or higher.
\item TeXWorks, available at \url{http://tug.org/texworks/}. The folder contains three programs named TeXworks-Leopard,
TeXworks-SnowLeopard, and TeXworks-MountainLion.
These were just recently released. The first is a universal binary. The second and third have 64 bit code for
various versions of OS X.
\item FixMacTeX2013.pkg. This is a small install package which fixes problems when a system containing MacTeX is upgraded to a later
version of the operating system.
\end{itemize}

\section{Building}

The first step in building a new package is to update all the supplied programs. Bibdesk, TeX Live Utility, and TeXShop all use the
Sparkle mechanism to update, so it suffices to read these programs and select the ``Check for Updates...'' menu. LaTeXit may use the
Sparkle mechanism as well, but in that case it seems to gray out the ``Check for Updates...'' menu when the program is up to date.
To be sure, check
\begin{quotation}
 \url{ http://chachatelier.fr/programmation/latexit_en.php}
 \end{quotation}
 TeXworks updates can be found on \url{www.tug.org/texworks}. 
 
The Excalibur spell checker is available at \url{http://excalibur.sourceforge.net/}. Note that it is provided in a folder containing the
version number. If a new version is available, be sure to revise buildPackage.sh so it will copy the new folder to root/Applications/TeX.

Then update the documentation. Note that source code for the documentation is in the TeX-Source folder.

Finally, build by
\begin{verbatim}
     sudo sh buildPackage.sh
     sudo sh buildDVDpackage.sh
\end{verbatim}

\section{Documentation}

Since Apple's installer cannot install in user directories, there is no convenient place for it to install documentation. But sometimes
new features of a release need to be pointed out. In that case, we install such documents in /Applications/TeX. 

In general, it is a bad idea to put extensive documentation in /Applications/TeX because TeX Live has extensive and up to date information.
Thus documentation we add tends to duplicate TeX Live documentation, and also tends not to be up to date. Currently, we provide
the following documents:

\begin{itemize}
\item READ ME FIRST: This document is designed to help new users begin using the system
\item LuaTeX-and-XeTeX: This document was added in 2010 to show users how to use system fonts in LuaTeX, and remind them
that XeTeX has the same ability. 
\item Eps-and-PdfLaTeX: This was added to explain that TeX Live 2010 automatically converted eps files to pdf files when running pdfTeX.
\item What is installed: An explanation of what is installed and where. Particularly useful when people want to remove things.
\end{itemize}


\section{Updating for a New Year}

Since the package name does not change from year to year, very little editing is require. The  ``Welcome.rtf'' should be edited to
reflect the release date.

\section{Building the Final Install Package with Packagemaker}

The remaining steps are optional and not required for the final build of MacTeX.

Now edit GUIApplicationsBuild and GUIApplicationsDVDBuild, the Packagemaker project files, using the GUI interface, as follows.
Both packages are built the same way, so we only list parameters of GUIApplicationsBuild.

\begin{enumerate}
\item Click the top item on the left. The right side will change to a view with three tabs. First select
the Configuration tab. Edit so
\begin{enumerate}
\item Title: GUI-Applications
\item User Sees: Easy Install Only
\item Install Destination: System volume
\item Certificate: Leave this blank. You might think that putting a certificate name here would correctly sign
the package, but experiments show that it does not. The package needs to be signed after it is constructed.
\item Description: Empty
\end{enumerate}
\item The Requirements and Actions tab entries for the top item can be left blank
\item Click the entry GUI-Applications in the Contents section on the left. The right side will change to a view with two tabs.
Select the Configuration tab. Edit so
\begin{enumerate}
\item Choice Name: GUI-Applications
\item Identifier: choice1
\item Initial State: Selected and Enabled
\item Destiination: Leave Blank
\item Tooltip: Leave Blank
\item Description: Leave Blank
\end{enumerate}
\item The Requirements tab entries for this contents item can be left blank
\item Open the GUI-Applications  entry in the bottom left column. This item should show an ``Applications'' directory,
obtained by dragging root/Applications to the left column. The right side will change to a view with four tabs.
 It is not necessary to edit the
items under the Contents tab. But it is {\em very important} to edit items in the  Components tab, turning off all boxes labeled ``Allow Relocation''. The items under the
Configuration tab should be edited as follows:
\begin{enumerate}
\item Install: root/Applications (The item on the right should have selected ``Relative To Project'')
\item Destination: /Applications (The item on the right should have selected ``Relative To Project'')
\item Do not check ``Allow custom location''
\item Patch: No patch root selected
\item Package Identifier: org.tug.mactex.gui
\item Package Version: 1.0
\item Restart Action: None
\item Check ``Require admin authentication''
\item PackageLocation: Self-Contained
\end{enumerate}
The items under the Scripts tab should be edited to read
\begin{enumerate}
\item Scripts directory: scripts (The item on the right should have selected ``Relative To Project'')
\item Preinstall: Leave Blank
\item Postinstall: scripts/postinstall (The item on the right should have selected ``Relative To Project'')
\end{enumerate}

\end{enumerate}

After verifying all these items, build the install package by clicking the ``Build'' icon. When asked to select
a name, choose ``GUI-Applications-Temp''. 
After the package has been made, sign it by executing the following line in Terminal:
\begin{verbatim}
     sh signPackage.sh
\end{verbatim}
This script simply calls
\begin{verbatim}
     productsign --sign "Developer ID Installer: Richard Koch" old-name new-name
\end{verbatim}
where ``old-name'' is GUI-Applications-Temp.pkg and ``new-name'' is GUI-Applications.pkg.

Similar remarks apply to building the second install package.








\end{document}  