From 20b79660fb560eb1dd8e80d44837e0d4c17ca03c Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Tue, 12 Oct 2021 03:00:58 +0000 Subject: CTAN sync 202110120300 --- macros/latex/contrib/phfnote/phfnote.dtx | 2582 +++++++++++++++++++++--------- 1 file changed, 1862 insertions(+), 720 deletions(-) (limited to 'macros/latex/contrib/phfnote/phfnote.dtx') 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 +% Copyright (C) 2019 by Philippe Faist, philippe.faist@bluewin.ch % ------------------------------------------------------- % % This file may be distributed and/or modified under the @@ -22,8 +22,9 @@ %\NeedsTeXFormat{LaTeX2e}[2005/12/01] %\ProvidesPackage{phfnote} %<*package> - [2016/08/15 v1.0 phfnote package] + [2021/10/08 v4.0 phfnote package] % +%%This preset file for phfnote is used when you call `\usepackage[preset=]{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} % +%<*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} % -% \subsubsection{Customizing the style of the \phfverb{default} and \phfverb{small} title styles} +% \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}, \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,115 +1530,645 @@ % % 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}{\notetitle@style@default} -% The default title style. Nothing mysterious, hopefully. +% \begin{macro}{\notetitleinnervsep} +% Controls the vertical spacing between individual elements of the title. % \begin{macrocode} -\newcommand{\notetitle@style@default}{% - \begingroup\par\raggedright% - \phfnote@setupthanksmpfootnote% - \vspace*{\notetitletopspace}% - \phfnote@title@checksetspace{default}% - \begin{minipage}{\textwidth}% - \begin{singlespace}% - \parskip=0pt\parindent=0pt\relax% - {\let\phfnote@old@par\par% - \def\par{\phfnote@old@par% - \parskip=1.5ex\relax\parshape 1 0pt \textwidth\relax% - \noindent}% - \par% - \Large {\notetitlefont \@title}\par}% - \vskip 2mm\relax - \if\relax\detokenize\expandafter{\@author}\relax\else% - \par\parshape 1 0.04\textwidth 0.96\textwidth\relax% - {\notetitleauthorfont \@author}% - \vskip 2mm\relax% - \fi - \if\relax\detokenize\expandafter{\@date}\relax\else% - \par\parshape 1 0.04\textwidth 0.96\textwidth\relax% - {\notetitledatefont \@date} - \vskip 2mm\relax% - \fi - \global\let\@thanks\@empty% - \phfnote@finalizempfootnotes% - \end{singlespace}% - \end{minipage}\par% - \vspace*{2mm}% - \notetitlehrule\relax% - \par% - \endgroup% - \vskip\notetitlebelowspace\relax% don't change this, abstract needs to \removelastskip -} +\newcommand\notetitleinnervsep{1.15ex} % \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. +% \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} -\newcommand{\notetitle@style@small}{% - \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}}}% - \vspace*{1mm}\notetitlehrule\relax\vspace*{1mm}% - \par% - \endgroup% - \vskip\notetitlebelowspace\relax% don't change this, abstract needs to \removelastskip -} +\def\notetitlewidth{\textwidth} % \end{macrocode} % \end{macro} -% % -% \paragraph{Title style: `article'} -% -% Implementation the `article' title style. -% -% \begin{macro}{\notetitle@style@article} -% The title style definition. Nothing mysterious, hopefully. +% \begin{macro}{\notetitleparskip} +% The paragraph skip that is used if the title contains multiple paragraphs. % \begin{macrocode} -\newcommand{\notetitle@style@article}{% - \vspace*{-3em}% - \begingroup - \centering - \let\footnote\thanks% - {\LARGE \@title \par}% - \vskip 1.5em% - {\large% - \lineskip .5em% - \begin{tabular}[t]{c}% - \@author% - \end{tabular}\par}% - \vskip 1.5em% - {\large \@date}% - \par% - \endgroup% - \par% - \vskip 2.5em\relax% -} +\def\notetitleparskip{1.4ex}% parskip for multiple pars in main title % \end{macrocode} % \end{macro} % -% \subsubsection{Plugging into \phfverb{\maketitle}} +% \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} % -% 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. +% \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}{\phfnote@do@notetitle} -% This macro takes care of installing the correct title into the +% \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} +% 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{defaultv1}% + \begin{minipage}{\textwidth}% + \begin{singlespace}% + \parskip=0pt\parindent=0pt\relax% + {\let\phfnote@old@par\par% + \def\par{\phfnote@old@par% + \parskip=1.5ex\relax\parshape 1 0pt \textwidth\relax% + \noindent}% + \par% + \Large {\notetitlefont \@title}\par}% + \vskip 2mm\relax + \if\relax\detokenize\expandafter{\@author}\relax\else% + \par\parshape 1 0.04\textwidth 0.96\textwidth\relax% + {\notetitleauthorfont \@author}% + \vskip 2mm\relax% + \fi + \if\relax\detokenize\expandafter{\@date}\relax\else% + \par\parshape 1 0.04\textwidth 0.96\textwidth\relax% + {\notetitledatefont \@date} + \vskip 2mm\relax% + \fi + \global\let\@thanks\@empty% + \csname phfnote@finalizempfootnotes@v1\endcsname% + \end{singlespace}% + \end{minipage}\par% + \vspace*{2mm}% + \notetitlehrule\relax% + \par% + \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 small title style. Again, use the main title engine, but customize the settings. +% \begin{macrocode} +\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}% + {\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} +% +% +% \paragraph{Title style: `article'} +% +% Implementation the `article' title style. +% +% \begin{macro}{\notetitle@style@article} +% \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} +\csdef{notetitle@style@articlev1}{% + \vspace*{-3em}% + \begingroup + \centering + \let\footnote\thanks% + {\LARGE \@title \par}% + \vskip 1.5em% + {\large% + \lineskip .5em% + \begin{tabular}[t]{c}% + \@author% + \end{tabular}\par}% + \vskip 1.5em% + {\large \@date}% + \par% + \endgroup% + \par% + \vskip 2.5em\relax% +} +% \end{macrocode} +% \end{macro} +% +% \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 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 % document, by overriding |\@maketitle|. % % This macro is called later after processing the package options. @@ -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,8 +2418,24 @@ % % \begin{macro}{\phfnote@pagegeomstyle@xwide} % Extra wide. +% +% \changedreftext{chg-pagegeom-xwide} % \begin{macrocode} \def\phfnote@pagegeomstyle@xwide{ + \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=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 @@ -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} +\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} +% +% Define the attributes that can be set for hyperref-related options. See +% \autoref{sec:hyperrefdefs}. +% % \begin{macrocode} -\newcommand{\phfnote@do@pdfhyperrefdefs}{% +\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} -% Make sure a color-managing package is loaded, {color} or {xcolor}, and define our default color: +% +% +% \begin{macro}{\phfnote@do@hyperrefdefs} +% \begin{macro}{\email} +% \begin{macro}{\url} +% Do all stuff related to hyperref. % \begin{macrocode} - \phfnote@requirecolorpackage% - \definecolor{docnotelinkcolor}{rgb}{0,0,0.4}% +\def\phfnote@do@hyperrefdefs#1{% + \ifstrequal{#1}{false}{}{% % \end{macrocode} -% -% Load URL package, and save a version of |\url| which is not patched -% by \pkgname{hyperref}: +% Make sure a color-managing package is loaded, {color} or {xcolor}, and define +% our default link color: % \begin{macrocode} - \RequirePackage{url}% - \DeclareUrlCommand\phfnote@format@url{}% + \phfnote@requirecolorpackage% + \definecolor{docnotelinkcolor}{rgb}{0,0,0.4}% % \end{macrocode} -% -% Set up \pkgname{hyperref} options: +% 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} - \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}% + \RequirePackage{url}% + \DeclareUrlCommand\phfnote@format@url{}% + \let\phfnoteEmail\phfnote@email % \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}. +% +% Set up everything according to the user's selected attributes. % \begin{macrocode} - \let\email\phfnote@email% + \phfnote@internal@execattribs{phfnote@do@hyperrefdefs@attr@}{% + phfnote hyperref-related option}{#1}% % \end{macrocode} -% -% And finally set a nicer default |\url|/|\email| style: +% +% 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 +% +% \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 -} -% \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} +\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} -% -% -% -% -% \subsubsection{Finally, Process and Execute the Package Options} -% -% -% -% Process the options: % -% \begin{macrocode} -\ProcessKeyvalOptions* -% \end{macrocode} +% \begin{verbatim} +% +% \end{verbatim} +% \iffalse +%<*package> +% \fi % % -% 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 +% \endinput -- cgit v1.2.3