% $Id: locguide.doc,v 1.5 1994/02/01 21:19:02 schrod Exp $ %---------------------------------------------------------------------- % % LaTeX document class guide % % [LaTeX in MAKEPROG] % (history at end) % have to change this to 2e %%%% %%%% %%%% These TeX macros were documented with the documentation system %%%% MAKEPROG and automatically converted to the current form. %%%% If you have MAKEPROG available you may transform it back to %%%% the original input: Remove every occurence of three percents %%%% and one optional blank from the beginning of a line and remove %%%% every line which starts with four percents. The following lex %%%% program will do this: %%%% %%%% %% %%%% %%%% ^%%%\ ? ; %%%% ^%%%%.*\n ; %%%% %%%% If you just want to print out the documentation you may fetch %%%% the archive print-makeprog.tar.Z from ftp.th-darmstadt.de (directory %%%% pub/tex/latex). It contains *all* used styles -- but beware, they %%%% may not be documented since parts of them are still in alpha release... %%%% %%% \documentstyle[progltx,a4-9,rcs,names]{article} %%% \nofiles % don't need an aux file %%% \begin{document} %%% \title{The {\tt locguide\/} Document Class} %%% \author{% % LaTeX does not discard unnecessary glue... %%% Joachim Schrod% %%% \thanks{% %%% TU~Darmstadt, Alexanderstr.~10, D-64283 Darmstadt, Germany.\newline %%% Email: {\tt schrod@iti.informatik.th-darmstadt.de}.% %%% }% %%% } %%% \RCSdate $Date: 1994/02/01 21:19:02 $ %%% \maketitle %%% % doesn't work with progltx yet %%% %\tableofcontents %%% % ------------------------------------------------------------ %%% % %%% % subdocument: The user interface of locguide.cls %%% % %%% %\input locguide-user %%% {\bf User manual is missing} %%% % %%% % ------------------------------------------------------------ %%% \sect This document class reserves the namespace |lg|. %%% \beginprog \ifx \lg@loaded\undefined \def\lg@loaded{$Revision: 1.5 $} \else \endinput \fi % <-- one line! %%% \endprog %%% \sect This document class is supported. Send bug reports, comments and %%% repairs. %%% The reference version may be retrieved via anonymous ftp from %%% |ftp.th-darmstadt.de| [130.83.55.75], directory |pub/tex/latex|. It's %%% part of the Generic Local Guide which you find there as a compressed %%% tar file. (The information on the IP~number is dated %%% January~30,~1994. It might have changed, also this is very %%% unlikely. Use your friendly nameserver.) %%% \chap Implementation. %%% This is {\bf very\/} quick implementation of a class for the Generic %%% Local Guide. It must still be documented. This will be done during the %%% creation of the {\it Meta Guide} that explains how to adapt and change %%% the GLG. %%% \sect We use |\import| instead of |\input| when we want to emphasize %%% that this inclusion is a part of our implementation strategie. %%% |\import|s might also be inlined. %%% \beginprog \let\import=\input %%% \endprog %%% \sect |locguide| is a subclass of |article|. It does not define any %%% new options. %%% \beginprog \NeedsTeXFormat{LaTeX2e} \DeclareOption*{\PassOptionsToClass{\CurrentOption}{article}} \ProcessOptions \LoadClass{article} %%% \endprog %%% \sect The |logos| package is a collection of logos from the \TeX{} %%% world. Something like |texnames.sty| by Nelson and |tugboat.cmn|, %%% but has more logos in it. I didn't want to distribute the $n+1$st %%% |texnames.sty|. %%% But we still need some more logos, that we simply add here. %%% \beginprog \RequirePackage{logos} \newcommand\TFM{\texttt{TFM}\@} %%% \endprog %%% \sect We use a few styles that were written for \LaTeX{}~2.09. They %%% will be transformed into \LaTeXe{} packages as soon as I will find %%% time for this. %%% % %%% \begin{itemize} %%% \item The |idverb| style option (``identifier verbatim'') allows the %%% usage of vertical bars (`{\tt \vbar}') as a delimiter for verbatim %%% texts. Most probably this style will not survive, I'll replace it %%% by a |shortverb| package which is an extract of the |\MakeShortVerb| %%% feature of the |doc| package. %%% \item The |rcs| style option allows the usage of RCS supplied %%% information in the GLG. It will be paramatrized in section~\ref{sec:rcs}. %%% \end{itemize} %%% \beginprog \import{idverb.sty} \import{rcs.sty} %%% \endprog %%% \sect Now can introduce the additional markup possibilities. We'll %%% start with the environments, introduce new section markup, and finish %%% with tags for classification of terms. %%% Before we start we declare some shorthands for category codes. %%% By declaring the underscore~`(|_|)' as letter we can use it in our %%% macros. (I agree with {\sc D.~Knuth} that %%% |\identifier_several_words_long| is more readable than %%% |\IdentifierSeveralWordsLong| and in every case better than %%% |\p@@@s|.) As this is a \LaTeX{} class the at sign is a letter %%% anyhow; so we can use the ``private'' Plain and \LaTeX{} macros; and %%% with the underscore we can make our own macros more readable. But as %%% we have to restore this category code at the end of this macro file %%% we store its former value in the control sequence |\uscode|. This %%% method is better than to use a group because not all macros have to %%% be defined global this way. %%% \beginprog \ifx \CatEscape\undefined \chardef\CatEscape=0 \chardef\CatOpen=1 \chardef\CatClose=2 \chardef\CatIgnore=9 \chardef\CatLetter=11 \chardef\CatOther=12 \chardef\CatActive=13 % is defined in Plain already \chardef\CatUsCode=\catcode`\_ \fi \catcode`\_=\CatLetter % top level macro file %%% \endprog %%% \sect Let's identify this document class against the user and in the %%% Log file. We name also the class we're using for the \LaTeX{} kernel. %%% \beginprog \begingroup \catcode`\$=\CatIgnore \catcode`\:=\CatIgnore \typeout{Document Class `locguide' for the Local Guide, $Revision: 1.5 $} \endgroup \ProvidesClass{locguide} %%% \endprog %%% \chap New environments. %%% The |frametext| environment sets its content in a framed box. The %%% width of the box is three quarters of the column width. Due to the new %%% |lrbox| environment of \LaTeXe{} the implementation is easy. %%% The |framebox| environment is our basic building block for more %%% enviroments that are introduced below. %%% \beginprog \newbox\lg_framed_text \newenvironment{frametext}% {% \begin{lrbox}\lg_framed_text \begin{minipage}{.75\columnwidth}% \sloppy }{% \end{minipage}% \end{lrbox}% \fbox{\box\lg_framed_text}% } %%% \endprog %%% \sect The |todo| environment features hints for the persons that will %%% complete the GLG. If the hints of all |todo| environments are %%% followed, a Local Guide has been created. %%% The environment takes one parameter, the category of this todo text. %%% This will help in the creation of partially replacements. The category %%% is simply set in the margin. %%% If any |todo| is presented in the text the |@lg@todoPresent@| flag is %%% set and code to set it is written to the |AUX| file. %%% \beginprog \newif\if@lg@todoPresent@ \@lg@todoPresent@false \newenvironment{todo}[1]% {% \center \noindent \marginpar{#1}% \lg_write_set_flag{todo}% \frametext }{% \endframetext \endcenter } %%% \endprog %%% \sect The |fixme| environment is used to present problems with the %%% GLG\@. It's for our fellow readers to remind them that this document is %%% not yet finished. %%% Fixmes are marked by dangerous bend signs, well known from the %%% \TeX{}book. This sign is part of the |manfnt| font. %%% \noindent {\bf Caveat:}\quad This is pre-NFSS code that must still be %%% adapted. %%% If any |fixme| is presented in the text the |@lg@fixmePresent@| flag %%% is set and code to set it is written to the |AUX| file. %%% \beginprog \newif\if@lg@fixmePresent@ \@lg@fixmePresent@false \font\lg_manfnt=manfnt % with the dangerous bend sign \chardef\lg_dbend="7F % I like the non-S curve ;-) \newenvironment{fixme}% {% \center \noindent \marginpar{{\lg_manfnt\lg_dbend}}% \lg_write_set_flag{fixme}% \frametext }{% \endframetext \endcenter } %%% \endprog %%% \sect To write the flag set code we use the fact that |\string| does %%% not append a space token to the token list created from a control %%% sequence. This way we'll get \emph{one} token when the \AUX{} file is %%% read. %%% \beginprog \def\lg_write_set_flag#1{% \csname if@lg@#1Present@\endcsname \else \write\@auxout{\global \string\@lg@#1Present@true}% \expandafter\global \csname @lg@#1Present@true\endcsname \fi } %%% \endprog %%% \sect At the start of the document text we can check these flags and %%% add an appropriate warning that explains the todo and the fixme %%% feature. When we add the warning, the flag set code must not be added %%% to the |AUX| file. This is no real todo/fixme, only an explanation. %%% After we added the warning we reset the flag. Otherwise the deletion %%% of the last environment will not be noticed in the next run. %%% \beginprog \def\lg_add_warning#1{% \csname if@lg@#1Present@\endcsname \begingroup \let\write\@gobbletwo \csname lg_warn_#1s\endcsname \expandafter\global \csname @lg@#1Present@false\endcsname \endgroup \fi % release space \expandafter\global \expandafter\let \csname lg_warn_#1s\endcsname \relax } %%% \endprog %%% \sect The checks are not made at the real beginning of the document, %%% the titlepage shall come first. This has the consequence that we %%% cannot use the \textit{begin document hook}, we have to supply our own %%% one. %%% We call this tag |\frontMatterFinished|, it will also eject the page. %%% \beginprog \newcommand\frontMatterFinished{% \eject \lg_add_warning{fixme}% \lg_add_warning{todo}% } %%% \endprog %%% \sect Let's formulate the two warnings. %%% \beginprog \def\lg_warn_todos{% \begin{todo}{}% This document, the Generic Local Guide, has still places where information about your local installation is missing. All these places are marked with a hint what to do. This hint is typeset in a box, like this text you're reading. In the \LaTeX{} source you'll find the places to change if you look for the |todo| environment. Sometimes these ``todo hints'' are categorized, to help you in your decision if you want to attack them right now. This categorization is shown in the margin then. \end{todo}% } \def\lg_warn_fixmes{% \begin{fixme}% This document is still not ready; it has known problems. These problems are explained in notes throughout this text. To be able to see them very quickly, they are framed with a dangerous bend in the margin (like this explanation itself). If you know the answer to any question posed in a problem note, or if you have suggestions how to avoid the problem, please contact the author. \end{fixme}% } %%% \endprog %%% \sect The |shortdesc| environment is a description list with short %%% langes in monospace and short text (not longer than one column) in %%% italics. %%% \beginprog \def\lg_shortdesc_label#1{\hspace\labelsep \reset@font\ttfamily #1} \newenvironment{shortdesc}% {% \list{}{% \labelwidth\z@ \itemindent -.5\leftmargin \itemsep \z@ plus \p@ \let\makelabel\lg_shortdesc_label \itshape }% }{% \endlist } %%% \endprog %%% \chap New section tags. %%% The abstracts in the module descriptions are tagged with high-level %%% constructs. This way it's possible to use these abstracts in other %%% contexts, too. %%% \beginprog \newcommand\classAbstract[1]{\subsubsection{The \class{#1} Document Class}} \newcommand\packageAbstract[1]{\subsubsection{The \package{#1} Package}} \newcommand\Abstract{\errmessage{Sorry, there is no `Abstract' environment}} \let\endAbstract=\endinput %%% \endprog %%% \sect The class and package abstracts are each kept in a single files. %%% That way we easily can easily add new abstracts. One file exists, for %%% classes and packages respectively, that inputs all files of this %%% category. This file is input in the GLG by |\inputAbstracts|, the %%% argument is either `|classes|' or `|packages|'. %%% \beginprog \newcommand\inputAbstract[1]{% \InputIfFileExists{#1}% {}% {% \errhelp{% Please read the configuration-manual for the Generic Local Guide.^^J% It explains how to setup the file `#1.tex'. This file is needed^^J% to generate a description of all installed #1.}% \errmessage{You have forgotten to create #1.tex}% }% } %%% \endprog %%% \sect Hints are started with |\hint|. %%% \beginprog \newcommand\hint{% \par \medskip \noindent \textsl{Hint:}\quad \ignorespaces } %%% \endprog %%% \sect |\lgNotComplete| may be used after |\if| to test if generic %%% parts are still in the GLG (\textit{true}), or if it got a real Local %%% Guide by now (\textit{false}). %%% \beginprog \def\lgNotComplete{yn\fi \if@lg@todoPresent@} %%% \endprog %%% \sect \label{sec:rcs}% %%% During the GLG time, we keep the version history in the printed %%% document. It will be discarded if the last |todo| is discarded. %%% We also supply our own names for the revision log. %%% \beginprog \def\lg_end_document{\end{document}} \newcommand\proceedIfGLG{% \if@lg@todoPresent@ \let\lg_end_document\relax \fi \lg_end_document } \def\RcsLogStyle{% \clearpage \def\RcsLogHeading{\subsection*}% % should be default... \footnotesize } \rcsAuthor{schrod}{Joachim Schrod} \rcsAuthor{detig}{Christine Detig} %%% \endprog %%% \chap Small tags. %%% Directories, files, extensions, document classes, packages, options, %%% and pagestyles are all tagged differently. This will enable us later %%% to produce an index for these terms. %%% The tag for pagestyles is named |\pgsty| because |\pagestyle| is %%% already a \LaTeX{} tag. |\pagesty| is not appropriate because it's too %%% easy to intermix. %%% \beginprog \newcommand\dir[1]{\texttt{#1}} \newcommand\file[1]{\texttt{#1}} \newcommand\ext[1]{\texttt{#1}} \newcommand\class[1]{\textsf{#1}} \newcommand\package[1]{\textsf{#1}} \newcommand\option[1]{\textsf{#1}} \newcommand\pgsty[1]{\textsf{#1}} %%% \endprog %%% \sect Typography aware authors use |\eg| and |\ie|. %%% \beginprog \newcommand\eg{e.\,g.\spacefactor\@m} \newcommand\ie{i.\,e.\spacefactor\@m} %%% \endprog %%% \sect The following switches describe what subsystems are installed on %%% the local host. %%% This must be checked more carefully... %%% \beginprog \newif\ifInstalledBabel \newif\ifInstalledMakeIndex %%% \endprog %%% \sect This is a kludge, until I introduced configuration files. %%% \beginprog \def\platform{\fbox{platform}} %%% \endprog %%% \chap Layout. %%% Figures and tables are placed `top', `bottom', `page'. They are too %%% large to place them `here'. %%% More figures are allowed per page. These values need fine tuning, they %%% might be even invalid. %%% \beginprog \def\fps@figure{tbp} \def\fps@table{tbp} \def\textfraction{.15} % must be at least 15% text on page \def\topfraction{.8} % for top insertion \def\bottomfraction{.5} % for bottom insertion \def\floatpagefraction{.8} % float pages only if the float is larger than 80% %%% \endprog %%% \sect Captions are typeset with hanging indentation. %%% \beginprog \long\def\@makecaption#1#2{% \vskip\abovecaptionskip \begingroup \reset@font \setbox\@tempboxa\hbox{#1: #2}% \ifdim \wd\@tempboxa >\hsize % IF longer than one line: \@hangfrom{#1: }#2\par % THEN set as hanging paragraph \else % ELSE center. \hbox to\hsize{\hfil\box\@tempboxa\hfil}% \fi \endgroup } %%% \endprog %%% \sect Try harder to prevent overfull boxes. We have a lot of material %%% that can't be broken across two lines (verbatim, file names, etc.) %%% \beginprog \emergencystretch=2em %%% \endprog %%% \chap The end. %%% Well, after all we're finished with this style. We must not forget to %%% restore the underscore catcode. %%% \beginprog \catcode`\_=\CatUsCode \endinput %%% \endprog %%% %\sect {\it Acknowledgements:}\quad I would like to thank XXX %%% \def\RcsLogStyle{% % Until progltx supports rcs.sty %%% \def\RcsLogHeading##1{% %%% \begingroup %%% \normalsize %%% \sect {\sl ##1.}% %%% \par %%% \endgroup %%% }% %%% \footnotesize %%% } %%% \begin{rcslog} %%% $Log: locguide.doc,v $ %%% \Revision 1.5 1994/02/01 21:19:02 schrod %%% Added tag |\hint| to introduce hints for authors. %%% \Revision 1.4 1994/02/01 20:48:47 schrod %%% Renamed the presence flags for the |todo| and |fixme| environment. It %%% does not contain underscores any more and is better readable from the %%% |AUX| file this way. The |todo| flag is now written their as well. %%% Introduced |\frontMatterFinished|, |\AtBeginDocument| is not used any %%% more. The additional material should not be in front of the title page. %%% Added a public switch to check if this document is still a GLG, or %%% already a LG. %%% Added layout definitions: float specification, hanging captions, %%% emergency stretch. %%% \Revision 1.3 1994/01/31 21:21:18 schrod %%% Replaced the |guide| style option (\LaTeX{} 2.09) by the |locguide| %%% document class (\LaTeXe{}). %%% \Revision 1.2 1994/01/26 14:23:36 detig %%% Preliminary formatting needed definition of |\dir|, |\file|, and |\tbw|. %%% \Revision 1.1.1.1 1994/01/17 13:03:41 detig %%% English Generic Local Guide, I\LaTeX{} version as of 90--04--19. %%% \Revision 0.0 1990/04/19 00:00:00 schrod %%% \begin{verbatim} %%% % OLD VERSION HISTORY (before I used CVS) %%% % %%% % DATE PERSON REMARKS %%% % 90-04-20 js defined \zb, \dh, \eg, and \ie. %%% % 90-20-12 js german markup supported (a la dlocal.tex) %%% % 89-11-18 js first version %%% \end{verbatim} %%% \end{rcslog} %%% \end{document} %%% %%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%% Local Variables: %%% mode: LaTeX %%% TeX-brace-indent-level: 4 %%% TeX-auto-regexp-list: LaTeX-auto-minimal-regexp-list %%% End: