% $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:
