Return to howtohowto.tex CVS log | Up to [HallC] / Documents / Howtos |
File: [HallC] / Documents / Howtos / howtohowto.tex
(download)
/
(as text)
Revision: 1.4, Fri Apr 4 14:28:38 2003 UTC (21 years, 5 months ago) by saw Branch: MAIN CVS Tags: mar2005, hks05, HEAD Changes since 1.3: +7 -4 lines 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 %
Analyzer/Replay: Mark Jones, Documents: Stephen Wood |
Powered by ViewCVS 0.9.2-cvsgraph-1.4.0 |