summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/titlesec/titlesec.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-12-17 00:59:21 +0000
committerKarl Berry <karl@freefriends.org>2011-12-17 00:59:21 +0000
commitbb697854fb4e6eca8595e8c660b3a8aaffa47b06 (patch)
treefe48672d2ddf634c75efa2c4e9d5a7ffc4b67a52 /Master/texmf-dist/doc/latex/titlesec/titlesec.tex
parentb85dc708bbe89bd54f2e998e166032f5d35a7e6a (diff)
titlesec/titleps 1.1.0 (15dec11)
git-svn-id: svn://tug.org/texlive/trunk@24852 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/titlesec/titlesec.tex')
-rw-r--r--Master/texmf-dist/doc/latex/titlesec/titlesec.tex403
1 files changed, 42 insertions, 361 deletions
diff --git a/Master/texmf-dist/doc/latex/titlesec/titlesec.tex b/Master/texmf-dist/doc/latex/titlesec/titlesec.tex
index 29d2a6ef517..463ae8e711e 100644
--- a/Master/texmf-dist/doc/latex/titlesec/titlesec.tex
+++ b/Master/texmf-dist/doc/latex/titlesec/titlesec.tex
@@ -5,7 +5,7 @@
% Copyright (c) 1998-2011 by Javier Bezos.
% All Rights Reserved.
%
-% This file is part of the titlesec distribution release 2.9.2
+% This file is part of the titlesec distribution release 2.10.0
% -----------------------------------------------------------
%
% It may be distributed and/or modified under the
@@ -20,8 +20,8 @@
%
% The Current Maintainer of this work is Javier Bezos.
-\def\fileversion{2.9.2}
-\def\docdate{2011-11-17}
+\def\fileversion{2.10.0}
+\def\docdate{2011-12-15}
\documentclass[a4paper]{ltxguide}
\usepackage[sf,bf,compact,topmarks,calcwidth,pagestyles]{titlesec}
@@ -43,10 +43,10 @@
\title{The \textsf{titlesec}, \textsf{titleps} and \textsf{titletoc}
Packages\footnote{The \textsf{titlesec} package is currently at
-version 2.9.2. \copyright{} 1998--2011 Javier Bezos.
+version 2.10.0. \copyright{} 1998--2011 Javier Bezos.
The \textsf{titletoc} package is currently at
version 1.6. The \textsf{titleps} package is currently at version
-1.0. \copyright{} 1999--2011 Javier Bezos. All Rights
+1.1.0 \copyright{} 1999--2011 Javier Bezos. All Rights
Reserved.}}
\author{Javier Bezos\footnote{For bug reports, comments and
@@ -55,7 +55,7 @@ suggestions go to \href{http://www.tex-tipografia.com/contact.html}%
is not my strong point, so contact me when you find mistakes in the
manual. Other packages by the same author: \textsf{gloss} (with
Jos\'e Luis D\'{\i}az), \textsf{enumitem, accents, tensind, esindex,
-dotlessi}.}}
+dotlessi, babeltools}.}}
\date{\docdate}
@@ -113,7 +113,9 @@ contents. The goal is to provide new features unavailable in current
standard \LaTeX{} but without changing the way \LaTeX{} works you may
consider using \textsf{fancyhdr}, by Piet van Oostrum, \textsf{sectsty},
by Rowland McDonnell, and \textsf{tocloft}, by Peter Wilson, which you
-can make pretty things with.
+can make pretty things with.\footnote{Since the sectioning commands
+are rewritten, their behaviour could be somewhat different
+in some cases.}
Some of the new features provided are:
\begin{itemize}
@@ -1025,370 +1027,49 @@ underlining), you can say:
However, you might prefer the package option \texttt{explicit}.
-\section{Page Styles}
+\section{\textsf{titleps} and Page Styles}
%~~~~~~~~~~~~~~~~~~~
-As a part of this package a set of commands are provided for one-step
-headline and footline settings. Those page styles has been designed to work
-with sectioning related information; you shouldn't use to create
-headers with the first an last entry of a page in a dictionary,
-for example (you could, but it is more complicated than with
-\textsf{fancyhdr}). Most of these features (but not all) are also
-available as a separate package named \texttt{titleps} -- see below
-for further details.
-
-It works with standard classes and many others; however, additional
-\LaTeX{} layout
-adjustments could be necessary in some of them (for instance the
-\textsc{AMS} classes).\footnote{%
-Two columns layout requires the
-\textsf{fix2col} package by David Carlisle.} For using them,
-set the following package option:\footnote{The
-way page styles works was reimplemented in full in release 2.3.
-However, in most of cases you won't notice it at all.}
-\begin{desc}
-|pagestyles|
-\end{desc}
-
-Once this has been done, you can define your own page styles
-and then activate them.\footnote{Page styles so defined cannot
-be used with \texttt{\string\thispagestyle} except if the surrounding
-page style has been defined with \textsf{titlesec}, too.}
-
-\subsection{Defining Page Styles}
-
-\begin{desc}
-|\newpagestyle{<name>}[<global-style>]{<commands>}|\\
-|\renewpagestyle{<name>}[<global-style>]{<commands>}|
-\end{desc}
-
-Defines a new style or redefines an existing one, named |<name>|.
-For convenience, end of lines are ignored, and you need not ``hide''
-them with |%|.\footnote{Even if marks should be reserved to
-pass information to headers, some classes, like AMS ones, introduce additional
-code. When redefining the |plain| style of AMS classes, you must add the
-following line:
-|\cs{global}\cs{topskip}\cs{normaltopskip}|.}
-
-|<global-style>| is any command to be applied to both footlines and
-headlines. Fragile commands are allowed.
-
-In |<commands>| you can use
-
-\begin{desc}
-|\headrule \footrule|\\
-|\setheadrule{<length>} \setfootrule{<length>}|
-\end{desc}
-
-If you want a rule below the headline and above the footline. You may
-also set their width directly with the commands |\setheadrule| and
-|\setfootrule|. (For instance, |\setheadrule{.4pt}| which is, by the
-way, the default value.)
-
-These commands are local to a page
-style, i.e., defining them directly in the preamble will
-not work because the page style settings will override them.
-
-\begin{desc}
-|\makeheadrule \makefootrule|
-\end{desc}
-
-These commands are used by \textsf{titlesec} to typeset the rules.
-If there is no rule, both commands are empty (this value is the
-default).
-|\setheadrule{|\emph{dim}|}| just stands for
-\begin{verbatim}
-\renewcommand{\makeheadrule}{\rule[-.3\baselineskip]{\linewidth}{<dim>}}
-\end{verbatim}
-unless if \emph{dim} is 0 pt, which empties
-|\makeheadrule| (and similarly |\setfootrule|).
-
-You can access the total head/foot width with |\linewidth|
-but the box enclosing the rule is in fact dimensionless. Hence,
-you must be concerned with the rule placement only. Its
-baseline is the same as that of the head/foot. That means the
-material to be used as rule should be raised or lowered with
-|\raisebox|, the lifting argument in |\rule| or by using sensible
-coordinates in |picture|, for instance. That makes easy to
-place material above \emph{and} below. For instance,
-the following code creates a headline with a black bold line
-above and a red rule below (the \textsf{color} package is required):
-\begin{verbatim}
-\renewcommand{\makeheadrule}{%
- \makebox[0pt][l]{\rule[.7\baselineskip]{\linewidth}{0.8pt}}%
- \color[named]{Red}%
- \rule[-.3\baselineskip]{\linewidth}{0.4pt}}
-\end{verbatim}
-
-Of course, the material to be used
-as rule is not restricted to actual rules; pictures and leaders, for
-instance, are allowed, too.
-
-\begin{desc}
-|\sethead[<even-left>][<even-center>][<even-right>]|\\
-| {<odd-left>}{<odd-center>}{<odd-right>}|\\
-|\setfoot[<even-left>][<even-center>][<even-right>]|\\
-| {<odd-left>}{<odd-center>}{<odd-right>}|
-\end{desc}
-
-Set the corresponding part in heads and foots. The optional arguments
-are all or none. If no optional arguments are given the odd-page
-settings applies to both even and odd pages. A couple of starred
-variant (|\setfoot*|, |\sethead*|) reverses the order of the settings
-for even pages (obviously, with them the optional arguments are
-not allowed). In the arguments of |\sethead|/|\setfoot| and because
-of its one-step mechanism, we must distinguish between two groups of
-commands. The first one includes those saved when the marks are sent, with
-information related to sections, and includes:
-\begin{itemize}
-\item |\thechapter|, |\thesection|\dots{}
-\item |\chaptertitle|, |\sectiontitle|\dots{} which print the
-chapter,
-section\dots{} title.
-\item |\ifthechapter{<true>}{<false>}|,
- |\ifthesection{<true>}{<false>}|\dots{} which expands to |<true>|
- except if the corresponding title lacks of label or there is
- no title yet after the superior level (for example, between
- |\chapter| and a subsequent |\section|).
-\item Any other command or value ``registered'' as ``mark.'' (See below.)
-\end{itemize}
-The second group are those expanded in every page, and includes:
-\begin{itemize}
-\item |\thepage|.
-\item Any other command not included in the previous items.
-\end{itemize}
-
-\begin{desc}
-|\setmarks{<primary>}{<secondary>}|
-\end{desc}
-Sets which |\...title| commands are to be defined, and when the marks
-are updated. For example
-|\setmarks{chapter}{section}|
-means that:
-\begin{itemize}
-\item |\chaptertitle| and |\sectiontitle| are the allowed titles in
- heads,
-\item |\sectiontitle| is reset in |\chapter|,
-\item |\ifthechapter| and |\ifthesection| are valid tests, and
-\item Marks are updated in |\chapter| and |\section|.
-\end{itemize}
-By default it is
-|\setmarks{chapter}{section}| but |\setmarks{section}{subsection}| in
-\textsf{article} class. |\setmarks| may be used outside |\(re)newpagestyle|
-to set the default to be used in newly defined and redefined page styles.
-Use it before |\pagestyle|.
-
-Note |\markboth| is a command to set the |myheadings| marks and
-here does not make sense. In fact, using it can lead to unpredictable
-results. Anyway, using directly the marking commands is discouraged
-(see sec.~\ref{s:starred}) but if you need them, you may use them
-as in:
-\begin{verbatim}
-\chapter*{My Chapter}
-\chaptermark{My Chapter}
-\end{verbatim}
-
-\subsection{Additional Settings}
-
-\begin{desc}
-|\widenhead[<even-left>][<even-right>]{<odd-left>}{<odd-right>}|\\
-|\widenhead*{<even-right>/<odd-left>}{<even-left>/<odd-right>}|
-\end{desc}
-
-Makes the head/foot lines wider. The extra width is asymmetrically
-added and hence the two [four] arguments. Like |\sethead|, the
-starred version reverses the setting for even pages---for example,
-|\widenhead*{0pt}{6pc}| is the same as
-|\widenhead[6pc][0pt]{0pt}{6pc}|.
-
-\subsection{Running heads with floats}
-
-\begin{desc}
-|psfloats| \quad (Package option.)
-\end{desc}
-
-This package option activates the commands described in this section.%
-\footnote{It redefines some internal \LaTeX{} commands and there could be
-incompatibilities with other packages modifying the same commands. That's
-the very reason these commands are loaded only optionally. As of
-version 2.6 the syntax was extended with a new argument to allow
-extra stuff in running heads/foots. This change was backward
-compatible---just preserve the old name \verb|floatps|, which
-is deprecated, if you want the pre-2.6 behaviour.}
-
-
-\begin{desc}
-|\setfloathead*{.}{.}{.}{<extra>}[<which-floats>]|\\
-|\setfloathead[.][.][.]{.}{.}{.}{<extra>}[<which-floats>]|\\
-(Similarly |\setfloatfoot|.)
-\end{desc}
-
-The arguments with a dot are similar to those of |\sethead|. The final
-argument says the head is used when there is a float of
-the specified types (default is |tp| in headers, and |bp| in footers).
-For example:
-\begin{verbatim}
-\newpagestyle{main}{%
- \sethead ... your definition
- \setfoot ... your definition
- \headrule
- \footrule
- \setfloathead{}{}{}{\setheadrule{0pt}}[p]
- \setfloatfoot{}{}{}{\setfootrule{0pt}}[p]}
-\end{verbatim}
-removes the header/footer on float pages, including the rules.
-
-\begin{desc}
-|\nextfloathead*{.}{.}{.}{<extra>}[<which-floats>]|\\
-|\nextfloathead[.][.][.]{.}{.}{.}{<extra>}[<which-floats>]|\\
-(Similarly |\nextfloatfoot|.)
-\end{desc}
-
-You may force a header (respectively footer) when a certain
-float is the first top one (respectively last bottom) with
-those commands, where the arguments with a dot are similar to
-those of |\sethead|, just before the corresponding float.
-Those commands are used by themselves, without putting them
-inside |\(re)newpagestyle|.
-
-\subsection{Marks}
-
-\begin{desc}
-|outermarks innermarks topmarks botmarks| \quad (Package options)
-\end{desc}
-
-|innermarks| is the default in \LaTeX, with bottom marks in even pages
-and first marks in odd pages. More convenient is |outermarks|, with
-top marks in even pages and bottom marks in odd pages; it is the more
-usual system in classic scientific literature and it is described in
-\textit{The \TeX{}book}, p.~259. Both of them are intended for two
-side printing; |topmarks|/|botmarks| are intended for one side
-printing with top/bot marks in every page (they can be used in two
-side printing as well).%
-\footnote{|outermarks| does not work well in conjunction with explicit
-|\string\<section>mark| commands. The top marks mechanism fails just
-after explicit page breaks.}
-
-\begin{desc}
-|\bottitlemarks \toptitlemarks \firsttitlemarks \nexttoptitlemark|\\
-|\outertitlemarks \innertitlemarks|
-\end{desc}
-
-One of the cooler features added to page styles is the possibility of
-selecting which marks are used in subsequent macros. These commands
-set which mark the values of |\thesection|, |\sectiontitle|,
-etc., will be taken from. You can use freely in your headers;\,%
-\footnote{Not exactly: top marks must not be used in the page where a
-chapter begins, except by overriding the default definition and making
-it of |top| class.} just for fun, the following header shows the
-section label from three of these marks:
-\begin{verbatim}
-\newpagestyle{funny}{
- \sethead{Top~is~\toptitlemarks\thesection}
- {First~is~\firsttitlemarks\thesection}
- {Bot~is~\bottitlemarks\thesection}}
-\end{verbatim}
-
-|\outertitlemarks| is the default value when the |outermarks| package
-option is set, |\toptitlemarks| when |topmarks| is set, and so on.
-|\innertitlemarks| is the default value in \LaTeX{} and in this
-package if none of those option is used. A further set of marks is
-provided with |\nexttoptitlemarks| which provides a bottom mark with
-the values of the top mark of the next page (straight class only); by
-picking some value from it and comparing with the corresponding value
-of the |\bottitlemarks| you may know if a section continues in the
-next page. Of course, these commands will not be used very often.
-
-\begin{desc}
-|\newtitlemark{<macro-name>}|\\
-|\newtitlemark*{<variable-name>}|
-\end{desc}
-
-Add a macro or a variable to the list of ``marks'' to be saved.
-The macro must be parameterless, and the variable should be in \TeX{}
-form (which is the same in lengths but not in counters---the latter
-take the form |\c@<counter>|).
-
-\subsection{A couple of examples}
-
-Because of the way marks are handled, special constructions like this are
-allowed:
-\begin{verbatim}
-\newpagestyle{main}[\small\sffamily]{
- \sethead [\textbf{\thepage}]
- [\textsl{\chaptertitle}]
- [[\toptitlemarks\thesection--\bottitlemarks\thesection]
- {\toptitlemarks\thesection--\bottitlemarks\thesection]}
- {\textsl{\sectiontitle}}
- {\textbf{\thepage}}}
-\end{verbatim}
-As you can see, the range of sections in a page |\thesection| is
-printed in both left and right heads.
-Of course, this example should be fine tuned to collapse the
-ranges if there is a single section in a page, but it gives
-a hint of how to get stunning headers.
-
-In this document, the following styles are used:
-\begin{verbatim}
-\widenhead{2.1pc}{0pc}
-\renewpagestyle{plain}[\small\sffamily\slshape]{
- \footrule
- \setfoot{}{\thepage}{}}
-\newpagestyle{myps}[\small\sffamily\slshape]{
- \headrule
- \sethead{Titlesec}{\sectiontitle}{\thepage}}
-\end{verbatim}
-
-The following definitions provide page styles similar to
-those of Lamport's \LaTeX\ book (with the \textsf{calc}
-package):
-\begin{verbatim}
-\widenhead*{0pt}{\marginparsep + \marginparwidth} % symmetrically
-\renewpagestyle{plain}{}
-\newpagestyle{latex}[\bfseries]{
- \headrule
- \sethead[\thepage][][\chaptertitle]
- {\thesection\ \sectiontitle}{}{\thepage}}
-\pagestyle{latex}
+The \textsf{titleps} package provides tools for one-stage setting of
+page styles (headlines and footlines). A higher-level interface is
+used, where the mark mechanism is hidden and there is no need to deal
+with |\leftmark|s and |\rightmark|s -- just use a command or variable
+registered as a ``mark'' as the expected value will be returned, i.e.,
+those when the mark was emitted, either by a sectioning command or
+explicitly with |\chaptermark|, |\sectionmark|, etc. A simple
+example, whose meaning should be obvious, is:
+\begin{verbatim}
+\newpagestyle{main}{
+ \sethead[\thepage][\chaptertitle][(\thesection] % even
+ {\thesection)}{\sectiontitle}{\thepage}} % odd
+\pagestyle{main}
\end{verbatim}
-\subsection{\textsf{titleps}}
-
-With this package you have access to most of the features described in
-this section without having to load \textsf{titlesec}. The following
-are not supported:
+Other features are:
\begin{itemize}
-\item top marks, and related options -- only first and bottom marks
-are allowed;
-\item |\ifthechapter|, |\ifthesection|, |\ifthesubsection|, etc.;
-\item being a new package, the deprecated option |floatps| is not
-available, but only |psfloats|.
+\item Working top marks, compatible with floats (unlike the standard
+|\topmark|, which does not work correctly in \LaTeX{}).
+\item Access to top, first and bot marks in a single headline/footline
+(e.g., the first and last section numbers).
+\item Marks for more than 2 sectioning levels.
+\item Simple (and not so simple) headrules and footrules.
+\item Headlines and footlines for pages with floats.
+\item Headlines and footlines for specific floats (a sort of
+|\thispagestyle| for floats).
+\item Multiple sets of marks (named here \emph{markset}s and
+\textit{extra marks}).
\end{itemize}
-
-\section{Final comments}
-%~~~~~~~~~~~~~~~~~~~~~
-
-\begin{itemize}
-
-\item Only a |\footnote| command is allowed in titles, but it
-will work. However, the footnote mark is not removed from
-toc entries or running headings; for that use
+It can be used without \textsf{titlesec}, but you will get most of
+it when used together. To load it as a separate package, use the
+customary \verb|\usepackage{titleps}|, but with \textsf{titlesec} you
+have to load it with:
\begin{verbatim}
-\usepackage[stable]{footmisc}
+\usepackage[pagestyles]{titlesec}
\end{verbatim}
-\item The page styles have been reimplemented in full in version 2.3.
-Most of previous definition will work with the current code, even if
-many things have changed. In particular, headers using just |\the...|
-and |\...title| commands, besides |\usepage| and formatting commands
-still work. Now, pagestyles should be loaded explicitly with the
-|pagestyles| option, but if it is not given and the three basic
-commands are used, the page styles macros are loaded with a warning.
-The new code overcomes the limitations of previous releases, fixes
-some bugs (the incompatibility between top marks and floats, for
-example), and adds new features.
-\end{itemize}
+Please, read |titleps.pdf| (or typeset |titleps.tex|) for further
+information.
\section{Contents: The \textsf{titletoc} package}
% ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~