diff options
author | Karl Berry <karl@freefriends.org> | 2018-10-02 21:39:16 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-10-02 21:39:16 +0000 |
commit | 1a6674f16762a7b9b71d62c545e49c83ddcd7989 (patch) | |
tree | 3827bb6860a7d2721145933512720c1538549295 /Master/texmf-dist/doc/latex/biblatex-ext/biblatex-ext.tex | |
parent | 44309fd5467358b33ce06716f1eb4b475fdfdf2b (diff) |
biblatex-ext (2oct18)
git-svn-id: svn://tug.org/texlive/trunk@48818 c570f23f-e606-0410-a88d-b1316a301751
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.tex | 329 |
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}})}, |