summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/easylist/easylist-doc.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2008-11-17 01:22:36 +0000
committerKarl Berry <karl@freefriends.org>2008-11-17 01:22:36 +0000
commit7501fa1170fbcbcbaad8364cc865a056a9aa90c0 (patch)
tree2681f29f09177b0e38437d6d7d82dd733ee1c6b5 /Master/texmf-dist/doc/latex/easylist/easylist-doc.tex
parent9b28381167cbb008caf200df2868564c4d454c66 (diff)
new package easylist (16nov08)
git-svn-id: svn://tug.org/texlive/trunk@11311 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/easylist/easylist-doc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/easylist/easylist-doc.tex289
1 files changed, 289 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/easylist/easylist-doc.tex b/Master/texmf-dist/doc/latex/easylist/easylist-doc.tex
new file mode 100644
index 00000000000..3af56faa9ce
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/easylist/easylist-doc.tex
@@ -0,0 +1,289 @@
+\documentclass[a4paper]{article}
+
+\usepackage{easylist}
+\usepackage[T1]{fontenc}
+\usepackage[textwidth=16cm,textheight=24cm]{geometry}
+\usepackage{xcolor}
+
+\title{\Exemple{12}{\bfseries The \texttt{easylist} package for numbered items}}
+\author{Paul Isambert\\ \texttt{zappathustra@free.fr}\\ \texttt{http://paulisambert.free.fr}}
+
+\newcommand{\vs}{\vspace{1ex}}
+
+\newlength{\marginlength}
+\newcommand{\Note}[2]{\settowidth{\marginlength}{\texttt{#1}}\marginpar{\fboxrule1pt\vspace{-2.2ex}\raggedleft\fcolorbox{black}{gray!50!white!90!red}{\parbox{\marginlength}{\raggedleft\ttfamily #2}}}\fboxrule.4pt}
+\reversemarginpar
+
+\definecolor{Exemple}{rgb}{1,1,.8}
+\definecolor{Frame}{rgb}{1,.3,.3}
+
+\newcommand{\Code}[2]{%
+\vs\begin{center}
+\noindent\fboxrule1pt\fcolorbox{Frame}{Exemple}{\begin{minipage}{#1cm}\ttfamily\noindent$\backslash$begin\{eList\}\\#2$\backslash$end\{eList\}
+\end{minipage}}\end{center}\fboxrule.4pt}
+
+\newcommand{\Exemple}[2]{%
+\vs\begin{center}
+\noindent\fboxrule1pt\fcolorbox{Frame}{Exemple}{\begin{minipage}{#1cm}#2\end{minipage}}\end{center}\fboxrule.4pt}
+
+\let\NormalFont\normalfont
+\let\ssection\section
+\renewcommand{\section}[1]{\let\normalfont\sffamily\ssection{#1}\let\normalfont\NormalFont}
+
+
+\begin{document}
+
+\maketitle
+\begin{abstract}This package is designed for typesetting lists of numbered items (like Wittgenstein's \textit{Tractatus} or--more likely--the outline of a work yet to be done) with a single active character acting as the only command. Various options are available to achieve greater control over the general appearance of the list.\end{abstract}
+
+\section{Choosing the symbol}
+Here's what the \LaTeX\ code with \verb+easylist+ in its default usage looks like:
+
+\Code{12}{
+\S\ First proposition.\\
+\S\S\ Interesting comment.\\
+\S\S\S\ A note on the comment.\\
+\S\S\S\ Another note.\\
+\S\S\S\S\ By the way...\\
+\S\S\S\S\S\ This is a subsub...-proposition.\\
+\S\ Let's start something new...\\}
+
+\vs
+\noindent And it yields:
+
+\Activate\Exemple{8}{
+\begin{eList}
+§ First proposition.
+§§ Interesting comment.
+§§§ A note on the comment.
+§§§ Another note.
+§§§§ By the way...
+§§§§§ This is a subsub...-proposition.
+§ Let's start something new...
+\end{eList}}\Deactivate
+
+\vs
+Now, the section sign \S\ might not be readily accessible on some (most?) keyboards (although it is accessible and useless on French ones). So you can choose another one instead by setting an option when calling the package (\S\ is default):
+
+\Exemple{8}{\ttfamily$\backslash$usepackage[pilcrow]{easylist} \rmfamily to use \textparagraph.\\
+\ttfamily$\backslash$usepackage[at]{easylist} \rmfamily to use \ttfamily @.\\
+\ttfamily$\backslash$usepackage[sharp]{easylist} \rmfamily to use \ttfamily \#.\\
+\ttfamily$\backslash$usepackage[ampersand]{easylist} \rmfamily to use \ttfamily \&.}
+
+\vs
+The selected character is made active between \verb+\begin{eList}+ and \verb+\end{eList}+ and then returns to its initial value. So when using \verb+#+ for instance, just make sure to define new commands outside the \verb+eList+, or use the \verb+\Activate+ and \verb+\Deactivate+ commands in your list (see below), and everything will be right. (Ending a list and then beginning a new one will not be noticeable in the final product, so you can interrupt your list to create a new command.) In what follows, I will be using \S, but everything applies to other symbols too.\footnote{You might not be happy with the symbols and maybe you'd like to use another one, or simply have your favorite symbol as default to avoid remembering such a cumbersome name as `pilcrow'. Here's a simple hack that does the job: select the entire code of the package, and replace all occurrences of \S\ with your symbol. Make sure you won't use it in the list for other purposes, though.}
+
+\section{Usage}
+The example above says it all, so let's repeat it for clarity's sake:
+
+\Code{8}{
+\S\ First proposition.\\
+\S\S\ Interesting comment.\\
+\S\S\S\ A note on the comment.\\
+\S\S\S\ Another note.\\
+\S\S\S\S\ By the way...\\
+\S\S\S\S\S\ This is a subsub...-proposition.\\
+\S\ Let's start something new...\\}
+
+\vs
+\noindent Your list must be enclosed between \verb+\begin{eList}+ and \verb+\end{eList}+, which is welcome since a character is made active and active characters are notoriously dangerous. As you might have guessed, one \S\ creates a proposition of the first level, two \S's make a proposition of the second level, and so on down to the fifth level. If you concatenate more than five \S's, you'll get an error and the problematic line will begin with \fbox{!!!} instead of numbers. Every sequence of \S's must terminate with a space, otherwise numbers won't be printed.
+
+Two things are worth mentioning. First, note that \S\ automatically creates a new line, so typing your propositions in a row will not affect the result. Hence
+
+\Exemple{14}{\ttfamily$\backslash$begin\{eList\} \S\ First proposition. \S\S\ Interesting comment. $\backslash$end\{eList\}}
+
+\vs
+\noindent still yieds
+
+\Activate\Exemple{8}{
+\ListProperties(Start1=1)\begin{eList} § First proposition. §§ Interesting comment. \end{eList}}\Deactivate
+
+\vs
+Second, when skipping one or more level(s), that(those) level(s) will be numbered 0 (except otherwise specified--see below), as in:
+
+\Code{8}{\S\ First proposition.\\
+\S\S\S\ A sub-comment to the first proposition.\\}
+
+
+\vs
+\noindent which yields:
+
+\Activate\Exemple{8}{\ListProperties(Start1=1)
+\begin{eList}
+§ First proposition.
+§§§ A sub-comment to the first proposition.
+\end{eList}}\Deactivate
+
+\vs
+That's it. The following sections deal with labelling and referring and layout options, but for basic purpose you don't need more than that.
+
+\section{Referring to an item}
+It may be useful to refer to a previous item, so \verb+easylist+ includes a labelling device (note that it's not possible to refer to a \emph{subsequent} item--maybe in a later version?). The command is \verb+\Llabel{key}+ (with two l's on purpose to avoid possible conflicts with packages also allowing labelling) and works exactly like \LaTeX's \verb+\label+ command. It may be issued anywhere in the proposition, but if you type it between the sequence of \S's and your text, make sure to leave a space after the \S's. \verb+\Lref{key}+ and \verb+\Pref{key}+ are the corresponding referring commands, and they work just like \verb+\ref+ and \verb+\pageref+, i.e. the former yields the number of the proposition and the latter the page where it appears.\footnote{More precisely, $\backslash$\texttt{Pref} refers to the page where the proposition starts, even when the corresponding $\backslash$\texttt{Llabel} is at the end of the proposition and possibly on the following page in the final output. So if you want to refer to some part of your proposition, use $\backslash$\texttt{label} and $\backslash$\texttt{pageref} instead.}
+
+\section{Options}
+Several parameters are available to achieve fine control over the final output. The general command is \verb+\ListProperties(key=value,key=value...)+, where \verb+key+ is a parameter. Depending on where the command is called, it will have different scopes. If you call it inside an \verb+eList+, it will be active for that list only, and in that list for items that follow it. Outside the \verb+eList+, the parameters will affect all subsequent lists, unless specified otherwise (the parameter \verb+Start+--see below--always works in this way, since it affects numbering). Let's review them in turn and indicate the default values.
+
+\vs
+This parameter \Note{Start5}{Start1\\Start2\\Start3\\Start4\\Start5}sets the starting value of one of the five levels. Consecutive items (even in different lists) are normally consecutively numbered, but you may skip a value for whatever reason, for instance creating this document with all examples starting at 1, or avoiding the 0 mentionned above. Note that, for any given level, this command will work if and only if it is issued just before an item containing this level, as exemplified by:
+
+\Code{8}{%
+$\backslash$ListProperties(Start1=1,Start2=17)\\
+\S\ First proposition.\\
+\S\ Second proposition.\\
+\S\S\ Numbering doesn't work.\\
+$\backslash$ListProperties(Start2=17)\\
+\S\S\ This is better.\\}
+
+\vs
+\noindent which yields:
+
+\Activate\Exemple{8}{
+\begin{eList}
+\ListProperties(Start1=1,Start2=17)
+§ First proposition.
+§ Second proposition.
+§§ Numbering doesn't work.
+\ListProperties(Start2=17)
+§§ This is better.
+\end{eList}}\Deactivate
+
+\vs
+\noindent This makes sense since every counter is set back to 1 when the one above it is incremented. The default value is of course 1.
+
+\vs
+This parameter \Note{FinalMark}{Mark1\\Mark2\\Mark3\\Mark4\\FinalMark\\Mark}controls the punctuation mark that follows the first, second... final number respectively. There is no \verb+Mark5+, since the fifth number is always followed by the final mark (which is the mark that follows the final number, not simply the \emph{fifth} number; the final mark always supersedes the first or second... mark in case they are the same). \verb+Mark+ sets all marks together. Note that the general rule for this parameter and the following ones is `Last wins', i.e. \verb+\ListProperties(Mark=.,FinalMark=)+ yields a stop after each number except the final one, which will be followed by nothing, while on the other hand \verb+\ListProperties(FinalMark=,Mark=.)+ will produce a stop for all numbers including the final one, since \verb+FinalMark+ has been superseded by \verb+Mark+ (by the way notice that a missing value, i.e. the `$=$' sign followed by a comma or the closing parenthesis, is acceptable and understood as a null value).
+
+If you want one of the mark to be a comma, you have to enclose it between curly braces as in \verb+\ListProperties(Mark1={,})+, since commas are also used to delimit parameters in this command. \verb+FinalMark+ may also be used to add some space before the text, as in\\ \verb+\ListProperties(FinalMark=.\hspace{1ex})+.
+
+The default value for these parameters is a full stop.
+
+\vs
+This parameter \Note{Numbers5}{Numbers1\\Numbers2\\Numbers3\\Numbers4\\Numbers5\\Numbers}sets the way numbers are printed. It takes the following values:
+
+\Exemple{8}{
+\texttt{r} for lower case roman numerals;\\
+\texttt{R} for upper case roman numerals;\\
+\texttt{l} for lower case letters;\\
+\texttt{L} for upper case letters;\\
+anything else for arabic numbers, which are the default value.}
+
+Note that if you choose letters for a given counter, it should not exceed 26, or \TeX\ will complain--and you'll have no number at all. Since I think that using letters with more than, say, 10 items, is ill-advised, I didn't overcome that limitation.
+
+
+\vs
+This is \Note{Style5}{Style1\\Style2\\Style3\\Style4\\Style5\\Style}used to set the style of the propositions of the first, second... levels, with \verb+Style+ specifying all the styles at once. Here you may use values such as \verb+\large+, \verb+\bfseries+... and so on. If you add a star to the name of the parameter, as in \verb+Style3*+ or \verb+Style*+, only the numbers will be affected, as in:
+
+\Code{9.4}{
+$\backslash$ListProperties(Style1*=$\backslash$bfseries,Style2*=$\backslash$itshape)\\
+\S\ A fundamental proposition.\\
+\S\S\ An essential comment.\\}
+
+\vs
+\noindent which produces:
+
+\Activate\Exemple{8}{%
+\begin{eList}
+\ListProperties(Style1*=\bfseries,Style2*=\itshape,Start1=1)
+§ A fundamental proposition.
+§§ An essential comment.
+\end{eList}}\Deactivate
+
+\vs
+With two stars, as in \verb+Style2**+ or \verb+Style**+, only the text of the item will be affected. The default value for this parameter is \verb+\normalsize+, \verb+\upshape+, \verb+\rmfamily+ and \verb+\mdseries+, and \emph{not} the style you might have set at the beginning of your document. So for instance if you're writing with sans-serif and include an \verb+eList+ in your document, it will be typeset in roman, unless you specify \verb+\ListProperties(Style=\sffamily)+. This default style is accessible with \verb+\NormalStyle+, so you may redefine the latter at the beginning of your document to match your needs.
+
+\vs
+This parameter \Note{Margin5}{Margin1\\Margin2\\Margin3\\Margin4\\Margin5\\Margin}sets the distance from the left margin at which the concerned propositions should start. Once again, \verb+Margin+ sets all the parameters at once. So you can have a clearly designed list, as in:
+
+\Code{12}{$\backslash$ListProperties(Margin2=3ex,Margin3=6ex,Margin4=9ex,Margin5=12ex)\\
+\S\ First proposition.\\
+\S\S\ Interesting comment.\\
+\S\S\S\ A note on the comment.\\
+\S\S\S\ Another note.$\backslash\backslash$ \textit{\textrm{\textcolor{red}{(Those backslashes are part of the code! See below.)}}}\\
+This is fascinating. We can start a new paragraph at any level.\\
+\S\S\S\S\ By the way...\\
+\S\S\S\S\S\ This is a subsub...-proposition.\\
+\S\ Let's start something new...\\}
+
+\vs
+\noindent and we have:
+
+\Activate\Exemple{12}{%
+\begin{eList}
+\ListProperties(Start1=1,Margin2=3ex,Margin3=6ex,Margin4=9ex,Margin5=12ex)
+§ First proposition.
+§§ Interesting comment.
+§§§ A note on the comment.
+§§§ Another note.\\
+This is fascinating. We can start a new paragraph at any level.
+§§§§ By the way...
+§§§§§ This is a subsub...-proposition.
+§ Let's start something new...
+\end{eList}}\Deactivate
+
+\vs
+Your items may be made of paragraphs, but if you want them to be properly aligned, you should use \verb+\\+ or \verb+\newline+ instead of a blank line to create a new paragraph, or you'll get unwanted results.
+
+The default value for this parameter is no distance at all from the margin.
+
+\vs
+This is used \Note{Indent5}{Indent1\\Indent2\\Indent3\\Indent4\\Indent5\\Indent}to control the indentation of your items from their left justification. It is meant to receive commands such as \verb+\indent+, \verb+\noindent+, \verb+\hspace{5mm}+, etc, but not simply \verb+5mm+, for instance, as with \verb+Margin+. The default value is \verb+\noindent+.
+
+\vs\vs\vs\vs\vs
+\section{\sffamily Troubles with boxes}
+Active characters, as is well known, are nasty beings, and it's hard to keep them activated all the way down. That's why the \verb+eList+ environment in its present state won't work in boxes. That is
+
+\Exemple{8}{\ttfamily
+$\backslash$fbox\{\%\\
+$\backslash$begin\{eList\}\\
+\S\ First proposition.\\
+$\backslash$end\{eList\}\}}
+
+\vs
+\noindent will print:
+
+\Exemple{8}{\fboxrule.4pt\fbox{\begin{eList}§ First proposition.\end{eList}}}
+
+\vs
+\noindent where § is the normal value of \S. Lists in boxes aren't that common (except for this document), but such a limitation is always annoying. So here are two solutions\footnote{The first one is due to Enrico Gregorio on the \texttt{comp.text.tex} user group.} (in a later version I will hopefully overcome the problem). First, you can save your code in a \verb+\lrbox+ and then issue it as wanted:
+
+\Exemple{8.1}{\ttfamily%
+$\backslash$newsavebox\{$\backslash$mybox\} {\rmfamily\itshape\textcolor{red}{(This can be done anywhere.)}}\\
+$\backslash$begin\{lrbox\}\{$\backslash$mybox\}\\
+$\backslash$begin\{eList\}\\
+\S\ First proposition.\\
+$\backslash$end\{eList\}\\
+$\backslash$end\{lrbox\}\\
+$\backslash$fbox\{$\backslash$usebox\{$\backslash$mybox\}\}}
+
+\vs
+Once the content of your box has become useless you can reuse \verb+\mybox+ with a new content. The following technique is faster (but also more dangerous if you're not careful). What you have to do is to make active the character you've chosen to create items just before the box and then turn it back to its initial value. For that purpose, \verb+easylist+ has the two commands \verb+\Activate+ and \verb+\Deactivate+. So here's what you'll do:
+
+\Exemple{8}{\ttfamily
+$\backslash$Activate\\
+$\backslash$fbox\{\%\\
+$\backslash$begin\{eList\}\\
+\S\ First proposition.\\
+$\backslash$end\{eList\}\}\\
+$\backslash$Deactivate}
+
+\vs
+\noindent and you'll get:
+
+\ListProperties(Start1=1)\Activate\Exemple{8}{\fboxrule.4pt\fbox{\begin{eList}§ First proposition.\end{eList}}}\Deactivate
+
+\vs
+Unfortunately, this has to be issued for every box. That is, the following code won't work (even if you surround your command definition with \verb+\Activate+ and \verb+\Deactivate+--I told you that active characters were nasty):
+
+\Exemple{10}{\ttfamily
+$\backslash$newcommand\{$\backslash$myfbox\}[1]\{$\backslash$Activate$\backslash$fbox\{\#1\}$\backslash$Deactivate\}\\
+$\backslash$myfbox\{\%\\
+$\backslash$begin\{eList\}\\
+\S\ First proposition.\\
+$\backslash$end\{eList\}\}
+}
+
+\vs
+\noindent The same impossibility arises with the previous solution, so choose your favorite or avoid boxes!
+
+\end{document}
+