summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/phfnote/phfnote.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/phfnote/phfnote.dtx')
-rw-r--r--macros/latex/contrib/phfnote/phfnote.dtx2434
1 files changed, 1788 insertions, 646 deletions
diff --git a/macros/latex/contrib/phfnote/phfnote.dtx b/macros/latex/contrib/phfnote/phfnote.dtx
index 05deb87518..a0632f9997 100644
--- a/macros/latex/contrib/phfnote/phfnote.dtx
+++ b/macros/latex/contrib/phfnote/phfnote.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright (C) 2016 by Philippe Faist <philippe.faist@bluewin.ch>
+% Copyright (C) 2019 by Philippe Faist, philippe.faist@bluewin.ch
% -------------------------------------------------------
%
% This file may be distributed and/or modified under the
@@ -22,8 +22,9 @@
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{phfnote}
%<*package>
- [2016/08/15 v1.0 phfnote package]
+ [2021/10/08 v4.0 phfnote package]
%</package>
+%<phfnotepreset>%This preset file for phfnote is used when you call `\usepackage[preset=<PRESET NAME>]{phfnote}'
%
%<*driver>
\documentclass{ltxdoc}
@@ -34,6 +35,10 @@
\usepackage{needspace}
\makeatletter
+
+ % the factor by which to compress macro names in the margin
+\def\phf@xpkgdoc@marginmacronamecompressfactor{0.9}
+
\newsavebox\phfnoteDocVirtualPage@contents
\newenvironment{phfnoteDocVirtualPage}{%
\par%
@@ -50,6 +55,7 @@
\def\@title{Notes on Lambda-Majorization}%
\def\@author{Ph. Faist}%
\def\@date{23.12.2011}%
+ \let\RequirePackage\@gobble%
\def\notetitletopspace{0pt}%
\def\notetitlefont{\sffamily\bfseries}%
\def\morepagecontents{\par\vspace{1em}\centering\ldots}%
@@ -68,6 +74,10 @@
%%\par%
\endgroup%
}
+
+\def\eqsign@{=}
+\def\eqsign{\protect\eqsign@}
+\robustify\eqsign
\makeatother
\def\RevTeX{{\small R\raise-0.2ex\hbox{\textsc{ev}}}\TeX}
@@ -80,6 +90,7 @@
\DocInput{phfnote.dtx}
\end{document}
%</driver>
+%<*package>
% \fi
%
% \CheckSum{0}
@@ -114,7 +125,7 @@
% \maketitle
%
% \begin{abstract}
-% \pkgname{phfnote}---A handy \LaTeX{} class for typesetting short notes and
+% \pkgname{phfnote}---A handy \LaTeX{} package for typesetting short notes and
% medium-length reports, full of goodies to make it look just right.
% \end{abstract}
%
@@ -135,7 +146,7 @@
% too much space, better page margin sizes, and some basic styling to make
% the note look nicer. At the same time, it is highly configurable so that
% nothing is really unchangeable. And all overridden features can be
-% restored individually to their class-provided defaults.
+% restored individually to their defaults provided by the underlying class.
%
% This package has been designed to work optimally along with the |article|
% document class, but in principle any relatively standard \LaTeX{} class should
@@ -148,8 +159,8 @@
% complicated articles. For that, you should use a specialized class such as
% \RevTeX.\footnote{See \url{https://journals.aps.org/revtex}}
%
-% In the following, we detail individual features of this class, and explain how
-% to activate, deactivate, and customize them.
+% In the following, we detail individual features of this package, and explain
+% how to activate, deactivate, and customize them.
%
%
% \section{Basic Usage}
@@ -209,7 +220,7 @@
% \item[preset=sfssnote] {\fontfamily{cmss}\selectfont Format the note in
% \LaTeX' default sans-serif font. A very nice sans serif font. It might
% look heavy though, depending on your taste.}
-% \item[preset=opensansnote] {\fontfamily{fosj}\selectfont Format the note
+% \item[preset=opensansnote] {\opensans Format the note
% in Open Sans font (using the `\pkgname{opensans}' package with some
% default options). A very beautiful and readable sans serif font.}
% \item[preset=utopianote] {\fontfamily{futs}\selectfont Format the note in
@@ -232,12 +243,12 @@
% \begin{pkgoptions}
% \item[preset=pkgdoc] Basic formatting and settings for documenting \LaTeX{}
% packages. This preset was used for the current document.
-% \item[preset=xpkgdoc] Same as |preset=pkgdoc|, but in addition a set of
-% useful commands are also provided, the \pkgname{tcolorbox} package is
-% loaded along with some default boxes. Also some commands are patched
-% to achieve some fixes. This preset is used for the documentation of
-% packages in the \pkgname{phfqitltx} package suite. (For details see
-% the implementation of |\phfnote@preset@xpkgdoc| below.)
+% \item[preset=xpkgdoc] Same as |preset=pkgdoc|, but in addition a set of useful
+% commands are also provided, the \pkgname{tcolorbox} package is loaded along
+% with some default boxes. Also some commands are patched to achieve some
+% fixes. This preset is used for the documentation of packages in the
+% \pkgname{phfqitltx} package suite. (For details see the implementation of
+% the |xpkgdoc| preset in \autoref{sec:impl-xpkgdoc}.)
% \end{pkgoptions}
%
%
@@ -269,6 +280,52 @@
% case, the preset |reset| will guarantee all features to be deactivated.
% \end{pkgoptions}
%
+%
+%
+%
+% \section{Summary of Package Options}
+% \label{sec:package-options}
+%
+% \begin{pkgoptions}
+% \item[preset=\meta{preset name}] Load a preset specifying a predefined set of
+% options for the general appearance of the document. See documentation in
+% \autoref{sec:presets}
+% \item[title=\meta{title style},notitle] Set the title style. Use
+% \pkgoptionfmt{notitle} to disable feature and use latex default.
+% Documentation in \autoref{sec:title-styles}
+% \item[abstract=\meta{abstract attributes},noabstract] Set the abstract style by
+% specifying a comma-separated list of attributes. Don't forget to
+% put the list of attributes within braces,
+% |[abstract={wide,noname,it}]|. Documentation in
+% \autoref{sec:abstract-attributes}
+% \item[pkgset=\meta{package set}] Specify a standard set of \LaTeX{}
+% packages to load. See \autoref{sec:package-sets}.
+% \item[pagegeom=\meta{geom style},nopagegeom] Set a page margin style. Use |nopagegeom|
+% to leave page geometry unchanged. Options are documented in
+% \autoref{sec:pagegeomdefs}.
+% \item[secfmt=\meta{section formatting attributes},nosecfmt] A list of
+% attributes defining how section (and possibly paragraph) headings should
+% look like. See \autoref{sec:secfmt}.
+% \item[par=\meta{par style},nopar] Define how paragraphs should be spaced.
+% Refer to \autoref{sec:par-defs}.
+% \item[spacingdefs,nospacingdefs] Adjust spacing of lines and words
+% (\autoref{sec:spacingdefs}).
+% \item[fontdefs,nofontdefs] Adjust some fonts (\autoref{sec:fontdefs}).
+% \item[footnotedefs,nofootnotedefs] Adjust slightly the appearance of
+% footnotes. See \autoref{sec:footnotedefs}.
+% \item[hyperrefdefs=\meta{settings},nohyperrefdefs] Load the \pkgname{hyperref}
+% package, and set some defaults settings. See \autoref{sec:hyperrefdefs}.
+% \item[bibliographydefs,nobibliographydefs] Adjust the appearance and style of
+% the bibliography. See \autoref{sec:bibliographydefs}.
+% \end{pkgoptions}
+%
+% \begin{pkgtip}
+% To activate only a subset of features, use \pkgoptionfmt{preset=reset} and then
+% enable only the features required. In this way, you can ensure that only those
+% features which are explicitly specified are enabled.
+% \end{pkgtip}
+%
+%
% \section{Features}
%
% This package provides a large collection of small features, which, put all
@@ -305,29 +362,95 @@
% As you can see, it saves more space on the page compared to the default
% article title.
%
+% \changed[chg-title-default-spacing]{v3.0}{2018/10/25}{The default title
+% style was redesigned to improved spacing of the elements in all cases
+% including multiline titles, author and/or date not specified, and presence
+% or absence of thanks notes. Use \texttt{title\eqsign defaultv1}
+% for old behavior}
+%
+% If you would like your document to appear exactly as with \pkgname{phfnote}
+% version 1.0, then you can set the special title style |title=defaultv1|.
+%
+% \item[title=pretty,title=pretty2] A prettier, fancier title style. The title
+% is centered, with two side bars providing a visual guide. The |pretty|
+% style looks like this:
+% \begin{phfnoteDocVirtualPage}
+% \notetitle@stylesetup@pretty
+% \notetitle@style@pretty\null \shortlipsum \morepagecontents
+% \end{phfnoteDocVirtualPage}
+% And the |pretty2| style looks like this:
+% \begin{phfnoteDocVirtualPage}
+% \csname notetitle@stylesetup@pretty2\endcsname
+% \csname notetitle@style@pretty2\endcsname\null \shortlipsum \morepagecontents
+% \end{phfnoteDocVirtualPage}
+%
+% \changed[chg-title-add-style-pretty]{v3.0}{2018/10/25}{Added the
+% \phfverb{pretty} and \phfverb{pretty2} title styles}
+%
+% This title style is highly customizable (see below), in fact the |pretty2|
+% style is an alias for the |pretty| style, with adjusted settings.
+%
+% These styles require the |xcolor| package (it will be loaded automatically).
+%
% \item[title=small] A smaller title style which displays all the relevant
% information on a single line. This is useful for when even the default
% title style appears too large. It looks like this:
% \begin{phfnoteDocVirtualPage}
+% \notetitle@stylesetup@small
% \notetitle@style@small\null \shortlipsum \morepagecontents
% \end{phfnoteDocVirtualPage}
%
% \item[title=article] Mimics the default title style from the |article| class,
% but saves a little more space. It looks like this:
% \begin{phfnoteDocVirtualPage}
-% \vspace*{3em}\notetitle@style@article\null \shortlipsum \morepagecontents
+% \notetitle@stylesetup@article
+% \notetitle@style@article\null \shortlipsum \morepagecontents
% \end{phfnoteDocVirtualPage}
%
-% \item[title=] An empty argument to |title| instructs \pkgname{phfnote} not to
-% override any title definition, thus preserving the default class title
-% style.
+% \changed[chg-title-article-spacing]{v3.0}{2018/10/26}{The \phfverb{article}
+% title style was redesigned to use our new title engine, with improved
+% spacing of the elements in all cases including multiline titles, author
+% and/or date not specified, and presence or absence of thanks notes.
+% Use \texttt{title\eqsign articlev1} for old behavior}
+%
+% If you would like your document to appear exactly as with \pkgname{phfnote}
+% version 1.0, then you can set the special title style |title=articlev1|.
+%
+% \item[notitle] Also equivalently, |title=false|. Instructs \pkgname{phfnote}
+% not to override any title definition, thus preserving the default class
+% title style.
%
% Beware that some other title goodies, such as our more advanced |\thanks|
% notes, or spacing adjustments for the abstract, will probably not work.
+%
+% For compatibility with previous versions of |phfnote|, you may also specify
+% an empty option value ``|title=|''.
% \end{pkgoptions}
%
+% \begin{pkgtip}
+% When using the |default| and |pretty*| title styles, the argument to
+% |\title| may contain blank lines. In this case, each part is typeset on a
+% separate line with an appropriate spacing. For instance:
+% \begin{verbatim}
+% \title{Letter of Motivation
+%
+% John Doe}
+% \end{verbatim}
+% will be typeset as
+% \begin{phfnoteDocVirtualPage}
+% \expandafter\def\csname @title\endcsname{Letter of Motivation\par John Doe}
+% \expandafter\def\csname @author\endcsname{}
+% \expandafter\def\csname @date\endcsname{}
+% \notetitle@style@default\null \morepagecontents
+% \end{phfnoteDocVirtualPage}
+% \end{pkgtip}
+%
+% \changed[chg-title-false-pkgoption]{v3.0}{2018/10/16}{Improved
+% \phfverb{title,notitle} package options syntax}
%
-% \subsubsection{Customizing the style of the \phfverb{default} and \phfverb{small} title styles}
+% \subsubsection{Customizing the style of the \phfverb{default}, \phfverb{pretty}
+% and \phfverb{small} title styles}
+% \label{sec:title-styles-customization}
%
% You may customize the appearance of the |default| and |small| title styles by
% overriding some macros.
@@ -339,10 +462,17 @@
% default main font title, author text and date text. You may override these
% settings with, for instance:
% \begin{verbatim}
-% \renewcommand{\notetitlefont}{\sffamily\bfseries}
-% \renewcommand{\notetitleauthorfont}{\itshape}
-% \renewcommand{\notetitledatefont}{\footnotesize}
+% \renewcommand{\notetitlefont}[1]{\sffamily\bfseries #1}
+% \renewcommand{\notetitleauthorfont}[1]{\itshape #1}
+% \renewcommand{\notetitledatefont}[1]{\footnotesize #1}
% \end{verbatim}
+% In these macros, the parameter is expanded to the value provided by |\title|,
+% |\author|, and |\date|, respectively.\footnote{While you can normally define
+% \string\notetitlefont, \string\notetitleauthorfont\space and
+% \string\notetitledatefont\space without an explicit parameter, this might
+% produce some unexpected errors in some cases since some title styles (for
+% technical details see implementation of the \texttt{article} title style).}
+%
% The spacing of the title may be adjusted with the macros
% \DescribeMacro{\notetitlebelowspace} |\notetitlebelowspace| and
% \DescribeMacro{\notetitletopspace} |\notetitletopspace|. Override these with
@@ -356,8 +486,45 @@
% \begin{verbatim}
% \renewcommand{\notetitlehrule}{\hrule height 0.8pt}
% \end{verbatim}
+%
+% \DescribeMacro{\notetitleusempfootnotestrue}
+% \DescribeMacro{\notetitleusempfootnotesfalse} The commands
+% |\notetitleusempfootnotestrue| and |\notetitleusempfootnotesfalse| set
+% respectively whether any |\thanks| commands in the title generate footnotes
+% inside the title area (which is drawn within a minipage), i.e., all thanks
+% notes are collected on an additional line below the date, or whether they
+% appear as regular footnotes at the bottom of the page. Simply call the
+% relevant command to set either setting (don't redefine these).
+%
+%
+% The |small| title style allows you to customize the separator between the
+% author and the date:
+% \begin{verbatim}
+% \renewcommand\notetitlesmallauthordatesep{\hspace*{0.5em}\cdot\hspace*{0.5em}}
+% \end{verbatim}
%
%
+% In addition to the above settings for the default title style, the |pretty|
+% and |pretty2| styles provide a few macros that you can adjust some visual
+% aspects to your needs:
+% \begin{verbatim}
+% \renewcommand\notetitleprettylsiderulewidth{10pt}
+% \renewcommand\notetitleprettylsidespacewidth{10pt}
+% \renewcommand\notetitleprettyrsiderulewidth{10pt}
+% \renewcommand\notetitleprettyrsidespacewidth{10pt}
+% \renewcommand\notetitleprettytopspace{10pt}
+% \renewcommand\notetitleprettybottomspace{10pt}
+% \renewcommand\notetitleprettytophrulewidth{0pt}
+% \renewcommand\notetitleprettybottomhrulewidth{0pt}
+%
+% \colorlet{notetitleprettylsiderulecolor}{blue!40!black}
+% \colorlet{notetitleprettyrsiderulecolor}{notetitleprettylsiderulecolor}
+% \colorlet{notetitleprettytophrulecolor}{notetitleprettylsiderulecolor}
+% \colorlet{notetitleprettybottomhrulecolor}{notetitleprettylsiderulecolor}
+% \colorlet{notetitleprettytextcolor}{blue!20!black}
+% \colorlet{notetitleprettybgcolor}{white!95!blue}
+% \end{verbatim}
+%
%
% \subsubsection{Title notes: \phfverb\thanks{} and \phfverb\thanksmark}
%
@@ -376,7 +543,7 @@
% \end{phfnoteDocVirtualPage}
% whereas with the other styles, this information is typeset as regular footnotes.
%
-% \leavevmode\marginpar{\raggedleft \phfverb\thanks\phfverb{[N]}}\relax
+% \leavevmode\PrintMarginLabel{\string\thanks[N]}\relax
% You may specify an optional argument to |\thanks|, forcing the footnote to a
% specific number (it must be a number). For example, with
% {\ttfamily|\|author\{Ph.\@ Faist|\|thanks[9]\{|\|itshape Institute for
@@ -411,12 +578,21 @@
%
% \begin{pkgwarning}
% The optional argument to |\thanks|, as well as the command |\thanksmark|,
-% are not made available if you don't use one of |\phfnote|'s title styles.
+% are not made available if you don't use one of \pkgname{phfnote}'s title
+% styles.
%
% This behavior is such as to prevent interference with more advanced class
% mechanisms, such as \RevTeX's.
% \end{pkgwarning}
%
+% \begin{pkgtip}
+% For \pkgname{phfnote}'s title styles, you can issue the commands
+% |\notetitleusempfootnotestrue| or |\notetitleusempfootnotesfalse|
+% (documentation in \autoref{sec:title-styles-customization}) to decide
+% whether the thanks notes are issued in a separate title line, or if they are
+% displayed as regular footnotes at the bottom of the page.
+% \end{pkgtip}
+%
%
% \subsection{Abstract}
% \label{sec:abstract-attributes}
@@ -464,15 +640,16 @@
% then by default.
% \item[abstract=\pkgoptattrib{noname}] The title ``Abstract.'' above the text
% will not be typeset. The abstract text is typeset directly instead.
-% \item[abstract=\pkgoptattrib{original}] Revert to the class' default
-% implementation of the |abstract| environment. The class' implementation is
-% restored and no longer tampered with.
% \item[abstract=\pkgoptattrib{small}] Use a smaller font for the abstract text
% (|\small| font).
% \item[abstract=\pkgoptattrib{compact}] Reduce spacing before and after the
% abstract. If the abstract is short, this might look slightly better.
% \item[abstract=\pkgoptattrib{it}] Typeset the abstract text using an italic
% typeface.
+% \item[noabstract] Do not (re)define the |abstract| environment, do not execute
+% abstract definitions. This leaves the original |abstract| environment
+% definition of the underlying \LaTeX{} class. You can also equivalently say
+% |abstract=false|.
% \end{pkgoptions}
%
%
@@ -494,6 +671,18 @@
% (|\noteabstractbeforespacing|) the abstract can further be
% specified, also as macros.
%
+%
+% Obsolete options:
+% \begin{pkgoptions}
+% \item[abstract=\pkgoptattrib{original}] Revert to the original class' default
+% implementation of the |abstract| environment before \pkgname{phfnote} was
+% loaded. The original class' implementation is restored and no longer
+% tampered with. This option is OBSOLETE, use |noabstract| instead.
+% \end{pkgoptions}
+%
+% \changed[chg-noabstract-pkgoption]{v3.0}{2018/10/16}{Improved
+% \phfverb{abstract,noabstract} package options syntax}
+%
% \subsection{Table of Contents}
% \label{sec:inline-toc}
%
@@ -539,14 +728,23 @@
% \pkgname{amssymb}, \pkgname{amsfonts}, and \pkgname{amsthm}. The
% \pkgname{xcolor} package is also loaded.
%
-% \item[pkgset=rich] Include a fair amount of packages which may be useful.
-% On top of the |minimal| package set, this set includes the packages
+% \item[pkgset=rich] Include a fair amount of packages which may be useful. On
+% top of the |minimal| package set, this set includes the packages
% \pkgname{enumitem}, \pkgname{graphicx}, \pkgname{microtype},
-% \pkgname{caption}, \pkgname{setspace}, as well as \pkgname{inputenc}
-% with the |utf8| option and \pkgname{fontenc} with the |T1| option.
+% \pkgname{caption}, \pkgname{setspace}, as well as \pkgname{inputenc} with
+% the |utf8| option and \pkgname{fontenc} with the |T1| option (the packages
+% \pkgname{fontenc} and \pkgname{inputenc} are not loaded if running Xe(La)TeX
+% or Lua(La)TeX, or if they are already loaded with possibly different
+% options).
%
% This package set is loaded by default.
%
+% \changed[chg-xe-luatex-input-fontenc-pkgset]{v1.1}{2018/08/27}{If running
+% XeTeX or LuaTeX, then do not load \pkgname{inputenc} and \pkgname{fontenc}
+% as part of \texttt{rich} and \texttt{extended} package sets. Plus, do not
+% load \pkgname{inputenc} (resp. \pkgname{fontenc}) if the package is already
+% loaded}
+%
% \item[pkgset=extended] Additionally, include packages \pkgname{float},
% \pkgname{verbdef}, \pkgname{csquotes}, \pkgname{dsfont}, \pkgname{bbm}
% and \pkgname{mathtools}.
@@ -569,16 +767,8 @@
% and whether the document is typeset in two columns.
%
% If you want anything more complicated than what is provided by a default
-% setting here, just use |pagegeomdefs=false| and invoke the \pkgname{geometry} package
-% directly with your preferred set of options.
-%
-% \begin{pkgoptions}
-% \item[pagegeomdefs=true] Include the \pkgname{geometry} package, using the default
-% settings or whatever is specified with the |pagegeom| option.
-% \item[pagegeomdefs=false] Do not attempt to change the document margins, and
-% don't load the \pkgname{geometry} package.
-% \item[nopagegeomdefs] Same as |pagegeomdefs=false|.
-% \end{pkgoptions}
+% setting here, just use the |nopagegeom| package option and invoke the
+% \pkgname{geometry} package directly with your preferred set of options.
%
% The page geometry predefined settings are the following.
%
@@ -586,6 +776,8 @@
% \item[pagegeom=default] Default settings. Not too wide, not too
% narrow. Settings vary according to single or double column setting, and
% according to default font point size.
+% \item[nopagegeom] Also, |pagegeom=false|. Do not change page geometry
+% settings, do not load the \pkgname{geometry} package.
% \item[pagegeom=narrow] Narrower style. For single-column documents, this is
% closer to the typographically-advertised-optimal of 50--80 characters per
% line, but it might look narrow to some.
@@ -595,20 +787,38 @@
% note can fit. This style is used in this package documentation, for
% example.
% \end{pkgoptions}
-%
+%
+% The following package options are OBSOLETE:
+% \begin{pkgoptions}
+% \item[pagegeomdefs=\meta{true or false}] Whether to care about page
+% margins. |nopagegeomdefs| is synonym for |pagegeomdefs=false|. This option
+% is OBSOLETE, please use |nopagegeom| or |pagegeom=false| instead of
+% |pagegeomdefs=false| and |pagegeom| (or |pagegeom=...| with setting) instead
+% of |pagegeomdefs=true|.
+% \end{pkgoptions}
+%
+% \changed[chg-pagegeom-pkgoption-onoff]{v3.0}{2018/10/16}{Changed how to turn
+% on/off the page geometry settings by improving the \phfverb{pagegeom} package
+% options, deprecated \phfverb{pagegeomdefs} option}
+%
+% \changed[chg-pagegeom-xwide]{v3.0}{2018/11/30}{Changed the \texttt{xwide} page
+% geometry for tighter vertical margin for single-column text (use
+% \texttt{pagegeom\eqsign xwidev1} instead for old behavior)}
+%
%
% \subsection{Section Headers Styling}
% \label{sec:secfmt}
%
-% The \pkgname{phfnote} package provides some limited styling of section headers. The
-% font, size and ``compactness'' of the headers can be adjusted with title options.
-% But really, these options are quite basic. You should use \pkgname{titlesec} or
-% \pkgname{sectsty} directly if you want anything serious.
+% The \pkgname{phfnote} package provides some limited styling of section
+% headers. The font, size and ``compactness'' of the headers can be adjusted
+% with title options. But really, these options are quite basic. You should
+% use \pkgname{titlesec} or \pkgname{sectsty} directly if you want anything
+% serious.
%
-% The section headings are customized using the \pkgname{sectsty} package. If this
-% conflicts in your document, then use the |[secfmt={}]| package option to
-% indicate that section headings should NOT be styled by this package. Then take
-% care of section styling manually.
+% The section headings are customized using the \pkgname{sectsty} package. If
+% this conflicts in your document, then use the |nosecfmt| package option to
+% indicate that section headings should NOT be styled by this package. Then
+% you have the full freedom to take care of section styling manually.
%
% Package options may be used to customize the appearance of the section
% headings by specifying a list of attributes. When you combine arguments, make
@@ -663,8 +873,9 @@
% \item[secfmt=\pkgoptattrib{blockpar}] Change the paragraph-level headings not
% to be in ``run-in'' style, but to be typeset on their own line like section
% headings.
-% \item[secfmt=\pkgoptattribempty] Leave the argument empty to keep the original class styling;
-% nothing will be overridden and the \pkgname{sectsty} package is not loaded.
+% \item[nosecfmt] Keep the original class styling; nothing will be overridden
+% and the \pkgname{sectsty} package is not loaded. (Equivalently, you may
+% specify |secfmt=false|.)
% \end{pkgoptions}
%
% You can also directly modify the section heading style by redefining some
@@ -691,6 +902,7 @@
% Beware that if you redefine |\notesectionallfont| then you are responsible for
% honoring, or ignoring, the value of |\notesectionallfontfamily|.
%
+% \needspace{5\baselineskip}
% \DescribeMacro{\notesectionfont} \DescribeMacro{\notesubsectionfont}
% \DescribeMacro{\notesubsubsectionfont} \DescribeMacro{\noteparagraphfont}
% \DescribeMacro{\notesubparagraphfont} These macros define the font commands to
@@ -713,6 +925,17 @@
% arguments, the font definitions to apply for headings of level |\paragraph|
% and |\subparagraph|.
%
+% Obsolete options:
+% \begin{pkgoptions}
+% \item[secfmt=\pkgoptattribempty] Leave the argument empty to keep the original
+% class styling; nothing will be overridden and the \pkgname{sectsty} package
+% is not loaded. This option is OBSOLETE, use |nosecfmt| instead.
+% \end{pkgoptions}
+%
+% \changed[chg-secfmt-false-pkgoption]{v3.0}{2018/10/16}{Improved
+% \phfverb{secfmt,nosecfmt} package options syntax}
+%
+%
% \subsection{Appearance of Paragraphs}
% \label{sec:par-defs}
%
@@ -725,10 +948,22 @@
% and not indented.
% \item[par=indentminiskip] Paragraphs are indented, but there is also a small
% space between each paragraph.
-% \item[par=original] Do not modify the appearance of paragraphs, and leave the
-% class default.
+% \item[nopar] Do not modify the appearance of paragraphs, and leave the
+% original class' default.
+%
+% You may also use |par=false|.
% \end{pkgoptions}
%
+%
+% Obsolete options:
+% \begin{pkgoptions}
+% \item[par=original] OBSOLETE---use |nopar| instead.
+% \end{pkgoptions}
+%
+% \changed[chg-par-false-pkgoption]{v3.0}{2018/10/16}{Improved
+% \phfverb{par,nopar} package options syntax}
+%
+%
% \subsection{Adjusting Spacing of Lines and Words}
% \label{sec:spacingdefs}
%
@@ -739,13 +974,16 @@
% long words.
%
% \begin{pkgoptions}
-% \item[spacingdefs=true] Apply adjustments to line and word spacing.
-% \item[spacingdefs=false] Do not attempt any adjustments of line or word
-% spacing.
-% \item[nospacingdefs] Alias for |spacingdefs=false|.
+% \item[spacingdefs] Apply adjustments to line and word spacing.
+%
+% This feature is on by default. You can also use |spacingdefs=true|.
+%
+% \item[nospacingdefs] Do not attempt any adjustments of line or word spacing. You
+% can also use the alias |spacingdefs=false|.
% \end{pkgoptions}
%
%
+%
% \subsection{Adjustments for Fonts}
% \label{sec:fontdefs}
%
@@ -758,21 +996,30 @@
% instead of the default |OT1|.
%
% \begin{pkgoptions}
-% \item[fontdefs=true] Apply adjustments to fonts.
-% \item[fontdefs=false] Do not apply adjustments to fonts.
-% \item[nofontdefs] Same as |fontdefs=false|.
+% \item[fontdefs] Apply adjustments to fonts. This is on by default, except on
+% Xe\TeX{} and Lua\TeX{}.
+%
+% You can also use |fontdefs=true|.
+%
+% \item[nofontdefs] Do not apply adjustments to fonts. You can also set
+% |fontdefs=false|.
+%
% \end{pkgoptions}
%
-% \subsection{Footnote Figure Style}
+%
+% \subsection{Footnote Style}
% \label{sec:footnotedefs}
%
% The footnotes' appearance can also be slightly enhanced.
%
% \begin{pkgoptions}
-% \item[footnotedefs=true] Changes the symbol appearance a little bit---the
+% \item[footnotedefs] Changes the symbol appearance a little bit---the
% footnote number is smaller and typeset in boldface.
-% \item[footnotedefs=false] Do not change the footnote appearance.
-% \item[nofootnotedefs] Same as |footnotedefs=false|.
+%
+% You can also use |footnotedefs=true|. This feature is on by default.
+%
+% \item[nofootnotedefs] Do not change the footnote appearance. You can also set
+% |footnotedefs=false|.
% \end{pkgoptions}
%
%
@@ -785,21 +1032,93 @@
% personally like better (dark blue links as in this document).
%
% \begin{pkgoptions}
-% \item[hyperrefdefs=true] Load the \pkgname{hyperref} package, and set some sensible
-% settings. Also ensures the |\email| and |\url| commands are made available.
-% \item[hyperrefdefs=false] Do not load the \pkgname{hyperref} package, do not set
-% sensible settings.
-% \item[nohyperrefdefs] Same as |hyperrefdefs=false|.
+% \item[hyperrefdefs] Load the \pkgname{hyperref} package, and
+% set some sensible default settings. Also ensures the |\email| and |\url| commands
+% are made available.
+%
+% You can also use |hyperrefdefs=true|. This feature is on by default.
+%
+% \item[nohyperrefdefs] Do not load the \pkgname{hyperref} package. Do not set
+% any settings. Do not care to provide |\email| or |\url|. Same as
+% |hyperrefdefs=false|.
+%
+% Depending on the situation, you might prefer to specify |hyperrefdefs=defer|
+% or |hyperrefdefs=noload|, so that some basic setup (e.g. |\url|/|\email|
+% commands) can still be provided. See below.
+%
+% \item[hyperrefdefs=\pkgoptattrib{defer}] Prepare the document for hyperlinks,
+% schedule settings for \pkgname{hyperref}, but do not actually load the
+% \pkgname{hyperref} package.
+%
+% This is useful if you would like to load more packages that need to be
+% loaded before loading \pkgname{hyperref}. A lot of packages need to be
+% loaded before \pkgname{hyperref} so if you load several other packages,
+% you're probably better off using this option and calling
+% |\usepackage{hyperref}| at the end of your preamble, i.e.\@ right before
+% |\begin{document}|, rather than chasing mysterious errors.
+% \iffalse \end{document} -- [...emacs indentation gets fooled easily...] \fi
+%
+% When using this option it is the user's responsibility to load the load the
+% package with |\usepackage{hyperref}| somewhere in the preamble. You will
+% get an error if you don't do this.
+%
+% \item[hyperrefdefs=\pkgoptattrib{noemail}] Do not override any existing
+% |\email| command. Use this for instance in Rev\TeX{}, where our
+% implementation of |\email| clashes with Rev\TeX{}'s |\email| command which
+% is used to specify e-mail addresses for authors.
+%
+% The version of this command by \pkgname{phfnote} is still available as
+% |\phfnoteEmail|.
+%
+% \item[hyperrefdefs=\pkgoptattrib{noeqref}] Do not redefine the |\eqref|
+% command to include the parenthesis in the hyperlink.
+%
+% \changed[chg-hyperref-redefeqref]{v3.2}{2021/07/29}{We now redefine
+% \phfverb{\eqref} by default to include the parentheses inside the hyperlink.
+% Use the \texttt{hyperrefdefs\eqsign noeqref} package option to disable this
+% feature}
+%
+% \item[hyperrefdefs=\pkgoptattrib{noload}] Do not load the \pkgname{hyperref}
+% package, and don't bother to set any related settings. However,
+% \pkgname{url} package is loaded, and the commands |\url| and |\email| are
+% provided (they output the same visual text but don't produce a clickable
+% color link).
+%
+% \item[hyperrefdefs=\pkgoptattrib{clearoptions}] Do not attempt to set any
+% options via |\hypersetup| (and don't schedule setting any such options
+% later). You'll get \pkgname{hyperref}'s default settings, so it's up to you
+% to call |\hypersetup| with however you'd like to see your links look like.
+%
% \end{pkgoptions}
%
-% \DescribeMacro{\url} In order to typeset URLs, the |\url| command is made
-% available from the package \pkgname{url} (which is then linkified by \pkgname{hyperref}). For
-% example, you can type |\url{https://github.com/phfaist/}|.
+% Attributes may be combined, as in |hyperrefdefs={noemail,noload}|. In this
+% case make sure you put them in a braced group. Also, beware that attributes
+% are not merged between different occurrences of the |hyperrefdefs| keyword in
+% the package options; the last occurrence defines all set attributes.
+%
+% When the |hyperref| package is loaded, it is done so with the |unicode=true|
+% package option. In case you need, you can specify your own package options
+% with |hyperrefdefs=defer| and then calling |\usepackage[...]{hyperref}|. For
+% most options though it's simpler to use |\hypersetup{...}|.
%
-% \DescribeMacro{\email} A similar command allows to typeset e-mail addresses.
-% The text is displayed as a hyperlink, which when clicked opens a e-mail
-% composer to that address (via a |mailto:XXX| link). For example, try
-% |\email{pulp_fiction@tarantino.com}|.
+%
+% \DescribeMacro{\url} In order to typeset URLs, the |\url| command is made
+% available from the package \pkgname{url} (which is then linkified by
+% \pkgname{hyperref}). For example, you can type
+% |\url{https://github.com/phfaist/}|.
+%
+% \DescribeMacro{\email} \DescribeMacro{\phfnoteEmail} A similar command allows
+% to typeset e-mail addresses. The text is displayed as a hyperlink, which when
+% clicked opens a e-mail composer to that address (via a |mailto:XXX| link).
+% For example, try |\email{pulp_fiction@tarantino.com}|. The command
+% |\phfnoteEmail| is an alias for this, which is defined even if the |noemail|
+% attribute is given.
+%
+% The commands |\url| and |\email| (along with |\phfnoteEmail|) are defined
+% unless |nohyperrefs| (or |hyperrefdefs=false|) is specified. If you would
+% like to use these commands but not load the |hyperref| package, consider using
+% |hyperrefdefs=noload|.
+%
%
% \DescribeMacro{\phfnotePdfLinkColor} The command |\phfnotePdfLinkColor| may by
% used to set the color of the links. It takes one argument, a color
@@ -815,6 +1134,9 @@
% see \autoref{sec:package-sets}.)
% \end{pkgnote}
%
+% The internal name for the link color is |docnotelinkcolor|. (This name is
+% historical, and I'm not really willing to change it.)
+%
%
% \subsection{Bibliography Definitions}
% \label{sec:bibliographydefs}
@@ -830,11 +1152,12 @@
% Finally, an entry in the table of contents is generated.
%
% \begin{pkgoptions}
-% \item[bibliographydefs=true] Load the \pkgname{hyperref} package, and set some sensible
-% settings. Also ensures the |\email| and |\url| commands are made available.
-% \item[bibliographydefs=false] Do not load the \pkgname{hyperref} package, do not set
-% sensible settings.
-% \item[nobibliographydefs] Same as |bibliographydefs=false|.
+% \item[bibliographydefs] Set some default bibliography settings.
+%
+% This feature is on by default. You can also use |bibliographydefs=true|.
+%
+% \item[nobibliographydefs] Do not set some bibliography settings. You may also
+% use |bibliographydefs=false|.
% \end{pkgoptions}
%
% \DescribeMacro{\bibliography} \DescribeMacro{\bibliographystyle} The
@@ -848,6 +1171,25 @@
% custom |naturemagdoi| bibliography style is used.
%
%
+% \subsection{Inline Commenting in Documents}
+% \label{sec:inline-commenting}
+%
+% Inline commenting features (|\phfMakeCommentingCommand|) have been moved to
+% the separate dedicated package \pkgname{phfcc}. If you were using these
+% features in your document, simply do
+% \begin{verbatim}
+% \usepackage{phfcc}
+% \end{verbatim}
+% and everything should work as expected.
+%
+% \changed[chg-inline-commenting]{v3.0}{2018/10/03}{Added support for inline
+% commenting using \phfverb\phfMakeCommentingCommand}
+%
+% \changed[chg-inline-commenting-moved]{v3.1}{2020/04/02}{Moved support for
+% inline commenting to the separate dedicated package \pkgname{phfcc}}
+%
+%
+%
% \subsection{URL Styles}
% \label{sec:url-styles}
%
@@ -884,7 +1226,7 @@
% size to a fraction of the surrounding font size. The fraction may be
% specified as an optional argument. A fraction of 0.8 makes the text size 0.8
% times that of the surrounding text, that is, smaller than the surrounding
-% text. A value of 1 does not change the font size. If the fraction is not
+% text. A value of~1 does not change the font size. If the fraction is not
% specified, the value stored in |\notesmallerfrac| is used.
%
% \DescribeMacro{\notesmallerfrac} The fraction by which |\notesmaller| typesets
@@ -905,48 +1247,7 @@
%
%
%
-% \section{Summary of Package Options}
-% \label{sec:package-options}
%
-% \begin{pkgoptions}
-% \item[preset=\meta{preset name}] Load a preset specifying a predefined set of
-% options for the general appearance of the document. See documentation in
-% \autoref{sec:presets}
-% \item[title=\meta{title style}] Set the title style. Documentation in
-% \autoref{sec:title-styles}
-% \item[abstract=\meta{abstract attributes}] Set the abstract style by
-% specifying a comma-separated list of attributes. Don't forget to
-% put the list of attributes within braces,
-% |[abstract={wide,noname,it}]|. Documentation in
-% \autoref{sec:abstract-attributes}
-% \item[pkgset=\meta{package set}] Specify a standard set of \LaTeX{}
-% packages to load. See \autoref{sec:package-sets}.
-% \item[pagegeomdefs=\meta{true or false}] Whether to care about page
-% margins. |nopagegeomdefs| is synonym for |pagegeomdefs=false|.
-% \item[pagegeom=\meta{geom style}] Set a page margin style. Only has effect if
-% |pagegeomdefs=true|. Options are documented in \autoref{sec:pagegeomdefs}.
-% \item[secfmt=\meta{section formatting attributes}] A list of attributes
-% defining how section (and possibly paragraph) headings should look like.
-% See \autoref{sec:secfmt}.
-% \item[par=\meta{par style}] Define how paragraphs should be spaced. Refer to
-% \autoref{sec:par-defs}.
-% \item[spacingdefs=\meta{true or false}] Adjust spacing of lines and words
-% (\autoref{sec:spacingdefs}).
-% \item[fontdefs=\meta{true or false}] Adjust some fonts
-% (\autoref{sec:fontdefs}).
-% \item[footnotedefs=\meta{true or false}] Adjust slighly the appearance of
-% footnotes. See \autoref{sec:footnotedefs}.
-% \item[hyperrefdefs=\meta{true or false}] Load the \pkgname{hyperref} package, and set
-% some defaults settings. See \autoref{sec:hyperrefdefs}.
-% \item[bibliographydefs=\meta{true or false}] Adjust the appearance and style
-% of the bibliography. See \autoref{sec:bibliographydefs}.
-% \end{pkgoptions}
-%
-% \begin{pkgtip}
-% To activate only a subset of features, use \pkgoptionfmt{preset=reset} and then
-% enable only the features required. In this way, you can ensure that only those
-% features which are explicitly specified are enabled.
-% \end{pkgtip}
%
%
% \StopEventually{\PrintChangesAndIndex}
@@ -966,9 +1267,11 @@
\RequirePackage{kvoptions}
% \end{macrocode}
%
-% Also load \pkgname{etoolbox}, for various utilities.
+% Also load \pkgname{etoolbox}, for various utilities and \pkgname{xparse}
+% (for parsing optional arguments with recursive matching open/close brackets).
% \begin{macrocode}
\RequirePackage{etoolbox}
+\RequirePackage{xparse}
% \end{macrocode}
%
% \subsection{Internal Generic Code}
@@ -1001,7 +1304,9 @@
\ifcsname #1\next\endcsname%
\csname #1\next\endcsname%
\else%
- \PackageWarning{phfnote}{Unknown #2: '\next'. Ignoring.}
+ \PackageError{phfnote}{Unknown #2: '\next'. Ignoring.}{The given #2 '\next'
+ is invalid. Consult the package documentation for information about
+ valid attributes.}
\fi
}
}
@@ -1022,9 +1327,9 @@
% These may be redefined to adapt the font of the title, author and date.
%
% \begin{macrocode}
-\newcommand{\notetitlefont}{\sffamily\bfseries}
-\newcommand{\notetitleauthorfont}{}
-\newcommand{\notetitledatefont}{\footnotesize}
+\newcommand{\notetitlefont}[1]{\sffamily\bfseries #1}
+\newcommand{\notetitleauthorfont}[1]{#1}
+\newcommand{\notetitledatefont}[1]{\footnotesize #1}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -1062,21 +1367,6 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\phfnote@title@checksetspace}
-% Some of our title styles require the \pkgname{setspace} package. This utility checks that
-% this package is loaded, and generates an error otherwise.
-%
-% |#1| = the current title style name; this is required only for the error message.
-% \begin{macrocode}
-\def\phfnote@title@checksetspace#1{%
- \ifdefined\singlespace\else%
- \PackageError{phfnote}{Note title style `#1' requires the
- `setspace' package to be loaded! Please load it, or use a
- pkgset which loads it automatically}%
- \fi%
-}
-% \end{macrocode}
-% \end{macro}
%
% \subsubsection{Implementation of \phfverb\thanks{} and \phfverb\thanksmark}
%
@@ -1084,8 +1374,9 @@
% `default' title style as well as for other simpler styles. Our implementation supports
% |\thanks[N]{...}| and |\thanksmark[N]| as for footnotes.
%
-% These newer implementations are only applied if one of our title styles is set.
-% Otherwise, the class defaults are left (which may be needed, e.g., for \RevTeX).
+% These newer implementations are only applied if one of our title styles is
+% set. Otherwise, the class defaults are left untouched (which may be needed,
+% e.g., for \RevTeX).
%
% \paragraph{Implementation of \phfverb{\thanks} and friends for our main
% `default' title style}
@@ -1141,14 +1432,22 @@
% This simply takes all the tokens collected in |\phfnote@mpfootmaterial| (see just
% above), and typesets it in the |\@mpfootins| box. The latter is automatically typeset
% by the minipage in |\end{minipage}|.
+%
+% The argument |#1| is the skip length between the text and the footnotes.
% \begin{macrocode}
-\def\phfnote@finalizempfootnotes{%
- \global\setbox\@mpfootins=\vbox{%
- \parskip=0pt\parindent=0pt\parshape 1 0.04\textwidth 0.96\textwidth\relax%
- \noindent\leavevmode%
- \reset@font\footnotesize%
- \phfnote@fmt@titlefootnotes%
- \phfnote@mpfootmaterial}%
+\def\phfnote@finalizempfootnotes#1{%
+ \if\relax\detokenize\expandafter{\phfnote@mpfootmaterial}\relax
+ \else
+ \global\skip\@mpfootins=#1\relax
+ \global\setbox\@mpfootins=\vbox{%
+ \parskip=\z@\relax
+ \parindent=\z@\relax
+ \phfnote@mpfootnotes@fontparsetup
+ \noindent\leavevmode%
+ \reset@font\footnotesize%
+ \phfnote@fmt@titlefootnotes%
+ \phfnote@mpfootmaterial}%
+ \fi
}
% \end{macrocode}
% \end{macro}
@@ -1164,6 +1463,8 @@
% |\phfnote@mpfootnoteglue| is the glue which is used between two footnote texts (as
% they are typeset in a single paragraph).
% \begin{macrocode}
+\def\phfnote@mpfootnotes@fontparsetup{%
+ \parshape 1 0.04\textwidth 0.96\textwidth\relax}
\def\phfnote@fmt@titlefootnotes{}
\def\phfnote@mympfootnotemark#1{\@textsuperscript{\normalfont#1}}
\def\phfnote@mpfootnoteglue{\hskip 1.2em plus 2em minus 0.5em\relax}
@@ -1229,18 +1530,330 @@
%
% The title styles are documented in \autoref{sec:title-styles}.
%
+%
% \paragraph{Title style: `default'}
%
-% Implementation our main `default' title style. See \autoref{sec:main-default-title-style}.
+% Implementation our main `default' title style. See
+% \autoref{sec:main-default-title-style}.
+%
+% \begin{macro}{\notetitleinnervsep}
+% Controls the vertical spacing between individual elements of the title.
+% \begin{macrocode}
+\newcommand\notetitleinnervsep{1.15ex}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitlewidth}
+% Controls the width of the area in which the title content is typeset. For
+% more complex titles (e.g., |pretty| style, the title is typeset in a smaller
+% width than the text width to allow room for decorations).
+% \begin{macrocode}
+\def\notetitlewidth{\textwidth}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitleparskip}
+% The paragraph skip that is used if the title contains multiple paragraphs.
+% \begin{macrocode}
+\def\notetitleparskip{1.4ex}% parskip for multiple pars in main title
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitlefontparsetup}
+% \begin{macro}{\notetitleaftertitleskip}
+% |\notetitlefontparsetup| sets up any necessary \LaTeX{} commands to typeset
+% the main title. This should set the font size, and then maybe |\centering|,
+% a |\parshape|, or a text color.
+% \begin{macrocode}
+\def\notetitlefontparsetup{\raggedright\setstretch{1.05}\Large}
+% \end{macrocode}
+% |\notetitleaftertitleskip| generates the spacing after the main title. The
+% default implementation behaves differently whether the title was
+% multi-paragraph or not.
+% \begin{macrocode}
+\def\notetitleaftertitleskip{%
+ \ifnotetitle@default@ismultipar
+ \vspace{\parskip}%
+ %\gdef\phfnote@tmp@nextskip{\z@}%
+ \gdef\phfnote@tmp@nextskip{0.5\dimexpr\notetitleinnervsep\relax}%
+ \else
+ \gdef\phfnote@tmp@nextskip{\notetitleinnervsep}%
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\notetitleauthorfontparsetup}
+% \begin{macro}{\notetitledatefontparsetup}
+% These macros set up any necessary \LaTeX{} commands to typeset the author
+% and the date. This should set the font size, and then maybe |\centering|, a
+% |\parshape|, or a text color. These should use calls to
+% |\notetitledontextvskip| to adjust vertical spacing between the title items.
+% \begin{macrocode}
+\def\notetitleauthorfontparsetup{%
+ \notetitledonextvskip[2]%
+ \parshape 1 0.04\textwidth 0.96\textwidth\relax
+ \strut
+}
+\def\notetitledatefontparsetup{%
+ \notetitledonextvskip
+ \parshape 1 0.04\textwidth 0.96\textwidth\relax
+ \strut
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\notetitledonextvskip}
+% This helper macro is not meant to be redefined, but rather invoked from
+% |\notetitleauthorfontparsetup| and |\notetitledatefontparsetup|. It adds
+% the vertical space that was stored in |\phfnote@tmp@nextskip|.
+% \begin{macrocode}
+\newcommand\notetitledonextvskip[1][]{%
+ \vspace{#1\dimexpr\phfnote@tmp@nextskip\relax}%
+ \gdef\phfnote@tmp@nextskip{\notetitleinnervsep}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitlemakecontents}
+% Helper command that produces the content of the title. The default
+% implementation uses the set |\title|, |\author|, and |\date| to render
+% everything nicely. Note that if you redefine this, then it's up to you to
+% honor what to do with |\notetitlefontparsetup|, |\notetitlefont|,
+% |\notetitleauthorfont|, etc.
+%
+% The default implementation of |\notetitlemakecontents| allows
+% |\notetitle*fontparsetup| to take a single argument, the whole
+% title/author/date including necessary formatting. In that case make sure to
+% enclose that argument in a group.
+% \begin{macrocode}
+\newcommand\notetitlemakecontents{
+ \notetitlemakecontentstop
+ {\par
+ \let\phfnote@old@par\par
+ \notetitle@titledefault@preparetitle
+ \expandafter\notetitlefontparsetup\expandafter{%
+ \expandafter\notetitlefont\expandafter{\@title}}%
+ \phfnote@old@par
+ \notetitleaftertitleskip
+ }%
+ \if\relax\detokenize\expandafter{\@author}\relax\else
+ \expandafter\notetitleauthorfontparsetup\expandafter{%
+ \expandafter\notetitleauthorfont\expandafter{\@author}}\par
+ \fi
+ \if\relax\detokenize\expandafter{\@date}\relax\else
+ \expandafter\notetitledatefontparsetup\expandafter{%
+ \expandafter\notetitledatefont\expandafter{\@date}}\par
+ \fi
+ \notetitlemakecontentsbottom
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitlemakecontentstop}
+% \begin{macro}{\notetitlemakecontentsbottom}
+% If you just want to insert stuff before/after in the title box, then you
+% don't have to redefine all of |\notetitlemakecontents|, you can simply
+% redefine these macros to whatever you like.
+% \begin{macrocode}
+\def\notetitlemakecontentstop{}
+\def\notetitlemakecontentsbottom{}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\notetitlebeginrender}
+% \begin{macro}{\notetitleendrender}
+% The title is rendered enclosed by calls to these macros. By default, render
+% the title in a minipage.
+%
+% WARNING: An important thing to note is that if you use
+% |\notetitle@default@usesavebox|, then the saved box is an |\hbox|, not a
+% |\vbox| (more flexibility). That means that the |\notetitlebeginrender| and
+% |\notetitleendrender| commands must open and close some environment (or a
+% |\vbox| or something like that) so that the whole
+% |\notetitlebeginrender...\notetitleendrender| construction results in
+% something that can be placed in an |\hbox|.
+% \begin{macrocode}
+\def\notetitlebeginrender{\begin{minipage}{\notetitlewidth}}
+\def\notetitleendrender{\end{minipage}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\notetitleusemainbox}
+% This macro is the main formatting command for the title's global appearance.
+% After the title is typeset in a \TeX{} box register, this macro is invoked
+% to actually display it. The default title style simply displays it with a
+% rule below, but the |pretty| title style does fancier things. Note this is
+% only used if |\ifnotetitle@default@usesavebox| is true.
+% \begin{macrocode}
+\newcommand\notetitleusemainbox[1]{%
+ \par
+ \box#1%
+ \vspace*{\notetitleinnervsep}%
+ \notetitlehrule\relax
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitle@default@mainbox}
+% The main box register in which the title contents is saved.
+% \begin{macrocode}
+\newsavebox\notetitle@default@mainbox
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ifnotetitle@default@usesavebox}
+% This |if| controls whether or not we set up the title in a temporary \TeX{}
+% box register first, before displaying it. This allows to play around with
+% the box, measure its height/width, place it into graphics, etc. But if we
+% want a simple title, this is not necessary, and it might break some more
+% fragile constructions (footnotes, etc).
+%
+% If this is true, then the macro |\notetitleusemainbox| is called to render
+% the box. Otherwise, |\notetitleusemainbox| is not called and the title is
+% rendered directly.
+% \begin{macrocode}
+\newif\ifnotetitle@default@usesavebox
+\notetitle@default@usesaveboxtrue
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ifnotetitleusempfootnotes}
+% Whether any |\thanks| commands in the title generate footnotes inside the
+% minipage (i.e., a line at the bottom with e.g.\ affiliations), or whether
+% they appear as regular footnotes at the bottom of the page.
+%
+% This conditional may only be set to true if the rendering happens in a
+% minipage. The minipage must be opened in |\notetitlebeginrender| and closed
+% in |\notetitleendrender|.
+% \begin{macrocode}
+\newif\ifnotetitleusempfootnotes
+\notetitleusempfootnotestrue
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitle@default@setup}
+% Any additional setup to be done at the beginning.
+% \begin{macrocode}
+\def\notetitle@default@setup{%
+ \notetitle@default@ismultiparfalse
+ \gdef\phfnote@tmp@nextskip{\z@}%
+ \par\raggedright}
+% \end{macrocode}
+% \end{macro}
+%
+% Now we have the main implementation of the default title style.
%
% \begin{macro}{\notetitle@style@default}
-% The default title style. Nothing mysterious, hopefully.
+% A default title style, providing a flexible engine with powerful
+% customization features (the same engine is used for the |pretty| title
+% style).
+%
+% The strategy goes like this: First typeset everything in a minipage enclosed
+% in a box register, and then display that box register using
+% |\notetitleusemainbox|.
% \begin{macrocode}
\newcommand{\notetitle@style@default}{%
+ \begingroup
+ \parskip=\z@\relax
+ \parindent=\z@\relax
+ \providecommand\singlespace{}%
+ \notetitle@default@setup
+ \ifnotetitleusempfootnotes
+ \phfnote@setupthanksmpfootnote
+ \fi
+ \vspace*{\notetitletopspace}%
+ \def\x{}%
+% \end{macrocode}
+%
+% Now, draw the title (either in a box, or directly). If we save in a box, use
+% an |\hbox|, not a |\vbox|, because we get size problems otherwise. See
+% |\notetitlebeginrender| and |\notetitleendrender|.
+% \begin{macrocode}
+ \ifnotetitle@default@usesavebox
+ \def\x{\setbox\notetitle@default@mainbox=\hbox\bgroup}
+ \fi
+ \x\notetitlebeginrender
+ \begingroup
+ \singlespace%
+ \notetitlemakecontents\par
+ \ifnotetitleusempfootnotes
+ \expandafter\ifstrequal\expandafter{\@mpfn}{mpfootnote}{}{%
+ \PackageError{phfnote}{phfnote title: can only have
+ 'usempfootnotes' in a minipage}{Make sure you open a
+ \string\begin{minipage} in the definition of
+ \string\notetitlebeginrender \space and correspondingly close
+ it with \string\end{minipage} in \string\notetitleendrender}%
+ }
+ \global\let\@thanks\@empty
+ \phfnote@finalizempfootnotes{\phfnote@tmp@nextskip}%
+ \fi
+ \endgroup
+ \notetitleendrender
+ \def\x{}%
+ \ifnotetitle@default@usesavebox
+ \def\x{\egroup
+ \notetitleusemainbox{\notetitle@default@mainbox}}%
+ \fi
+ \x
+ \par
+ \endgroup
+ \vskip\notetitlebelowspace\relax% don't change this, abstract needs to \removelastskip
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% Some helpers for the default title style.
+%
+% \begin{macro}{\ifnotetitle@default@ismultipar}
+% This flag registers whether or not the title has multiple paragraphs (and
+% thus renders on several spaced lines). It is set to |true| by redefining
+% the |\par| command in the title (see |\notetitle@titledefault@preparetitle|
+% below).
+% \begin{macrocode}
+\newif\ifnotetitle@default@ismultipar
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitle@titledefault@preparetitle}
+% This helper sets everything up to display the title. It redefines |\par| to
+% register that the title has several paragraphs. Also, note that |\parskip|
+% is inserted in |\leavevmode|, so that setting |\parskip| as below only
+% affects subsequent paragraphs.
+%
+% To change the parskip amount, you may simply patch this command, e.g., as
+% |\appto\notetitle@titledefault@preparetitle{\parskip=1.2ex\relax}|.
+% \begin{macrocode}
+\newcommand\notetitle@titledefault@preparetitle{%
+ \def\par{\phfnote@old@par\global\notetitle@default@ismultipartrue}%
+ \leavevmode\parskip=\notetitleparskip\relax}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \paragraph{Title style: `defaultv1'}
+%
+% \begin{macro}{\notetitle@style@defaultv1}
+% The default title style, copied from \pkgname{phfnote} v1.0. DO NOT
+% CHANGE. Kept only for backwards compatibility, in case someone had spent
+% lots of time fine-tuning their title and patching the v1 of this package, or
+% if they want the document to appear exactly as the v1 of the package.
+%
+% [We need to use |\csdef| because of the ``1'' in the title name, which is
+% not valid in an \TeX{} usual escape sequence (!!)]
+% \begin{macrocode}
+\csdef{notetitle@style@defaultv1}{%
\begingroup\par\raggedright%
\phfnote@setupthanksmpfootnote%
\vspace*{\notetitletopspace}%
- \phfnote@title@checksetspace{default}%
+ \phfnote@title@checksetspace{defaultv1}%
\begin{minipage}{\textwidth}%
\begin{singlespace}%
\parskip=0pt\parindent=0pt\relax%
@@ -1262,7 +1875,7 @@
\vskip 2mm\relax%
\fi
\global\let\@thanks\@empty%
- \phfnote@finalizempfootnotes%
+ \csname phfnote@finalizempfootnotes@v1\endcsname%
\end{singlespace}%
\end{minipage}\par%
\vspace*{2mm}%
@@ -1271,31 +1884,206 @@
\endgroup%
\vskip\notetitlebelowspace\relax% don't change this, abstract needs to \removelastskip
}
+\csdef{phfnote@finalizempfootnotes@v1}{%
+ \global\setbox\@mpfootins=\vbox{%
+ \parskip=0pt\parindent=0pt\parshape 1 0.04\textwidth 0.96\textwidth\relax%
+ \noindent\leavevmode%
+ \reset@font\footnotesize%
+ \phfnote@fmt@titlefootnotes%
+ \phfnote@mpfootmaterial}%
+}
+\def\phfnote@title@checksetspace#1{%
+ \ifdefined\singlespace\else%
+ \PackageError{phfnote}{Note title style `#1' requires the
+ `setspace' package to be loaded! Please load it, or use a
+ pkgset which loads it automatically}{}%
+ \fi%
+}
% \end{macrocode}
% \end{macro}
%
%
+% \paragraph{Title style: `pretty' and `pretty2'}
+%
+% The |pretty| \& |pretty2| styles uses the same engine as the default, with
+% different settings.
+%
+% \begin{macro}{\notetitle@style@pretty}
+% \begin{macro}{\notetitle@style@pretty2}
+% Alias the main maketitle engine to the default one.
+% \begin{macrocode}
+\let\notetitle@style@pretty\notetitle@style@default
+\cslet{notetitle@style@pretty2}\notetitle@style@default
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\notetitle@stylesetup@pretty}
+% Setup macro that makes everything nice. Do all these defs in the macro
+% definition, and not directly in the global space, to avoid polluting the
+% \LaTeX{} environment with useless definitions if we don't use this title
+% style.
+% \begin{macrocode}
+\def\notetitle@stylesetup@pretty{%
+ \RequirePackage{xcolor}
+ \long\def\notetitlefont##1{\bfseries ##1}
+ \def\notetitlefontparsetup{%
+ \color{notetitleprettytextcolor}\centering}
+ \def\notetitleauthorfontparsetup{%
+ \notetitledonextvskip[2]%
+ \color{notetitleprettytextcolor}\centering}
+ \def\notetitledatefontparsetup{%
+ \notetitledonextvskip
+ \color{notetitleprettytextcolor}\centering}
+ \def\phfnote@mpfootnotes@fontparsetup{\color{notetitleprettytextcolor}}
+ %
+ \def\notetitlewidth{\dimexpr\textwidth
+ -\notetitleprettylsiderulewidth
+ -\notetitleprettyrsiderulewidth
+ -\notetitleprettylsidespacewidth
+ -\notetitleprettyrsidespacewidth\relax}
+ \let\notetitleusemainbox\notetitle@pretty@usemainbox
+ %
+ \def\notetitleprettylsiderulewidth{10pt}
+ \def\notetitleprettylsidespacewidth{10pt}
+ \def\notetitleprettyrsiderulewidth{10pt}
+ \def\notetitleprettyrsidespacewidth{10pt}
+ \def\notetitleprettytopspace{10pt}
+ \def\notetitleprettybottomspace{10pt}
+ \def\notetitleprettytophrulewidth{0pt}
+ \def\notetitleprettybottomhrulewidth{0pt}
+ %
+ \definecolor{notetitleprettylsiderulecolor}{RGB}{0,68,126}
+ \colorlet{notetitleprettyrsiderulecolor}{notetitleprettylsiderulecolor}
+ \colorlet{notetitleprettytophrulecolor}{notetitleprettylsiderulecolor}
+ \colorlet{notetitleprettybottomhrulecolor}{notetitleprettylsiderulecolor}
+ \definecolor{notetitleprettytextcolor}{RGB}{25,25,38}
+ \colorlet{notetitleprettybgcolor}{white}
+}
+\newlength\notetitle@pretty@tmplenht
+\newlength\notetitle@pretty@tmplendp
+\def\notetitle@pretty@usemainbox#1{%
+ \parskip=\z@\relax
+ \parindent=\z@\relax
+ \notetitle@pretty@tmplenht=\ht#1\relax%
+ \notetitle@pretty@tmplendp=\dp#1\relax%
+ \edef\tmp@dorule##1##2{%
+ {\noexpand\color{notetitlepretty##1siderulecolor}%
+ \noexpand\rule{##2}{%
+ \dimexpr \notetitleprettytopspace+
+ \notetitleprettybottomspace+
+ \notetitleprettytophrulewidth+
+ \notetitleprettybottomhrulewidth+
+ \notetitle@pretty@tmplendp+
+ \notetitle@pretty@tmplenht\relax}}}%
+ \fboxsep=0pt% for \colorbox
+ \par\hbox to \textwidth{%
+ \hskip 0pt plus 0.1fil minus 0.1fil\relax%
+ \tmp@dorule{l}{\notetitleprettylsiderulewidth}%
+ \colorbox{notetitleprettybgcolor}{%
+ \vbox{%
+ {\color{notetitleprettytophrulecolor}%
+ \hrule height \notetitleprettytophrulewidth\relax}%
+ \hbox{%
+ \hskip \notetitleprettylsidespacewidth\relax
+ % \fbox% DEBUG
+ {\vbox{\vskip \notetitleprettytopspace\relax
+ \box#1%
+ \vskip \notetitleprettybottomspace\relax}}%
+ \hskip \notetitleprettyrsidespacewidth\relax
+ }%
+ {\color{notetitleprettybottomhrulecolor}%
+ \hrule height \notetitleprettybottomhrulewidth\relax}%
+ }}%
+ \tmp@dorule{r}{\notetitleprettyrsiderulewidth}%
+ \hskip 0pt plus 0.1fil minus 0.1fil\relax}%
+ \par%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\notetitle@stylesetup@pretty2}
+% The |pretty2| style simply loads the |pretty| style, and ajusts some
+% settings.
+% \begin{macrocode}
+\csdef{notetitle@stylesetup@pretty2}{%
+ \notetitle@stylesetup@pretty
+ %
+ \definecolor{notetitleprettylsiderulecolor}{RGB}{0,68,126}
+ \colorlet{notetitleprettyrsiderulecolor}{notetitleprettylsiderulecolor}
+ \colorlet{notetitleprettytophrulecolor}{notetitleprettylsiderulecolor}
+ \colorlet{notetitleprettybottomhrulecolor}{notetitleprettylsiderulecolor}
+ \colorlet{notetitleprettytextcolor}{notetitleprettylsiderulecolor!50!black}
+ \colorlet{notetitleprettybgcolor}{white!95!notetitleprettytextcolor}
+ %
+ \def\notetitleprettytophrulewidth{.4pt}
+ \def\notetitleprettybottomhrulewidth{.4pt}
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
% \paragraph{Title style: `small'}
%
% Implementation an alternate `small' title style.
%
% \begin{macro}{\notetitle@style@small}
-% The default title style. Nothing mysterious, hopefully.
+% The small title style. Again, use the main title engine, but customize the settings.
% \begin{macrocode}
-\newcommand{\notetitle@style@small}{%
+\let\notetitle@style@small\notetitle@style@default
+\newcommand\notetitle@stylesetup@small{%
+ \notetitleusempfootnotesfalse
+ %
+ \def\notetitlemakecontents{%
+ {\expandafter\notetitlefont\expandafter{\@title}}%
+ \hfill\makebox{\fontsize{9pt}{10pt}\selectfont
+ \notetitle@small@renderauthordate}%
+ }
+ %\notetitle@default@usesaveboxfalse
+ %\def\notetitlebeginrender{\par}
+ %\def\notetitleendrender{%
+ % \vspace*{\notetitleinnervsep}\notetitlehrule\relax\vspace*{\notetitleinnervsep}}
+ \def\notetitleusemainbox##1{%
+ \par\box##1%
+ \vspace*{\notetitleinnervsep}\notetitlehrule\relax\vspace*{\notetitleinnervsep}}
+ \def\notetitle@small@renderauthordate{%
+ \expandafter\notblank\expandafter{\@author}{%
+ \expandafter\notblank\expandafter{\@date}{% both not blank
+ {\expandafter\notetitleauthorfont\expandafter{\@author}}%
+ \notetitlesmallauthordatesep
+ {\emph{\expandafter\notetitledatefont\expandafter{\@date}}}%
+ }{% only author
+ {\expandafter\notetitleauthorfont\expandafter{\@author}}%
+ }%
+ }{% only date
+ {\emph{\expandafter\notetitledatefont\expandafter{\@date}}}%
+ }}
+ %
+ \def\notetitleinnervsep{1mm}
+ \def\notetitlesmallauthordatesep{\hspace*{2mm}--\hspace*{2mm}}
+}
+% \end{macrocode}
+% \end{macro}
+%
+% Style |smallv1| provided for backwards compatibility, to make sure that all
+% spacing and formatting is exactly the same as for \pkgname{phfnote} version
+% 1.0.
+% \begin{macrocode}
+\csdef{notetitle@style@smallv1}{%
\begingroup\par\raggedright%
\let\footnote\thanks%
\vspace*{\notetitletopspace}%
- {\notetitlefont \@title}%
- \hfill\makebox{\fontsize{9pt}{10pt}\selectfont {\notetitleauthorfont \@author}%
- \hspace*{2mm}--\hspace*{2mm}{\emph{\notetitledatefont \@date}}}%
+ {\expandafter\notetitlefont\expandafter{\@title}}%
+ \hfill\makebox{\fontsize{9pt}{10pt}\selectfont
+ {\expandafter\notetitleauthorfont\expandafter{\@author}}%
+ \hspace*{2mm}--\hspace*{2mm}{\emph{\expandafter\notetitledatefont\expandafter{\@date}}}}%
\vspace*{1mm}\notetitlehrule\relax\vspace*{1mm}%
\par%
\endgroup%
\vskip\notetitlebelowspace\relax% don't change this, abstract needs to \removelastskip
}
% \end{macrocode}
-% \end{macro}
%
%
% \paragraph{Title style: `article'}
@@ -1303,9 +2091,53 @@
% Implementation the `article' title style.
%
% \begin{macro}{\notetitle@style@article}
-% The title style definition. Nothing mysterious, hopefully.
+% \begin{macro}{\notetitle@stylesetup@article}
+% Technical note. Here, by using a |tabular| environment for authors, we need
+% to assume that the macro |\notetitleauthorfont| takes one argument and does
+% not leave the author contents surrounded with full braces. This would cause
+% `|\\|' tokens enclosed in the protective braces to cause errors in the
+% tabular environment.
+%
+% \begin{macrocode}
+\let\notetitle@style@article\notetitle@style@default
+\newcommand{\notetitle@stylesetup@article}{
+ %\def\notetitletopspace{-3em}
+ \def\notetitlebottomspace{2.5em}
+ \def\notetitleinnervsep{1.5em}
+ \def\notetitlefont{}
+ \def\notetitlefontparsetup{%
+ \LARGE\centering}
+ \long\def\notetitleauthorfontparsetup##1{%
+ \notetitledonextvskip%
+ {\large\centering
+ \lineskip .5em\relax%
+ \begin{tabular}[t]{c}%
+ ##1%
+ \end{tabular}\par}}
+ \long\def\notetitleauthorfont##1{\large ##1}
+ \def\notetitledatefontparsetup{%
+ \notetitledonextvskip
+ \centering}
+ \def\phfnote@mpfootnotes@fontparsetup{}
+ \def\notetitleusemainbox##1{%
+ \par
+ \box##1%
+ }
+ \appto\notetitle@default@setup{%
+ %\def\singlespace{}%
+ }
+ %
+ \notetitleusempfootnotesfalse
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\notetitle@style@articlev1}
+% Backwards compatibility style |articlev1|.
% \begin{macrocode}
-\newcommand{\notetitle@style@article}{%
+\csdef{notetitle@style@articlev1}{%
\vspace*{-3em}%
\begingroup
\centering
@@ -1329,12 +2161,11 @@
%
% \subsubsection{Plugging into \phfverb{\maketitle}}
%
-% Actually perform the definitions to make |\maketitle| produce the
-% title with the given style. Specifically, we override
-% |\@maketitle|. The latter is called internally by |\maketitle|, and
-% the advantage of overriding |\@maketitle| only is that we inherit
-% the mechanism provided by the style class to deal with two-column
-% layouts.
+% Actually perform the definitions to make |\maketitle| produce the title with
+% the given style. Specifically, we override |\@maketitle|. The latter is
+% called internally by |\maketitle|, and the advantage of overriding
+% |\@maketitle| only is that we inherit the mechanism provided by the original
+% class (e.g., |article|) to deal with two-column layouts.
%
% \begin{macro}{\phfnote@do@notetitle}
% This macro takes care of installing the correct title into the
@@ -1346,34 +2177,49 @@
% \begin{macrocode}
\def\phfnote@do@notetitle#1{
% \end{macrocode}
-% If we have an empty title style, then we leave default title provided by the class.
+% If we have the title style |false|, or an empty title style, then we leave
+% default title provided by the class.
% \begin{macrocode}
- \if\relax\detokenize\expandafter{#1}\relax
- \else
+ \ifstrequal{#1}{false}{}{%
+ \if\relax\detokenize\expandafter{#1}\relax
+ \else
% \end{macrocode}
% Otherwise, we have a title style to set. Do some checks that the given style is indeed
% defined.
% \begin{macrocode}
- \ifcsname notetitle@style@#1\endcsname
- \def\phfnote@tmp@titsty{#1}%
- \else
- \PackageError{phfnote}{Unknown title style: '#1'.}{Unknown title
- style: '#1'. Please consult the package documentation for available
- styles.}
- \def\phfnote@tmp@titsty{default}%
- \fi
+ \ifcsname notetitle@style@#1\endcsname
+ \def\phfnote@tmp@titsty{#1}%
+ \else
+ \PackageError{phfnote}{Unknown title style: '#1'.}{Unknown title
+ style: '#1'. Please consult the package documentation for available
+ styles.}
+ \def\phfnote@tmp@titsty{default}%
+ \fi
% \end{macrocode}
% Apply new (default) definitions of |\thanks|, |\thanksmark| and |\title|. Do this here
% only, because this can clash with more complicated versions from, e.g., \RevTeX.
% \begin{macrocode}
- \let\title\notetitle@title
- \let\thanks\notetitle@thanks
- \let\thanksmark\notetitle@thanksmark
+ \let\title\notetitle@title
+ \let\thanks\notetitle@thanks
+ \let\thanksmark\notetitle@thanksmark
% \end{macrocode}
-% Now, actually overload the title style by redefining |\@maketitle|.
+% Also, LaTeX initializes |\@author| with code that generates a warning that no
+% author is given. We don't want that. It's perfectly fine not to have an
+% author, and in this case this must be empty so that our title routines can
+% properly handle this case.
% \begin{macrocode}
- \def\@maketitle{\csname notetitle@style@\phfnote@tmp@titsty\endcsname}
- \fi
+ \def\@author{}%
+% \end{macrocode}
+% Now, actually overload the title style by redefining |\@maketitle|. Also, if
+% the style defines a ``setup'' macro |\notetitle@stylesetup@...|, then we
+% invoke it.
+% \begin{macrocode}
+ \ifcsname notetitle@stylesetup@\phfnote@tmp@titsty\endcsname
+ \csname notetitle@stylesetup@\phfnote@tmp@titsty\endcsname
+ \fi
+ \def\@maketitle{\csname notetitle@style@\phfnote@tmp@titsty\endcsname}%
+ \fi
+ }%
}
% \end{macrocode}
% \end{macro}
@@ -1487,12 +2333,14 @@
% This helper both defines the |abstract| environment, and also sets the abstract
% attributes. This macro will be called according to the package options.
%
-% |#1| = a comma-separated list of attributes.
+% |#1| = a comma-separated list of attributes, or the string |false|.
% \begin{macrocode}
-\def\phfnote@do@noteabstract#1{
- \let\abstract\noteabstract
- \let\endabstract\endnoteabstract
- \phfnote@internal@execattribs{noteabstract@attr@}{abstract attribute}{#1}
+\def\phfnote@do@noteabstract#1{%
+ \ifstrequal{#1}{false}{}{%
+ \let\abstract\noteabstract
+ \let\endabstract\endnoteabstract
+ \phfnote@internal@execattribs{noteabstract@attr@}{abstract attribute}{#1}
+ }%
}
% \end{macrocode}
% \end{macro}
@@ -1570,6 +2418,8 @@
%
% \begin{macro}{\phfnote@pagegeomstyle@xwide}
% Extra wide.
+%
+% \changedreftext{chg-pagegeom-xwide}
% \begin{macrocode}
\def\phfnote@pagegeomstyle@xwide{
\if@twocolumn
@@ -1577,6 +2427,20 @@
\else
% fix the margins a bit to make text wider
\ifcase\@ptsize% mods for 10 pt
+ \PassOptionsToPackage{hmargin=1in,vmargin=1in}{geometry}%
+ \or% mods for 11 pt
+ \PassOptionsToPackage{hmargin=1in,vmargin=1in}{geometry}%
+ \or% mods for 12 pt
+ \PassOptionsToPackage{hmargin=0.75in,vmargin=1in}{geometry}%
+ \fi%
+ \fi
+}
+\csdef{phfnote@pagegeomstyle@xwidev1}{
+ \if@twocolumn
+ \PassOptionsToPackage{hmargin=0.5in,vmargin=0.5in,includeheadfoot}{geometry}%
+ \else
+ % fix the margins a bit to make text wider
+ \ifcase\@ptsize% mods for 10 pt
\PassOptionsToPackage{hmargin=1in,vmargin=1.25in}{geometry}%
\or% mods for 11 pt
\PassOptionsToPackage{hmargin=1in,vmargin=1.25in}{geometry}%
@@ -1588,6 +2452,7 @@
% \end{macrocode}
% \end{macro}
%
+%
% \begin{macro}{\phfnote@pagegeomstyle@bigmargin}
% |bigmargin| style.
% \begin{macrocode}
@@ -1609,17 +2474,21 @@
% \end{macro}
%
%
-% \begin{macro}{\phfnote@do@pagegeomdefs}
-% Finally, provide a helper to set the page geometry. Just call the right macro.
-% \begin{macrocode}
-\newcommand{\phfnote@do@pagegeomdefs}[1]{
- \ifcsname phfnote@pagegeomstyle@#1\endcsname
- \csname phfnote@pagegeomstyle@#1\endcsname
- \else
- \PackageWarning{phfnote}{Unknown page geometry style: `#1'!}
- \fi
-
- \RequirePackage{geometry}%
+% \begin{macro}{\phfnote@do@pagegeom}
+% Finally, provide a helper to set the page geometry. Just call the right
+% macro. If the argument is |false|, don't do anything.
+% \begin{macrocode}
+\newcommand{\phfnote@do@pagegeom}[1]{
+ \ifstrequal{#1}{false}{}{%
+ \message{phfnote: Setting page geometry style #1}%
+ \ifcsname phfnote@pagegeomstyle@#1\endcsname
+ \csname phfnote@pagegeomstyle@#1\endcsname
+ \else
+ \PackageWarning{phfnote}{Unknown page geometry style: `#1'!}%
+ \fi
+ %
+ \RequirePackage{geometry}%
+ }%
}
% \end{macrocode}
% \end{macro}
@@ -1639,36 +2508,38 @@
% Also set an |\emergencystretch| so that lines get spaced out for underfull boxes,
% rather than overflowing far into the margin.
% \begin{macrocode}
-\def\phfnote@do@spacing{
- \@ifpackageloaded{setspace}{
- \def\phfnote@dostretch##1{%
- \setstretch{##1}\phfnote@docaptionstretch{##1}}
- }{
- \def\phfnote@dostretch##1{%
- \renewcommand\baselinestretch{##1}\phfnote@docaptionstretch{##1}}
- }
- \@ifpackageloaded{caption}{
- \def\phfnote@docaptionstretch##1{\captionsetup{font={stretch=##1}}}
- }{
- \def\phfnote@docaptionstretch##1{\PackageWarning{phfnote}{Can't
- set line spacing for captions, because the package `caption'
- is not loaded. Please load it before `phfnote', or use an
- appropriate (e.g. `rich') pkgset which loads this package
- automatically .}}
- }
- \if@twocolumn
- \phfnote@dostretch{1.0} % leave default
- \emergencystretch=3em\relax
- \else
- \ifcase\@ptsize% 10pt
- \phfnote@dostretch{1.1}
- \or% 11pt
- \phfnote@dostretch{1.0} % 1.05? better 1.0...
- \or% 12pt
- \phfnote@dostretch{1.0} % 1.03? not really noticeable...
+\def\phfnote@do@spacingdefs#1{
+ \ifstrequal{#1}{false}{}{%
+ \@ifpackageloaded{setspace}{
+ \def\phfnote@dostretch##1{%
+ \setstretch{##1}\phfnote@docaptionstretch{##1}}
+ }{
+ \def\phfnote@dostretch##1{%
+ \renewcommand\baselinestretch{##1}\phfnote@docaptionstretch{##1}}
+ }
+ \@ifpackageloaded{caption}{
+ \def\phfnote@docaptionstretch##1{\captionsetup{font={stretch=##1}}}
+ }{
+ \def\phfnote@docaptionstretch##1{\PackageWarning{phfnote}{Can't
+ set line spacing for captions, because the package `caption'
+ is not loaded. Please load it before `phfnote', or use an
+ appropriate pkgset (e.g. `rich') which loads this package
+ automatically.}}
+ }
+ \if@twocolumn
+ \phfnote@dostretch{1.0} % leave default
+ \emergencystretch=3em\relax
+ \else
+ \ifcase\@ptsize% 10pt
+ \phfnote@dostretch{1.1}
+ \or% 11pt
+ \phfnote@dostretch{1.0} % 1.05? better 1.0...
+ \or% 12pt
+ \phfnote@dostretch{1.0} % 1.03? not really noticeable...
+ \fi
+ \emergencystretch=6em\relax
\fi
- \emergencystretch=6em\relax
- \fi
+ }
}
% \end{macrocode}
% \end{macro}
@@ -1702,11 +2573,13 @@
% |skip|.
% \begin{macrocode}
\def\phfnote@do@par#1{%
- \ifcsname phfnote@par@#1\endcsname
- \csname phfnote@par@#1\endcsname
- \else
- \PackageWarning{phfnote}{Bad paragraph setting: #1. Leaving original}
- \fi
+ \ifstrequal{#1}{false}{}{%
+ \ifcsname phfnote@par@#1\endcsname
+ \csname phfnote@par@#1\endcsname
+ \else
+ \PackageWarning{phfnote}{Bad paragraph setting: #1. Leaving original}
+ \fi
+ }
}
% \end{macrocode}
% \end{macro}
@@ -1836,12 +2709,14 @@
%
%
% \begin{macro}{\phfnote@do@secfmt}
-% Actually perform the required styling, according to the package
-% options given as argument. The argument is a comma-separated list
-% of attributes specified by the user.
+% Actually perform the required styling, according to the package options
+% given as argument. The argument is a comma-separated list of attributes
+% specified by the user, or the string |false|.
% \begin{macrocode}
\def\phfnote@do@secfmt#1{%
- \phfnote@internal@execattribs{phfnote@do@secfmt@}{section formatting preset}{#1}
+ \ifstrequal{#1}{false}{}{%
+ \phfnote@internal@execattribs{phfnote@do@secfmt@}{section formatting preset}{#1}%
+ }
}
% \end{macrocode}
% \end{macro}
@@ -1877,6 +2752,12 @@
}
+
+\def\phfnote@internal@setifxeorlua#1#2{%
+ \ifXeTeX\let#1#2\fi
+ \ifLuaTeX\let#1#2\fi
+}
+
\def\phfnote@do@pkgset@rich{
\phfnote@do@pkgset@minimal
@@ -1884,18 +2765,43 @@
\RequirePackage{setspace}
\RequirePackage{caption}
- \RequirePackage{microtype}
-
\PassOptionsToPackage{shortlabels}{enumitem}
\RequirePackage{enumitem}
\RequirePackage{graphicx}
- \PassOptionsToPackage{T1}{fontenc}
- \RequirePackage{fontenc}
+% \end{macrocode}
+% For this bit, use the \pkgname{iftex} package to determine if we're running
+% XeTeX or LuaTeX; if that's the case then we inhibit the loading of
+% \pkgname{inputenc} and \pkgname{fontenc}. The |\IfFileExists| is to ensure
+% the package runs on older LaTeX distributions without \pkgname{iftex}.
+%
+% Plus, load \pkgname{inputenc}, resp. \pkgname{fontenc}, only if it isn't
+% already loaded.
+%
+% \changedreftext{chg-xe-luatex-input-fontenc-pkgset}
+% \begin{macrocode}
+ \def\phfnote@tmp@requireinputencfontenc{
+ \@ifpackageloaded{fontenc}{}{
+ \PassOptionsToPackage{T1}{fontenc}
+ \RequirePackage{fontenc}
+ }
+ \@ifpackageloaded{inputenc}{}{
+ \PassOptionsToPackage{utf8}{inputenc}
+ \RequirePackage{inputenc}
+ }
+ }
+ \IfFileExists{iftex.sty}{
+ \RequirePackage{iftex}
+ \phfnote@internal@setifxeorlua\phfnote@tmp@requireinputencfontenc\relax
+ }{}
+ \phfnote@tmp@requireinputencfontenc
- \PassOptionsToPackage{utf8}{inputenc}
- \RequirePackage{inputenc}
+% \end{macrocode}
+%
+% Load \pkgname{microtype} after \pkgname{fontenc} (just in case).
+% \begin{macrocode}
+ \RequirePackage{microtype}
}
\def\phfnote@do@pkgset@extended{
@@ -1937,58 +2843,121 @@
% The name `|docnotelinkcolor|' is historical and hard-coded in many
% other files I've used, so I'm DEFINITELY NOT changing it.
% \end{pkgnote}
-%
-% \needspace{3\baselineskip}
-% \begin{macro}{\phfnote@do@pdfhyperrefdefs}
-% \begin{macro}{\email}
-% \begin{macro}{\url}
-% Load the \pkgname{hyperref} package and provide sensible defaults.
+%
+%
+%
+% Helpers---default set of hyperref options, and other helper macros.
% \begin{macrocode}
-\newcommand{\phfnote@do@pdfhyperrefdefs}{%
+\def\phfnote@hyperrefdefs@val@options{%
+ bookmarksnumbered=false,bookmarksopen=false,bookmarksopenlevel=1,%
+ breaklinks=true,pdfborder={0 0 0},colorlinks=true,%
+ anchorcolor=docnotelinkcolor,citecolor=docnotelinkcolor,%
+ filecolor=docnotelinkcolor,linkcolor=docnotelinkcolor,%
+ menucolor=docnotelinkcolor,runcolor=docnotelinkcolor,%
+ urlcolor=docnotelinkcolor%
+}%
+\def\phfnote@hyperrefdefs@deferredhypersetup#1{%
+ \AtBeginDocument{%
+ \@ifpackageloaded{hyperref}{%
+ \hypersetup{#1}%
+ }{%
+ \PackageWarning{phfnote}{\MessageBreak\MessageBreak
+ *** package `hyperref` was not loaded ***\MessageBreak
+ Since you specified `hyperrefdefs=defer`, I was expecting you would call
+ `\string\usepackage{hyperref}` at some point later in your preamble, but
+ it does not appear you did so. Your document might look weird.}%
+ }%
+ }%
+}
+\providecommand\phfnote@hyperrefdefs@dopkgoptions{%
+ \PassOptionsToPackage{unicode=true}{hyperref}
+}
+\def\phfnote@hyperrefdefs@loadhyperref{%
+ \phfnote@hyperrefdefs@dopkgoptions
+ \RequirePackage{hyperref}}
+\def\phfnote@hyperrefdefs@provideemail{\let\email\phfnote@email}
+\def\phfnote@eqref#1{%
+ \hyperref[{#1}]{\textup{\tagform@{\ref*{#1}}}}%
+}
+\def\phfnote@hyperrefdefs@redefeqref{%
+ \let\eqref\phfnote@eqref
+}
+\def\phfnote@hyperrefdefs@afterhook{}
% \end{macrocode}
-% Make sure a color-managing package is loaded, {color} or {xcolor}, and define our default color:
+%
+% Define the attributes that can be set for hyperref-related options. See
+% \autoref{sec:hyperrefdefs}.
+%
% \begin{macrocode}
- \phfnote@requirecolorpackage%
- \definecolor{docnotelinkcolor}{rgb}{0,0,0.4}%
+\def\phfnote@do@hyperrefdefs@attr@true{}% for explicit value "hyperrefdefs=true"
+\def\phfnote@do@hyperrefdefs@attr@defer{
+ \def\phfnote@hyperrefdefs@loadhyperref{%
+ \phfnote@hyperrefdefs@dopkgoptions
+ \let\hypersetup\phfnote@hyperrefdefs@deferredhypersetup}
+}
+\def\phfnote@do@hyperrefdefs@attr@clearoptions{
+ \def\phfnote@hyperrefdefs@val@options{}
+}
+\def\phfnote@do@hyperrefdefs@attr@noemail{
+ \def\phfnote@hyperrefdefs@provideemail{}
+}
+\def\phfnote@do@hyperrefdefs@attr@noeqref{
+ \def\phfnote@hyperrefdefs@redefeqref{}
+}
+\def\phfnote@do@hyperrefdefs@attr@noload{
+ \def\phfnote@hyperrefdefs@loadhyperref{}
+ \def\phfnote@hyperrefdefs@redefeqref{}
+ \let\hypersetup\@gobble
+}
% \end{macrocode}
-%
-% Load URL package, and save a version of |\url| which is not patched
-% by \pkgname{hyperref}:
+%
+%
+% \begin{macro}{\phfnote@do@hyperrefdefs}
+% \begin{macro}{\email}
+% \begin{macro}{\url}
+% Do all stuff related to hyperref.
% \begin{macrocode}
- \RequirePackage{url}%
- \DeclareUrlCommand\phfnote@format@url{}%
+\def\phfnote@do@hyperrefdefs#1{%
+ \ifstrequal{#1}{false}{}{%
% \end{macrocode}
-%
-% Set up \pkgname{hyperref} options:
+% Make sure a color-managing package is loaded, {color} or {xcolor}, and define
+% our default link color:
% \begin{macrocode}
- \PassOptionsToPackage{bookmarks=true,backref=false}{hyperref}%
- \RequirePackage{hyperref}%
- %
- \hypersetup{unicode=true,%
- bookmarksnumbered=false,bookmarksopen=false,bookmarksopenlevel=1,%
- breaklinks=true,pdfborder={0 0 0},colorlinks=true}%
- \hypersetup{%
- anchorcolor=docnotelinkcolor,citecolor=docnotelinkcolor,%
- filecolor=docnotelinkcolor,linkcolor=docnotelinkcolor,%
- menucolor=docnotelinkcolor,runcolor=docnotelinkcolor,%
- urlcolor=docnotelinkcolor}%
+ \phfnote@requirecolorpackage%
+ \definecolor{docnotelinkcolor}{rgb}{0,0,0.4}%
% \end{macrocode}
-%
-% Provide an |\email| command for specifying e-mails. Note that the |\url| command is
-% already provided by the packages \pkgname{url} and \pkgname{hyperref}.
+% Load the \pkgname{url} package, and save a version of |\url| which is not
+% patched by \pkgname{hyperref} to format URLs, and provide |\phfnoteEmail| for
+% emails (not |\email| right away because it might conflict with RevTeX. Provide
+% |\email| later after parsing attribs):
% \begin{macrocode}
- \let\email\phfnote@email%
+ \RequirePackage{url}%
+ \DeclareUrlCommand\phfnote@format@url{}%
+ \let\phfnoteEmail\phfnote@email
% \end{macrocode}
-%
-% And finally set a nicer default |\url|/|\email| style:
+%
+% Set up everything according to the user's selected attributes.
+% \begin{macrocode}
+ \phfnote@internal@execattribs{phfnote@do@hyperrefdefs@attr@}{%
+ phfnote hyperref-related option}{#1}%
+% \end{macrocode}
+%
+% And now, load the hyperref package (or don't, if it's deferred), and set some
+% options.
% \begin{macrocode}
- \urlstyle{notesf}%
+ \phfnote@hyperrefdefs@loadhyperref
+ \expandafter\hypersetup\expandafter{\phfnote@hyperrefdefs@val@options}
+ \phfnote@hyperrefdefs@provideemail
+ \phfnote@hyperrefdefs@redefeqref
+ \urlstyle{notesf}
+ \phfnote@hyperrefdefs@afterhook
+ }
}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
-%
+%
% \begin{macro}{\phfnotePdfLinkColor}
% Set links color. Use as |\phfnotePdfLinkColor|\marg{color}.
% Color may be any color name or specification recognized by the
@@ -1999,8 +2968,8 @@
\@ifpackageloaded{xcolor}{%
\colorlet{docnotelinkcolor}{#1}%
}{% else:
- \PackageWarning{phfnote}{\protect\phfnotePdfLinkColor may only be
- used if the package xcolor is loaded.}%
+ \PackageError{phfnote}{\protect\phfnotePdfLinkColor may only be
+ used if the package xcolor is loaded.}{}%
}%
}
% \end{macrocode}
@@ -2014,9 +2983,12 @@
% Provide base macros to be able to build up |\email| command for emails and other
% URL-like commands which should sanitize their arguments.
%
-% Also prepare the command |\phfnote@email| which will be renamed |\email| in our
+% Also prepare the command |\phfnoteEmail| which will be renamed |\email| in our
% \pkgname{hyperref} package setup (see above).
%
+% NOTE: The commands |\phfnote@email| and |\phfnote@format@url| will only work
+% if you don't have |hyperrefdefs=false|. They will work with
+% |hyperrefdefs=noload| if you don't want to load the |hyperref| package.
% \begin{macrocode}
\def\phfnote@sanitize@url{%
\catcode`\$12%
@@ -2029,7 +3001,6 @@
% \catcode`\^^M10% newline = space
\relax%
}%
-\providecommand\phfnote@format@url{\texttt}
\def\phfnote@email{\begingroup\phfnote@sanitize@url\phfnote@impl@email@}%
\def\phfnote@impl@email@#1{\endgroup\href{mailto:#1}{\phfnote@format@url{#1}}}%
% \end{macrocode}
@@ -2040,8 +3011,9 @@
%
%
% \begin{macro}{\phfnote@requirecolorpackage}
-% And finally define an internal utility to make sure that a color package (either
-% \pkgname{color} or \pkgname{xcolor}) is loaded. If none are loaded, the \pkgname{xcolor} package is loaded.
+% And finally define an internal utility to make sure that a color package
+% (either \pkgname{color} or \pkgname{xcolor}) is loaded. If none are loaded,
+% the \pkgname{xcolor} package is loaded.
% \begin{macrocode}
\def\phfnote@requirecolorpackage{%
\@ifpackageloaded{color}{%
@@ -2063,14 +3035,22 @@
% encoding which is better. Also, use Computer Modern Bright as
% sans-serif font by default instead of Computer Modern Sans Serif.
%
-% \begin{macrocode}
-\def\phfnote@do@fontdefs{
-
- \PassOptionsToPackage{T1}{fontenc}
- \RequirePackage{fontenc}
-
- \renewcommand\sfdefault{cmbr}
-
+% If on Xe\TeX{} or Lua\TeX{}, don't do anything.
+%
+% \begin{macrocode}
+\def\phfnote@do@fontdefs#1{
+ \ifstrequal{#1}{false}{}{%
+ \let\phfnote@tmp@do\@firstofone
+ \IfFileExists{iftex.sty}{%
+ \RequirePackage{iftex}%
+ \phfnote@internal@setifxeorlua\phfnote@tmp@do\@gobble
+ }{}
+ \phfnote@tmp@do{
+ \PassOptionsToPackage{T1}{fontenc}
+ \RequirePackage{fontenc}
+ \renewcommand\sfdefault{cmbr}
+ }
+ }
}
% \end{macrocode}
% \end{macro}
@@ -2127,6 +3107,11 @@
% \begin{macrocode}
\providecommand\eprint[2][]{\href{http://arxiv.org/abs/##2}{arXiv:##2}}
% \end{macrocode}
+%
+% Fix for RevTeX styles that use |\doibase| with a newline following them ---
+% \begin{macrocode}
+ \providecommand\doibase{\phfnote@doibasefix}
+% \end{macrocode}
%
% Relay the call to the ``old'' |\bibliography| command to actually implement the
% bibliography.
@@ -2134,6 +3119,7 @@
\phfnote@old@bibliography{#1}%
\endgroup%
}
+\def\phfnote@doibasefix#110.{https://doi.org/10.}
% \end{macrocode}
% \end{macro}
% \begin{macro}{\phfnote@bibliographystyle}
@@ -2153,9 +3139,11 @@
% \begin{macro}{\phfnote@do@bibliographydefs}
% Make our changes live. Will be called later according to package options.
% \begin{macrocode}
-\def\phfnote@do@bibliographydefs{%
- \let\bibliographystyle\phfnote@bibliographystyle%
- \let\bibliography\phfnote@bibliography%
+\def\phfnote@do@bibliographydefs#1{%
+ \ifstrequal{#1}{false}{}{%
+ \let\bibliographystyle\phfnote@bibliographystyle%
+ \let\bibliography\phfnote@bibliography%
+ }
}
% \end{macrocode}
% \end{macro}
@@ -2168,14 +3156,16 @@
% Adjust the formatting of footnotes so they look better. Again,
% this is called later according to the package options.
% \begin{macrocode}
-\def\phfnote@do@footnotedefs{
- \let\phfnote@orig@makefnmark\@makefnmark
-%% \def\@makefnmark{\hbox{\@textsuperscript{%
-%% \normalfont\tiny\fontseries{sb}\selectfont\@thefnmark}}}
- \def\@makefnmark{\hbox{\@textsuperscript{%
- \normalfont\tiny\bfseries\@thefnmark}}}
-%% \def\@makefnmark{\hbox{\@textsuperscript{%
-%% \normalfont\scriptsize\bfseries\@thefnmark}}}% too large
+\def\phfnote@do@footnotedefs#1{
+ \ifstrequal{#1}{false}{}{%
+ \let\phfnote@orig@makefnmark\@makefnmark
+%% \def\@makefnmark{\hbox{\@textsuperscript{%
+%% \normalfont\tiny\fontseries{sb}\selectfont\@thefnmark}}}
+ \def\@makefnmark{\hbox{\@textsuperscript{%
+ \normalfont\tiny\bfseries\@thefnmark}}}
+%% \def\@makefnmark{\hbox{\@textsuperscript{%
+%% \normalfont\scriptsize\bfseries\@thefnmark}}}% too large
+ }
}
% \end{macrocode}
% \end{macro}
@@ -2240,6 +3230,11 @@
%
% \end{macro}
%
+% \subsubsection{Inline commenting in documents}
+%
+% The code that was initially here was moved into a separate package:
+% \pkgname{phfcc}.
+%
% \subsubsection{URL Styles}
%
% \needspace{7\baselineskip}
@@ -2416,7 +3411,7 @@
\csname phfnote@restoredefs@#1\endcsname%
\else%
\PackageError{phfnote}{\string\phfnoteRestoreDefs: no such
- definitions stored (#1)}
+ definitions stored (#1)}{}
\fi%
}
% \end{macrocode}
@@ -2455,96 +3450,121 @@
% \end{macrocode}
%
%
-% The title style to use. \marginpar{\raggedleft \phfverb{[title=...]}}
+% The title style to use. \PrintMarginLabel{[title=...]}
% See \autoref{sec:title-styles}.
% \begin{macrocode}
\DeclareStringOption[default]{title}
+\DeclareVoidOption{notitle}{\def\phfnote@opt@title{false}}
% \end{macrocode}
%
%
-% Option for abstract attributes \marginpar{\raggedleft
-% \phfverb{[abstract=...]}} (\autoref{sec:abstract-attributes}).
+% Option for abstract attributes \PrintMarginLabel{[abstract=...]}
+% (\autoref{sec:abstract-attributes}).
% \begin{macrocode}
\DeclareStringOption[]{abstract}
+\DeclareVoidOption{noabstract}{\def\phfnote@opt@abstract{false}}
% \end{macrocode}
%
-% Option for Package sets \marginpar{\raggedleft \phfverb{[pkgset=...]}}
+% Option for Package sets \PrintMarginLabel{[pkgset=...]}
% (\autoref{sec:package-sets})
% \begin{macrocode}
\DeclareStringOption[rich]{pkgset}
% \end{macrocode}
%
-% Define the page geometry. \marginpar{\raggedleft
-% \phfverb{[pagegeomdefs=...]}} \marginpar{\raggedleft \phfverb{[pagegeom=...]}}
-% See \autoref{sec:pagegeomdefs}.
+% Define the page geometry. \PrintMarginLabel{[pagegeomdefs=...]}
+% \PrintMarginLabel{[pagegeom=...]} See \autoref{sec:pagegeomdefs}.
+% \begin{macrocode}
+\DeclareStringOption[default]{pagegeom}
+\DeclareVoidOption{nopagegeom}{\def\phfnote@opt@pagegeom{false}}
+% \end{macrocode}
+%
+% Obsolete options---
% \begin{macrocode}
\DeclareBoolOption[true]{pagegeomdefs}
\DeclareComplementaryOption{nopagegeomdefs}{pagegeomdefs}
-\DeclareStringOption[default]{pagegeom}
% \end{macrocode}
+% ---we handle these as follows. By default, |\ifphfnote@opt@pagegeomdefs| is
+% true. If it isn't, that means it was overridden and we need to respect that.
%
%
-%
-% Styling of section headings. \marginpar{\raggedleft \phfverb{[secfmt=...]}}
+% Styling of section headings. \PrintMarginLabel{[secfmt=...]}
% See \autoref{sec:secfmt}.
% \begin{macrocode}
\DeclareStringOption[section]{secfmt}
+\DeclareVoidOption{nosecfmt}{\def\phfnote@opt@secfmt{false}}
% \end{macrocode}
%
-% How to treat paragraphs. \marginpar{\raggedleft \phfverb{[par=...]}} See
+% How to treat paragraphs. \PrintMarginLabel{[par=...]} See
% \autoref{sec:par-defs}.
% \begin{macrocode}
\DeclareStringOption[skip]{par}
+\DeclareVoidOption{nopar}{\def\phfnote@opt@par{false}}
% \end{macrocode}
%
-% Add definitions to adjust spacing of lines and words. \marginpar{\raggedleft
-% \phfverb{[spacingdefs=...]}} See \autoref{sec:spacingdefs}.
+% Add definitions to adjust spacing of lines and
+% words. \PrintMarginLabel{[spacingdefs=...]} See \autoref{sec:spacingdefs}.
% \begin{macrocode}
-\DeclareBoolOption[true]{spacingdefs}
-\DeclareComplementaryOption{nospacingdefs}{spacingdefs}
+\DeclareStringOption[true]{spacingdefs}[true]
+\DeclareVoidOption{nospacingdefs}{\def\phfnote@opt@spacingdefs{false}}
% \end{macrocode}
%
-% Do some adjustments to the fonts. \marginpar{\raggedleft
-% \phfverb{[fontdefs=...]}} See \autoref{sec:fontdefs}.
+%
+% Do some adjustments to the fonts. \PrintMarginLabel{[fontdefs=...]} See
+% \autoref{sec:fontdefs}.
% \begin{macrocode}
-\DeclareBoolOption[true]{fontdefs}
-\DeclareComplementaryOption{nofontdefs}{fontdefs}
+\DeclareStringOption[true]{fontdefs}[true]
+\DeclareVoidOption{nofontdefs}{\def\phfnote@opt@fontdefs{false}}
% \end{macrocode}
%
-% Adjustments for footnotes. \marginpar{\raggedleft
-% \phfverb{[footnotedefs=...]}} See \autoref{sec:footnotedefs}.
+% Adjustments for footnotes. \PrintMarginLabel{[footnotedefs=...]} See
+% \autoref{sec:footnotedefs}.
% \begin{macrocode}
-\DeclareBoolOption[true]{footnotedefs}
-\DeclareComplementaryOption{nofootnotedefs}{footnotedefs}
+\DeclareStringOption[true]{footnotedefs}[true]
+\DeclareVoidOption{nofootnotedefs}{\def\phfnote@opt@footnotedefs{false}}
% \end{macrocode}
%
-% Load hyperref and corresponding definitions. \marginpar{\raggedleft
-% \phfverb{[hyperrefdefs=...]}} See \autoref{sec:hyperrefdefs}.
+% Load \pkgname{hyperref} and corresponding
+% definitions. \PrintMarginLabel{[hyperrefdefs=...]} See
+% \autoref{sec:hyperrefdefs}.
% \begin{macrocode}
-\DeclareBoolOption[true]{hyperrefdefs}
-\DeclareComplementaryOption{nohyperrefdefs}{hyperrefdefs}
+\DeclareStringOption[]{hyperrefdefs}[]
+\DeclareVoidOption{nohyperrefdefs}{\def\phfnote@opt@hyperrefdefs{false}}
% \end{macrocode}
%
-% Adjustments for bibliography, including default style. \marginpar{\raggedleft
-% \phfverb{[bibliographydefs=...]}} See \autoref{sec:bibliographydefs}.
+% Adjustments for bibliography, including default
+% style. \PrintMarginLabel{[bibliographydefs=...]} See
+% \autoref{sec:bibliographydefs}.
% \begin{macrocode}
-\DeclareBoolOption[true]{bibliographydefs}
-\DeclareComplementaryOption{nobibliographydefs}{bibliographydefs}
+\DeclareStringOption[true]{bibliographydefs}[true]
+\DeclareVoidOption{nobibliographydefs}{\def\phfnote@opt@bibliographydefs{false}}
% \end{macrocode}
%
-%
-% Preset option. \marginpar{\raggedleft \phfverb{[preset=...]}} See
-% \autoref{sec:presets}.
+% \begin{macro}{\phfnote@loadpreset}
+% A helper macro to load presets. Can be used by presets that want to extend
+% other presets.
% \begin{macrocode}
-\define@key{phfnote}{preset}{%
- \ifcsname phfnote@preset@#1\endcsname%
- \csname phfnote@preset@#1\endcsname%
- \else%
- \PackageError{phfnote}{Unknown preset: `#1'!}{You specified the
- option 'preset=...' with an invalid value. Please look up the
- package documentation corresponding to your version of phfnote
- for possible values.}
+\def\phfnote@loadpreset#1{%
+ \IfFileExists{phfnotepreset-#1.def}{%
+ \input{phfnotepreset-#1.def}%
+ }{%
+ \ifcsname phfnote@preset@#1\endcsname%
+ \csname phfnote@preset@#1\endcsname%
+ \else%
+ \PackageError{phfnote}{Unknown preset: `#1'!}{You specified the
+ option 'preset=...' with an invalid value. Please look up the
+ package documentation corresponding to your version of phfnote
+ for possible values. Additionally, no file named `phfnotepreset-#1.def'
+ was found.}%
\fi%
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% Preset option. \PrintMarginLabel{[preset=...]} See \autoref{sec:presets}.
+% \begin{macrocode}
+\define@key{phfnote}{preset}{%
+ \phfnote@loadpreset{#1}%
}
% \end{macrocode}
%
@@ -2556,12 +3576,35 @@
}
% \end{macrocode}
%
+%
+%
+% Small utility to deal with obsolete |XXXdefs=true/false| options. If the
+% (obsolete) bool option |#1| is set to false (which means it was set
+% explicitly, so this must be respected), then emit a package warning and set
+% option |#2| (the regular option) to the string value |false|.
+% \begin{macrocode}
+\def\phfnote@ifpkgoptfalsesetfalse#1#2{%
+ \edef\x{%
+ \expandafter\noexpand\csname ifphfnote@opt@#1\endcsname\noexpand\else
+ \noexpand\PackageWarning{phfnote}{Option #1 is obsolete. Please use "#2=false'' instead.}%
+ \noexpand\csgdef{phfnote@opt@#2}{false}\noexpand\fi}%
+ \x
+}
+% \end{macrocode}
+%
% \subsubsection{Define Global Presets}
% \label{impl:presets}
%
% Define the global presets here. See \autoref{sec:presets} for a description
% of what these presets do.
%
+% Some of the presets whose definitions are short are defined here directly
+% here, in the |sty| file. Other presets are placed in a separate
+% |phfnotepreset-XXX.def| file to avoid bloating the main style file.
+%
+% \changed[chg-presets-dotdef-files]{v4.0}{2021/10/08}{Moved some presets to
+% external \phfverb{.def} files}
+%
% \begin{macro}{\phfnote@hook@atendload}
% A hook for presets to do stuff at the end of package load.
% \begin{macrocode}
@@ -2569,7 +3612,6 @@
% \end{macrocode}
% \end{macro}
%
-%
% \begin{macro}{\phfnote@preset@article}
% Article preset.
% \begin{macrocode}
@@ -2588,7 +3630,7 @@
\newcommand\phfnote@presetcommon@xnote[1][noteitsf]{
\def\phfnote@opt@title{default}
\def\phfnote@opt@par{skip}
- \phfnote@opt@pagegeomdefstrue
+ %\phfnote@opt@pagegeomdefstrue
\def\phfnote@opt@pagegeom{wide}
\setlength{\footnotesep}{5pt}
\g@addto@macro\phfnote@hook@atendload{
@@ -2610,8 +3652,8 @@
% \begin{macrocode}
\def\phfnote@preset@sfnote{
\phfnote@presetcommon@xnote
- \phfnote@opt@footnotedefstrue
- \phfnote@opt@fontdefstrue
+ \def\phfnote@opt@footnotedefs{true}
+ \def\phfnote@opt@fontdefs{true}
\renewcommand\familydefault{\sfdefault}
\renewcommand{\notesectionallfontfamily}{\sfdefault}
}
@@ -2619,11 +3661,11 @@
% \end{macrocode}
% set up all the settings as for |sfnote| \ldots
% \begin{macrocode}
- \phfnote@preset@sfnote
+ \phfnote@loadpreset{sfnote}%
% \end{macrocode}
% \ldots but override:
% \begin{macrocode}
- \phfnote@opt@fontdefsfalse
+ \def\phfnote@opt@fontdefs{false}
\PassOptionsToPackage{T1}{fontenc}
\RequirePackage{fontenc}
\renewcommand\sfdefault{cmss}
@@ -2632,19 +3674,19 @@
% \end{macrocode}
% set up all the settings as for |sfnote| \ldots
% \begin{macrocode}
- \phfnote@preset@sfnote
+ \phfnote@loadpreset{sfnote}%
% \end{macrocode}
% \ldots but override:
% \begin{macrocode}
- \phfnote@opt@fontdefsfalse
+ \def\phfnote@opt@fontdefs{false}
\PassOptionsToPackage{T1}{fontenc}
\RequirePackage{fontenc}
- \PassOptionsToPackage{default,osfigures,scale=0.9}{opensans}
+ \PassOptionsToPackage{default,scale=0.9}{opensans}
\RequirePackage{opensans}
}
\def\phfnote@preset@utopianote{
\phfnote@presetcommon@xnote[noteit]
- \phfnote@opt@fontdefsfalse
+ \def\phfnote@opt@fontdefs{false}
\PassOptionsToPackage{T1}{fontenc}
\RequirePackage{fontenc}
\RequirePackage{fourier}
@@ -2654,8 +3696,8 @@
}
\def\phfnote@preset@mnmynote{
\phfnote@presetcommon@xnote[noteit]
- \phfnote@opt@footnotedefsfalse
- \phfnote@opt@fontdefsfalse
+ \def\phfnote@opt@footnotedefs{false}
+ \def\phfnote@opt@fontdefs{false}
\PassOptionsToPackage{T1}{fontenc}
\RequirePackage{fontenc}
\renewcommand{\notesectionallfontfamily}{\sfdefault}
@@ -2680,7 +3722,6 @@
% \end{macro}
% \end{macro}
%
-%
% \begin{macro}{\phfnote@preset@pkgdoc}
% Preset for a package documentation.
%
@@ -2688,7 +3729,7 @@
% \begin{macrocode}
\def\phfnote@preset@pkgdoc{
\phfnote@presetcommon@xnote[noteit]
- \phfnote@opt@fontdefsfalse
+ \def\phfnote@opt@fontdefs{false}
% \end{macrocode}
%
% Then set up the font, which is done in a separate macro
@@ -2713,6 +3754,9 @@
% font. Override |\phfnote@pkgdoc@setupfont| to adjust the whole font
% set-up, or |\phfnote@pkgdoc@setupmainfont| to adjust only the main
% document font.
+%
+% \changed[chg-opensans-fosj]{v3.1}{2020/05/25}{Fixes for more recent
+% versions of the \pkgname{opensans} package.}
% \begin{macrocode}
\providecommand\phfnote@pkgdoc@setupfont{
\PassOptionsToPackage{T1}{fontenc}
@@ -2723,25 +3767,147 @@
\IfFileExists{opensans.sty}{}{\PackageError{phfnote}{Font OpenSans is not
available (need `opensans' package)}{Please install the opensans
package, which provides the OpenSans font.}}
- \def\opensans@scale{s*[0.85]}
- \renewcommand{\sfdefault}{fosj}
+ \PassOptionsToPackage{scale=0.85,defaultsans}{opensans}
+ \RequirePackage{opensans}
}
\providecommand\phfnote@pkgdoc@setupmainfont{\RequirePackage{fourier}}
% \end{macrocode}
% \end{macro}
+%
+% \begin{macro}{\phfnote@preset@reset}
+% Finally, the |reset| preset:
+% \begin{macrocode}
+\def\phfnote@preset@reset{
+ \def\phfnote@opt@pkgset{none}
+ \def\phfnote@opt@title{false}
+ \def\phfnote@opt@pagegeom{false}
+ \def\phfnote@opt@spacingdefs{false}
+ \def\phfnote@opt@par{false}
+ \def\phfnote@opt@abstract{false}
+ \def\phfnote@opt@hyperrefdefs{false}
+ \def\phfnote@opt@fontdefs{false}
+ \def\phfnote@opt@secfmt{false}
+ \def\phfnote@opt@bibliographydefs{false}
+ \def\phfnote@opt@footnotedefs{false}
+% \end{macrocode}
+%
+% \begin{pkgwarning}
+% NOTE TO SELF: DO NOT FORGET TO ADD HERE RESET COMMANDS FOR ANY NEW OPTION
+% THAT WE PROVIDE IN THE FUTURE.
+% \end{pkgwarning}
+%
+% \begin{macrocode}
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsubsection{Finally, Process and Execute the Package Options}
+%
+%
+%
+% Process the options:
+%
+% \begin{macrocode}
+\ProcessKeyvalOptions*
+% \end{macrocode}
+%
+%
+% Take action according to the user options.
+%
+% For the |pkgset| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@pkgset\expandafter{\phfnote@opt@pkgset}
+% \end{macrocode}
+%
+% For the |title| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@notetitle\expandafter{\phfnote@opt@title}
+% \end{macrocode}
+%
+% For the |abstract| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@noteabstract\expandafter{\phfnote@opt@abstract}
+% \end{macrocode}
+%
+% For the |secfmt| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@secfmt\expandafter{\phfnote@opt@secfmt}
+% \end{macrocode}
+%
+% For the |pagegeomdefs| option. Here, the first line is needed to deal with
+% the obsolete option `|pagegeom|'.
+% \begin{macrocode}
+\phfnote@ifpkgoptfalsesetfalse{pagegeomdefs}{pagegeom}
+\expandafter\phfnote@do@pagegeom\expandafter{\phfnote@opt@pagegeom}
+% \end{macrocode}
+%
+% For the |spacingdefs| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@spacingdefs\expandafter{\phfnote@opt@spacingdefs}
+% \end{macrocode}
+%
+% For the |par| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@par\expandafter{\phfnote@opt@par}
+% \end{macrocode}
+%
+% For the |hyperrefdefs| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@hyperrefdefs\expandafter{\phfnote@opt@hyperrefdefs}
+% \end{macrocode}
+%
+% For the |fontdefs| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@fontdefs\expandafter{\phfnote@opt@fontdefs}
+% \end{macrocode}
+%
+% For the |bibliographydefs| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@bibliographydefs\expandafter{\phfnote@opt@bibliographydefs}
+% \end{macrocode}
+%
+% For the |footnotedefs| option.
+% \begin{macrocode}
+\expandafter\phfnote@do@footnotedefs\expandafter{\phfnote@opt@footnotedefs}
+% \end{macrocode}
%
-% \begin{macro}{\phfnote@preset@xpkgdoc}
-% Same as |preset=pkgdoc|, but also provide some handy hacks and
-% commands.
+% Finally, execute the hook we set up for definitions at the end of the package
+% loading:
+% \begin{macrocode}
+\phfnote@hook@atendload
+% \end{macrocode}
+%
+%
+% \subsection{Helper files}
+%
+% Now we write some code to some external |.def| files for large chunks of code
+% that are only needed in specific situations, in order to avoid bloating the
+% main style file.
+%
+% \subsubsection{The \emph{xpkgdoc} preset}
+% \label{sec:impl-xpkgdoc}
+%
+% The |xpkgdoc| preset is based on the |pkgdoc| preset. It introduces multiple
+% pretty involved tools and definitions on top of |pkgdoc|; these are not needed
+% unless this preset is loaded. Let's write all of the corresponding
+% definitions into a separate |.def| file.
+%
+% \iffalse
+%</package>
+% \fi
+% \begin{verbatim}
+%<*phfnotepreset-xpkgdoc>
+% \end{verbatim}
%
+% Load the |pkgdoc| preset before anything else:
% \begin{macrocode}
-\def\phfnote@preset@xpkgdoc{
- \phfnote@preset@pkgdoc
+\phfnote@loadpreset{pkgdoc}
% \end{macrocode}
%
% Include the \pkgname{verbdef} package, because it's always useful.
% \begin{macrocode}
- \RequirePackage{verbdef}
+\RequirePackage{verbdef}
% \end{macrocode}
%
% \textbf{Some patching first:}
@@ -2751,71 +3917,106 @@
% |\PrintChangesAndIndex|, which calls both |\PrintChanges| and |\PrintIndex| with
% some additional spacing.
% \begin{macrocode}
- \ifdefined\PrintChanges
- \phfnoteHackSectionStarWithTOCInCommand\PrintChanges
- \fi
- \ifdefined\PrintIndex
- \phfnoteHackSectionStarWithTOCInCommand\PrintIndex
- \fi
- \def\PrintChangesAndIndexSpacing{\vspace{3cm plus 2cm minus 2cm}}
- \def\PrintChangesAndIndex{\PrintChangesAndIndexSpacing\PrintChanges
- \PrintChangesAndIndexSpacing\PrintIndex}
+\ifdefined\PrintChanges
+ \phfnoteHackSectionStarWithTOCInCommand\PrintChanges
+\fi
+\ifdefined\PrintIndex
+ \phfnoteHackSectionStarWithTOCInCommand\PrintIndex
+\fi
+\def\PrintChangesAndIndexSpacing{\vspace{3cm plus 2cm minus 2cm}}
+\def\PrintChangesAndIndex{\PrintChangesAndIndexSpacing\PrintChanges
+ \PrintChangesAndIndexSpacing\PrintIndex}
% \end{macrocode}
%
% Set the index to TWO columns only (three is too tight).
% \begin{macrocode}
- \ifdefined\c@IndexColumns
- \setcounter{IndexColumns}{2}
- \fi
+\ifdefined\c@IndexColumns
+ \setcounter{IndexColumns}{2}
+\fi
% \end{macrocode}
%
-% And set the glossary, that is, the list of changes history to single-column. For this,
-% renew the environment completely to remove the |multicols| environment.
-% \begin{macrocode}
- \let\phfnote@xpkgdoc@old@theglossary\theglossary
- \let\phfnote@xpkgdoc@old@endtheglossary\endtheglossary
- \renewenvironment{theglossary}{%
- \glossary@prologue%
- \GlossaryParms \let\item\@idxitem \ignorespaces}
- {}
+% And set the glossary, that is, the list of changes history to single-column.
+% For this, renew the environment completely to remove the |multicols|
+% environment.
+% \begin{macrocode}
+\let\phfnote@xpkgdoc@old@theglossary\theglossary
+\let\phfnote@xpkgdoc@old@endtheglossary\endtheglossary
+\renewenvironment{theglossary}{%
+ \glossary@prologue%
+ \GlossaryParms \let\item\@idxitem \ignorespaces}
+{}
+% \end{macrocode}
+%
+% Tools to condense the macro names in the margins, and make them break at the
+% margin width (at arbitrary points in the macro name) instead of overflowing on
+% the documentation text.
+% \begin{macrocode}
+\def\phf@fillwithdiscretionaries#1#2#3{%
+ \def\phf@fillwithdescretionaries@a{#1}%
+ \def\phf@fillwithdescretionaries@b{#2}%
+ \edef\x{#3}%
+ \expandafter \phf@fillwithdiscretionaries@ \x \@nil
+}
+\def\phf@fillwithdiscretionaries@#1#2\@nil{%
+ \if\relax\detokenize{#1}\relax\else
+ #1%
+ \if\relax\detokenize{#2}\relax\else
+ \discretionary{\phf@fillwithdescretionaries@a}{%
+ \phf@fillwithdescretionaries@b}{}%
+ \phf@fillwithdiscretionaries@#2\@nil
+ \fi
+ \fi
+}
+\definecolor{phfxpkgdocmacronamehyphencolor}{rgb}{0.6,0.6,0.7}
+\def\phf@xpkgdoc@macrobreakhyphen{%
+ \hbox{\textcolor{phfxpkgdocmacronamehyphencolor}{-}}}
+\def\ScaleHorizontallyAndHyphenateAnywhere#1#2{% {hscale-factor}{text}
+ \scalebox{#1}[1.0]{%
+ \parbox{% compute inverse of #1 ...
+ \dimexpr \marginparwidth*65536 /
+ \number\dimexpr #1\p@ \relax \relax
+ }{\raggedleft\phf@fillwithdiscretionaries{%
+ \phf@xpkgdoc@macrobreakhyphen}{}{#2}\hfill}%
+ }%
+}
+\def\phf@xpkgdoc@marginmacronamecompressfactor{0.85}
+\def\phf@xpkgdoc@macrofont{\small\bfseries}% \footnotesize ?
+\def\PrintMarginLabelContents#1{%
+ \strut\MacroFont\phf@xpkgdoc@macrofont
+ \ScaleHorizontallyAndHyphenateAnywhere{%
+ \phf@xpkgdoc@marginmacronamecompressfactor}{#1}%
+ \par
+}
+\def\PrintMarginLabel#1{\marginpar{\PrintMarginLabelContents{#1}}}
+\def\PrintDescribeMacro#1{\PrintMarginLabelContents{\string#1}}
+\let\PrintMacroName\PrintDescribeMacro
+\let\PrintDescribeEnv\PrintMarginLabelContents
+\let\PrintEnvName\PrintMarginLabelContents
% \end{macrocode}
-%
-%
-% \textbf{Hyperref:} No ``default'' \pkgname{hyperref} definitions, we'll use
-% \pkgname{hyperdoc} instead.
-% \begin{macrocode}
- \phfnote@opt@hyperrefdefsfalse
- \g@addto@macro\phfnote@hook@atendload{
- \definecolor{docnotelinkcolor}{rgb}{0,0,0.4}%
- \RequirePackage{url}%
- \DeclareUrlCommand\phfnote@format@url{}%
- \RequirePackage{hypdoc}
- %
- \hypersetup{bookmarks=true,backref=false,unicode=true,%
- bookmarksnumbered=false,bookmarksopen=false,bookmarksopenlevel=1,%
- breaklinks=true,pdfborder={0 0 0},colorlinks=true}%
- \hypersetup{%
- anchorcolor=docnotelinkcolor,citecolor=docnotelinkcolor,%
- filecolor=docnotelinkcolor,linkcolor=docnotelinkcolor,%
- menucolor=docnotelinkcolor,runcolor=docnotelinkcolor,%
- urlcolor=docnotelinkcolor}%
- \let\email\phfnote@email%
- \urlstyle{noteit}
- }
+%
+% \textbf{Hyperref:} Request default \pkgname{hyperref} definitions with
+% |hyperrefdefs=defer|, but we'll load \pkgname{hyperdoc} instead of
+% \pkgname{hyperref}.
+% \begin{macrocode}
+\def\phfnote@opt@hyperrefdefs{defer}
+\g@addto@macro\phfnote@hook@atendload{
+ \RequirePackage{hypdoc}
+ \urlstyle{noteit}
+}
% \end{macrocode}
%
% \textbf{Provide Macro:} |\pkgname|\marg{package name} to format a package
% name. Also place it in the general index. This command is robust and
% can be used in section titles etc.
% \begin{macrocode}
- \def\pkgname##1{%
- \pkgnamefmt{##1}%
- \index{##1=\pkgnamefmt{##1}|hyperpage}%
- \index{packages:>##1=\pkgnamefmt{##1}|hyperpage}%
- }
- \robustify\pkgname
- \def\pkgnamefmt##1{\textsf{##1}}
- \robustify\pkgnamefmt
+\def\pkgname#1{%
+ \pkgnamefmt{#1}%
+ \index{#1=\pkgnamefmt{#1}|hyperpage}%
+ \index{packages:>#1=\pkgnamefmt{#1}|hyperpage}%
+}
+\robustify\pkgname
+\def\pkgnamefmt#1{\textsf{#1}}
+\robustify\pkgnamefmt
% \end{macrocode}
%
%
@@ -2824,7 +4025,7 @@
%
% First, we need a counter for the x-ref system.
% \begin{macrocode}
- \newcounter{phfnotechanged}
+\newcounter{phfnotechanged}
% \end{macrocode}
%
% Mark changes in the implementation section of the package documentation
@@ -2834,73 +4035,74 @@
% allows you to refer to this change anywhere else in the package doc with
% |\changedreftext|.
% \begin{macrocode}
- \newcommand*\changed[4][]{%
+\newcommand*\changed[4][]{%
% \end{macrocode}
%
% First, if no label is given as optional argument, then just display the
% change and add it to the package changes list.
% \begin{macrocode}
- \if\relax\detokenize{##1}\relax%
- \changedtextfmt{##2}{##3}{##4}%
- \changes{##2}{##3}{##4}%
- \else%
+ \if\relax\detokenize{#1}\relax%
+ \changedtextfmt{#2}{#3}{#4}%
+ \changes{#2}{#3}{#4}%
+ \else%
% \end{macrocode}
%
% If a label name is provided as optional argument, then we need to write
% some stuff to the \texttt{.aux} file to make the change visible in the
% whole document.
% \begin{macrocode}
- \protected@edef\phfnotechanged@tmpa{{##2}{##3}{##4}}%
- \immediate\write\@auxout{\string\phfnote@changed@set%
- {##1}{\expandonce\phfnotechanged@tmpa}}%
- \par\hspace*{0pt}\refstepcounter{phfnotechanged}\label{phfnotechanged:##1}%
- \begingroup\let\phfnote@changedreftext@par\relax
- \changedreftext{##1}%
- \endgroup
- \changes{##2}{##3}{\hyperref[phfnotechanged:##1]{##4}}%
- \fi
- }
- \def\phfnote@changed@set##1{%
- \expandafter\gdef\csname phfnote@changed@lbl@##1\endcsname%
- }
+ \protected@edef\phfnotechanged@tmpa{{#2}{#3}{#4}}%
+ \immediate\write\@auxout{\string\phfnote@changed@set%
+ {#1}{\expandonce\phfnotechanged@tmpa}}%
+ \par\hspace*{0pt}\refstepcounter{phfnotechanged}\label{phfnotechanged:#1}%
+ \begingroup\let\phfnote@changedreftext@par\relax
+ \changedreftext[\@secondoftwo]{#1}%
+ \endgroup
+ \changes{#2}{#3}{\hyperref[phfnotechanged:#1]{#4}}%
+ \fi
+}
+\def\phfnote@changed@set#1{%
+ \expandafter\gdef\csname phfnote@changed@lbl@#1\endcsname%
+}
% \end{macrocode}
%
% When you document changes with the help of |\changed|, you may refer to
% any specific change from anywhere else in the package doc with the help
% of |\changedreftext|\marg{label name}.
% \begin{macrocode}
- \def\phfnote@changedreftext@par{\par}
- \newcommand*\changedreftext[1]{%
- \phfnote@changedreftext@par%
- \ifcsname phfnote@changed@lbl@##1\endcsname
- \hyperref[phfnotechanged:##1]{%
- \expandafter\expandafter\expandafter\changedtextfmt%
- \csname phfnote@changed@lbl@##1\endcsname
- }
- \else
- \hyperref[phfnotechanged:##1]{%
- \changedtextfmt{???}{???}{[\textbf{missing ref}]}%
- }%
- \fi
- \par
- }
+\def\phfnote@changedreftext@par{\par}
+\newcommand*\changedreftext[2][\phfnote@changedrefto]{%
+ \phfnote@changedreftext@par%
+ \ifcsname phfnote@changed@lbl@#2\endcsname
+ #1{#2}{%
+ \expandafter\expandafter\expandafter\changedtextfmt%
+ \csname phfnote@changed@lbl@#2\endcsname
+ }
+ \else
+ \hyperref[phfnotechanged:#2]{%
+ \changedtextfmt{???}{???}{[\textbf{missing ref}]}%
+ }%
+ \fi
+ \par
+}
+\def\phfnote@changedrefto#1{\hyperref[phfnotechanged:#1]}
% \end{macrocode}
%
% The macro |\changedtextfmt|\marg{v1.0}\marg{2016/05/22}\marg{description}
% takes care of formatting the change on the spot.
% \begin{macrocode}
- \newcommand*\changedtextfmt[3]{%
- \textit{Changed in {##1\kern 0.3ex\relax[##2]}:} ##3.
- }
+\newcommand*\changedtextfmt[3]{%
+ \textit{Changed in {#1\kern 0.3ex\relax[#2]}:} #3.
+}
% \end{macrocode}
%
% \textbf{Provide environment \phfverb{pkgoptions}:} Set up an elaborate
% environment (based on a |description| environment) to describe package
% options.
% \begin{macrocode}
- \RequirePackage{enumitem}
- \newlist{pkgoptions}{description}{1}
- \setlist[pkgoptions]{font=\pkgoptionfmt[{\vspace*{5pt}}],style=nextline}
+\RequirePackage{enumitem}
+\newlist{pkgoptions}{description}{1}
+\setlist[pkgoptions]{font=\pkgoptionfmt@many[{\vspace*{5pt}}],style=nextline}
% \end{macrocode}
%
% But patch the |pkgoptions|' |\item| command, so that it puts an additional
@@ -2908,21 +4110,22 @@
% the list sees the full label as its next token, and can be used as a macro
% argument. (This is not needed for newer versions of \pkgname{enumitem}.)
% \begin{macrocode}
- \apptocmd\pkgoptions{\let\pkgoptions@old@item\item%
- \def\item{\@ifnextchar[\pkgoptions@item@\pkgoptions@item@@}%]
- \def\pkgoptions@item@[##1]{\pkgoptions@old@item[{{##1}}]}%
- \def\pkgoptions@item@@{\PackageWarning{phfnote}{{pkgoptions}: you must
- specify label to \string\item as \string\item[label].}%
- \pkgoptions@old@item}%
- }{}{\PackageWarning{phfnote}{preset xpkgdoc: Failed to patch command
- \string\pkgoptions}}
- \def\pkgoptionscombineitem{\leavevmode\vspace{\dimexpr-\baselineskip-\parskip-\itemsep\relax}}
+\def\pkgoptions@item{\@ifnextchar[\pkgoptions@item@\pkgoptions@item@@}%]
+\def\pkgoptions@item@[#1]{\pkgoptions@old@item[{{#1}}]}%
+\def\pkgoptions@item@@{\PackageWarning{phfnote}{{pkgoptions}: you must
+ specify label to \string\item as \string\item[label].}%
+ \pkgoptions@old@item}%
+\apptocmd\pkgoptions{%
+ \let\pkgoptions@old@item\item
+ \let\item\pkgoptions@item
+}{}{\PackageWarning{phfnote}{preset xpkgdoc: Failed to patch command
+ \string\pkgoptions}}
% \end{macrocode}
%
% For convenience, also provide a |\meta|-like command for boolean arguments
% (|true| or |false|). `|\metatruefalsearg|' typesets as `\metatruefalsearg'.
% \begin{macrocode}
- \def\metatruefalsearg{\meta{\phfverb{true} $\mid$ \phfverb{false}}}
+\def\metatruefalsearg{\meta{\phfverb{true} $\mid$ \phfverb{false}}}
% \end{macrocode}
%
% Include also a command to format a package option. Puts the option in a box
@@ -2932,12 +4135,19 @@
%
% When indexing the packages, make sure to remove the protective braces if any.
% \begin{macrocode}
- \newcommand\pkgoptionfmt[2][]{%
- \begingroup\let\meta\pkgoptfmt@meta\fbox{\normalfont\ttfamily ##2}\endgroup%
- \expandafter\phfnote@pkgdoc@index\expandafter{\@firstofone ##2}%
- ##1}
- \let\pkgopt@save@meta\meta
- \def\pkgoptfmt@meta##1{\begingroup\normalfont\itshape\pkgopt@save@meta{##1}\endgroup}
+\newcommand\pkgoptionfmt[2][]{%
+ \begingroup\let\meta\pkgoptfmt@meta\pkgopt@fbox{\normalfont\ttfamily #2}\endgroup%
+ \expandafter\phfnote@pkgdoc@index\expandafter{\@firstofone #2}%
+ #1}
+\newcommand\pkgoptionfmt@many[2][]{%
+ \def\pkgoptionfmt@tmp@addcomma{}
+ \def\do##1{\pkgoptionfmt@tmp@addcomma\pkgoptionfmt{\vphantom{#2}##1}%
+ \def\pkgoptionfmt@tmp@addcomma{\hskip0.25em\relax,\hskip0.8em\relax}}%
+ \expandafter\docsvlist\expandafter{\@firstofone #2}%
+ #1}
+\let\pkgopt@save@meta\meta
+\def\pkgopt@fbox{\fbox}
+\def\pkgoptfmt@meta#1{\begingroup\normalfont\itshape\pkgopt@save@meta{#1}\endgroup}
% \end{macrocode}
%
% Whenever a package option is formatted with |\pkgoptionfmt|, it is placed in
@@ -2948,49 +4158,51 @@
% version of that code is executed instead, where the |=|'s have been replaced
% by |,|'s.
% \begin{macrocode}
- \def\phfnote@pkgdoc@index##1{%
- \begingroup\lccode`\= = `\,\relax%
- \def\x{\lowercase{\def\@tmpa{##1}}}%
- \x%
- \let\meta\@gobble%
- \let\marg\@gobble%
- \let\oarg\@gobble%
- \let\parg\@gobble%
- \let\pkgoptattrib\@firstofone%
- \let\pkgoptattribnodots\@firstofone%
- \let\pkgoptattribempty\@empty%
- \def\handleitemindex####1{%
- \edef\@tmpc{####1}%
- \if\relax\detokenize\expandafter{\@tmpc}\relax\else%
- \edef\@tmpb{{\expandonce\@tmpc=\string\verb!*+\expandonce\@tmpc+ (\pkgoptname)|hyperpage}}%
- \expandafter\index\@tmpb%
- \edef\@tmpb{{\packageoptionsname:>\expandonce\@tmpc=\string\verb!*+\expandonce\@tmpc+|hyperpage}}%
- \expandafter\index\@tmpb%
- \fi%
- }%
- \def\@tmpc{\forcsvlist{\handleitemindex}}%
- \expandafter\@tmpc\expandafter{\@tmpa}%
- \endgroup%
- }
- \def\pkgoptname{pkg. opt.}
- \def\packageoptionsname{package options}
+\def\phfnote@pkgdoc@index#1{%
+ \begingroup\lccode`\= = `\,\relax%
+ \def\x{\lowercase{\def\@tmpa{#1}}}%
+ \x%
+ \let\meta\@gobble%
+ \let\marg\@gobble%
+ \let\oarg\@gobble%
+ \let\parg\@gobble%
+ \let\vphantom\@gobble%
+ \let\hphantom\@gobble%
+ \let\pkgoptattrib\@firstofone%
+ \let\pkgoptattribnodots\@firstofone%
+ \let\pkgoptattribempty\@empty%
+ \def\handleitemindex##1{%
+ \edef\@tmpc{##1}%
+ \if\relax\detokenize\expandafter{\@tmpc}\relax\else%
+ \edef\@tmpb{{\expandonce\@tmpc=\string\verb!*+\expandonce\@tmpc+ (\pkgoptname)|hyperpage}}%
+ \expandafter\index\@tmpb%
+ \edef\@tmpb{{\packageoptionsname:>\expandonce\@tmpc=\string\verb!*+\expandonce\@tmpc+|hyperpage}}%
+ \expandafter\index\@tmpb%
+ \fi%
+ }%
+ \def\@tmpc{\forcsvlist{\handleitemindex}}%
+ \expandafter\@tmpc\expandafter{\@tmpa}%
+ \endgroup%
+}
+\def\pkgoptname{pkg. opt.}
+\def\packageoptionsname{package options}
% \end{macrocode}
%
% \textbf{Provide environment \phfverb{cmdoptions}:} hijack the |pkgoptions|
% environment to do the same thing, except we place the items in the index under
% ``command options'' instead of ``package options.''
% \begin{macrocode}
- \def\cmdoptions{\begingroup\setcmdnotpkgoptions
- \pkgoptions}
- \def\endcmdoptions{\endpkgoptions\endgroup}
- \newcommand\cmdoptionfmt[2][]{\begingroup\setcmdnotpkgoptions
- \pkgoptionfmt[{##1}]{##2}\endgroup}
- \def\cmdoptname{cmd. opt.}
- \def\commandoptionsname{command options}
- \def\setcmdnotpkgoptions{\let\pkgoptname\cmdoptname
- \let\packageoptionsname\commandoptionsname
- \let\fbox\cmdoptionsfbox}
- \def\cmdoptionsfbox##1{\ensuremath{\underline{{\text{##1}}}}}
+\def\cmdoptions{\begingroup\setcmdnotpkgoptions
+ \pkgoptions}
+\def\endcmdoptions{\endpkgoptions\endgroup}
+\newcommand\cmdoptionfmt[2][]{\begingroup\setcmdnotpkgoptions
+ \pkgoptionfmt[{#1}]{#2}\endgroup}
+\def\cmdoptname{cmd. opt.}
+\def\commandoptionsname{command options}
+\def\setcmdnotpkgoptions{\let\pkgoptname\cmdoptname
+ \let\packageoptionsname\commandoptionsname
+ \let\pkgopt@fbox\cmdoptionsfbox}
+\def\cmdoptionsfbox#1{\ensuremath{\underline{{\text{#1}}}}}
% \end{macrocode}
%
% Provide the |\pkgoptattrib| command, which typesets its argument as
@@ -2998,9 +4210,9 @@
% \autoref{sec:abstract-attributes}. The variant |\pkgoptattribondots{arg}|
% typesets |\{arg\}| while |\pkgoptattribempty| expands to |{}|.
% \begin{macrocode}
- \def\pkgoptattrib##1{\{##1,...\}}
- \def\pkgoptattribnodots##1{\{##1\}}
- \def\pkgoptattribempty{\{\}}
+\def\pkgoptattrib#1{\{#1,...\}}
+\def\pkgoptattribnodots#1{\{#1\}}
+\def\pkgoptattribempty{\{\}}
% \end{macrocode}
%
% \textbf{Colorful boxes: environments \phfverb{pkgnote},
@@ -3012,146 +4224,76 @@
% to be stripped), we save the |verbatim|-related commands, and restore
% them after the interfering packages have been loaded.
% \begin{macrocode}
- \phfnoteSaveDefs{verbatimstuff}{%
- verbatim,@verbatim,@xverbatim,@sxverbatim,endverbatim}
- \usepackage{tcolorbox}
- \newtcolorbox{pkgnote}{
- colback=blue!5!white,
- colframe=blue!5!white,
- coltitle=blue!50!black,
- toptitle=1.5ex,
- fonttitle=\bfseries,
- title={NOTE}
- }
- \newtcolorbox{pkgwarning}{
- colback=red!5!white,
- colframe=red!5!white,
- coltitle=red!50!black,
- toptitle=1.5ex,
- fonttitle=\bfseries,
- title={WARNING}
- }
- \newtcolorbox{pkgtip}{
- colback=green!5!white,
- colframe=green!5!white,
- coltitle=green!50!black,
- toptitle=1.5ex,
- fonttitle=\bfseries,
- title={TIP}
- }
- \phfnoteRestoreDefs{verbatimstuff}
+\phfnoteSaveDefs{verbatimstuff}{%
+ verbatim,@verbatim,@xverbatim,@sxverbatim,endverbatim}
+\usepackage{tcolorbox}
+\newtcolorbox{pkgnote}{
+ colback=blue!5!white,
+ colframe=blue!5!white,
+ coltitle=blue!50!black,
+ toptitle=1.5ex,
+ fonttitle=\bfseries,
+ title={NOTE}
+}
+\newtcolorbox{pkgwarning}{
+ colback=red!5!white,
+ colframe=red!5!white,
+ coltitle=red!50!black,
+ toptitle=1.5ex,
+ fonttitle=\bfseries,
+ title={WARNING}
+}
+\newtcolorbox{pkgtip}{
+ colback=green!5!white,
+ colframe=green!5!white,
+ coltitle=green!50!black,
+ toptitle=1.5ex,
+ fonttitle=\bfseries,
+ title={TIP}
+}
+\phfnoteRestoreDefs{verbatimstuff}
+% \end{macrocode}
+%
+% Patch the |verbatim| environment to remove extraneous space after the
+% environment caused by I don't know what weird cause:
+% \begin{macrocode}
+\appto\endverbatim{\vspace{-\baselineskip}}
% \end{macrocode}
%
% Common title stuff:
% \begin{macrocode}
- \def\phfqitltxPkgTitle##1{The \pkgname{##1} package\thanks{\itshape
- This document corresponds to \pkgname{##1}~\fileversion, dated \filedate. It
- is part of the
- \href{https://github.com/phfaist/phfqitltx/}{\pkgname{phfqitltx}} package
- suite, see \url{https://github.com/phfaist/phfqitltx}.}}
+\def\phfqitltxPkgTitle#1{The \pkgname{#1} package\thanks{\itshape
+ This document corresponds to \pkgname{#1}~\fileversion, dated \filedate. It
+ is part of the
+ \href{https://github.com/phfaist/phfqitltx/}{\pkgname{phfqitltx}} package
+ suite, see \url{https://github.com/phfaist/phfqitltx}.}}
% \end{macrocode}
%
% Utility to parse package file date into ``|\today|''-style date: invoke as
% |\date{\pkgfmtdate\filedate}|.
% \begin{macrocode}
- \def\pkgfmtdate##1{%
- \edef\pkgfmtdate@thedate{##1}%
- \expandafter\pkgfmtdate@next\pkgfmtdate@thedate\@nil%
- }
- \def\pkgfmtdate@next##1/##2/##3\@nil{% YYYY/MM/DD
- \ifcase ##2 \or January\or February\or March\or April\or May%
- \or June\or July\or August\or September\or October\or November\or December\fi\space ##3,%
- \space ##1}
- \robustify\pkgfmtdate@next
+\def\pkgfmtdate#1{%
+ \edef\pkgfmtdate@thedate{#1}%
+ \expandafter\pkgfmtdate@next\pkgfmtdate@thedate\@nil%
}
+\def\pkgfmtdate@next#1/#2/#3\@nil{% YYYY/MM/DD
+ \ifcase #2 \or January\or February\or March\or April\or May%
+ \or June\or July\or August\or September\or October%
+ \or November\or December\fi\space #3,%
+ \space #1}
+\robustify\pkgfmtdate@next
% \end{macrocode}
-% \end{macro}
-%
%
-% \begin{macro}{\phfnote@preset@reset}
-% Finally, the |reset| preset:
-% \begin{macrocode}
-\def\phfnote@preset@reset{
- \def\phfnote@opt@pkgset{none}
- \def\phfnote@opt@title{}
- \phfnote@opt@pagegeomdefsfalse
- \phfnote@opt@spacingdefsfalse
- \def\phfnote@opt@par{original}
- \def\phfnote@opt@abstract{original}
- \phfnote@opt@hyperrefdefsfalse
- \phfnote@opt@fontdefsfalse
- \def\phfnote@opt@secfmt{}
- \phfnote@opt@bibliographydefsfalse
- \phfnote@opt@footnotedefsfalse
-% \end{macrocode}
-%
-% \begin{pkgwarning}
-% SELF-NOTE: DO NOT FORGET TO ADD HERE RESET COMMANDS FOR ANY NEW OPTION THAT
-% WE PROVIDE IN THE FUTURE.
-% \end{pkgwarning}
-%
-% \begin{macrocode}
-}
-% \end{macrocode}
-% \end{macro}
-%
-%
-%
-%
-% \subsubsection{Finally, Process and Execute the Package Options}
+% \begin{verbatim}
+%</phfnotepreset-xpkgdoc>
+% \end{verbatim}
+% \iffalse
+%<*package>
+% \fi
%
%
%
-% Process the options:
-%
-% \begin{macrocode}
-\ProcessKeyvalOptions*
-% \end{macrocode}
-%
-%
-% Take action according to the user options.
-%
-% \begin{macrocode}
-\phfnote@do@pkgset{\phfnote@opt@pkgset}
-
-\phfnote@do@notetitle{\phfnote@opt@title}
-
-\phfnote@do@noteabstract{\phfnote@opt@abstract}
-
-\phfnote@do@secfmt{\phfnote@opt@secfmt}
-
-\ifphfnote@opt@pagegeomdefs
- \phfnote@do@pagegeomdefs{\phfnote@opt@pagegeom}
-\fi
-
-\ifphfnote@opt@spacingdefs
- \phfnote@do@spacing
-\fi
-
-\phfnote@do@par{\phfnote@opt@par}
-
-\ifphfnote@opt@hyperrefdefs
- \phfnote@do@pdfhyperrefdefs
-\fi
-
-\ifphfnote@opt@fontdefs
- \phfnote@do@fontdefs
-\fi
-
-\ifphfnote@opt@bibliographydefs
- \phfnote@do@bibliographydefs
-\fi
-
-\ifphfnote@opt@footnotedefs
- \phfnote@do@footnotedefs
-\fi
-% \end{macrocode}
-%
-% Finally, execute the hook we set up for definitions at the end of the package
-% loading:
-% \begin{macrocode}
-\phfnote@hook@atendload
-% \end{macrocode}
%
%\Finale
+%</package>
\endinput