-*- text -*-

$Id: README,v 1.4 2000/07/14 04:25:44 jsquyres Exp $


13 July 2000


OVERVIEW
--------

This is a sample dissertation package for the University of Notre
Dame, provided by the Graduate Student Union (GSU).  This package also
doubles as a sample Master's Thesis, since the styles are the same
(except for a few words on the title page).

This package is meant for graduate students of any discipline at Notre
Dame, and has been tailored for the Solaris environment (2.6 or 7).
It *should* work on just about any Unix flavor at Notre Dame, as long
as you have access to AFS (where the central style file is kept).
Aside from getting access to the OIT-maintained LaTeX and dvips
executables, you should not need to do anything to your environment;
the style file, "ndthesis", should just magically be found when you
invoke LaTeX.

The ndthesis LaTeX class file was originally developed by Don
Peterson, a graduate student in the Physics department.  Thanks for
saving the rest of us much time and frustration!  :-)

Much effort has been put into coordinating with the Graduate School to
ensure that both this sample package and the ndthesis class are
completely up to spec with their formatting guidelines.  If you have
any problems with the Formatting Gods when you turn in your
thesis/dissertation, *please* let us know so that we can make any
corrections necessary.  Thanks!

************************************************
*** Please be sure to read the LICENSE file. ***
************************************************


WARNING
-------

Do *NOT* seek out and copy the ndthesis.cls file to your own local
directory!!  The ndthesis.cls file is deeply buried in a maze of
directories with all the other default TeX styles and fonts.  Leave it
there.  We periodically update the class file with minor changes,
etc. -- you are best off using the centralized copy so that you are
ensured to get the latest version of the class.

If the Formatting Gods turn down your thesis, and you were using a
local copy of ndthesis.cls, just erase it and recompile (using the
centralized copy).

If the Formatting Gods still turn your thesis down, and there appears
to be a problem with the template, or if you find a mistake in this
sample package, let us know, and we'll fix it.

HOWEVER: The ***vast*** majority of cases of incorrect formatting are
due to errors on the user's part, ***not*** because of problems with
the ndthesis class.  In other words, you can still create an
incorrectly formatted thesis, even if you use the ndthesis class!  You
*must* follow the directions in the instructions for the ndthesis
class; this example is *not* a substitute for the real ndthesis
instructions.


UNPACKING THE PACKAGE FILE
--------------------------

To unpack the file, go to the directory where you downloaded the file
and execute the following command:

	unix% gunzip -c sample_ndthesis.tar.gz | tar xvf -

This will create a sub directory called "sample_ndthesis" with all the
sample files in it.


HOW TO USE THE NDTHESIS CLASS
-----------------------------

The ndthesis class file provide for several options, and there are
several "variables" which you must fill in (your name, degree title,
advisor's name, etc.).  Rather than document that here, see the full
documentation for the class (it's easy to read, don't worry).  It's
available from the GSU web site:

	http://www.gsu.nd.edu/Committees/ITC/ndthesis.pdf
	or
	http://www.gsu.nd.edu/Committees/ITC/ndthesis.ps

This sample package includes concrete examples of most of what is
discussed in the ndthesis documentation file.


WHAT IS IN THIS SAMPLE DISSERTATION
-----------------------------------

If you type "make" in the sample_ndthesis directory, it will build
"sample_ndthesis.ps", which you can view with your favorite postscript
previewer.  This is a full thesis, and includes examples of many of
the types of things that usually appear in dissertations, such as
tables, figures, table of contents, a bibliography, etc.  You may wish
to print this file out and use it as an example for acceptable
formats.

You can also type "make pdf" to make the file "sample_ndthesis.pdf",
if you wish to make a PDF version of your dissertation.


HOW TO USE THIS SAMPLE DISSERTATION
-----------------------------------

The goal of this sample is to provide you with a set of files from
which you can simply delete the content and use as a template for your
own thesis.  

That is, we hope to have done all the hard work for you; you just have
to set a few switches (all clearly documented) and replace the text
content with your own.  Then, all you have to do is invoke "make",
which should do the trick of creating your thesis postscript file.
Hopefully, this will save a lot of headaches in trying to figure out
the mysteries of LaTeX, make, etc.

This sample is divided up into several files, all of which have
helpful comments included:

-------------------------------------------------------------------------
README			- This file
Makefile		- This makefile is setup to build the sample
			  dissertation postscript or PDF file.  Just
			  type "make" (or "make pdf" to build the PDF
			  file).

sample_ndthesis.tex	- This is the "top-level" .tex file.  It contains
			  the settings for the title page, table of
			  contents, list of tables/figures,
			  acknowledgments, dedication, abstract,
			  includes the two chapter .tex files, and the
			  bibliography.
chapter1.tex		- The text for the first chapter.
chapter2.tex		- The text for the second chapter.
appendix.tex		- The text for the appendix.

sample_ndthesis.bib	- BibTeX entries for the bibliography.
sample_ndthesis.eps	- An encapsulated postscript figure that is
			  used in the sample dissertation.
sample_ndthesis.m	- Short Matlab script to make the .eps figure.
-------------------------------------------------------------------------


A NOTE ABOUT THE MAKEFILE
-------------------------

The Makefile is heavily commented.  To use this Makefile for your own
thesis, you should really only need to change a few entries at the top
of the file, all of which are clearly marked.  There is also a clearly
marked "You should not need to edit below this line" line; unless you
understand LaTeX and the rules of "make", I would recommend against
fiddling with things below there.

Basically, you just need to enter the names of the .tex files (and any
other files in your dissertation, such a figure files, .bib files,
etc.) in your thesis, and make will ensure that when you edit any one
of those files, the thesis will be rebuilt.

The Makefile is "smart", in that it will re-run latex multiple times
until all references have stopped changing.  It will also run BibTeX,
if necessary, to generate your bibliography.  

Basically, once you put in your filenames, you should just need to
type "make", and when it is finished, your .ps file will be created.

Here is a list of all the targets pre-programmed into the Makefile:

-------------------------------------------------------------------------
ps (default)	- Builds the sample_ndthesis.ps file
pdf		- Builds the sample_ndthesis.ps and
		  sample_ndthesis.pdf files
dvi		- Builds the sample_ndthesis.dvi file
clean		- Removes various backup files created by text editors
squeaky		- Removes all the "extra" files that latex (et al.) 
		  create, and only leaves your source files (.tex,
		  .bib, figures, etc.).  This also removes your .ps
		  and .pdf files.
-------------------------------------------------------------------------


A NOTE ABOUT BIBLIOGRAPHIES
---------------------------

Most departments allow for a single bibliography at the end of the
paper.  This is the way that the sample_ndthesis will be built.
However, some departments want bibliographies at the end of each
chapter.  This sample can do that as well, but you must first perform
a few steps:

- In the beginning of sample_ndthesis.tex, uncomment the line
\usepackage{chapterbib}. 

- At the end of sample_ndthesis.tex, comment out the following lines:

	\backmatter

	\addcontentsline{toc}{chapter}{BIBLIOGRAPHY}
	\bibliographstyle{plain}
	\bibliography{sample_ndthesis}

- At the end of both chapter1.tex and chapter2.tex, uncomment the
following lines:

	\bibliographstyle{plain}
	\bibliography{sample_ndthesis}

- In the Makefile, fill in the top-level filenames for your chapters
(chapter1.tex and chapter2.tex in this example) in the CHAP_CITE_TEX
macros.  Be sure that these files are *not* mentioned again in the
OTHER_SRC_FILES macro, below.

You are now setup to "make".  Invoke "make", and you should have a .ps
file with bibliographies at the end of each chapter.


AVAILABILITY / CONTACT
----------------------

This package is provided by the Graduate Student Union of the
University of Notre Dame.  The tarfile of this package is available at
the GSU web site:

	http://www.gsu.nd.edu/Committees/ITC/sample_ndthesis.tar.gz

If you find any bugs with the sample package or the ndthesis class,
please send mail to:

	ndthesis@gsu.nd.edu

Good luck!
