path: root/macros/latex/contrib/cooking/cooking.dtx

%    \iffalse
%
% cooking.dtx
% Docstrip archive, run through LaTeX.
%
% Copyright (C) 1999 Axel Reichert
% See the files README and COPYING.
%
%    \fi
%
%    \changes{v0.9b}{1999-06-24}{First release}
%
%    \CheckSum{116}
%
%% \CharacterTable
%%   {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
%    \DeclareRobustCommand*{\env}[1]{\texttt{#1}}
%    \DeclareRobustCommand*{\file}[1]{\texttt{#1}}
%    \DeclareRobustCommand*{\mail}[1]{\texttt{#1}}
%    \DeclareRobustCommand*{\option}[1]{\texttt{#1}}
%    \DeclareRobustCommand*{\package}[1]{\texttt{#1}}
%    \DeclareRobustCommand*{\person}[1]{\textsc{#1}}
%    \DeclareRobustCommand*{\smiley}{\texttt{(-:}}
%    \DeclareRobustCommand*{\source}[1]{\texttt{#1}}
%    \DeclareRobustCommand*{\winkey}{\texttt{(-;}}
%
%    \title{\file{cooking.sty}}
%    \author{%
%      Axel Reichert \\
%      \mail{axel.reichert@gmx.de}%
%    }
%    \date{1999-06-24}
%    \maketitle
%    \begin{abstract}
%      \noindent
%      \file{cooking.sty} is a package for typesetting cooking
%      recipes.  See the files~\file{README} and~\file{COPYING} for
%      additional information and~\file{kraut.tex} for an example.
%    \end{abstract}
%
%    \tableofcontents
%
%
%    \section{Introduction}
%
%    Quite regularly in the german or international newsgroup someone
%    is asking for a style file or document class to typeset recipes.
%    As I really like to cook in my spare time (you know, when I am
%    not writing packages), I started with some macros inspired by the
%    layout of the well-known german cookbook published
%    by~\person{Dr.\,Oetker}~\cite{Gromzik:1996}.
%
%    Most books start a recipe with a list of ingredients, after that
%    a few paragraphs describing what to do.  Thus it is difficult to
%    find the continuation of the recipe, what to do next, because you
%    have put the recipe aside while you were performing the current
%    step.  Some books typeset the ingredients in bold face or use
%    enumerations with numbered steps.  In this way the recipe gets
%    more structured and it is easier to understand what to do in
%    which order.
%
%    An even better solution is to use a two-column layout:  Each
%    ingredient appears in the left-hand column, what to do with it is
%    written in the right-hand column.  The right column is less wide
%    than the usual width of the text, this makes quick browsing of
%    the recipe easier, like in newspapers.  Also, there is no need
%    for a list of ingredients, you just read the left column.  This
%    layout is used in~\cite{Gromzik:1996} and also recommended in the
%    popular german textbook on typography by~\person{Willberg}
%    and~\person{Forssman}~\cite{Willberg:1997}.
%
%
%    \section{What You Need}
%
%    Not much:
%    \begin{enumerate}
%    \item \LaTeXe{} (at least the 1994/12/01~release)
%    \item Only for the example file:
%      \begin{enumerate}
%      \item The \package{babel}~package
%      \item The \package{textcomp}~package and the companion fonts
%      \end{enumerate}
%      Both packages nowadays are ``required'' parts of~\LaTeXe{} and
%      included with every good distribution.
%    \end{enumerate}
%
%
%    \section{Loading}
%
%    Load the package with:
%\begin{verbatim}
%   \usepackage{cooking}
%\end{verbatim}
%
%
%    \section{Options}
%
%    \DescribeMacro{bf}
%    There are two package options that can be used to change the font
%    of the ingredients:
%    \DescribeMacro{it}
%\begin{verbatim}
%   \usepackage[bf]{cooking}
%\end{verbatim}
%    which uses bold face and
%\begin{verbatim}
%   \usepackage[it]{cooking}
%\end{verbatim}
%    which uses italic fonts.  The latter is the default and can thus
%    be omitted.
%
%    \DescribeMacro{nopage}
%    There are two further package options controlling the page breaks
%    between recipes:
%    \DescribeMacro{newpage}
%\begin{verbatim}
%   \usepackage[nopage]{cooking}
%\end{verbatim}
%    allows recipes anywhere on the page, whereas
%\begin{verbatim}
%   \usepackage[newpage]{cooking}
%\end{verbatim}
%    forces a new page after each recipe.  The latter is the default.
%
%
%    \section{Usage}
%
%    \DescribeMacro{recipe}
%    Recipes are written inside \env{recipe}~environments, which
%    requires one argument, the recipe title:
%\begin{verbatim}
%   \begin{recipe}{<recipe title>}
%     <recipe text>
%   \end{recipe}
%\end{verbatim}
%    \DescribeMacro{\ingredient}
%    The text of the recipe usually consists of various ingredients
%    and the corresponding step:
%\begin{verbatim}
%   \ingredient{<ingredient>} <step>
%   \ingredient{<ingredient>} <step>
%   \ingredient{<ingredient>}
%   \ingredient{<ingredient>} <step>
%   ...
%\end{verbatim}
%    Note that there is no need to specify a step.  In this way it is
%    possible to list several ingredients, e.\,g.\ spices.  The step
%    can be divided into paragraphs by blank lines, as usual.
%
%    \DescribeMacro{\energy}
%    All these commands take one mandatory argument and do what you
%    \DescribeMacro{\sidedish}
%    would expect:  They typeset the energy content (in~kJ), recommend a
%    \DescribeMacro{\hint}
%    sidedish, give a hint, typeset the preparation time and propose
%    \DescribeMacro{\preparationtime}
%    modifications of the recipe.  They can only be used inside the
%    \env{recipe}~environment.
%    \DescribeMacro{\modification}
%\begin{verbatim}
%   \energy{3500}
%   \sidedish{Potatoes}
%   \hint{Always use fresh vegetables}
%   \preparationtime{30 minutes}
%   \modification{You can also use beef instead of pork}
%\end{verbatim}
%    However, the ``standard''~text of these commands is written in
%    german, so foreign users have to adapt them.  This is explained
%    in the next section.
%
%    \DescribeMacro{\pagestyle}
%    The package also provides a new pagestyle that suits to the
%    layout of the recipes.  You can select this pagestyle with:
%\begin{verbatim}
%   \pagestyle{recipe}
%\end{verbatim}
%
%
%    \section{Customization}
%
%    \DescribeMacro{\recipemargin}
%    A crucial point of the layout chosen for the recipes is the width
%    of the column used for the ingredients (more precisely: the
%    horizontal position of the start of the right-hand column).  The
%    default value of~|0.35\columnwidth| is pretty good, but this of
%    course depends on the font used, the verbosity used to describe
%    the ingredients etc.  So you can change the width as usual
%    in~\LaTeX{} like this:
%\begin{verbatim}
%   \setlength{\recipemargin}{5cm}
%\end{verbatim}
%    Absolute measures like this, however, should be avoided, because
%    they are less flexible if you change the page margins or the font
%    size.
%
%    \DescribeMacro{\ingredientfont}
%    The font used for the ingredients can be changed, not only via
%    package options mentioned in section~``Loading'':
%\begin{verbatim}
%   \renewcommand*{\ingredientfont}{\scshape}
%\end{verbatim}
%    Of course, this would be a very bad choice, because a caps and
%    small caps font needs by far too much space for a reasonable line
%    breaking in the ingredients column.
%
%    \DescribeMacro{\recipeendhook}
%    If you neither want each recipe on a new page nor recipe after
%    recipe, you can set up a hook that is executed at the end of each
%    recipe.  A simple example would be:
%\begin{verbatim}
%   \renewcommand*{\recipeendhook}{\hrulefill}
%\end{verbatim}
%
%    \DescribeMacro{\recipetitlefont}
%    Normally the recipe title is typeset larger, ragged right and
%    with the same font as the ingredients.  Feel free to change
%    it. Some typographical remarks:  Many people like bold face for
%    the ingredients and the title.  In my opinion it is however not
%    necessary to emphasize these things so strongly.  The two-colomn
%    layout makes the distinction between ingredient and step an easy
%    one and the title already looks different because of size
%    \emph{and} shape.  Bold face does not further help the
%    reader. And in almost all cases you should use the same font for
%    title and ingredients.  Less is more.  OK.  And now something for
%    you strange guys out there:   \winkey
%\begin{verbatim}
%   \renewcommand*{\recipetitlefont}{%
%     \centering\tiny\ttfamily\itshape
%   }
%\end{verbatim}
%
%    \DescribeMacro{\recipetitle}
%    If you do not like the layout of the recipe title at all, you can
%    redefine the \cmd{\recipetitle}~command, which is used internally
%    by the \env{recipe}~environment and takes one mandatory argument,
%    the recipe title as passed to the \env{recipe}~environment.  As
%    usual, a stupid example:
%\begin{verbatim}
%   \renewcommand*{\recipetitle}[1]{\marginpar{#1}}
%\end{verbatim}
%
%    \DescribeMacro{\energy, ...}
%    As an example for the customization of these little commands, I
%    will provide an english translation of the default definitions:
%\begin{verbatim}
%   \renewcommand*{\energy}[1]{%
%     \item #1\,kJ per helping%
%   }
%   \renewcommand*{\sidedish}[1]{%
%     \item[Sidedish] #1%
%   }
%   \renewcommand*{\hint}[1]{%
%     \item[Hint] #1%
%   }
%   \renewcommand*{\preparationtime}[1]{%
%     \item[Preparation time] #1%
%   }
%   \renewcommand*{\modification}[1]{%
%     \item[Modification] #1%
%   }
%\end{verbatim}
%
%
%    \section{Example}
%
%    Run the example file~\file{kraut.tex} through~\LaTeX.  Sorry, it
%    is written in german.  My knowledge of the english language is
%    too poor, I am not able to translate a recipe.\footnote{Perhaps
%    you agree:  In my humble opinion this is one of the most
%    difficult problems when learning a language.  Remember yourself
%    explaining famous dishes of your country to those strange foreign
%    exchange students?   \winkey}
%
%    However, if you can get hold of a german-speaking person, you
%    definitely should, the recipe is really worth it.  But be
%    prepared:  Even native speakers sometimes do not know the meaning
%    of~``Rauchenden''.  A synonym is~``Landj\"ager''
%    or~``Schinkenmettwurst''.  ``Semmelbr\"osel'' could also be
%    replaced by~``Paniermehl''.   \smiley
%
%    And, of course:  If you tried the dish, please send me a mail.  I
%    am very interested in opinions about it.
%
%   \section{Implementation}
%
%
%    \iffalse
%<*driver>
\documentclass[12pt,a4paper]{ltxdoc}
\begin{document}
  \DocInput{cooking.dtx}
\end{document}
%</driver>
%    \fi
%    \StopEventually{%
%      \addcontentsline{toc}{section}{References}
%      \begin{thebibliography}{1}
%      \bibitem{Goossens:1994}
%        \textsc{Goossens, M.; Mittelbach, F.; Samarin, A.}: \emph{Der
%        \LaTeX-Begleiter}.  \newblock Addison-Wesley, Bonn, 1st edn.,
%        1994.
%      \bibitem{Gromzik:1996}
%        \textsc{Gromzik, J.; Reich, C.; Sander, C.} (ed.):
%        \emph{Dr.~Oetker Schulkochbuch -- Das Original}.  \newblock
%        Ceres, Bielefeld, 1996.
%      \bibitem{Willberg:1997}
%        \textsc{Willberg, H.\,P.; Forssman, F.}:
%        \emph{Lesetypographie}.  \newblock Schmidt, Mainz, 1997.
%      \end{thebibliography}
%    }
%    \iffalse
%<*package>
%    \fi
%
%
%    \subsection{Identification}
%
%    This package uses the \source{*}-form
%    of~\cmd{\DeclareRobustCommand}, so it will not work with the very
%    first \LaTeXe~release.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1994/12/01]%
%    \end{macrocode}
%    The package identifies itself with its release date, a version
%    number, and a short description.
%    \begin{macrocode}
\ProvidesPackage{cooking}[%
  1999/06/24 v0.9b Cooking recipes%
]%
%    \end{macrocode}
%
%
%    \subsection{Initialization}
%
%    \begin{macro}{\recipemargin}
%    This initializes the position of the main axis of the layout. The
%    value~``0.35'' is chosen such that the left column looks not too
%    ragged but does not occupy too much space.  Trust my experience.
%    \winkey
%    \begin{macrocode}
\newlength{\recipemargin}%
\setlength{\recipemargin}{0.35\columnwidth}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\ingredientfont}
%    This initializes the font used for ingredients.  The default
%    value will be set later by means of package options.
%    \begin{macrocode}
\DeclareRobustCommand*{\ingredientfont}{\@empty}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\recipeendhook}
%    This is the command to be executed after every recipe.  Its
%    default value will be set later by means of package options.
%    \begin{macrocode}
\DeclareRobustCommand*{\recipeendhook}{\@empty}%
%    \end{macrocode}
%    \end{macro}
%
%
%    \subsection{Option Declaration}
%
%    \begin{macro}{bf}
%    \begin{macro}{it}
%    These options change the font used for ingredients.
%    \begin{macrocode}
\DeclareOption{bf}{%
  \renewcommand*{\ingredientfont}{\bfseries}%
}%
\DeclareOption{it}{%
  \renewcommand*{\ingredientfont}{\itshape}%
}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%    \begin{macro}{nopage}
%    \begin{macro}{newpage}
%    These options set up the hook that is executed at the end of each
%    recipe.
%    \begin{macrocode}
\DeclareOption{nopage}{%
  \renewcommand*{\recipeendhook}{\@empty}%
}%
\DeclareOption{newpage}{%
  \renewcommand*{\recipeendhook}{\newpage}%
}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%
%    \subsection{Option Processing}
%
%    By default, italics are used for the ingredients and each recipe
%    starts on a new page.  If you specify contradicting options
%    like~\option{[it,bf]}, the last one ``wins''.
%    \begin{macrocode}
\ExecuteOptions{it,newpage}%
\ProcessOptions*%
%    \end{macrocode}
%
%
%    \subsection{Defining Commands}
%
%    \begin{macro}{\recipetitlefont}
%    Normally, the title of the recipe is typeset with the font used
%    also for the ingredients.  It should be sufficient to use one
%    font for both kinds of text.
%    \begin{macrocode}
\DeclareRobustCommand*{\recipetitlefont}{%
  \raggedright\large\ingredientfont
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\recipetitle}
%    This command is used for the title of the recipe.  There is no
%    need to use it directly because it will be called by the
%    \env{recipe}~environment automatically.  Nevertheless I decided
%    not to make it an internal command because you will hack it
%    anyway.   \winkey
%    \begin{macrocode}
\DeclareRobustCommand*{\recipetitle}{%
  \@startsection{recipetitle}{1}{\recipemargin}%
    {3.5ex plus 1ex minus 0.2ex}{2.3ex plus 0.2ex}%
    {\recipetitlefont}*%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\energy}
%    \begin{macro}{\sidedish}
%    \begin{macro}{\hint}
%    \begin{macro}{\preparationtime}
%    \begin{macro}{\modification}
%    These commands will probably be redefined by everyone, even
%    german users.  They are meant as examples for logical markup.
%    \begin{macrocode}
\DeclareRobustCommand*{\energy}[1]{%
  \item Pro Portion ca.~#1\,kJ%
}%
\DeclareRobustCommand*{\sidedish}[1]{\item[Beilage] #1}%
\DeclareRobustCommand*{\hint}[1]{\item[Tip] #1}%
\DeclareRobustCommand*{\preparationtime}[1]{%
  \item[Zubereitungszeit] #1%
}%
\DeclareRobustCommand*{\modification}[1]{%
  \item[Abwandlung] #1%
}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%    \begin{macro}{\ingredient}
%    \cmd{\item}~commands are used for nearly everything.  In order to
%    obtain a clearer logical markup, ingredients are typeset with
%    this command.  It takes one mandatory argument, guess what: the
%    ingredient.  The extra level of grouping makes life easier if you
%    want to use my \package{units} or \package{nicefrac}~package for
%    the ingredients.   \smiley
%    \begin{macrocode}
\DeclareRobustCommand*{\ingredient}[1]{\item[{#1}]}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@make@ingredient}
%    If the ingredient takes more than one line, the description of
%    what to do with it continues on the bottom-most line of the
%    ingredient column.  By means of~|\hspace{0pt}| hyphenation of the
%    very first word in the ingredient column is
%    enabled~\cite[p.\,134]{Goossens:1994}.
%    \begin{macrocode}
\DeclareRobustCommand*{\@make@ingredient}[1]{%
  \begin{minipage}[b]{\labelwidth}%
    \vspace{\parsep}%
    \raggedleft\ingredientfont\hspace{0pt}#1%
  \end{minipage}%
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{recipe}
%    This is the environment used for all the recipes.  It takes one
%    mandatory argument, the title of the recipe, which is typeset
%    immediatly.
%    \begin{macrocode}
\newenvironment{recipe}[1]{%
  \recipetitle{#1}%
%    \end{macrocode}
%    The recipe is typeset as a list.  The left-hand column contains
%    the ingredients, the right-hand column the things to do with
%    these ingredients.  The vertical spacing is quite compact.
%    \begin{macrocode}
  \begin{list}%
    {}%
    {%
      \setlength{\topsep}{0ex}%
      \setlength{\partopsep}{0ex}%
      \setlength{\leftmargin}{\recipemargin}%
      \setlength{\labelwidth}{\recipemargin}%
      \setlength{\labelsep}{1em}%
      \addtolength{\labelwidth}{-\labelsep}%
      \setlength{\itemsep}{0ex}%
      \renewcommand*{\makelabel}[1]{%
        \@make@ingredient{##1}%
      }%
%    \end{macrocode}
%    At the end of the environment the hook is executed.
%    \begin{macrocode}
    }%
}{%
  \end{list}%
%  \recipeendhook
}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\ps@recipe}
%    The package also defines a pagestyle for recipes.  It uses the
%    axis defined by~\cmd{\recipemargin} because a centered page
%    number does not work well with this layout.
%    \begin{macrocode}
\DeclareRobustCommand*{\ps@recipe}{%
  \let\@mkboth\@gobbletwo
  \let\@oddhead\@empty
  \let\@evenhead\@empty
  \renewcommand*{\@oddfoot}{%
    \normalfont\hspace{\recipemargin}\thepage\hfill
  }%
  \let\@evenfoot\@oddfoot
}%
%    \end{macrocode}
%    \end{macro}
%    \iffalse
%</package>
%    \fi
%    \Finale
%    \iffalse
%<*testfile>
\documentclass[12pt,a4paper]{article}
\usepackage[german]{babel}
\usepackage{cooking,textcomp}
\pagestyle{recipe}
\begin{document}
\begin{recipe}{Ungarischer Sauerkrautauf"|lauf (6~Portionen)}
\ingredient{30\,g~Butter oder Margarine} zerlassen.
\ingredient{500\,g~Sauerkraut} lo"cker zupfen, kurze Zeit im Fett
  erhitzen.
\ingredient{125\,ml~Wasser}
\ingredient{2~kleine Lorbeerbl"atter} hinzuf"ugen, mit
\ingredient{Salz}
\ingredient{frisch gemahlenem Pfeffer}
\ingredient{1~Prise Zu"cker} w"urzen, das Sauerkraut gar d"unsten lassen
  (es darf keine Br"uhe mehr vorhanden sein).

  Das Sauerkraut mit Salz, Pfeffer und Zu"cker abschme"cken.
\ingredient{500\,ml~Wasser} mit
\ingredient{125\,g~Langkornreis (parboiled)} in den Topf geben, einige
  Minuten quellen lassen.
\ingredient{1/2\,TL~Salz} zuf"ugen, Reis auf h"ochster Stufe zum Kochen
  bringen, etwa 2~Minuten kochen lassen.  Herdplatte ausschalten und den
  Topf mit einem De"ckel bede"cken.  Reis 15~Minuten quellen lassen, bis er
  das Wasser aufgenommen hat.

  Abtropfen lassen, mit kaltem Wasser "ubergie"sen, zum Auf"|lo"ckern
  umr"uhren.
\ingredient{1~mittelgro"se Zwiebel} abziehen, w"urfeln.
\ingredient{20\,g~Margarine} zerlassen,
\ingredient{500\,g~Gehacktes (halb Rind"~, halb Schweinefleisch)} mit
  Salz und Pfeffer w"urzen, mit den Zwiebelw"ur"-feln in dem Fett unter
  st"andigem R"uhren anbraten, dabei die Fleischkl"umpchen mit einer Gabel
  zerdr"u"cken, dann den Reis unterheben.
\ingredient{2~Rauchenden (200\,g)} waschen, in Scheiben
  schneiden.  Sauerkraut, Gehacktes, Rauchenden abwechselnd lagenweise in
  eine gefettete Auf"|lauf"|form schichten, die oberste Schicht soll aus
  Sauerkraut bestehen.
\ingredient{1~Becher (150\,g) Cr\`eme fra\^\i che} mit
\ingredient{250\,ml~Schlagsahne} verr"uhren, "uber den Auf"|lauf gie"sen,
  mit
\ingredient{20\,g~Semmelbr"oseln} bestreuen.
\ingredient{25\,g~Butter} in Fl"ockchen darauf setzen.  Die Form auf
  dem Rost in den Backofen schieben.  Ober"~/""Unterhitze:
  220\,\textcelsius, Hei"sluft: 200\,\textcelsius.
\item[Backzeit] Etwa 30~Minuten
\sidedish{Br"otchen, Bier}
\energy{3\,300}
\end{recipe}
\end{document}
%</testfile>
%    \fi
\endinput