Because LaTeX/XeTeX files are simply plain text, you can draft your documents in any text editor. However, for beginners, I recommend TeXShop. With TeXShop, you can draft and compile your document in one application. I use TextMate to draft and compile my documents, but it requires some setup. You can use TeXShop immediately after downloading it and installing it in your /Applications folder.

After installing TeXLive 2008 and TeXShop, you can begin to draft documents. Let’s start with an easy one. Open TeXShop and type the following:

\documentclass{article}

This is the second paragraph.
\end{document}


LaTeX/XeTeX documents always begin with a \documentclass command. In almost every case, you will use the article document class.

Next, you send the \begin{document} command to LaTeX to let it know where your document begins. You then write your text. When you are done, you send the \end{document} command to LaTeX. In TeXShop, press the “Typeset” button and you should see the output. Notice that LaTeX automatically set the margins and added the page number at the bottom of the page. Of course, we can customize all the properties of your document if needed.

So, how can we fit this into our workflow? Suppose that you want to draft a letter to a contact from your FileMaker database. First, you would have to get the data from your database. Your script might look something like this:

tell application "FileMaker Pro"
tell database "Contacts.fp7"
set addressee to "fullName" of current record
end tell
end tell


Now, you can construct a string of text to use as your document:

set latexString to "\\documentclass{article}" & return & "\\begin{document}" & return & "Hello, " & addressee & " This is the first paragraph." & return & return & "This is the second paragraph." & return & "\\end{document}"


This string looks just like our LaTeX document that we typeset above, except that we need to escape the backward slashes so we don’t confuse AppleScript.

Next, we need to write the string out to a file. This serves two purposes. First, we cannot compile our documents easily without a document file. Second, we have a document to put under version control. To write a string out to a file, type the following:

try
set filePath to (((path to desktop) as string) & "letter.tex")
set f to open for access file filePath with write permission
write latexString to f
close access f
on error e
close access f
end try


This code sets a path to a file on our desktop. If the file doesn’t already exists (and it shouldn’t), then AppleScript creates a blank file for us. We then write our latexString to the file and close the file. Notice the error handling, too. We use this to ensure that our file gets closed. AppleScript does not like it when you open a file and forget to close it.

In the Finder, you should see a new document on your desktop named “letter.tex”. To typeset the document, we will use TeXShop’s AppleScript dictionary. Type this into your script:

tell application "TeXShop"
set doc to open file filePath
typeset doc
end tell


This chunk of code tells TeXShop to open the document and typeset it. Easy. When you run the script, you should see a file named “letter.pdf” on your desktop. Open it up and you will see your document typeset in PDF. But what are all those extra documents on the desktop? Relax. TeX outputs a log file and an auxillary file every time it compiles your document. The log file contains any errors or warning messages. You can safely delete these files.

As with many scripts, this seems like a lot of work. But the beauty of scripting is that you only need to setup your scripts once and then run them over and over again.

In the next installment, we’ll look at how to use your Mac fonts with TeX using XeTeX.

I note that you don’t need to use TeXShop to typeset your documents. You can use the “do shell script” command to typeset your documents using programs from the command line. This requires some advanced setup that is beyond the scope of this tutorial.

So what’s the solution? Before getting to that, let’s think about some requirements that we expect from a document production system. First, we want to focus on writing, not formatting. Second, we want the output to look great. No more mixing of fonts or strange leading. Third, we want to be able to incorporate our system into our overall workflow via scripting. We might also want the format to be portable, capable of versioning, and obsolescence-proof.

With these requirements, the choice for the format looks clear: plain text. Plain text allows you to focus on writing. Just open your text editor and start typing. But what about formatting? We can mark up our plain text to format our document. HTML is an example of marked up plain text. Plain text can also produce great looking output through a typesetting system called LaTeX. LaTeX files are marked up plain text files that, when typeset, look fantastic. Here’s an example of a document typeset in LaTeX: Answer Typeset in LaTeX. As you can see, LaTeX produces beautiful documents with consistent margins, consistent paragraph numbering, and output as PDF. I encourage you to download the PDF file above and zoom in to reveal the details.

Of course, plain text documents will easily incorporate into any scripted workflow. Indeed, your scripts will generally run faster with plain text documents because you will not incur the overhead of opening another application to format your text. In addition, you can take plain text documents to any computer and open them for editing. You can even install LaTeX on just about any operating system. Plain text documents are also capable of versioning, also known as “track changes” in Word. You can do simple versioning using the diff tool or more sophisticated versioning using software such as Subversion or Git. With Subversion and Git, you can upload your documents to a private server (”repository”) and allow others to view and edit the text. You then update your personal repository on your local computer and the changes appear. Don’t like the changes? Roll back to the last version. I have all of my LaTeX files in a Subversion repository. Note, too, that the offsite repository acts as a backup file system.

Finally, plain text is nearly obsolescence-proof. Unless a new way of computing appears soon and does away with plain text, then your documents are safe from becoming as useless as WordPerfect files on the Mac. (Yes, I know about WP3.5 and SheepShaver.)

So how can we incorporate these plain text documents into our workflows? I’ll show you in the next installment. Stay tuned!

When you want to manipulate a Pages document, you should get the document class of your document:

set doc to document 1

You can now tell doc to change the properties and elements of your document. One of the main properties of the document class is body text. Body text is the main flow of your text document. If you extract data from your database and copy that data to the clipboard, you use AppleScript to paste that data to the body text of your Pages document.

set body text of doc to the clipboard

A Pages document is also comprised of pages, sections, and paragraphs, which you can access through AppleScript.

Because Pages also acts as a page layout application, you can create and access text boxes, shapes, graphics, and images.

We’ll look at Pages more as we go forward, but you should know that Pages has an excellent AppleScript dictionary and can be used in your workflows.

I’m also available to develop and design database solutions for your business. I have extensive experience with FileMaker Pro and open source databases such as MySQL, PostgreSQL, and SQLite.

You can contact me at info@sweetpeasoftware.com.

First, the user could highlight the citation, then select the type of citation (case or statute) from a dialog box. Microsoft Word for Windows uses this method. I don’t particularly like this method, but it’s familiar to many switchers.

The second way is to delimit the citations using a markup language. For example, one might use something like \case{A v. B., 123 U.S. 456 (2008)} within their text to delimit the case citation. With my background in LaTeX and HTML, I prefer this method as it’s easier to parse the document. Moreover, the user would not have to go back and highlight each citation, hoping not to miss a citation. Instead, the user would simply delimit the cases as he or she types.

Here’s a quick movie of what I have so far. I’d love to get your feedback on how you might delimit the citations. Thanks!

Before we get to our script, we need to create a template with preset tags. Open up Microsoft Word and type the following:

Dear First_Name:
Please call me at Appt_Time on Appt_Date to discuss your case.

Save your document to your desktop as “template.doc”. As you can see, this template includes 3 tags:  First_Name, Appt_Time, and Appt_Date. Our script will search for these tags and replace the tags with data from our data source.

Let’s again suppose that we retrieved the relevant data from our data source and stored the data in 3 variables:

set firstName to "Larry"
set appointmentDate to "July 4, 2008"
set appointmentTime to "9:00"

Now that we have our data, we need to open up our template document, search for each tag, replace the tag with the variable data, and then save the document as a different name. Here goes:

tell application "Microsoft Word"
set doc to open ((path to desktop as string) & "template.doc")
set findRange to find object of selection
tell findRange
execute find find text "First_Name" replace with firstName replace replace all
execute find find text "Appt_Time" replace with appointmentTime replace replace all
execute find find text "Appt_Date" replace with appointmentDate replace replace all
end tell
save as active document file name "letter.doc"
end tell

What’s going on here? In the second line, we open the template file using a special command called “path to desktop”. This command returns the path to the desktop as an alias, which we convert to a string and concatenate our template file name. The document is now open. In the third line we create a find object for our document. This find object is specific to Microsoft Word. The find object specifies a range of text to execute our search and replace. Because nothing is selected, Word assigns the entire document to the find object. In lines 4–8, we tell our find object to execute a find by finding text and replacing the text with the data stored in our variables. At the end of lines 5–7, we need to tell the find object to “replace all” occurrences of the found text. In line 9, we save the document as “letter.doc” to preserve our template.

Using this method, you only have to prepare the script once and the script will run properly. If you want to change the template, you do not need to change the script (unless you want to add variables). This type of template scripting (mostly) separates your logic from your presentation and is generally easier to maintain.

In the next lesson, we’ll look at search and replace using a third-party OSAX.

When writing a script that incorporates your template, you should be aware of a few things. First, you need to remember that if your template changes, then you need to change your script. This can be trivial, but it can also lead to some problems if you aren’t careful. Second, you need to be aware of any escape characters in your script. Escape characters are used when you want AppleScript to ignore its normal behavior when dealing with certain characters and, instead, behave according to different rules. For example, if we want to set a variable named sampleText to a text string, we would do this:

set sampleText to "This is a text string."

But what if we wanted to use a literal quote in our text string? The immediate response is to simply add the quotation marks like so:

set sampleText to "This is a "quoted" text string."

AppleScript will raise an error for this code because it will come to the second quotation mark (the one before the letter “q” in “quoted”) and interpret that mark as the closing quote for the first quotation mark. So what do we do? We escape the quotation mark using the forward slash escape character, “\”.

set sampleText to "This is a \"quoted\" text string."

So if your template contains lots of quotation marks, you’ll have to be careful of those escape characters.

Back to our script. Another issue to consider involves what to do with the output of your script. Unlike the second type of script where we will search-and-replace from within a Word document, in this script, we will create the entire template in our script. The next step involves moving the template output from the script to your word processor. A simple way to do this involves copying the final template output to the clipboard, then pressing Command+V in the word processor of your choice.

Let’s look at a simple template. Suppose that we want to write a brief letter to a client with the following template:


Dear FIRST_NAME:

Please call me on APPOINTMENT_DATE at APPOINTMENT_TIME to discuss your case.

Me


Let’s further suppose that we have a FileMaker database that holds the data for this client’s FIRST_NAME, APPOINTMENT_DATE, and APPOINTMENT_TIME. Because we do not have a FileMaker database setup for this, we’ll just assume that we’ve taken the data out of FileMaker and we have stored it in some variables:


set firstName to "Larry"
set appointmentDate to "June 18, 2008"
set appointmentTime to "9:00"


Before going further, note the use of descriptive variable names. While not required, I recommend using descriptive variable names to help you keep track of your variables. Imagine if you named each variable x, y, and z. After several uses of each, you would quickly get confused.

On to the template. Now that we have our variables, we can simple plug them into the template. Type the following into Script Editor and run it:


set firstName to "Larry"
set appointmentDate to "June 18, 2008"
set appointmentTime to "9:00"

set templateOutput to "Dear " & firstName & ":" & return & return & "Please call me on " & appointmentDate & " at " & appointmentTime & " to discuss your case." & return & return & "Sincerely," & return & return & "Me"

The first three lines are the variables from above. The next variable, templateOutput, holds our final template. We begin with the first line with “Dear “. Note the space after “Dear “. We need this because our variable does not know about spaces before or after itself and a variable follows “Dear “. Next we see the ampersand character. The ampersand character tells AppleScript to concatenate the text on either side of the ampersand. Here, we concatenate “Dear ” and our firstName variable. We then concatenate a colon on to the end of the first line. Next, we concatenate a return. return is a reserved word in AppleScript that does just what you think it does&emdash;it inserts a return at the end of a line. In our case, we concatenate another return to effect two lines. The rest of the script follows these same principles.

Now that we have our output, we need to copy it to the clipboard. Add this line to your script:

set the clipboard to templateOutput

Compile and run your script. You should not see any output in the “Result” tab in the bottom pane of Script Editor. Now open TextEdit and press Command+V to paste your output into TextEdit. Now open up Word, Pages, NeoOffice, or your favorite word processor and paste your output into the frontmost document. Because we’ve copied the output to the clipboard, we can paste that output anywhere we can use the clipboard.

Well, you’ve done it! You created a simple template and inserted variables into the template for insertion into a document. Next, we’ll look at using search-and-replace to insert those variables into a document.
 

A typical template includes pre-defined fields where data from a database or spreadsheet gets inserted. For example, we might have the following greeting in a template:

Dear FIRST_NAME LAST_NAME:

With this template, we would replace the FIRST_NAME field in the template with data from our data source. We would then do the same for the LAST_NAME field. At a basic level, this resembles a merge that you might find as a feature in Word or WordPerfect. But we can use AppleScript to control all aspects of this “merge” including calculating values and making decisions depending on the values in your data source. In addition, by using AppleScript, you are not necessarily tied to one word processing vendor.

There are two ways to accomplish this task. With the first method, we can recreate the entire document from scratch every time we run our script. Our script will hold the template, use variables to replace the fields in the template, then write out the entire document to a file. The second method uses search and replace to find the template variables and change them to the proper variables.

The advantage of the first method is that the final script need not be dependent on your word processor. You can simply copy the resulting template to the clipboard and the paste it into your preferred word processor. The advantage of the second method is that you can use existing templates to the extent that they exist. In addition, if you want to change the template, you don’t have to fiddle with your script.

In the next two posts, we’ll look at each method of using templates to create documents.

UPDATE: You may need to turn up your volume. I need to get a microphone for these screencasts.

Scripting Rocket Matter

So let’s look at how we might get our data from FileMaker to Word. In our last script, we told FileMaker to get the first name and last name of the first record of our Contact Management database. In the last line of our script, we stuffed that data into a variable named fullName. Let’s put fullName into Word as we might do if we wanted to draft a letter to this person.

tell application "Microsoft Word"
	tell selection
		type text text fullName
	end tell
end tell

There are several different ways to insert text into a Microsoft Word document. With Word’s robust AppleScript dictionary, you can even access Word’s AutoText feature to insert text. In this example, we use the simplest way to insert text—we tell Word to type text. In line 2, notice that we don’t tell document 1 to do anything. In Word, you can work with selection objects and text range objects to insert your text precisely where you need it. Don’t worry about what is a selection object or text range object right now. Just know that when you tell selection, you insert text at the insertion point (i.e., the blinking cursor). On a blank document, the insertion point will be at the beginning of the document.

In our last few posts, we’ve seen how to use AppleScript to access data from a database and push it to a word processor. You can do this on your local machine. You could also access a remote database and push it to the word processor on your MacBook. Hopefully, you’re beginning to imagine the possibilities of what you can do with AppleScript. One possibility is using AppleScript to push data from FileMaker to Word templates. We’ll look at that idea in our next installment.