| Back to Computer Support Back to PAV Home Page Email to PAV |
Writing Your OSU Dissertation Using SWPMay 24, 2004
1 Introduction
2 Get The Files 3 Install the Files 3.1 The LaTeX files 3.2 The shell file 3.3 The style (.cst) file 3.4 Set up your dissertation directory 3.5 HanesTest.dvi 3.6 The other files 4 Writing Your Dissertation With SWP 4.1 Set up your dissertation 4.2 Create the first subdocument 4.3 Import existing text 4.4 Back-matter 4.5 The uppercase problem 4.6 The Index 4.7 The Times option 4.8 Producing drafts 4.9 Some General Advice 4.9.1 Use BiBTeX 4.9.2 Make Backups 5 Preparing to Confront The Grad School 5.1 Getting Started 5.2 The Abstract 5.2.1 The Abstract as a subdocument 5.2.2 The inline Abstracts 5.3 The External Abstract 5.4 Dedication 5.5 Acknowledgments 5.5.1 Acknowledgments as a subdocument 5.5.2 Inline Acknowledgments 5.6 Significant events 5.7 Publications 5.8 Major field 5.9 TOCs, etc 5.10 Finishing up 5.11 Other types of thesis 6 Troubleshooting 6.1 Front-Matter errors 6.2 File not found 6.3 Missing chapter cross-references 6.4 Incorrect Table of Contents 7 Unsupported Stuff 8 File List 1 IntroductionThis note explains how to use Scientific Word or Scientific WorkPlace (SWP, for short) to write your OSU dissertation. Writing the guts of the document is straightforward; the problem comes with all the bells-and-whistles that the Grad School requires for the front-matter. The solution provided here is something of a hack, making extensive use of TeX fields which you need to edit by hand. But this is just one file, you won’t have to worry it about until the dissertation’s about ready to be handed in; and the advantage of being able to edit your text in a WYSIWYG-like setting is so great that I think you won’t mind. SWP versions supported: 3.0+. Version 3.0 has a number of minor glitches for which we provide work-arounds; but if you can afford it, it’s worth upgrading. I’ve no reason to believe that this can’t be made to work with version 2.5, but the structure of SWP’s internal files (lat files, etc) is more complicated and I’m no longer confident of my ability to get the details right. Scientific NoteBook is not supported at all. Caveat: The typesetting of your dissertation is completely controlled by a pair of LaTeX files, which you’ll retrieve in the next section. I did not create, and I do not maintain, these files. They are supposed to produce a dissertation acceptable to the Grad School, but I do not vouch for this. My contribution is restricted to the SWP files. I will try to support these, as time permits; but if you send me an emergency email the day before the dissertation needs to be handed in, you will be disappointed. A copy of this document in DVI format is included in the SWP distribution referred to below.
2 Get The FilesFirst you need the LaTeX class and package files. These may be obtained from Mark Hanes’ web site:
Click on Source Code in the left-hand frame. You want the package 1996 Osu Dissertation Class. May 2004: this site no longer seems to be available. I’ve put an archived copy on my website, and you can get it here:
Second, you need the SWP support. This is available at
Create a temporary directory on your hard disk, and unzip both packages to that area.
3 Install the FilesIn the following, we refer to your top-level SWP directory as swpdir: this is something like c:\sw351 (Scientific Word) or c:\swp351 (Scientific WorkPlace).
3.1 The LaTeX filesThe files osudissert96.cls and osudissert96-mods.sty can go in any directory under swpdir\TCITex\TeX\latex. I recommend (if you’ve not done so) that you create a personal directory under this one for your own files, to keep them separate from those supplied with SWP itself.
3.2 The shell fileCopy OSU_Dissertation.shl to any directory under swpdir\shells. Again, you can create your own directory if you’d like; otherwise a natural place is in the Other Documents\SWP directory, since the OSU Dissertation class is based on the Report class.
3.3 The style (.cst) fileBecause it describes a class file, this must go into a subdirectory whose name is the class name. Create the directory swpdir\styles\osudissert96 and copy osudissert96.cst to there.
3.4 Set up your dissertation directoryIf you’ve not already done so, create a directory for your dissertation’s TeX files. I recommend that you create this directory outside the SWP tree; but you don’t have to. Copy swsuppdoc.tex, swsuppdoc1.tex, osudiss.html (this file, for future reference) and HanesTest.dvi to this directory.
3.5 HanesTest.dviThe SWP support comes with HanesTest.dvi, a DVI version of Mark Hanes’ test document which illustrates how everything should look when your dissertation is typeset: it also contains some useful hints about writing your dissertation (though for SWP users some of the discussion, eg on including figures, won’t be useful). The original files needed a bit of tweaking to be process-able through SWP, which is why I’ve supplied a DVI version. (I also re-organized the order of some of the front-matter, to make it conform to the Grad School Handbook: the Acknowledgments and Vita are supposed to come before the Table of Contents).You can preview and/or print this document using the stand-alone TrueTeX previewer (Dvigdi32.exe).
3.6 The other filesYou can delete all of these. You’re now ready to use SWP to write your dissertation.
4 Writing Your Dissertation With SWPHow should you lay out your dissertation? One strategy is to use the subdocument feature, and put each chapter in a separate subdocument. This is especially useful if you have a very long dissertation, since it’s easier to move through a short chapter than through the entire document. But there are a few down-sides to this strategy:
So it’s up to you (at least it is if you’re using SWP 3.5+) whether to use subdocuments or not. Personally, I like proper citations and extensive cross-references, so I’m inclined to advise against; but on the other hand I’ve never prepared a huge document in SWP. Another strategy which always works is to write individual chapters in separate documents (I’d advise using the Standard LaTeX Article or Standard LaTeX Report shell for these) and then import their contents to the master thesis document (or to subdocuments) only when you’re ready to produce final copy. If you do this, be careful to make all labels unique.
4.1 Set up your dissertation
If you will be using subdocuments, this will be your master document; if you’re using SWP3.0, it will be your only (text) document. In either case, I’ll refer to it as the master document in what follows. You might as well fill in realistic values for the front-matter now. Click Typeset -> Front Matter. You see examples of every field which is allowed here: delete the inapplicable ones, and fill in appropriate data for the others. (SWP3.0 may have problems with inserting additional \member fields, which is why the front-matter tries to provide everything). If you have co-advisors, delete the Advisor field, and keep the Coadvisor fields. You can delete Member fields, according to your needs. Usually you will not need the GraduationYear field, but it’s provided (the default, if you eliminate it, is this year). Important: do not try to enter your Acknowledgments via the acknowledgement tag. This acknowledgment is a type of theorem, and won’t give the form required by the Grad School. We’ll take care of the real Acknowledgements later. Close the Front Matter dialog and save your file. This might be a good time to run what you’ve got through the typesetter, to make sure nothing has gone wrong. If errors arise, see section 6.1. Otherwise, if you’re putting your dissertation into a single file, you can start writing now.
4.2 Create the first subdocumentBefore doing this, take a minute to re-read the beginning of this section, on the advisability of using the subdocument feature. If you decide to use subdocuments:
4.3 Import existing textIf you’ve already written part of your dissertation with SWP, you need to import it into either the master document of the appropriate subdocument. Do File -> Import Contents. If your previous text used one of the standard document classes (Article, Book or Report) you should not have any problems. If your previous work was written using an ASCII editor, then, in order for the import to be successful, you need to be aware that SWP does not support all LaTeX macros. When this happens, the unrecognized material will appear as a gray field, and you’ll need to do some fixup to get it right. To minimize this, remember that:
You will need also to re-import any figures, because of the way SWP interfaces with TrueTeX in order to display them on screen and print or preview them. But importing graphics is easy.
4.4 Back-matterYou set up the back-matter of your dissertation in the master document in the normal SWP way: after the last “real” chapter, insert the appendix fragment, then create your appendices as additional chapter-like subdocuments (or chapters, if you’re not using subdocuments). Lastly, (assuming you’re using a BiBTeX bibliography) insert the Bibliography field (Insert -> Field -> Bibliography) or click the Bibliography icon on the Typeset Field toolbar.
4.5 The uppercase problemThe Grad School requires that chapter titles in the Table of Contents have normal appearance (first letter capitalized), while chapter titles in the text itself must be all-caps. There are two ways you can handle this; on balance I tend to prefer the first.
4.6 The IndexThe Grad School Handbook “highly recommends” that you create an Index. At least in the sciences, I recommend that you don’t, simply to preserve your sanity. Indexes are tricky, especially if you go the whole hog and have various levels of sub-items. Who needs the aggravation? However, SWP does support index creation and the MakeIndex program, though I’ve never used it. To typeset the index, you need to insert the Index fragment after the BiBTeX fragment in your document.
4.7 The Times optionAs distributed, the dissertation class will typeset using the Computer Modern Fonts. SWP3.0+ includes complete support for Times Roman fonts (including Times in mathematics), and you may want to switch (for one thing, it photocopies much better). To use Times:
If your work involves the US cents symbol, you may want to get my alltimes package from my website: it produces a much nicer representation of this symbol. If you use this, you can say \RequirePackage{alltimes} instead of the command given above.
4.8 Producing draftsThe OSU Dissertation class typesets your text double-spaced, which is what the Grad School wants. But while you’re writing, that’s not important, and if you’d like to produce your drafts single-spaced you can place an encapsulated TeX field saying \startsinglespace at the beginning of the text in any of your subdocuments; and until you delete the field you will be typesetting single-spaced.
4.9 Some General Advice
4.9.1 Use BiBTeXI strongly encourage you to use BibTeX for your bibliography: as you’ll soon discover, one of the genuine annoyances in preparing articles for publication is that each journal seems to require its own bibliography layout. Using BiBTeX can often completely eliminate this sort of busy-work. So get into the habit of putting all of your references in a BiBTeX .bib file: it may even be worth taking day to collect all the references in your written papers and insert them into a .bib file. SWP comes with the public domain WBibdb program, which makes this easy.
4.9.2 Make BackupsI’d like to take this opportunity to remind you to back up your work regularly. Computers can crash, floppy disks can go bad, and you could be the one to discover a bug in SWP itself. Without backups, that could be traumatic.
5 Preparing to Confront The Grad SchoolOK, you’ve written the dissertation, and your committee seems happy with it — happy enough to schedule the Final Oral Examination. (Congratulations, by the way). It’s now time to prepare a properly formatted document with all the necessary front-matter. This is the only time you will need to write a few lines of actual LaTeX code, and you need to be careful. Fortunately there’s very little of this, and it’s not too difficult. TeX and LaTeX reserve several characters (notably &, #, $, @ and \) for their internal use, and if you need them you must use special sequences instead. Foreign students have an additional problem in that they may need to use accented characters, and these require a special syntax, too. Here’s the simplest way to get them.
It’s cumbersome, I know, but I don’t see any way around it, and besides, there’s not much of it to do. If you need to insert an explicit line-break, you do so by inserting \\ at the appropriate place.
5.1 Getting StartedWe now work through the details of creating the rest of the front matter. The main complication is that you have two strategies for the Abstract (and possibly for the Acknowledgements, too): they can be subdocuments or they can be created inline. The subdocument strategy is slightly easier to work with; but if you are using SWP3.0 and your abstract contains lots of math, you should go for the inline strategy. Whichever Abstract strategy you decide on, begin by creating a subdocument for the rest of front matter. In what follows, I’ll refer to this as your Front-Matter Shell document.
This creates the Front-Matter Shell as an empty subdocument in your dissertation folder. Open it. Now import an outline of the additional front-matter.
In either case, you see a bunch of TeX fields. Save the Front-Matter Shell subdocument.
5.2 The AbstractWe’ll begin by creating the Abstract. Remember that you’ve already decided how you want to create this. The next two parts explain the details, according to the selected strategy.
5.2.1 The Abstract as a subdocument
5.2.2 The inline Abstracts
5.3 The External AbstractThe instructions here apply only if your Abstract is in a subdocument (if it’s inline, you’ve already created the text of the External Abstract). The external abstract pages required by the Graduate School will just be specially formatted versions of your existing abstract.
5.4 Dedication
Technical note: you’re actually entering text into the DEDICATION environment (environment name in caps). The Preamble defines this environment, where it’s essentially a copy of the \dedication command provided in the document class. This is the only way I’ve found to allow you to use SWP’s editing facilities for this section.
5.5 AcknowledgmentsThere’s no reason not to create your Acknowledgments as a subdocument, even with SWP3.0; but if you’d rather that it be inline, skip forward to section 5.5.2.
5.5.1 Acknowledgments as a subdocument
5.5.2 Inline AcknowledgmentsIf you’d prefer to create your Acknowledgments as inline text, you can do so as follows:
5.6 Significant eventsNow we begin to set up your Vita page. Open the Front-Matter Shell subdocument (extras.tex) if it isn’t already open. Your Vita describes the academic world’s view of the significant events in your life. The first one is usually your date and place of birth, and the others tell us when and where you got your prior degrees (if any), and what academic experience you’ve had (if any). Some people include their service as GRAs or GTAs; others think that’s a bit tacky. You might want to consult your advisor about this. To put items in the Significant Events section you add or modify the encapsulated TeX fields labelled [Dateitem]. The page you’re working one contains one of these: to provide more, just cut-and-paste. The contents of each of these must consist of two phrases, each enclosed in braces ({}). The first consists of the date, and the second describes the event. For example, if you were born on February 31st, 1945 in Rome, you’d modify the first [Dateitem] field to say
(Note that, just as in SWP, the long em-dash is entered as three ordinary dashes). Add as many of these [Dateitem]’s as you think appropriate.
5.7 PublicationsThe next set of fields describe any publications you may have produced, divided into “Research Publications” and “Instructional Publications”. Again, you may want to consult with your advisor as to what’s appropriate in each of these categories. You will use SWP’s editing tools to type in the information. What you can’t do is insert a reference to an entry in a BiBTeX bibliography file — you must type in the full reference by hand.
Technical note: the space between the headings (“Research Publications” or “Instructional Publications”) and the actual publication listings in the typeset text is governed by a LaTeX vertical space command (\vspace) in the respective TeX fields. As distributed, we specify -16pt, which looks about right to me. But you can fiddle with this if you’d like.
5.8 Major fieldNext, you need to enter information about your major field.
5.9 TOCs, etcThe last three TeX fields generate the table of contents, and list of figures and/or tables. The Table of Contents is required; if you do not have any tables or any figures, delete the inapplicable fields. Important: In the Grad School’s setup, the dissertation Table of Contents comes at an unusual place, so you can’t use the Make TOC field, which would normally be inserted in the Front Matter dialog. The effect of this is that you cannot rely on SWP’s built-in mechanism for setting the number of LaTeX passes when you typeset your dissertation. You may need to set this manually: two passes will often work, but if there are problems, increase this to 3.
5.10 Finishing upSave the Font Matter Shell, and return to the master document. Do Typeset -> Compile and check Generate a Bibliography. Remember, you need to re-generate the bibliogrpahy only when your references change. If you typeset-preview your text, you should see everything in the right place.
5.11 Other types of thesisAs distributed, the SWP shell document is set up for a PhD dissertation; but the LaTeX support can deal with the other types too. In order to set this up, you must use a text (ASCII) editor, and make a simple change in the master document. Here’s how:
6 TroubleshootingHere are some hints on resolving problems you may encounter.
6.1 Front-Matter errorsUnder SWP30, something can go wrong if you try to add fields (eg Member fields) in the front-matter dialog. (This is why the shell documents provide a full complement of these fields, in the hopes that you won’t have to add; SWP3.5+ seems OK in this regard). The technical issue is that additional fields get added as continuation lines to the existing field. Suppose for example you try to add another Member, “Professor M.N. Oh” after “Professor J.K. Ell”. Under SWP30, if you open your document in an ASCII editor you’ll see that this is rendered as:
which is obviously wrong. You need to fix this by hand so that it reads
6.2 File not foundThe most likely problem involves a report from LaTeX that one file or another can’t be found. You probably got the folder wrong when you entered one or other of the \include commands for subdocuments. Check the followng places: the Front-Matter dialog (if you create the Abstract as a subdocument); the [ExternalAbstract] field in the Front Matter Shell (again, if your Abstract is a subdocument); the [Acknolwledgments] field in the Front Matter Shell (if your Acknowledgments are a subdocument).
6.3 Missing chapter cross-referencesIf you find that cross-references to your chapters are missing — you see something like “As explained in chapter ??” in the typeset version — did you implement the \typesetChapterTitle command, as explained in section 4.5, without making markers uppercase? If so, you need to fix this. You should change any \label’s at the end of each \chapter command to uppercase, and then find and change each \ref to that label. You can do this with SWP’s search-and-replace function.
6.4 Incorrect Table of ContentsIf you find that the Table of Contents page is empty or incorrect, you probably forgot to set the number of passes correctly. See section 5.9
7 Unsupported StuffMark Hanes’ documentation lists a number of features (eg the \degree command), which, it says, are “unnneded if you have used the appropriate documentclass option”. We assume that this applies to SWP users; on the other hand, you can always use any of these commands by creating the appropriate TeX field in your SWP document. We do not directly support the twoside class option, but if you need it, you can simply add it by hand: treat it like another xxx option in the discussion in Other types of dissertation, above, and separated by other options by a comma. Same for the osudraft option; but note that this will only work if you have a postscript printer.
8 File ListHere are the files you’ve placed in your SWP tree, for easy reference in case you upgrade SWP and need to re-create them. arb means an arbitrary directory; and swpdir is your top-level Scientific Word or Scientific WorkPlace directory.
In addition, you need swpsuppdoc.tex and swpsuppdoc1.tex in your dissertation directory.
|