summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/titlesec/titleps.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/titlesec/titleps.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/titlesec/titleps.tex')
-rw-r--r--macros/latex/contrib/titlesec/titleps.tex835
1 files changed, 835 insertions, 0 deletions
diff --git a/macros/latex/contrib/titlesec/titleps.tex b/macros/latex/contrib/titlesec/titleps.tex
new file mode 100644
index 0000000000..51149c9fa8
--- /dev/null
+++ b/macros/latex/contrib/titlesec/titleps.tex
@@ -0,0 +1,835 @@
+%
+% Copyright (C) 1998-2019 Javier Bezos http://www.texnia.com
+%
+% This file may be distributed and/or modified under the conditions of
+% the MIT License. A version can be found at the end of this file.
+%
+% Repository: https://github.com/jbezos/titlesec
+%
+
+\def\fileversion{2.11}
+\def\docdate{2019/07/16}
+
+\documentclass[a4paper]{ltxguide}
+\usepackage[sf,bf,compact,topmarks,calcwidth,pagestyles]{titlesec}
+\usepackage{titletoc}
+\def\gobble#1{}
+\DeclareRobustCommand\cs[1]{\expandafter\gobble\string\\#1}
+\makeatletter
+\newenvironment{desc}
+ {\if@nobreak
+ \vskip-\lastskip
+ \vspace*{-2.5ex}%
+ \fi
+ \decl}
+ {\enddecl}
+\makeatother
+
+\usepackage{textcomp,pslatex}
+\usepackage[linktocpage]{hyperref}
+
+\title{Headers and footers with \textsf{titleps}\footnote{The
+\textsf{titleps} package is currently at version \fileversion.
+\copyright{} 2016 Javier Bezos. All Rights Reserved.}}
+
+\author{Javier Bezos\footnote{For bug reports, comments and
+suggestions go to \href{http://www.texnia.com/contact.html}%
+{\texttt{http://www.texnia.com/contact.html}}. English
+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}.}}
+
+\date{\docdate}
+
+\widenhead{2.1pc}{0pc}
+\titlelabel{\thetitle.\quad}
+
+\renewpagestyle{plain}[\small\sffamily\slshape]{
+ \footrule
+ \setfoot{}{\thepage}{}}
+
+\newpagestyle{myps}[\small\sffamily\slshape]{
+ \headrule
+ \sethead{titlesec -- titleps}{\sectiontitle}{\thepage}}
+
+\pagestyle{myps}
+
+\newcommand{\examplesep}{%
+ \begin{center}%
+ \rule{4pt}{4pt}%
+ \end{center}}
+
+\contentsmargin{0pt}
+
+\titlecontents*{section}[0pt]%[1.8pc]
+ {}
+ {\thecontentslabel. }
+ {}
+ {, \thecontentspage}
+ [. --- ][.]
+
+\addtolength{\topmargin}{-3pc}
+\addtolength{\textwidth}{6pc}
+\addtolength{\oddsidemargin}{-2pc}
+\addtolength{\textheight}{7pc}
+
+\raggedright
+\parindent1em
+\parskip0pt
+
+\begin{document}
+
+\maketitle
+\tableofcontents
+\section{Introduction}
+
+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}
+
+Other features are:
+\begin{itemize}
+\item Working top marks, compatible with floats (unlike the standard
+|\topmark|, which does not work correctly in \LaTeX{}).
+\item Access to top, first and botttom marks in a single headline/footline
+(e.g., the first and last section numbers).
+\item Marks for more than 2 sectioning levels.
+\item Auto-defining of suitable |\sectionmark| and the like.
+\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}
+
+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[pagestyles]{titlesec}
+\end{verbatim}
+
+Specific tools for sectioning command marks are provided, which are
+considered the main \textit{markset} (unnamed) and carry out some
+internal task. However, \textsf{titleps} can be used as well for
+headers with the first an last entry of a page in a dictionary or index,
+for example, thank to the \textit{extra marks} described below.
+
+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) and several packages emitting marks
+directly with \verb|\markboth| and \verb|\markleft|.\footnote{%
+Two columns layout requires the \textsf{fix2col} package by David
+Carlisle.}
+
+Once loaded the package, you can define your own page styles and then
+activate them, but note page styles so defined cannot be used with
+\verb|\thispagestyle| except if the surrounding page style has been
+defined with \textsf{titleps}, too.
+
+%%%% empty ? plain ?
+
+\section{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, spaces and 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 the 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}
+|\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 headlines and footlines (note the
+``visual'' layout of parameters). The optional arguments are the
+three 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). If |\sethead| is not given, then the headline it is left
+empty, and same for |\setfoot| and the footline.
+
+In the arguments of |\sethead|/|\setfoot| and because of its one-stage
+mechanism, we must distinguish between two groups of commands:
+\begin{itemize}
+\item The first one includes those saved when the marks are emitted,
+with information related to sections, and includes:
+\begin{itemize}
+\item |\thechapter|, |\thesection|, |\thesubsection|\dots{}
+\item |\chaptertitle|, |\sectiontitle|, |\subsectiontitle|\dots{} which print the
+chapter, section\dots{} title.
+\item (Only \textsf{titlesec}. Not in \textsf{titleps}.)
+|\ifthechapter{<true>}{<false>}|, |\ifthesection{<true>}{<false>}|,
+|\ifthesubsection{<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}
+They are ordinary commands, with no internal marks at all, and you can
+test if, for example, they are empty.
+
+\item The second group are those expanded on every page, and includes:
+\begin{itemize}
+\item |\thepage|.
+\item Any other command not included in the previous items.
+\end{itemize}
+\end{itemize}
+
+\begin{desc}
+|\settitlemarks{<level-name>,<sublevel-name>,<subsublevel-name>...}|\\
+|\settitlemarks*{<level-name>,<sublevel-name>,<subsublevel-name>...}|
+\end{desc}
+Sets which |\...title| commands are to be defined, and when the marks
+are emitted; any number of levels is allowed (1, 2, 3...). For example
+|\settitlemarks{chapter,section}|
+means that:
+\begin{itemize}
+\item |\chaptertitle| and |\sectiontitle| are the allowed titles in
+ headlines,
+\item |\sectiontitle| is reset in |\chapter|,
+\item (Only \textsf{titlesec}. Not in \textsf{titleps}.)
+|\ifthechapter| and |\ifthesection| are valid tests.
+\item Marks are updated in |\chapter| and |\section|.
+\end{itemize}
+Default is |\settitlemarks{chapter,section}|, but
+|\settitlemarks{section,subsection}| in \textsf{article} class.
+|\settitlemarks| may be used outside |\(re)newpagestyle| to set the
+default to be used in newly defined and redefined page styles -- it is
+used in |\pagestyle|.\footnote{The command \texttt{\string\setmarks} is
+deprecated. Now
+\texttt{\string\setmarks\string{<primary>\string}\string{<secondary>\string}}is
+\texttt{\string\settitlemarks\allowbreak\string{<primary>,\allowbreak<secundary>\string}}.}
+
+The starred version |\settitlemarks*| creates parallel extra marks
+as described below.
+
+\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{titleps} 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 header/footer 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 header/footer. 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.
+
+\section{On \texttt{\cs{markboth}} and \texttt{\cs{markleft}}}
+
+As \textit{The \LaTeX{} Companion explains} ``Leslie Lamport had a
+specific marking scheme in mind when he designed those
+commands''. They are clearly intended for the \verb|heading| and
+\verb|myheading| pagestyles, with a \textit{main-mark} on the left
+page and a \textit{sub-mark} on the right one.
+
+In order to provide the functionality offered by \textsf{titleps}, a
+more general, less specific mechanism is devised, which means
+|\markboth| here does not make sense, because it doesn't work like in
+standard \LaTeX, and in fact, can lead to unpredictable results.
+
+Therefore, using directly the marking commands is discouraged (see
+|titlesec.pdf|), but if you need them, you may write:
+\begin{verbatim}
+\chapter*{My Chapter}
+\chaptermark{My Chapter}
+\end{verbatim}
+
+But some issues remain, because there are a number of packages
+assuming the pagestyle is \verb|heading| or \verb|myheading|. This is,
+of course, a reasonable guess, but not always correct (even if
+\textsf{titleps} is not used at all). Most of them do the right thing
+-- \verb|\markboth| is encapsulated into a macro easily redefinable so
+that the user can modify it if necessary. This is true, for example,
+for \textsf{biblatex}, but unfortunately not for \textsf{endnotes}.
+When this happens, you can resort to the following macro.
+
+\begin{desc}
+|\setmarkboth{<code-to-use>}|
+\end{desc}
+
+From this point on, \verb|\markboth| behaves as defined. It doesn't
+redefine directly the command, but rather provides a replacement code
+(you can use |#1| and |#2| for the two arguments). With
+|\resetmarkboth| (which can be used inside |\setmarkboth|) the
+original definition will be again in force. For example, to cancel the
+next |\markboth|:
+\begin{verbatim}
+\setmarkboth{\resetmarkboth\markboth{}{}}
+\end{verbatim}
+
+\section{Headline/footline width}
+
+\begin{desc}
+|\widenhead[<even-left>][<even-right>]{<odd-left>}{<odd-right>}|\\
+|\widenhead*{<even-right/odd-left>}{<even-left/odd-right>}|
+\end{desc}
+
+Makes the headlines/footlines 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}|.
+
+To be used outside |\(re)newpagestyle|.
+
+\begin{desc}
+|nopatches| \qquad (package option)
+\end{desc}
+
+By default, sectioning commands are patched slightly for top marks
+and |\@mkboth| to work, so that page styles behave like standard
+|headings|. However, if you want to be explicit, like with standard
+|myheadings|, and emit premarks and, if necessary, marks by yourself,
+set this package option. Remenber you have to use |\sectionmark| and
+the like, and not |\markboth| or |\markright|.
+
+You might also prefer to patch the sectioning commands by yourself,
+either with low-level definitions or with the provided
+|\TitlepsPatchSection| (with a starred version which adds no premark
+and intended mainly for chapters). For example:
+\begin{verbatim}
+\TitlepsPatchSection*{chapter} % patches \chapter
+\TitlepsPatchSection{section} % patches \section
+\end{verbatim}
+(In standard classes |\part| emits no mark, and therefore it is not
+patched by default.)
+
+\section{Marks}
+
+Marks can be retrieved in 4 ways:
+\begin{description}
+\item[top marks] If a page begins with text, they are the marks
+belonging to the sectioning unit of that text. If a page begin with a
+sectioning title, they are the marks of that title. In other words,
+top marks refer to the section immediately adjacent to the
+headline.
+\item[first marks] The marks of the very first sectioning title.
+\item[botttom marks] The marks of the very last (bottom) sectioning
+title (also known as \textit{bot marks}).
+\item[next top marks] A botttom mark with the values of the top mark of
+the next page (only |straight| class or equivalent); by picking some
+value from it and comparing it with the corresponding value from the
+botttom marks you may know if a section continues in the next page.
+Of course, it will not be used very often.
+\end{description}
+Standard \LaTeX{} provides only first and bottom marks. As you see, with
+\textsf{titleps} you have two additional marks, namely, top and next
+top marks.
+
+It should be stressed top marks are not the same as the primitive
+\verb|\topmark| (which, in fact, is not used internally at all). They
+are true top marks, returning the expected result when the title is at
+the top of the page. Further, they are compatible with floats, which
+is not true with \verb|\topmark|s. However, they fail with explicit
+page breaks, but you can use \verb|\pretitlemark| as described
+below.
+
+\begin{desc}
+|outermarks innermarks topmarks botmarks| \qquad (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.\footnote{|outermarks| may not work
+well in conjunction with explicit |\string\<section>mark| commands} 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).
+
+\begin{desc}
+|\bottitlemarks \toptitlemarks \firsttitlemarks \nexttoptitlemarks|\\
+|\outertitlemarks \innertitlemarks|
+\end{desc}
+
+These commands set which mark the values of the subsequent
+|\thesection|, |\sectiontitle|, etc., will be taken from.
+These macros are switches, and therefore subsequent commands and
+variables are taken from the selected mark. The following is valid:
+\begin{verbatim}
+\toptitlemarks\textbf{\thesection.} \sectiontitle --
+\bottitlemarks\textbf{\thesection.} \sectiontitle
+\end{verbatim}
+
+You can use them 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{\toptitlemarks Top is \thesection}
+ {\firsttitlemarks First is \thesection}
+ {\bottitlemarks Bot is \thesection}}
+\end{verbatim}
+
+In multilingual documents, the language in force is that corresponding
+to the package options -- command versions does not switch the
+language, but you can do it easily with the help a new title mark and
+then switching the language, as explained below.
+
+\begin{desc}
+|\newtitlemark{<command-name>}|\\
+|\newtitlemark*{<variable-name>}|
+\end{desc}
+
+Add a command or a variable to the list of ``marks'' to be emitted at
+a sectioning command. The macro must be parameterless, and the
+variable is either a length, if it has the form \verb|\<name>|, or a
+counter, if it has the form \verb|<name>| (i. e., a string).
+For example, if you write (with \textsf{babel}):
+\begin{verbatim}
+\newtitlemark{\languagename}
+\end{verbatim}
+then a |\languagename| in the head/foot will contain the language when
+the corresponding mark was emitted; unfortunately, \textsf{babel}
+does not allow |\languagename| as the first argument of
+|\foreignlanguage| (it enters in a infinite loop), but there is a
+simple trick -- just use an intermediate command:
+\begin{verbatim}
+\newcommand\titlelanguage{\languagename}
+\newtitlemark{\titlelanguage}
+\end{verbatim}
+(What is saved is the expansion of |\titlelanguage|, which is turn is
+the expansion of |\languagename|. Alternatively, you can create the
+intermediate command with |\let| in the header itself.)
+
+Marks to be emitted at other places (not sectioning commands) are
+handled with extra marks and \textit{marksets} (see below).
+
+Commands must be robust, but not protected, or the value returned will
+not be the right one. Remember there are two kinds of robust commands
+-- those containing in turn robust commands and those protected with,
+say, |\DeclareRobustCommand|.\footnote{Unfortunately,
+\texttt{\string\DeclareRobustCommand} has a misleading name, because a
+command created with \texttt{\string\newcommand} can be robust, too.
+A better name would have been
+\texttt{\string\DeclareProtectedCommand}.} An example of how to use
+protected commands is a layout used sometimes if sections are long as
+well as their titles, where the title is splitted across the left and
+the right pages. Here is how this can be carried out:
+\begin{verbatim}
+\DeclareRobustCommand\splitheader[2]{#1 #2}
+\def\contsplitheader{}
+
+\def\dosplitheader{%
+ \gdef\contsplitheader{}%
+ \DeclareRobustCommand\splitheader[2]{##1\gdef\contsplitheader{##2}}}
+
+\renewpagestyle{headings}{
+ \sethead[\thepage]
+ []
+ [\dosplitheader\sectiontitle]
+ {\contsplitheader}
+ {}
+ {\thepage}
+}
+
+\pagestyle{headings}
+\end{verbatim}
+(Note the header also uses |\DeclareRobustCommand|.)
+
+\begin{desc}
+|\pretitlemark{<section>}{<text>}|\\
+|\pretitlemark*{<section>}{<text>}|
+\end{desc}
+
+Top marks require in fact two marks, one before the page break and
+other after it. This is done by \textsf{titlesec}, while
+\textsf{titleps} patches the sectioning commands as described above.
+
+However, if you need an explicit page break you can emit the mark
+with |\pretitlemark|. For example:
+\begin{verbatim}
+\pretitlemark{section}{Performing Brahms}
+\newpage
+\section{Performing Brahms}
+\end{verbatim}
+Note the text in the premark is the title of the next section. The
+counter is advanced temporarily, so that it has the right value, but
+if for some reason you do not want that, just use
+\verb|\pretitlemark*|.
+
+\begin{desc}
+|\ifsamemark{<group>}{<command>}{<true>}{<false>}|
+\end{desc}
+
+One of the disavantaged of the switching mechanism is that comparing
+a command from, say, the top marks and the botttom marks is not
+trivial.
+This macro just makes it simpler. If you want to compare the
+currect \verb|\thesection| with that in the top mark, write:
+\begin{verbatim}
+\ifsamemark\toptitlemarks\thesection{<true>}{<false>}
+\end{verbatim}
+
+\section{Running heads with floats}
+
+\begin{desc}
+|psfloats| \qquad (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 is 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 just
+before the corresponding float, where the arguments with a dot are
+similar to those of |\sethead|. Those commands are used by
+themselves, without putting them inside |\(re)newpagestyle|. So, to
+empty the headline when a certain figure is placed at the top (because
+it is a bleed, for example):
+\begin{verbatim}
+\nextfloathead{}{}{}{}[t]
+\begin{figure}
+...
+\end{figure}
+\end{verbatim}
+
+\section{Extra marks}
+
+Both \textsf{titlesec} and \textsf{titleps} provide tools for handling
+extra marks, if you are using an $\epsilon$-\TeX{} based engine
+(currently most of them) and load the \textsf{etex} package or
+equivalent. The way they work are conceptually similar to the title
+marks described above -- you set which commands or variables are to
+get synchronized in heads and foots. To use extra marks, you have to
+load them with the following package option:
+
+\begin{desc}
+|extramarks| \qquad (package option)
+\end{desc}
+
+Extra marks are subsidiary. If page styles are modified internally by
+another package and the document does not make use of sectioning
+commands, you might still need an empty title mark (like
+\verb|\sectionmark{}|), as well as to synchronize the language by
+hand.
+
+In many cases, the following ``short'' marks mechanism will be enough.
+With it, you simply say with \verb|\newshormark| the name of a command
+to be used in heads or foots, and then emit the mark at appropiated
+places (short marks for variables are not available). An example
+illustrates how this is carried out:
+\begin{verbatim}
+\newcommand\lemmatitle{}
+
+\newshortmark\lemmatitle
+
+\newcommand\lemma[1]{%
+ \renewcommand\lemmatitle{#1}%
+ \preshortmark\lemmatitle % if you want top marks
+ \pagebreak[2]%
+ \vspace{1em}%
+ \textbf{#1}\enspace
+ \shortmark\lemmatitle}
+
+\newpagestyle{main}{
+ \sethead{}{\topshortmark\lemmatitle
+ --\firstshortmark\lemmatitle
+ --\botshortmark\lemmatitle
+ --\nexttopshortmark\lemmatitle}{}}
+
+\pagestyle{main}
+\end{verbatim}
+
+Top marks require emitting the marks before the page break -- just use
+the command \verb|\preshortmark| as shown above. Otherwise, you may
+omit it. Unlike title marks and extra marks, the selector of short
+marks (\verb|\topshortmark|, \verb|\firstshortmark|,
+\verb|\botshortmark|, \verb|\nexttopshortmark|), is \textit{not} a
+switch and must be always immediately followed by the command to be
+retrieved.
+
+For a more general approach use the following tools.
+
+\begin{desc}
+|\newmarkset{<markset>}|
+\end{desc}
+
+A \textit{markset} contains a set of related commands and variables
+intended to be emitted simultaneously as marks, so that their values
+can be retrieved in heads/foots. A typical \textit{markset} could be
+a title and its counter (and perhaps, in a multilingual document, the
+active language, i.e., \verb|\languagename| in \textsf{babel}, or an
+intermediate command). There is always a special unnamed
+\textit{markset} for sectioning marks, which is the main one and
+handled with the tools described above (with |title| in their names).
+
+\begin{desc}
+|\newextramark{<markset>}{<macro-name>}|\\
+|\newextramark*{<markset>}{<variable-name>}|
+\end{desc}
+
+Add to a \textit{markset} a command or a variable to be synchronized .
+They are identical to \verb|\newtitlemark| and \verb|\newtitlemark*|,
+except for the additional parameter with the \textit{markset} name.
+
+\begin{desc}
+|\botextramarks{<markset>} \topextramarks{<markset>}|\\
+|\firstextramarks{<markset>} \nexttopextramarks{<markset>}|\\
+|\outerextramarks{<markset>} \innerextramarks{<markset>}|
+\end{desc}
+
+The \verb|extra| counterparts of the \verb|title| commands described
+above, with the same behaviour. For example:
+\begin{verbatim}
+\newcommand{\lemmatitle}{}
+\newcounter{lemma}
+
+\newmarkset{lemma}
+\newextramark{lemma}{\lemmatitle}
+\newextramark*{lemma}{lemma} % ie, the counter `lemma'
+
+\newcommand{\lemma}[1]{%
+ \renewcommand{\lemmatitle}{#1}%
+ \stepcounter{lemma}%
+ \preextramark{lemma}%
+ \pagebreak[2]%
+ \vspace{1em}%
+ \textbf{(\arabic{lemma}) #1}\enspace
+ \extramark{lemma}}
+
+\newpagestyle{main}{
+ \sethead{}
+ {\topextramarks{lemma}(\arabic{lemma}) \textbf{\lemmatitle}}
+ {}}
+
+\pagestyle{main}
+\end{verbatim}
+
+\begin{desc}
+|\settitlemarks*{<level-name>,<sublevel-name>,<subsublevel-name>...}|
+\end{desc}
+
+By default, \LaTeX{} and \textsf{titleps} use a single \textit{markset} for
+all sectioning levels. This is problematic, for example, in the
+\textsf{article} class, because sections does not start a new page.
+Consider the following piece of code:
+\begin{verbatim}
+\section{A section}
+\subsection{A subsection}
+\end{verbatim}
+On odd pages with first marks and subsection titles, the head has
+no title, because \verb|\subsection| is the second mark, not the
+first one.
+
+To overcome this limitation, you can use the starred version of
+\verb|\settitlemarks|, which creates parallel \textit{marksets} (one per
+level) synchonized with the main \textit{markset}. They are retrieved like
+other extra marks, but they are special in that you cannot emit them
+by yourself -- they are always emitted by the corresponding
+sectioning mark. So, with
+\begin{verbatim}
+\settitlemarks*{section,subsection}
+\end{verbatim}
+and a page style containing
+\begin{verbatim}
+\firstextramarks{subsection}\subsectiontitle
+\end{verbatim}
+you retrieve the mark emitted by the first \verb|\subsection|, even
+if preceded by a \verb|\section|. (Top marks are best retrieved from
+the main \textit{markset}.)
+
+They are extra marks, and therefore language synchronization has to be
+done by hand -- add \verb|\languagename| or an intermediate command to
+the main \textit{markset} with \verb|\newtitlemark| and, if you want,
+define a command. For example:
+\begin{verbatim}
+% use an intermediate command because we'll need \foreignlanguage
+\newcommand\titlelanguage{\languagename}
+\newtitlemark{\titlelanguage}
+
+% define a command to ease defining page styles
+\newcommand{\toplang}[1]{%
+ {\topextramarks{section}%
+ \foreignlanguage{\titlelanguage}{#1}}}
+\end{verbatim}
+
+\section{A couple of examples}
+
+Because of the way marks are handled, special constructs 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 with |\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 (with |\ifsamemark|), 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 -- titleps}{\sectiontitle}{\thepage}}
+\end{verbatim}
+
+The following definitions provide page styles similar to those in
+Lamport's \textit{The \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}
+\end{verbatim}
+
+% \section{Remarks}
+%
+% Page styles in standard \LaTeX{} are somewhat rudimentary. For
+% example |\thispagestyle| is not always correctly synchronized with
+% sectioning marks, and if you set |\pagestyle{plain}| and then
+% |\thispagestyle{headings}|, its behaviour is not the expected one.
+% The same happens if a page style defined in \textsf{titleps} is used
+% in a |\thispagestyle| in the context of a standard page style -- you
+% have to define the main one as well.
+
+% \section{Some tips and tricks}
+%
+% star |\*|
+%
+% split heads
+%
+% bible
+
+\end{document}
+
+MIT License
+-----------
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+