Return to howtohowto.tex CVS log

Up to [HallC] / Documents / Howtos

Prohibit off site access to vendor manuals

% Hall C Howto
% To process this document, you also need the files:
%    chowto.cls
%    chowto.bib
% If you refer to publications not in chowto.bib, then create a file with the
% same name as this with the ``.tex'' changed to ``.bib'' and put the
% references into that file in BibTeX format.
%
% 
\documentclass{chowto}

\def\BibTeX{{\rmfamily B\kern-.05em%
      \textsc{i\kern-.025em b}\kern-.08em%
      T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}

\title{Creating Hall C Howto and Reference Documents}
\howtotype{expert} % ``expert'', ``user'', ``reference''
\category{general}
%\experiment{E02-XXX}
%\maintainer{Stephen A. Wood} % Optional
\author{Stephen A. Wood}
\date{March 19, 2003}

\begin{document}

\begin{abstract}
The Hall C documentation is provided as a set of short Howtos and References.  
This Howto describes how to find and use the {\LaTeX} Howto template and
class files to create a new Howto.  The source code for this Howto also
serves and an example howto.
\begin{figure}[htp]
\begin{center}
\includegraphics[bb=0 0 150 45]{howtohowto-hallc_logo.ps}
%\caption{Include Graphics}
\end{center}
\end{figure}

\end{abstract}

\section{Getting Started}
To prepare a Hall C howto or reference, download the tar file\\
\hturl{http://hallcweb.jlab.org/document/howtos/chowto.tgz}\\
and unpack it into a
working directory with with \verb|tar -zxf chowto.tgz|, yielding the
following files:
\begin{description}
\item[template.tex] The template for writing Hall C howto and reference
  documents.
\item[howtohowto.tex] The {\LaTeX} file for this document, provided as an
  example.
\item[chowto.cls] The {\LaTeX} class (style) file for howto and reference
  documents.
\item[chowto.bib] The Hall C bibliography database in {\BibTeX} format.
\item[chowto.bst] The Hall C bibliography database {\BibTeX} style file.
  (A copy of \verb|unsrt.bst| with the addition of the \verb|URL| key.)
\end{description}
The file \verb|template.tex| should be renamed to a filename unique and
appropriate for it's content.  In order to choose a unique filename,
please see the list of existing howto filenames at
\hturl{http://www.jlab.org/~saw/howto/howtolist.php}.

To compile a completed howto, use the following commands:
\begin{verbatim}
  latex myhowto
  bibtex myhowto
  latex myhowto
  latex myhowto
\end{verbatim}
following by \verb|xdvi| or \verb|dvips| commands to view or print the
results.  If the document contains no citations, then it is sufficient t
run {\LaTeX} once (or perhaps twice).

Note: Compiling {\LaTeX} Howto documents will work on
\htlink{JLab CUE}{http://cc.jlab.org/services/cue/} Linux machines such as
\verb|jlabl1|, \verb|ifarmlX|, or \verb|dlhXX|.  It may also work on other
systems with a recent {\LaTeX} installation.  If it doesn't work on one of
these sytems, it is likely because of a missing \verb|hthtml| package.  If
that is the case, download
\htlink{html.sty}{http://www.jlab.org/~saw/howto/html.sty} and
\htlink{hthtml.sty}{http://www.jlab.org/~saw/howto/hthtml.sty} into
the directory with your howto document and the chowto files.

\section{Creating a Howto document}
Hall C howtos and references use a simple custom {\LaTeX} class that is derived
from the article style.  This class automatically loads several {\LaTeX}
packages and a bibliography style, so no options or new commands should be
added before the \verb|\begin{document}| line.

The commands \verb|\title|, \verb|\author|, \verb|\howtotype|,
\verb|\category|,  and
\verb|\date| should be edited.  \verb|\howtotype| must contain either
\verb|user|, \verb|expert|, or \verb|reference| to mark the document as a
``User Howto'', ``Expert Howto'', or ``Reference''.  The required command
\verb|\category| will be used to group the howto documents into
related topics making web navigation of the online copies of the Howtos
easier.  The arugment of the \verb|\category| command must be one of the
following:
\begin{center}
\begin{tabular}{|l|l|}\hline
Category&Description\\
\hline\hline
hms&HMS detectors and other systems\\\hline
sos&SOS detectors and other systems\\\hline
magnet&SOS/HMS or other magnet systems\\\hline
beamline&Beamline instrumentation/operation\\\hline
daq&Data Acuisition and Online-Analysis\\\hline
electronics&Trigger Electronics and Cabling\\  \hline   
target&Cryo and Solid Target operation\\   \hline
general&General and Miscellaneous Hall C information\\\hline
\end{tabular}
\end{center}
The
\verb|\maintainer| command can be used if the person maintaining or
updating a document is different from the original author(s).

After the \verb|\begin{document}| command, the author should write an
abstract and then add \verb|\begin{section}| and \verb|\begin{subsection}|
commands as needed.

\subsection{References}
Citatations to references shall be made with the standard \verb|\cite|
command.  A number of references have been predefined in the master Hall C
documentation bibiography file, \verb|chowto.bib| which is included with
the howto tar file.  This file is in the
\htlink{\BibTeX}{http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html}
format.

References that are not already included in \verb|chowto.bib| should be
put into a file called \verb|filename.bib|
(Assuming that the {\LaTeX} file is \verb|filename.tex|), also
in {\BibTeX} format.

References to another howto document should be made with
\verb|\cite{howto:|{\it filename}\verb|}|, where {\it filename} is the filename of another
howto without the \verb|.tex| extension.  For example, a reference to this
document\cite{howto:howtohowto} is written as
\verb|\cite{howto:howtohowto}|.  The list of existing howto documents is
available at \\
\hturl{http://www.jlab.org/~saw/howto/howtolist.php}.

The \verb|chowto.bib| file also contains entries for various vendor supplied user
manuals that are being collected on the web at\\
\hturl{http://hallcweb.jlab.org/document/vendor_manuals/}.  That page lists the
{\BibTeX} keys that can be used to cite these manuals.

Web addresses (URLs) may be used in references by adding the {\BibTeX} key
\verb|URL| to the definition of a reference.  To put web addresses
directly in the text, use the commands \verb|\htlink| or \verb|\hturl|
from the
\htlink{hthtml}{http://www.mathcs.emory.edu/~mic/latex2html/docs/hthtml/hthtml/}
package.  These commands will put the URLs directly in the text (or as a
footnote) rather than in the bibliography when the document is processed
with {\LaTeX}.  Furthermore, when the document is published to the web
with LaTeX2html, web links will appear directly in the text.

\subsection{Including Figures and Graphics}

Either the epsfig, or the graphicx package may be used to include
graphics and figures.  The \verb|\usepackage| command is not required to
activate these packages.  All included graphics files should have
filenames that start with ``{\it filename}\verb|-|''.  Using this convention will
help in the planned automated management of the howto documents.

\section{The Bigger Picture}
While a howto prepared as described above can be printed out as a
stand-alone document, the goal is to provide a centrally maintained
collection of short, up-to-date documents that can easily be viewed on the
web.  All the documents will be kept in the Hall C CVS repository which
will keep a revision history of each document, and also allow branches of
the entire document collection to be forked off for large experiments
which require modified or custom documentation.

\end{document}

% Revision history:
% $Log: howtohowto.tex,v $
% Revision 1.4  2003/04/04 14:28:38  saw
% Prohibit off site access to vendor manuals
%
% Revision 1.3  2003/03/19 21:28:50  saw
% Mention Vendor Manuals list.
%
% Revision 1.2  2003/03/08 04:39:37  saw
% Update path to chowto.tgz
%
% Revision 1.1  2003/03/03 20:03:25  saw
% Initial checkin
%