From TeX on Mac OS X wiki

Clea F. Rees

Associate Editor, TeX on Mac Wiki

---

Contents 1 Disclaimers 2 Why use TeX? 3 Why not use TeX? 4 Which distribution? 5 Getting started for the rest of us 6 Less-obvious resources 6.1 How to make a document look "right" 6.2 Dissertation and thesis formatting 7 Recommended extras

Disclaimers

This is a user page and the editing guidelines prohibiting personal views elsewhere on the wiki are relaxed. Opinions, advice and preferences expressed here are the user's own. Use the "E-mail this user" link (bottom left) if you have comments or post them on the user's talk page. To view the pages in the main part of the wiki, use the links to the left or start from Main Page.

Note: Under Construction. This is a DRAFT.

Why use TeX?

People use TeX for a variety of reasons. If you work in a technical field such as mathematics or logic, TeX may be the easiest way to typeset your dissertation, paper or book. It may also make it easier to collaborate with colleagues and work with publishers since they are likely to be either using TeX themselves or used to working with those who do.

If you work in a non-technical field there are still good reasons to use TeX. One of the most important may be that TeX can produce output which is simply stunning. It typesets all kinds of documents simply beautifully.

On a more practical note, documents prepared for use with TeX are plain text. The chances are good that you will be able to read your documents on another machine or in ten or twenty years time - even if the application you originally used to produce them has long since disappeared. This also makes it easy to bring your work under version control if you wish and to easily manipulate, compare and archive documents.

TeX is incredibly powerful and extremely flexible. Although it makes it easy to produce beautiful documents without thinking about their design at all by separating document design from content and allowing authors to concentrate on the latter, it also allows users to customise almost any aspect of their documents' format should they wish to. It is relatively easy to write new packages or adapt existing ones if desired. It is also easy to use any of the many adaptations and extensions made available by others.

This flexibility depends on the fact that TeX is free software - free in the sense that it is "free as in speech", "open source" etc. If this matters to you - and it should - you have good reason to use free software when you can although TeX is not, of course, the only free software you can use to produce documents as the wide-range of free word processors and similar programs demonstrates. Although this consideration does not distinguish TeX from all the alternatives, then, it does, unfortunately, distinguish it from some of the most popular.

At this point, I strongly recommend reading Peter Smith's LaTeX - the very idea. Take no notice of the header "LaTeX for Logicians" unless you happen to be a logician - this is aimed at a much more general audience.

You may also enjoy the following resources:

• a showcase of humanities books typeset using TeX;
• Peter Flynn's publicity brochure;
• the TeX showcase edited by Gerben Wierda.

Why not use TeX?

There are plenty of reasons to use TeX, I think, but there are also some reasons not to. If you work in the humanities but not primarily in an area such as logic where the software is widely used, there are at least a couple of reasons to think twice.

First, you may find it more difficult to share editable documents with colleagues. Sharing documents is not in itself difficult as pdf(La)TeX makes it easy to produce pdf but this is not a good format to choose if the recipient needs to edit the document and not just read or print it. I know of no good solution to this. If I am setting up documents which will be shared back-and-forth and as they are edited, I don't use TeX.

Second, many journals, conferences and organisations require submissions in the formats used by word processors such as Word. Although some will accept pdf, many will not and in these cases you must either prepare your work using something other than TeX or convert TeX source into the required format. Neither is ideal. If you do not want to deal with conversion, I would not recommend using TeX at all. The benefits do not outweigh the extra work involved in maintaining two work-flows or in reproducing papers in different programs for different journals, for example. I therefore favour the conversion route.

It is possible to convert LaTeX source into various formats, including Word. The way I do this requires TeX4ht, a copy of OpenOffice and access to Microsoft Word to check the final results. I convert the source to Open Document Format using TeX4ht, open the result in OpenOffice and make corrections as necessary, export to Word format and then check the results. This is quite a lot of work the first time you do it but obviously much easier after that.

This conversion requirement significantly increases the level of technical skill required to use TeX successfully. For this reason, I do not recommend using TeX if you are not comfortable using the command line. In some cases, it may help if you are also happy to compile TeX4ht from source though this probably isn't essential for most users. I regret this. I wish I could say otherwise. Until one of two things happens, however, I cannot do so in good conscience.

The two things that would change my current recommendation are:

1. submissions in pdf format become much more widely accepted;
2. the conversion process becomes easier.

If I became convinced that either of these things have happened, I would change my recommendation. I see little prospect of the first happening at present. I therefore concentrate my current hopes on the second. If this changes enough to allow more people in the humanities to easily use TeX and more of them do so, this in itself may change the first over time resulting in a virtuous circle.

What are the prospects, then, for the second? At present, distributions such as TeX Live (and hence MacTeX) include a limited version of TeX4ht. Although everything you really need is included, the omission of certain scripts makes it slightly less straightforward to convert source documents to formats such as Open Document Format. Since this is arguably the most important target format for humanities users, it is a limitation, but it is not, it turns out, too difficult to work around it.

First, then, I would like to see such distributions including the full range of scripts available in the source distribution. This is especially important since compiling and installing TeX4ht from source is not easy. Installation is particularly problematic and the only solution I've found is one which involves making changes in the main TeX tree which is not something I would be happy recommending others try - and not something I'm very happy about having done myself. Indeed, given the resources of TeX Live 2008, I would not currently bother installing my own version merely for the added convenience of the extra scripts. It is much more inconvenient to install from source than to simply do without them.

With the full range of scripts available, it is possible to convert a LaTeX document to Open Document Format as follows:

oolatex <filename> "xhtml"

Following an exchange with Yves Gesnel concerning SimpleTeX4ht (see below), I understand that the following command - which requires only the default installation of TeX4ht included in TeX Live - is equivalent:

htlatex <filename> "xhtml,ooffice" "ooffice/! -cmozhtf" "-coo"

If you are submitting to a journal or organisation which requires endnotes rather than footnotes, use:

oolatex <filename> "xhtml,endnotes"

or, again courtesy of Yves Gesnel:

htlatex <filename> "xhtml,endnotes,ooffice" "ooffice/! -cmozhtf" "-coo"

Second, my recommendation may change for Mac OS X users in the light of the availability of a graphical frontend for TeX4ht called SimpleTeX4ht. Since I haven't tried this myself and don't know anybody who has, I can't recommend it, but if it lives up to its advertised features, it would provide a simple conversion route. Essentially, it allows users running a distribution which includes the basic version of TeX4ht to use SimpleTeX4ht to convert a document to Open Document Format. I understand from Yves Gesnel that it uses the command htlatex <filename> "xhtml,ooffice" "ooffice/! -cmozhtf" "-coo" (hence the above alternative for installations without the oolatex script). If you need to convert footnotes to endnotes, you must use the "expert" tab to specify options equivalent to htlatex <filename> "xhtml,endnotes,ooffice" "ooffice/! -cmozhtf" "-coo". The result can then be opened in OpenOffice for further editing and export to Word format.

At present, OpenOffice does not export to Word format sufficiently reliably to do without final checking in Microsoft Word itself. However, in my experience, the changes needed at this point are very minor so although I think it is necessary to have access to Word itself, it is not essential to own a copy if the program is available on a computer which you can access from time to time.

A third item on my wish list, then, is improved export to Word format. At present, this is not even completely reliable for documents without mathematical or logical symbols, diagrams and tables. I assume that the inclusion of any of these elements would further complicate the process though in fact it makes little difference since if the export is unreliable in any respect, access to a copy of Word is essential prior to submission.

I think the benefits of using TeX are worth it but it has to be said that others' mileage may vary - even if the conversion route is made as straightforward as SimpleTeX4ht suggests. It is therefore not possible to recommend TeX to humanities users without acknowledging the significant disadvantages involved. Of course, if enough users in the humanities were to use it, conference and journal submission policies would presumably change as a result. But one cannot recommend that any individual make the switch merely because it would be better if many of them did so.

Which distribution?

The chart to the right reflects my attempt to simplify and distil the guidelines concerning the best distribution of TeX for new users. It is essentially a flowchart which requires answering a number of questions. These reflect the considerations I think are most important in deciding which distribution to begin with. On the basis of your answers to these questions, the chart will suggest one of four possible distributions: MacTeX, BasicTeX, MacPorts TeX or Fink TeX.

Details of the various distributions are available in the Distribution Matrix and on the TeX Distributions page. If you are looking for more general advice or further information, try the Getting Started page which can guide you through all the steps involved in getting started and provides an overview of what's required.

To actually use the chart, you will probably need to click on it to view the PDF at a reasonable size.

Getting started for the rest of us

TeX sets mathematics, logic and technical texts of all kinds so beautifully - and everything else sets them so poorly or so expensively - that it would be easy to mistake TeX for a tool for mathematicians. So easy, in fact, that many do. This is a shame for at least two reasons. First, TeX sets other things at least as beautifully - ethics papers, for example, or syllabi for courses in feminist philosophy - and it is seems a shame for non-technical work to suffer aesthetically as a result of the myth. Second, while TeX is known for its "steep learning curve", people rarely go on to point out that the learning curve is nowhere near as steep for non-technical texts. If you do not need to typeset equations, formulae or technical diagrams, you do not need to learn how to do so. In fact, many of us can probably get started with only a handful of commands and a standard template.

This may explain why some people have claimed that there are no books or presentations available for "non-mathematicians" starting out with TeX. Although this is false - there are actually documents aimed specifically at non-technical users - it may also be because there is nothing specific to say. In truth, most non-technical users probably need a subset of what a technical user needs to get started. There may be much more material aimed at technical users in part because such users need to know a whole lot more in order to start working with TeX.

If you work in a non-technical field, I suggest installing a distribution and trying the following in the editor or front end of your choice. (If you don't know which to choose, try TeXShop.)

%:a comment about the beginning - TeX will ignore this line because it starts with a '%'
\documentclass{article} % another comment: TeX will ignore everything on this line after the '%'
\usepackage[T1]{fontenc} % recommended in any case and more-or-less essential if you need accented characters
\usepackage{textcomp} % enables various characters which complement T1
\usepackage{lmodern} % use Latin Modern fonts rather than the default Computer Modern as these are more up-to-date etc.
\usepackage[british]{babel} % this package internationalises TeX by making it easy to typeset text in languages other than American English
%\usepackage[welsh]{babel} % uncomment this line (remove the leading '%') and comment out the previous line (by adding a '%' at the start) if you are using Welsh
%\usepackage[welsh,british]{babel} % use this line if your document includes both British English and Welsh text and begins with British English
%\usepackage[utf8x]{inputenc} % uncomment this line if you are using an accented language such as Welsh and would like to input accented characters directly - this lets me input a circumflexed capital W, for example, rather than '\^W' which also allows my spell check to work correctly
\usepackage[a4paper]{geometry} % this package makes it easy to set paper size and page dimensions such as margins, header heights etc.
\usepackage[protrusion=true,expansion=true]{microtype} % make your output even more beautiful; comment this out if you are *not* using pdfTeX 
%\usepackage[protrusion=true,expansion=false]{microtype} % uncomment this and comment out the previous line if you need to create a smaller file
 
\author{Your Name}
\title{Paper Title}
 
\begin{document}
\maketitle
 
\begin{abstract}
This is an abstract.
\end{abstract}
 
Here's an introduction\footnote{This is a footnote.}.
 
\section{This is a section}
 
\emph{This bit is important.}
 
\emph{\textbf{This bit is even more important.}}
 
``Here's how to put something in double quotes.''
 
`Maybe you wanted single quotes.'
 
%if you enabled 'british' and 'welsh' uncomment the following lines
%\selectlanguage{welsh}
%Mae'n ddrwg gyda fi ond dydw i ddim yn gallu ysgrifennu (neu siarad) Cymraeg yn dda. Dw i'n dysgu ar hyn o bryd.
%\selectlanguage{british}
 
\subsection{This is a subsection}
 
\begin{quotation}
Here's a block quotation. Write some more here if you want the full effect.
\end{quotation}
 
\end{document}

If you work in the humanities and write in only European languages, you can probably go quite a long way with nothing further. Obviously if you are using a different size of paper or language, you should not ask for "british" or "a4paper". Use "letterpaper" or "canadian", for example, instead. If you use American English and won't be typesetting text in other languages, skip the line about "babel" altogether as American English is the default.

Of course, you will need to know a bit more to typeset a paper - how to insert citations, for example, and how to include a bibliography. But the above may well be enough to typeset a class handout or lecture notes, for example, and this should give you a sense of the way things work.

I like to have a book to fall back on when I'm learning something like this and, in any case, I don't know of a single electronic resource I like as much as Kopka and Daly's A Guide to LaTeX (see References). Ideally, you should go to a bookshop with a choice of books about LaTeX and browse. You may prefer a different presentation. If you can't do this - if, say, your local bookshop is fifty miles away or has yet to discover the joys of TeX - I don't think you will go too far wrong with Kopka and Daly. The nice thing about this book is that it covers all the LaTeX basics and many of the key packages without which I would be fairly lost. I found the appendix on using BibTeX to manage bibliographies and citations and the chapters on tables particularly useful. If you later decide to dabble in more sophisticated use by writing your own commands (or if you are forced to do so because your dissertation must conform to certain guidelines), it has useful information on that topic, too. See Print References for a list of some alternatives.

If you prefer to start with electronic resources - or want to explore these as well - I recommend looking at what, if anything, came with your distribution to begin with. MacTeX includes a directory of documentation, for example at /Library/TeX/Root/texmf-doc/doc/english/ in addition to a great deal more detailed information in other places. Some of this is quite specialised but some of it is introductory. Try /Library/TeX/Root/texmf-doc/doc/english/gentle/gentle.pdf or /Library/TeX/Root/texmf-doc/doc/english/lshort-english/lshort.pdf, for example, but note that these won't tell you about packages - such as BibTeX - which can make your life much easier but only about LaTeX itself. I think I would have found these documents rather off-putting when I was first starting to use TeX and you may prefer to begin with /Library/TeX/Root/texmf-doc/doc/english/visualfaq/visualfaq.pdf which allows you to select formatting you like. This links you to the relevant part of an online FAQ which explains how to achieve the desired formatting.

Online, Peter Smith offers some excellent resources on his LaTeX for Logicians site. These are not aimed only at logicians. Rather, they are grouped into three sections: general resources, resources for logicians and resources for classroom use. See References for a detailed listing. See Electronic References for a list of additional resources.

Less-obvious resources

How to make a document look "right"

There are times when you are faced not with a requirement to submit in Word format, say, but merely a requirement to submit something which looks as though it was produced by Word. This requirement is much easier to satisfy. All you need is a package which systematically undoes everything the standard packages do to make your work look beautiful. You need, in short, an unbeautifier. The answer is Gregory Wheeler's philosophy package which is itself based on Allin Cottrell's brain_damage.

If you need to use Times New Roman and you neither wish nor need to learn about font installation for independent reasons at this point in your life, try How to Use Times New Roman in pdflatex on Mac OS X. This provides step-by-step instructions without worrying about explanations or flexibility. It is aimed at those who need to install Times New Roman and just Times New Roman because they have to and tries to make the process as short and non-sour as possible.

Dissertation and thesis formatting

If you are a postgraduate (graduate) student working on a thesis or dissertation which must be formatted according to a set of school or university guidelines and you have no support, are completely stuck and know nobody else in the same position, find the mathematics department. Specifically, find their postgraduate (graduate) students and ask if they have a customised package they use to format their work for submission. If so, ask them very politely for a copy. If not, suggest you help them produce one. Even if nobody else at your institution is using LaTeX, the mathematicians almost certainly are. Since they are probably using the American Mathematical Society's packages, you will, too. That's fine - AMSLaTeX can typeset a dissertation in philosophy or history just as easily as one in mathematics. You should include AMS in your acknowledgements, though, and probably the mathematics department as well.

Recommended extras

If, like me, you can't spell for toffee, I recommend CocoAspell which can spell check as you type, utilise a wide-range of dictionaries and be configured to ignore both a standard and customised set of commands. I would rather recommend a free/open source checker but the main competitor, Excalibur cannot (or could not when I checked) be configured to check text as it is entered and if you really struggle with spelling and/or are learning language, this feature is invaluable. CocoAspell is free to use and the underlying software - aspell - and dictionaries are free/open source. Still, it would be nice to have a free alternative.

If you are using CocoAspell, you will probably want to download additional dictionaries unless you only use American English. There are a wide range available. I regularly use "English (United Kingdom) [ise_with_accents]" and "Welsh" although the latter is not as good as I might like. Since my Welsh is poor, I tend to assume the dictionary knows better which is not always the case, unfortunately. It seems to particularly dislike contractions for some reason. The U.K. English dictionary is really very good, however, and usually makes mistakes only in the case of names and technical terms.