summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex')
-rw-r--r--Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex329
1 files changed, 316 insertions, 13 deletions
diff --git a/Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex b/Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex
index 1d2cf477277..40969b48540 100644
--- a/Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex
+++ b/Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex
@@ -31,11 +31,16 @@
\usepackage{booktabs}
\usepackage{multicol}
\usepackage[svgnames]{xcolor}
+\usepackage{longtable}
+\usepackage{array}
+\newcolumntype{L}[1]{%
+ >{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}
\usepackage[listings, breakable, skins]{tcolorbox}%
\usetikzlibrary{arrows.meta}
-\usepackage[style=ext-authoryear-icomp, backend=biber]{biblatex}
+\usepackage[style=ext-authoryear-iecomp, backend=biber]{biblatex}
\addbibresource{biblatex-examples.bib}
\addbibresource{biblatex-ext-examples.bib}
+\usepackage{biblatex-ext-tabular}
\makeatletter
\defbibcheck{examplebib}{%
@@ -50,6 +55,14 @@
\docsvlist{#1}%
\printbibliography[check=examplebib, heading=none]}
+\newcommand*{\exampleprintbibtab}[1]{%
+ \nocite{#1}%
+ \let\extblxdoc@examplebib@list\empty
+ \def\do##1{\listeadd\extblxdoc@examplebib@list{\detokenize{##1}}}%
+ \docsvlist{#1}%
+ \printbibtabular[check=examplebib, heading=none]}
+
+
\iffontspec
\def\textvisiblespace{%
\raisebox{-2.2pt}{%
@@ -58,6 +71,14 @@
\hbox{\vrule \@height.5ex \@width.12ex}%
\kern.04em}}
\fi
+
+\newcommand{\warnsymbol}{%
+ \makebox[2em][c]{%
+ \makebox[0pt][c]{\raisebox{.26em}{\LARGE\bfseries!}}%
+ \makebox[0pt][c]{\fontsize{40}{40}\selectfont\color{red}$\bigtriangleup$}}}
+
+\newcommand*{\marginwarn}{%
+ \leavevmode\marginpar{\raisebox{-1.5em}{\warnsymbol}}}
\makeatother
@@ -108,13 +129,17 @@
\lstdefinestyle{extblxstylelatex}{%
language = {[LaTeX]TeX},
style = {extblxstylegeneral},
- moretexcs = {setlength,bibhang,addcomma,adddot,addperiod,addcolon,addspace,
+ moretexcs = {
+ dimexpr,arraybackslash,newcolumntype,anchor,driver,plain,plainlang,
+ anchorlang,
+ setlength,bibhang,addcomma,adddot,addperiod,addcolon,addspace,
addnbspace,
mkbibbold,mkbibemph,mkbibbrackets,mkbibparens,
usebibmacro,newbibmacro,renewbibmacro,setunit,newunit,printfield,printlist,
bibopenparen,bibcloseparen,bibopenbracket,bibclosebracket,
iflistundef,iffieldundef,ifnameundef,
ExecuteBibliographyOptions,
+ defbibtabular,defbibtabulartwocolumn,defbibenvironment,
DeclareFieldFormat,DeclareDelimFormat,DeclareDelimcontextAlias,
DeclareInnerCiteDelims,UndeclareInnerCiteDelims,DeclareInnerCiteDelimsAlias,
DeclareOuterCiteDelims,UndeclareOuterCiteDelims,DeclareOuterCiteDelimsAlias,
@@ -396,7 +421,7 @@
\newcommand*{\ctan}{\mkbibacro{CTAN}}
\newcommand*{\gitbaseurl}{https://github.com/moewew/biblatex-ext}
-\newcommand*{\extblxversion}{0.4}
+\newcommand*{\extblxversion}{0.5}
\newcommand*{\biber}{Biber}
\newcommand*{\gitissuelink}[1]{%
\href{\gitbaseurl/issues/#1}{issue \##1 on github}}
@@ -413,7 +438,7 @@
author = {Moritz Wemheuer},
link = {mwemheu@gmail.com},%
revision = {\extblxversion},
- date = {\DTMDate{2018-06-10}},
+ date = {\DTMDate{2018-10-02}},
}
\hypersetup{%
@@ -626,6 +651,7 @@ Please keep in mind that some of these texts were written a while ago and
that \sty{biblatex} is actively developed: technical details may have changed
and new features make some things easier.
+\clearpage
\section{Styles}\label{sec:styles}
This bundle provides an extended version of each standard style as well as a
few new styles.
@@ -805,9 +831,25 @@ This style is similar to \sty{ext-verbose-trad2}.
\subsection{New styles}\label{sec:styles:new}
The following styles are not mere extensions of a particular standard style,
-instead they implement new combinations of the concepts available in the
-standard styles.
+instead they implement new combinations or extensions of the concepts available
+in the standard styles.
\begin{stylelist}
+\styleitem{ext-authoryear-ecomp}
+An author-year citation that is even more compact than
+\sty{ext-authoryear-comp}, it compresses lists of \bibfield{extradate} letters
+from \enquote{Knuth 1986a,b,c} to \enquote{Knuth 1986a\bibrangedash c}.
+\begin{bibexample}
+Sigfridsson and Ryde 1998 \quad Knuth 1986a\bibrangedash c
+\end{bibexample}
+
+\styleitem{ext-authoryear-iecomp}
+An author-year citation that is even more compact than
+\sty{ext-authoryear-icomp}, it compresses lists of \bibfield{extradate} letters
+from \enquote{Knuth 1986a,b,c} to \enquote{Knuth 1986a\bibrangedash c}.
+\begin{bibexample}
+Sigfridsson and Ryde 1998 \quad ibid.\quad Knuth 1986a\bibrangedash c
+\end{bibexample}
+
\styleitem{ext-authoryear-terse}
An author-year citation style that suppresses years for author lists with only
one work in the bibliography.
@@ -826,6 +868,13 @@ This style is like \sty{ext-authortitle-tcomp}, but it is based on
Sigfridsson and Ryde \quad Knuth 1984, 1986
\end{bibexample}
+\styleitem{ext-authoryear-tecomp}
+A compact author-year citation style that combines \sty{ext-authoryear-tcomp}
+and \sty{ext-authoryear-ecomp}.
+\begin{bibexample}
+Sigfridsson and Ryde \quad Knuth 1984, 1986a\bibrangedash c
+\end{bibexample}
+
\styleitem{ext-authoryear-ticomp}
A compact author-year citation style with \enquote{ibidem} function that
suppresses years for author lists with only one work in the bibliography.
@@ -835,9 +884,16 @@ This style is like \sty{ext-authortitle-ticomp}, but it is based on
Sigfridsson and Ryde \quad ibid. \quad Knuth 1984, 1986
\end{bibexample}
-\end{stylelist}
+\styleitem{ext-authoryear-teicomp}
+A compact author-year citation style that combines \sty{ext-authoryear-ticomp}
+and \sty{ext-authoryear-iecomp}.
+\begin{bibexample}
+Sigfridsson and Ryde \quad ibid. \quad Knuth 1984, 1986a\bibrangedash c
+\end{bibexample}
+\end{stylelist}
+\clearpage
\section{Options}\label{sec:opt}
All options of the \sty{biblatex} package are supported and each style supports
the options of its standard counterpart.
@@ -1400,6 +1456,7 @@ back to the end of the entry.
\makeatother
\end{optionlist}
+\clearpage
\section{Further Customisations}\label{sec:opt:cust}
Aside from the new options mentioned in the last section the styles of this
bundle also offer additional field formats, punctuation and delimiter commands,
@@ -1717,16 +1774,28 @@ The default is a comma followed by a space.
\exampleprintbib{knuth:ct:a}
\end{bibexample}
+
\csitem{extradateonlycompcitedelim}\CSdelimMark
Similar to \cmd{compcitedelim}, but indended for use between compressed
citations where the second is an \bibfield{extradate} only.
The default is a comma (\emph{not} followed by a space).
-\end{ltxsyntax}
\begin{bibexample}
\DeclareDelimFormat{extradateonlycompcitedelim}{\highlightbf{\addcomma}}
\cite{knuth:ct:b,knuth:ct:c}
\end{bibexample}
+
+\csitem{extradateonlycompciterangedelim}\CSdelimMark
+Similar to \cmd{extradateonlycompcitedelim}, but indended for use in a
+compressed list of \bibfield{extradate}s in the \sty{-ecomp} styles.
+The default is \cmd{bibrangedash}.
+\begin{bibexample}
+\DeclareDelimFormat{extradateonlycompciterangedelim}{%
+ \highlightbf{\bibrangedash}}
+\cite{knuth:ct:b,knuth:ct:c,knuth:ct:d}
+\end{bibexample}
+\end{ltxsyntax}
+
\subsection{Delimiters for citation commands}\label{sec:opt:citedelims}
The delimiters for citation commands provided by the styles of this bundle
offer a simple way to customise the bracketing of citation commands.
@@ -1898,6 +1967,9 @@ All styles of \sty{biblatex-ext} define the following wrapper commands
\centering
\caption{Delimiter wrappers defined by \sty{biblatex-ext}}
\label{tab:delimwrappers}
+\begin{minipage}{\linewidth}
+\renewcommand\footnoterule{}
+\centering
\begin{tabular}{@{}lll@{}}
\toprule
& \multicolumn{2}{c}{Modifier} \\
@@ -1907,11 +1979,15 @@ Citation command & Outer & Inner\\
\cmd{cite} & \cmd{mkoutercitedelims} & \cmd{mkinnercitedelims}\\
\cmd{parencite} & \cmd{mkouterparencitedelims} & \cmd{mkinnerparencitedelims}\\
\cmd{textcite} & \cmd{mkoutertextcitedelims} & \cmd{mkinnertextcitedelims}\\
-\cmd{footcite} & & \cmd{mkinnerfootcitedelims}\\
-\cmd{bbx@xrefcite} & \cmd{mkouterbbx@xrefcitedelims} & \cmd{mkinnerbbx@xrefcitedelims}\\
-\enquote{\cmd{bbx@introcite}} & & \cmd{mkinnerbbx@introcitedelims}\\
+\cmd{footcite} & \cmd{mkouterfootcitedelims} & \cmd{mkinnerfootcitedelims}\\
+\cmd{bbx@xrefcite} & \cmd{mkouterbbx@xrefcitedelims} &
+ \cmd{mkinnerbbx@xrefcitedelims}\\
+\enquote{\cmd{bbx@introcite}} & ---%
+ \footnote{Use the field format \sty{bbx@introcite} instead,
+ see \secref{sec:opt:style}.} & \cmd{mkinnerbbx@introcitedelims}\\
\bottomrule
\end{tabular}
+\end{minipage}
\end{table}
@@ -1975,6 +2051,16 @@ fields will be printed by \bibmacro{maintitle+title} or
A bibliography macro to print the \bibfield{edition} field, this avoids a direct
\lstinline|\printfield{edition}| in the bibliography drivers.
+\keyitem[version]
+Similar to the \bibmacro{edition} bibliography macro, \bibmacro{version}
+prints the \bibfield{version} field, this avoids a direct
+\lstinline|\printfield{version}| in the bibliography drivers.
+
+\keyitem[pagetotal]
+Similar to the \bibmacro{edition} bibliograohy macro, \bibmacro{pagetotal}
+prints the \bibfield{pagetotal} field, this avoids a direct
+\lstinline|\printfield{pagetotal}| in the bibliography drivers.
+
\keyitem[in:editor(+others)]
The bibliography macro to print the \bibfield{editor} before the
\bibfield{booktitle} for \bibtype{inbook}, \bibtype{incollection} and
@@ -2022,11 +2108,228 @@ sensible values are \bibfield{publisher}, \bibfield{institution} and
A bibliography macro to print the \bibfield{type} and \bibfield{number} fields.
\end{keymarglistbook}
+\clearpage
+\section{Tabular Bibliographies}\label{sec:tabularbib}
+An experimental addition to this bundle is the package
+\sty{biblatex-ext-tabular} which allows you to typeset tabular
+(two-column) bibliographies.
+The package must be loaded after \sty{biblatex} and has no further options.
+\begin{biblatexcode}
+\usepackage[(*@\prm{options}@*)]{biblatex}
+(*@\dots @*)
+\usepackage{biblatex-ext-tabular}
+\end{biblatexcode}
+If it turns out that the tabular bibliography package is useful on its own,
+it may be split off from the rest of this bundle in the future.
+In that case the name \sty{biblatex-ext-tabular} may be deprecated in favour
+of something more snappy.
+The old name should then continue to work, but you may have to install a new
+package to be able to use it.
+
+The package \sty{biblatex-ext-tabular} can be used independently of the styles
+provided in this bundle.
+But no matter what style you use, you will probably have to apply some tweaks
+here and there to make the output look acceptable.
+
+The code for the tabular bibliographies is based on Audrey's%
+\fnurl{https://tex.stackexchange.com/users/4483/audrey}
+answer to a question%
+\fnurl{https://tex.stackexchange.com/q/71088/35864}
+on \tex{}~--~\latex{} Stack Exchange.
+The code has been modernised to keep in sync with changes to internal macros
+and modified to allow for slightly more flexible setups, so any bugs you find
+are mine and not Audrey's. Please report them via the channels mentioned above
+in~\secref{sec:feedback}.
+
+\marginwarn Before tabular bibliographies can be used, a suitable definition
+must be supplied with \cmd{defbibtabular}.
+
+\begin{ltxsyntax}
+\cmditem{printbibtabular}[key=value, \dots]
+
+This commands prints a tabular bibliography.
+It accepts the same options as \cmd{printbibliography}, but note that
+\opt{env} must be a tabular bibliography declared with \cmd{defbibtabular}.
+The default value for \opt{env} is \opt{bibtabular}.
+
+\marginwarn\emph{Note that there is no default definition for the
+\opt{bibtabular} environment, so you must define it with \cmd{defbibtabular}
+before use. An error will be issued if you fail to provide a definition
+for \opt{bibtabular} before you use \cmd{printbibtabular} with the default
+\opt{env} value, no bibliography will be printed.}
+
+\cmditem{defbibtabular}{name}{begin code}{end code}{row code}
+
+This command defines a tabular bibliography.
+The \prm{name} is an identifier passed to the \opt{env} option of
+\cmd{printbibtabular} when selecting the environment.
+The \prm{begin code} is \latex{} code to be executed at the beginning of the
+environment, usually it will begin a tabular environment.
+The \prm{end code} is executed at the end of the environment and would
+usually end the tabular environment.
+The \prm{row code} holds the code for one row in the tabular bibliography,
+it should have no more columns than ordered in \prm{begin code} and should
+end with \lstinline|\\|.
+
+Please keep in mind that the tabular bibliography is subject to all limitations
+of the particular tabular environment you decide to use.
+
+Within the \prm{row code} argument the following macros are defined and can be
+used to typeset the result of bibliography macros.
+Every cell should normally be wrapped into exactly one of the following macro
+since they are responsible for providing the necessary entry data to the
+bibliography macros.
+
+\cmditem{plain}{code}
+
+Typesets \prm{code} with the entry data of the current entry.
+
+\cmditem{plainlang}{code}
+
+Like \cmd{plain}, but typesets \prm{code} in the language of the current
+item if the language switching options are enabled.
+
+\cmditem{anchor}{code}
+
+Like \cmd{plain}, and but additionally sets a link anchor for the current entry.
+There should only be one \cmd{anchor} or \cmd{anchorlang} per row,
+and for proper linking there should be at least one.
+Usually \cmd{anchor} or \cmd{anchorlang} is the first cell in the row.
+
+\cmditem{anchorlang}{code}
+
+Like \cmd{anchor}, but in the entry language like \cmd{plainlang}.
+
+\cmditem{driver}{precode}
+
+Typesets the bibliography entry using the correct driver.
+This always uses the entry language if language switching is enabled.
+The \prm{precode} argument can be used to execute code before the driver
+is executed.
+Usually this would be the last cell in a row, duplicate information can be
+cleaned up with help of the \prm{precode} argument.
+
+Recall that standard \env{tabular} can't break across pages, so you may want
+to give \env{longtable} a try.
+Additionally, the standard column specifiers \sty{l}, \sty{r} and \sty{c}
+define flexible-sized columns which might not be appropriate here;
+\sty{p} defines fixed-width columns but imposes justification, which does not
+look good if the columns are too narrow.
+You may want to look into fixed-width flush-left or flush-right columns%
+\fnurl{https://tex.stackexchange.com/q/12703/35864}.
+\end{ltxsyntax}
+
+The package also defines two helpful bibliography macros.
+\begin{keymarglistbook}
+ \item[tabular:sortname] Prints the labelname/sortname.
+ \item[tabular:omitsortname] Suppresses the labelname/sortname in the current
+ group.
+\end{keymarglistbook}
+
+A simple example of a useful tabular bibliography setup is
+\begin{biblatexcode}
+\usepackage{longtable}
+\usepackage{array}
+\newcolumntype{L}[1]{%
+ >{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}
+
+\defbibtabular{bibtabular}
+ {\setlength{\LTpre}{0pt}%
+ \setlength{\LTpost}{0pt}%
+ \renewcommand*{\arraystretch}{2}%
+ \begin{longtable}{%
+ @{}
+ L{\dimexpr0.3\textwidth-\tabcolsep\relax}
+ L{\dimexpr0.7\textwidth-\tabcolsep\relax}
+ @{}}}
+ {\end{longtable}}
+ {\anchorlang{\usebibmacro{tabular:sortname}} &
+ \driver{\usebibmacro{tabular:omitsortname}} \\}
+\end{biblatexcode}
+This defines a two-column bibliography where the first column shows the
+primary name associated with the work (the labelname/sortname) and the
+second colum shows the bibliography data with the primary name suppressed
+to avoid duplication.
+The anchor is set to the first column, so that a viewer jumps there
+if a link to the entry is followed.
+
+\begin{bibexample}
+ \defbibtabular{bibtabular}
+ {\setlength{\LTpre}{0pt}%
+ \setlength{\LTpost}{0pt}%
+ \renewcommand*{\arraystretch}{2}%
+ \begin{longtable}{%
+ @{}
+ L{\dimexpr0.3\textwidth-\tabcolsep\relax}
+ L{\dimexpr0.7\textwidth-\tabcolsep\relax}
+ @{}}}
+ {\end{longtable}}
+ {\anchorlang{\usebibmacro{tabular:sortname}} &
+ \driver{\usebibmacro{tabular:omitsortname}} \\}
+
+ \exampleprintbibtab{sigfridsson,geer,nussbaum}
+\end{bibexample}
+
+For the common case of two-column tabular bibliographies there is a thin
+wrapper around \cmd{defbibtabular} that might turn out a bit easier to use.
+\begin{ltxsyntax}
+ \cmditem{defbibtabulartwocolumn}{name}{begin code}{end code}%
+ {anchor code}{driver precode}
+
+ This defines a two-column tabular bibliography environment with \prm{name},
+ \prm{begin code} and \prm{end code} as for \cmd{defbibtabular}.
+
+ The first column is an \cmd{anchorlang} column that executes
+ \prm{anchor code}, the second column executes a pre-code and
+ the bibliography driver.
+
+\begin{biblatexcode}
+\defbibtabulartwocolumn{(*@\prm{name}@*)}
+ {(*@\prm{begin code}@*)}{(*@\prm{end code}@*)}
+ {(*@\prm{anchor code}@*)}{(*@\prm{driver precode}@*)}
+\end{biblatexcode}
+is equivalent to
+\begin{biblatexcode}
+\defbibtabular{(*@\prm{name}@*)}
+ {(*@\prm{begin code}@*)}{(*@\prm{end code}@*)}
+ {\anchorlang{(*@\prm{anchor code}@*)} & \driver{(*@\prm{driver precode}@*)} \\}
+\end{biblatexcode}
+
+Using \cmd{defbibtabulartwocolumn} the example from above could be written as
+\begin{biblatexcode}
+\usepackage{longtable}
+\usepackage{array}
+\newcolumntype{L}[1]{%
+ >{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}
+
+\defbibtabulartwocolumn{bibtabular}
+ {\setlength{\LTpre}{0pt}%
+ \setlength{\LTpost}{0pt}%
+ \renewcommand*{\arraystretch}{2}%
+ \begin{longtable}{%
+ @{}
+ L{\dimexpr0.3\textwidth-\tabcolsep\relax}
+ L{\dimexpr0.7\textwidth-\tabcolsep\relax}
+ @{}}}
+ {\end{longtable}}
+ {\usebibmacro{tabular:sortname}}
+ {\usebibmacro{tabular:omitsortname}}
+\end{biblatexcode}
+\end{ltxsyntax}
+
+\clearpage
\section{Revision History}\label{sec:log}
The GitHub repository of this project uses release tags, so you can compare
the changes in source code there.\footnote{\url{\gitbaseurl/compare/}}
See also \sty{CHANGES.md}.
+
+The numbers on the right indicate the relevant section of the manual.
\begin{changelog}
+\begin{release}{0.5}{2018-10-02}
+\item New \sty{ext-authoryear-*ecomp} style subfamily\see{sec:styles:new}
+\item Added outer cite delimiters for \cmd{footcite}\see{sec:opt:citedelims}
+\item Added experimental tabular bibliography\see{sec:tabularbib}
+\end{release}
\begin{release}{0.4}{2018-06-10}
\item Renamed \cmd{DeclareOuterCiteDelim} and friends to
\cmd{DeclareOuterCiteDelims}
@@ -2062,7 +2365,7 @@ See also \sty{CHANGES.md}.
\end{changelog}
\begin{bibexample}[breakable]
-\printbibliography[title={Example References}]
+\printbibliography[title={Example \refname}]
\end{bibexample}
\clearpage
@@ -2072,7 +2375,7 @@ The following example bibliography shows some common punctuation commands
in use.
Commands provided by standard \sty{biblatex} are marked in
\textit{\cmd{italics}}, new commands defined by \sty{biblatex-ext} are in
-\textbf{\cmd{bold}}.
+\textbf{\cmd{bold}} and linked to their documentation.
\begin{bibexample}[title={Punctuation and delimiters
(defined by \textit{standard \sty{biblatex}} and
\textbf{\sty{biblatex-ext}})},