% \iffalse meta-comment
%
% Copyright (c) 2006 by Tikitu de Jager <tikitu@gmail.com>
% --------------------------------------------------
% 
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.2
% of this license or (at your option) any later version.
% The latest version of this license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.2 or later is part of all distributions of LaTeX 
% version 1999/12/01 or later.
%
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{taxonomy}[2006/11/26 v0.2 cases-like nested taxonomies; braces align differently] 
%<package>%\RequirePackage{amsmath}
%<*driver>
\documentclass{ltxdoc}
\usepackage{taxonomy}
\usepackage{compsci}
\usepackage[greek,english]{babel}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\def\docdate{2006/11/09} 
\begin{document}
  \DocInput{taxonomy.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{108}
%
% \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         \~}
%
%
% \changes{v1.0}{2006/11/09}{Initial version}
%
% \GetFileInfo{taxonomy.sty}
%
% \DoNotIndex{\newcommand,\newenvironment,\begin,\end,\def,\if,\else,
%             \ifx,\fi,\ensuremath,\let,\newsavebox,\providecommand,
%             \relax,\renewcommand,\InputIfFileExists}
% \MakeShortVerb{\"}
% 
%
% \title{The \texttt{taxonomy} package\thanks{This document
%   corresponds to \texttt{taxonomy}~\fileversion, dated \filedate.}}
% \author{Tikitu de Jager \\ \texttt{tikitu@gmail.com}}
%
% \maketitle
% 
% \begin{abstract}
%   A dirty horrible hack to get cases-like environments but with braces
%   limited to the size of the labels at each level, not the entire
%   rightward closure of the tree.
% \end{abstract}
%
% \section{Introduction}
%
% \subsection{Usage}
% Add "\usepackage"\marg{taxonomy} to the preamble 
% of your document.
%
% \section{The macros}
%
% Everything goes inside the environment |taxon| (read this as ``one
% taxonomic entry''). You'll be constructed nested trees of taxons.
%
% Within a taxon, you have four useful macros. 
% \begin{itemize}
% \item Use |\taxLabel| \emph{first} to introduce the label of the current
%   subtree. It takes an optional arg for the width of the minipage, and a
%   mandatory arg for the content. It typesets the minipage in raggedright,
%   to override this include whatever setting you like in your content. A
%   label is required, even if it's empty. 
% \item Use |\taxFirst| for the first sub-entry. If this is a subtree it
%   should contain only a |taxon| environment, but if it's just text you
%   don't need any additional markup. So: either
%   |\taxFirst{\begin{taxon}(subtree)\end{taxon}}| or |\taxFirst{text}|.
% \item Use |\taxMid| for all entries after the first and before the last.
%   Even when you have only two entries, it's sometimes useful to put an
%   empty |\taxMid{}| in for spacing. Same rules apply as for |\taxFirst|:
%   subtries contain \emph{only} a |taxon| environment, text entries are
%   just text.
% \item Use |taxLast| for the last entry, with the same rules as for the
%   other two.
% \end{itemize}
%
% All three subtree macros take an optional vertical alignment arg, which
% can be |[t]|, |[m]| or |[b]|. By default they will be aligned so that the
% brace exactly covers them, with the subtree rooted at the outside of the
% brace (that is, top line for |\taxFirst| and bottom line for
% |\taxLast|). For long labels this can look a bit daft, but unfortunately
% altering the alignment of the subtree will necessarily make the labels
% poke out outside the surrounding braces --- this is unavoidable given the
% approach taken here. Check out the example to see this in action.
%
% \section{Bugs and warnings}
%
% A |\taxLabel| is required, even if it's empty. Required. As in, it won't
% work without one.
% 
% The tree will spread to stop anything bumping into its immediate
% children, but \emph{not} necessarily its grandchildren or nieces and
% nephews. (This is pretty much unavoidable; the spacing works by
% forgetting the extra height contributed by the deeper reaches of the
% tree, and once it's forgotten it's gone for ever.) So you'll sometimes
% have to add space by hand --- especially to stop the top edge of the tree
% bumping into material completely outside the taxonomy.
% 
% The spacing will go haywire if you don't nest and order your |taxon|
% environments and label/first/mid/last macros correctly. That's the first
% thing to check, if it looks odd.
%
% Horizontal alignment between text-only and subtree entries isn't
% perfect. I can't see why at the moment, and to be honest I can't be
% bothered figuring it out.
%
% This is a dirty dirty hack, and I can't see any way to make it much
% prettier. Don't expect much from it.
%
% There's an example on the next page, shifted so that it will show up in
% landscape view.
%
% \clearpage
%
% \section{An Example}
%
% This is rewritten from an example taxonomy by the person who originally
% asked how to do this. I've added empty |\taxMid| entries in a few places
% for clarity, and altered the alignment for a couple of entries to let you
% see how that looks. (``Generalissimis'' and ``Aliquid'' are given |[m]|
% alignment; not much else would really make any sense.) You'll probably
% need to view the page in landscape to see the whole taxonomy.
%
% The horizontal line shows where the taxonomy thinks its top edge is; I've
% moved it down so it doesn't collide with this text.
%
% \vspace{.5in}
% \hrule
%
%\begin{taxon}
%  \taxLabel{
%    \emph{Metaphysic{\ae}} (qu{\ae} est GREEK, quatenus
%    ab homine naturali rationis lumine sine ullo materi{\ae} conceptu est
%    intelligibile.) partes sunt du{\ae}; Altera
%  }
%  \taxFirst{
%    \begin{taxon}
%      \taxLabel{
%        \emph{Vniversalis}, qu{\ae} c\~osistit in
%        Intelligibilium \& Entium t\`um
%      }
%      \taxFirst[m]{
%        \begin{taxon}
%          \taxLabel{
%            \emph{Generalissimis} distributionibus.
%            \emph{Intelligibilis} autem notetur.
%          }
%          \taxFirst{
%            {\greektext l'ogos}: \emph{Intelligibile}
%            dicitur omne, quod intellectu percipi ac compreh\~edi
%            potest.
%          }
%          \taxLast{
%            \begin{taxon}
%              \taxLabel{ 
%                \emph{Distributio}: Intelligibile est vel 
%              }
%              \taxFirst{
%                \emph{Nihil}: hoc simpliciter non est aliquid.
%              }
%              \taxMid{}
%              \taxLast[m]{
%                \begin{taxon}
%                  \taxLabel{
%                    \emph{Aliquid}: quodsimpliciter non est nihil.  Estq* vel
%                  }
%                  \taxFirst{
%                    \begin{taxon}
%                      \taxLabel{
%                        \emph{Positivum}, quod ponit seu
%                        affirmat quidpiam. Estq* vel
%                      }
%                      \taxFirst{
%                        \emph{Essentia}. Vide A.
%                      }
%                      \taxMid{}
%                      \taxLast{
%                        \emph{Ens}. Vide B.
%                      }
%                    \end{taxon}
%                  }
%                  \taxMid{}
%                  \taxLast{
%                    \emph{Negativ\~u}. Vide RRR.
%                  }
%                \end{taxon}
%              }
%            \end{taxon}
%          }
%        \end{taxon}
%      }
%      \taxLast{
%        \emph{Communissimis} attributis. Vide 
%      }
%    \end{taxon}
%  }
%  \taxLast{
%    \emph{Particularis}.  Vide EE.
%  }
%\end{taxon}
%
% \clearpage
%
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{Implementation}
%
% You probably don't want to read this. It's dirty hackery and most likely
% won't help you use the package better. It \emph{certainly} won't teach
% you anything useful about \LaTeX.
%
% The plan is this: typesetting the \emph{first} entry of a taxonomy we
% forget the height of the box, typesetting the \emph{last} entry we forget
% the depth. We typeset the material in a cases-like environment
% regardless, then we add a zero-width vertical of the correct height,
% outside the cases braces.
%
% We're going to keep track of heights and depths separately (it's
% profligate, I know):
%    \begin{macrocode}
\newdimen\tax@ht
\newdimen\tax@dp
\newdimen\tax@local@ht
\newdimen\tax@local@dp
\tax@ht=0pt
\tax@dp=0pt
%    \end{macrocode}
%
% We're also going to use a vertical alignment macro (user-specifiable if
% they really want to play silly-buggers):
%    \begin{macrocode}
\newcommand{\taxAlign}{m}
%    \end{macrocode}
%
% The |taxon| environment doesn't do much to start with, that's mostly
% handled by |\taxLabel| and |\taxFirst|. Closing down it resets the height
% and depth variables, which will have been messed with globalled by the
% subtree.
%    \begin{macrocode} 
\newenvironment{taxon}{
  \begin{math}
}{
  \endarray
  \right.
  \vrule height\tax@ht depth\tax@dp width 0pt \relax
  \global\tax@ht=\tax@local@ht
  \global\tax@dp=\tax@local@dp
  \end{math}
}
%    \end{macrocode}
%
% The setup for the cases-like braces is actually done by the |\taxLabel|,
% which is \emph{not} a good idea but is close enough for government work.
% The braces definition is ripped out of the |amsmath| package, since a
% full |cases| environment does stuff we don't want with the spacing.
%
%    \begin{macrocode}
\newcommand{\taxLabel}[2][3cm]{%
  \begin{minipage}[\taxAlign]{#1}
    \raggedright #2
  \end{minipage}%
  \tax@local@ht=\tax@ht
  \tax@local@dp=\tax@dp
  \global\tax@ht=0pt
  \global\tax@dp=0pt
  \left\lbrace
  \array{@{}l@{}}
}
%    \end{macrocode}
%
% The |\taxFirst| definition throws the material into a box, remembers the
% height and depth of the box, then smashes the height and typesets it. The
% height and depth are stored globally, because each cell of an array is a
% separate group; we can't use group nesting to restore the correct value
% except at the outermost level of the |taxon| environment.
%    \begin{macrocode}
\newcommand{\taxFirst}[2][t]{%
  \def\taxAlign{#1}%
  \setbox0\hbox{#2}%
  \global\advance\tax@ht by \ht0\relax
  \global\advance\tax@dp by \dp0\relax
  \ht0=0pt \box0\relax\\
}
%    \end{macrocode}
%
% The |\taxMid| definition is very slightly simpler, since it doesn't need
% to mess with the size of the box coming out.
%
%    \begin{macrocode}
\newcommand{\taxMid}[2][m]{%
  \def\taxAlign{#1}%
  \setbox0\hbox{\tabular{@{}l@{}}#2\endtabular}%
  \global\advance\tax@ht by \ht0\relax
  \global\advance\tax@dp by \dp0\relax
  \box0\relax\\                            
}
%    \end{macrocode}
%
% And |\taxLast| looks just like you'd expect by now.
%
%    \begin{macrocode}
\newcommand{\taxLast}[2][b]{%
  \def\taxAlign{#1}%
  \setbox0\hbox{#2}% 
  \global\advance\tax@ht by \ht0\relax
  \global\advance\tax@dp by \dp0\relax
  \dp0=0pt \box0\relax\\
}
%    \end{macrocode}
%
% That's all, folks. Ugly, ain't it?
%
% \Finale
\endinput