summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/biblatex-contrib/windycity/doc/windycity.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/biblatex-contrib/windycity/doc/windycity.tex')
-rw-r--r--macros/latex/contrib/biblatex-contrib/windycity/doc/windycity.tex270
1 files changed, 181 insertions, 89 deletions
diff --git a/macros/latex/contrib/biblatex-contrib/windycity/doc/windycity.tex b/macros/latex/contrib/biblatex-contrib/windycity/doc/windycity.tex
index 07f1fc504c..58fe3cc079 100644
--- a/macros/latex/contrib/biblatex-contrib/windycity/doc/windycity.tex
+++ b/macros/latex/contrib/biblatex-contrib/windycity/doc/windycity.tex
@@ -1,4 +1,4 @@
-% Last modified: Sun 02 May 2021 01:06:52 PM CDT
+% Last modified: Wed 07 Jul 2021 05:46:01 PM CDT
\documentclass[11pt,letterpaper,oneside]{article}
\usepackage{windycity}
@@ -8,7 +8,7 @@
\author{Brian Chase}
\email{brianmichaelchase@gmail.com}
\website{https://github.com/brianchase/windycity}
-\version{2021-05-02}
+\version{2021-07-07}
\maketitle
\begingroup
\hypersetup{linkcolor=black}
@@ -57,14 +57,14 @@ interest.
\subsection{Getting Started}
If you already know how to use \biblatex, getting started with Windy
-City is easy. The first task is to confirm that \biblatex and Windy
-City are installed properly on your system. Since both are included in
-some distributions of \LaTeX, you might be able to skip this step.
+City is easy. First, confirm that \biblatex and Windy City are
+installed properly on your system. Since both are included in some
+distributions of \LaTeX, you might already have them.
Either way, please consider downloading the most recent release of
-Windy City from \begingroup \hypersetup{urlcolor=blue}
-\href{https://www.ctan.org/pkg/windycity}{its home on CTAN}. Releases
-without the PDF user guide are available from Windy City's
+Windy City from its
+\begingroup\hypersetup{urlcolor=blue}\href{https://www.ctan.org/pkg/windycity}{home
+on CTAN} or
\href{https://github.com/brianchase/windycity/releases}{repository on
GitHub}. More recent but potentially less reliable updates are
available on \href{https://github.com/brianchase/windycity}{the main
@@ -237,9 +237,8 @@ A shorter form of this passage appears in \textit{CMOS}
feature of the style. For demonstration purposes, though, it's
possible.}
-% The use of 'shortfirst' below might be confusing. It's necessary to
-% simulate the effect of 'short' within a document that otherwise
-% gives default output.
+% Preamble option 'short' sets 'short' and 'shortfirst' toggles to
+% true. Set them to true to simulate the 'short' preamble option.
\begin{citeonly}
\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}}
@@ -283,30 +282,35 @@ explained in section \ref{preamble}, Windy City won't print
\textit{ibid.} in reference to a citation on a previous page. A page
break here may affect the output.}
+% Preamble option 'short' sets 'short' and 'shortfirst' toggles to
+% true. Preamble option 'ibid' sets 'ibid', 'ibidpage', and 'short'
+% toggles to true. Set all those toggles to true to simulate the
+% 'short' and 'ibid' preamble options.
+
\begin{citeonly}
-\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}}
\item \cite[3]{morrison2004a}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[18]{morrison2004a}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}\toggletrue{ibidpage}}
\item \cite[18]{morrison2004a}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[24--26]{morrison2004a}
-\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}}
\item \cite[401-2]{morrison2004b}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[433]{morrison2004b}
-\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}}
\item \cite[37--38]{diaz2008}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}}
\item \cite[403]{morrison2004b}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}}
\item \cite[152]{diaz2008}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[201-2]{diaz2008}
\AtNextMultiCite{\toggletrue{short}\toggletrue{shortfirst}}
\item \cites[240]{morrison2004b}[32]{morrison2004a}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}}
\item \cite[33]{morrison2004a}
\end{citeonly}
@@ -329,35 +333,33 @@ and other elements of a citation (see sections \ref{otherfields} and
A preamble option is an argument for the \cmd{usepackage} macro that
loads \biblatex. Preamble options affect the format of notes,
-bibliographies, and reference lists. Some features of the style
-require them.
-
-All options described below are \opt{false} by default. Set them to
-\opt{true} by passing the name of the option to \biblatex, with or
-without an additional \opt{=true}. In other words, using
-\opt{annotate} as an example, the following are equivalent:
+bibliographies, and reference lists. Windy City relies on many
+preamble options from \biblatex and supports or provides others to
+allow you to change the default output.
+
+% Windy City sets preamble options for \biblatex in
+% \file{windycity.bbx}. The list there isn't complete. The style needs
+% to set some options to comply with \textit{CMOS}, sets others as a
+% precaution, and leaves still others untouched. Users who want
+% fine-grained control of the style should look through the list along
+% with \biblatex's user guide.
+
+Many options below are \opt{false} by default. Make an option
+\opt{true} by passing its name to \biblatex, with or without
+\opt{=true}. Using \opt{annotate} as an example, the following are
+equivalent:
\begin{verbatim}
\usepackage[annotate,style=windycity]{biblatex}
\usepackage[annotate=true,style=windycity]{biblatex}
\end{verbatim}
-Bear in mind that Windy City uses many preamble options native to
-\biblatex, a few of which you may want to change. These options are
-set in \file{windycity.bbx}. In particular, the style sets
-\opt{idemtracker} to \opt{false}. If you set it to \opt{true} (or to
-some value that implies \opt{true}), Windy City will detect when the
-first citation of a work follows another citation of a work by the
-same author and shorten the author's name. Recall from the previous
-section the citation of Toni Morrison's \textit{Song of Solomon}
-immediately after a citation of her \textit{Beloved}. In a context
-like that, do you really need to remind readers of the author's full
-name? If you think not, change \opt{idemtracker} to an appropriate
-value (see section 3.1.2.3 of \biblatex's user
-guide).\footnote{\textit{CMOS} seems to have no policy on this point.
-In the 16th edition, however, Figure 14.3 shows consecutive citations
-of works by the same author, both of which give the author's full
-name.}
+If an option is \opt{true} by default, make it \opt{false} by passing
+its name with \opt{=false}. Using \opt{doi} as an example:
+
+\begin{verbatim}
+ \usepackage[doi=false,style=windycity]{biblatex}
+\end{verbatim}
\begin{optionlist}
@@ -379,17 +381,63 @@ it does filter out chapters of books, books in books, and volumes of
collections. For discussion of multivolume works, see section
\ref{multivolume}.
+\optitem[true]{dashed}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{false} to remove the 3-em dash for repeated names
+in bibliographies and reference lists.
+
+\optitem[true]{doi}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{false} to prevent the \bibfield{doi} field from
+printing.
+
+\optitem[true]{eprint}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{false} to prevent the \bibfield{eprint} field from
+printing. For more information about eprints, see section
+\ref{datafields}.
+
\optitem[false]{ibid}{\opt{true}, \opt{false}}
\noindent This option controls whether consecutive citations of a work
-on the same page receive an \textit{ibid}. The qualification ``on the
-same page'' means that \textit{ibid.} always refers to a work cited on
-the current page without an \textit{ibid}. The latter isn't a
-requirement of \textit{CMOS} but seems reasonable, since it prevents
-readers from having to look at another page to find the referent of an
-\textit{ibid}. For examples of its output, see section \ref{short} and
-\ref{14.34}. As of the 17th edition, \textit{CMOS} discourages the use
-of \textit{ibid.} (see \ref{14.34}).
+on the same page receive an \textit{ibid}. For examples, see section
+\ref{short} and \textit{CMOS} \ref{14.34}. As of the 17th edition,
+\textit{CMOS} discourages the use of \textit{ibid.}
+
+% The qualification ``on the same page'' means that the referent of an
+% \textit{ibid.} is never on a different page. The latter isn't a
+% requirement of \textit{CMOS} but seems reasonable, since it prevents
+% readers from having to look at another page to find the referent of
+% an \textit{ibid}.
+
+\optitem[false]{ibidpage}{\opt{true}, \opt{false}}
+
+\noindent If \opt{true}, the \bibfield{postnote} field won't print if
+the previous citation on the page is of the same entry with the same
+\bibfield{postnote}. The \opt{ibid} preamble option uses
+\opt{ibidpage}.
+
+\optitem[false]{idemtracker}{\opt{true}, \opt{false}, \opt{context},
+\opt{strict}, \opt{constrict}}
+
+\noindent If \opt{true}, the first citation of a work prints with a
+shortened author's name if the previous citation is of another work by
+the same author.
+
+Recall \textit{CMOS} \ref{14.34}, where the first citation of Toni
+Morrison's \textit{Song of Solomon} immediately follows citations of
+her \textit{Beloved}. The default output prints her full name twice,
+once for the first citation of \textit{Song of Solomon} and again for
+the first citation of \textit{Beloved}. If \opt{idemtracker} is
+\opt{true} (or in many contexts any value other than \opt{false}), her
+full name prints just once, at the beginning of the series.
+
+% As for \texit{CMOS}, the 16th edition, Figure 14.3, shows
+% consecutive citations of works by the same author, both of which
+% give the author's full name.
+
+For more information on \opt{idemtracker}, see the discussion in
+\biblatex's user guide.
\optitem[false]{isbn}{\opt{true}, \opt{false}}
@@ -427,7 +475,7 @@ bibliography, their results may overlap.
\bibfield{pages} field if the \bibfield{postnote} field is blank. This
lets you cite the entirety of a work without having to duplicate the
content of the \bibfield{pages} field in the \bibfield{postnote}. To
-override this feature, use the \opt{nopages} option.
+override this feature, use \opt{nopages}.
\optitem[false]{reflist}{\opt{true}, \opt{false}}
@@ -502,8 +550,7 @@ resulting output consists mainly of the author's name and the work's
title. According to \textit{CMOS}, this approach is optional for
documents with complete bibliographies. (See \textit{CMOS}
\ref{14.23}, also 14.29--14.36.) As with \opt{short}, you may use
-\opt{shortfirst} in conjunction with \opt{ibid} for more concise
-citations.
+\opt{shortfirst} with \opt{ibid} for more concise citations.
\optitem[false]{shortlinks}{\opt{true}, \opt{false}}
@@ -553,6 +600,11 @@ collection or \textit{vice versa}. Windy City gives priority to the
volume. To reverse this for all relevant citations, use \opt{swapvol}.
For more information, see section \ref{collorder}.
+\optitem[true]{url}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{false} to prevent the \bibfield{url} field from
+printing.
+
\end{optionlist}
\subsection{Entry Options}
@@ -562,8 +614,44 @@ An entry option goes in the \bibfield{options} field of a work's
database entry. It affects the format of that work. For options that
affect the format of every work, see section \ref{preamble}.
+As with preamble options, many options below are \opt{false} by
+default. Make an option \opt{true} by putting its name in the
+\bibfield{options} field of a work's bibliography database entry, with
+or without \opt{=true}. Using \opt{annotate} as an example, the
+following are equivalent:
+
+\begin{verbatim}
+ options = {annotate},
+ options = {annotate=true},
+\end{verbatim}
+
+If an option is \opt{true} by default, make it \opt{false} by putting
+its name with \opt{=false} in the \bibfield{options} field. Using
+\opt{doi} as an example:
+
+\begin{verbatim}
+ options = {doi=false},
+\end{verbatim}
+
\begin{optionlist}
+\optitem[false]{annotate}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{true} to print an entry's \bibfield{annotation}
+field. To change the spacing between entries and annotations, change
+the value of \cmd{bibitemsep}.
+
+\optitem[true]{doi}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{false} to prevent the \bibfield{doi} field from
+printing.
+
+\optitem[true]{eprint}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{false} to prevent the \bibfield{eprint} field from
+printing. For more information about eprints, see section
+\ref{datafields}.
+
\optitem[false]{isbn}{\opt{true}, \opt{false}}
\noindent Use this option to print the ISBN of a particular work in a
@@ -719,6 +807,11 @@ bibliographies and long citations, publication information for the
collection precedes that of the volume. For more information, see
section \ref{collorder}.
+\optitem[true]{url}{\opt{true}, \opt{false}}
+
+\noindent Set \opt{false} to prevent the \bibfield{url} field from
+printing.
+
\end{optionlist}
\subsection{Citation Commands}
@@ -1164,7 +1257,7 @@ contain:
\noindent Note that when \bibfield{date} contains just a year of
publication, you may use the classic \bibfield{year} field.
-\item[pages] See comments on the \opt{nopages} bibliography option in
+\item[pages] See comments on the \opt{nopages} preamble option in
section \ref{preamble}.
\item[pubstate] This fields indicates when a work is forthcoming (with
@@ -1445,10 +1538,9 @@ after the collection's title.
As the examples above also indicate, the style supports a variety of
editorial roles beyond just editor and translator. They are: compiler,
-expander, reviser, and updater. To assign them, you need to use the
-editor and translator type fields. Below are some bibliography
-database entries for examples in \textit{CMOS} \ref{14.103} and
-\ref{14.142}:
+expander, reviser, and updater. To assign them, use the editor and
+translator type fields. Below are some bibliography database entries
+for examples in \textit{CMOS} \ref{14.103} and \ref{14.142}:
\begin{verbatim}
@Book{schechter2011,
@@ -2115,15 +2207,14 @@ and if it lacks certain fields that it shouldn't have, such as a
\bibfield{maintitle} field or a \bibfield{volume} field inherited from
the cross-referenced entry. You can find the exact details in
\file{windycity.bbx}. Just remember that entries like these should
-always be cross-referenced to a \bibtype{collection} or one of its
+always be cross-referenced to a \bibtype{collection} or to one of its
aliases. Since Windy City treats them the same, it makes no difference
whether you designate entries for volumes as \bibtype{bookinbook} or
\bibtype{inbook}.
With one exception, you can get the same output with a \bibtype{book},
\bibtype{collection}, \bibtype{mvbook}, or \bibtype{mvcollection}
-entry. As before, the choice of entry type is arbitrary. All four are
-equivalent. Here's a counterpart to the previous example using
+entry. Here's a counterpart to the previous example using
\bibtype{collection}:
\begin{verbatim}
@@ -2142,21 +2233,22 @@ equivalent. Here's a counterpart to the previous example using
}
\end{verbatim}
-These entries work with \opt{swapvol} if they have \bibfield{volume}
-and \bibfield{maintitle} fields, among other conditions. You may
-prefer them over \bibfield{bookinbook} or \bibfield{inbook} entries if
-you only intend to cite one volume of the collection and have no need
-to cite the collection as a whole. You risk trouble, though, if the
-volumes of the collection have different publication dates, as they do
-for \textit{The Papers of Martin Luther King, Jr}. If the publication
-information for this volume goes last, the bibliography and long
-citation should list the publication date as \textit{2014}. If the
-publication information for the collection goes last, that date is
-\textit{1992–}. A \bibtype{book} or \bibtype{collection} entry,
-however, has just one field for a publication date, so using
-\opt{swapvol} on \bibfield{carson2014} would print \textit{2014}, not
-\textit{1992–}. Otherwise, the entry types are interchangeable. You
-can find examples of both approaches in \file{windycity.bib}.
+These entry types work with \opt{swapvol} if they have
+\bibfield{volume} and \bibfield{maintitle} fields, among other
+conditions. You may prefer them over \bibfield{bookinbook} or
+\bibfield{inbook} entries if you only intend to cite one volume of the
+collection and have no need to cite the collection as a whole. You
+risk trouble, though, if the volumes of the collection have different
+publication dates, as they do for \textit{The Papers of Martin Luther
+King, Jr}. If the publication information for this volume goes last,
+the bibliography and long citation should list the publication date as
+\textit{2014}. If the publication information for the collection goes
+last, that date is \textit{1992–}. A \bibtype{book} or
+\bibtype{collection} entry, however, has just one field for a
+publication date, so using \opt{swapvol} on \bibfield{carson2014}
+would print \textit{2014}, not \textit{1992–}. Otherwise, the entry
+types are interchangeable. You can find examples of both approaches in
+\file{windycity.bib}.
Certain entries cross-referenced to entries that work with
\opt{swapvol} also work with it. Those entry types are limited to
@@ -2249,10 +2341,10 @@ In citations of \textit{The Lisle Letters}, volume numbers and pages
are separated by a colon. With \textit{The Complete Tales of Henry
James}, only the second citation follows this pattern. In the first,
the volume number appears earlier, after the editor's name. Why?
-Apparently, \textit{The Lisle Letters} count as a single, multivolume
-work because every volume has the same title and publication date. Not
-so \textit{The Complete Tales of Henry James}. Its volumes have
-different titles and publication dates.
+Apparently, \textit{The Lisle Letters} is a single, multivolume work
+because every volume has the same title and publication date. Not so
+\textit{The Complete Tales of Henry James}. Its volumes have different
+titles and publication dates.
To get the right output, your bibliography database and citations need
to reflect this distinction. Think of it this way: If a multivolume
@@ -2329,7 +2421,7 @@ in the bibliography database. Here's the entry for the volume cited in
Since the volume number is part of the entry and needs to print in
different places depending on the context, don't include it in the
\bibfield{postnote}. Let Windy City handle it. Below is the source for
-the first and second citations of \textit{The Complete Tales Henry
+the first and second citations of \textit{The Complete Tales of Henry
James}:
\begin{verbatim}
@@ -2353,8 +2445,8 @@ Neither type of collection uses cross-referencing in the bibliography
database. For \textit{The Lisle Letters}, cross-referencing would
introduce needless complexity. A single work should have a single
entry, not multiple, cross-referenced entries. For \textit{The
-Complete Tales Henry James}, cross-referencing would result in errors
-because, with different titles and publication dates, not all
+Complete Tales of Henry James}, cross-referencing would result in
+errors because, with different titles and publication dates, not all
publication data for the collection is true of each volume. To cite
the collection as a whole, as in \textit{CMOS} \ref{14.117}, add a
separate entry:
@@ -2512,29 +2604,29 @@ options, see sections \ref{short} and \ref{preamble}.
\noindent With options \opt{short} and \opt{ibid}:
\begin{citeonly}
-\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}}
\item \cite[3]{morrison2004a}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[18]{morrison2004a}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}\toggletrue{ibidpage}}
\item \cite[18]{morrison2004a}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[24--26]{morrison2004a}
-\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}}
\item \cite[401-2]{morrison2004b}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[433]{morrison2004b}
-\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}\toggletrue{shortfirst}}
\item \cite[37--38]{diaz2008}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}}
\item \cite[403]{morrison2004b}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}}
\item \cite[152]{diaz2008}
\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
\item \cite[201-2]{diaz2008}
\AtNextMultiCite{\toggletrue{short}\toggletrue{shortfirst}}
\item \cites[240]{morrison2004b}[32]{morrison2004a}
-\AtNextCitekey{\toggletrue{short}\toggletrue{ibid}}
+\AtNextCitekey{\toggletrue{short}}
\item \cite[33]{morrison2004a}
\end{citeonly}