% \iffalse % $Id: nmbib.dtx,v 1.21 2015/07/27 20:22:45 boris Exp $ % %% Copyright 2015, Michael Cohen %% and Boris Veytsman %% This work may be distributed and/or modified under the %% conditions of the LaTeX Project Public License, either %% version 1.3 of this license or (at your option) any %% later version. %% The latest version of the license is in %% http://www.latex-project.org/lppl.txt %% and version 1.3 or later is part of all distributions of %% LaTeX version 2003/06/01 or later. %% %% This work has the LPPL maintenance status `maintained'. %% %% The Current Maintainer of this work is Boris Veytsman %% %<*gobble> % \fi % \CheckSum{978} % % %% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z %% Digits \0\1\2\3\4\5\6\7\8\9 %% Exclamation \! Double quote \" Hash (number) \# %% Dollar \$ Percent \% Ampersand \& %% Acute accent \' Left paren \( Right paren \) %% Asterisk \* Plus \+ Comma \, %% Minus \- Point \. Solidus \/ %% Colon \: Semicolon \; Less than \< %% Equals \= Greater than \> Question mark \? %% Commercial at \@ Left bracket \[ Backslash \\ %% Right bracket \] Circumflex \^ Underscore \_ %% Grave accent \` Left brace \{ Vertical bar \| %% Right brace \} Tilde \~} % %\iffalse % \begin{macrocode} \documentclass{ltxdoc} \usepackage{hypdoc} \usepackage{nmbib} \let\cite\citep \PageIndex \CodelineIndex \RecordChanges \EnableCrossrefs \begin{document} \DocInput{nmbib.dtx} \end{document} % \end{macrocode} % % \fi % \MakeShortVerb{|} % \GetFileInfo{nmbib.sty} % % \changes{v1.00}{2014/01/23}{Preliminary release} % \changes{v1.03}{2015/07/25}{Added day field in the chrono bst} % % \title{New Multibibliography Package\thanks{\copyright 2015 Michael % Cohen and Boris Veytsman}} % \author{Boris Veytsman\thanks{borisv@lk.net} % \and Michael Cohen\thanks{mcohen@u-aizu.ac.jp}} % \date{\filedate, \fileversion} % \maketitle % % \begin{abstract} % The |nmbib| package is a rewrite of |multibiliography| package % providing multiple bibliographies with different sorting. The new % version offers a number of citation commands, streamlines the % creation of bibliographies, ensures compatibility with the % |natbib| package, and provides other improvements. % \end{abstract} % % \tableofcontents % % \clearpage % %\section{Introduction} %\label{sec:intro} % % The list of cited works accompanying a scholarly work is not just % a technical appendix or a subtle way to avoid accusations of % plagiarism. Rather, it is an organic part of the work, telling the % user a story about the field of study and showing why the given % work is an organic part of it. There are several ways to tell the % story, and accordingly there are several ways to organize the list % of references. One can tell it accordingly to logical % development of ideas, so the order of citations follows the order % they are mentioned in the paper. This leads to the ``unsorted'' % style of references, usual in physics and mathematics papers and books. % Alternatively, one can choose to tell the story as the story of % people behind the ideas, ordering the citations alphabetically by % author names. This is the order used in humanities and other fields. % Yet another possibility is to tell the story in the chronological % order. The chronological order of citations is not widely used, % with the important exception of resumes and CVs, but it has its own % advantages. % % In the times BC (Before Computers), difficulties in manual creation % of reference lists discouraged presentation of more than one such % list. Now we can easily have as many lists as we want. Accordingly % we can have not one, but several lists of references, each telling a % different story. The package % |multibibliography|~\cite{Multibibliography, Multibibliography13} % provided just this: multiple bibliographies with the same references arranged % in different orders, with hyperlinks between entries. However, this % package had various limitations, including: the fixed format of % typesetting citations in text, the limitation on the possible % Bib\TeX\ styles. Also, it requires post-processing by a Perl % script. % % This package tries to lift these limitations. It provides the % following improvements over the original |multibiliography|: % \begin{enumerate} % \item A Perl postprocessing is no longer needed: all processing is done % by Bib\TeX. % \item The user can work with familiar |natbib|~\cite{Daly:Natbib} % commands \cs{citep}, \cs{citet}, \cs{citeauthor}, \cs{citeyear}, % \cs{citenum}. % \item Any |natbib|-compatible |.bst| file can be used for formatting % the bibliography provided that it has the right sorting of entries % (note that the provided style gives |natbib|-compatible % chronological ordering). % \item The style is much more customizable than that produced by % |multibibliography|. % \item Hyperlinks between the entries are improved. % \end{enumerate} % % Note about the name. The letter \emph{n} in the package name can be % interpreted as % \begin{enumerate} % \item \emph{N}ew multibibliography style, or % \item \emph{N}atbib-compatible multibibliography style, or even % \item \emph{N}-ordering multibibliography style, with $N$ being a % usual mathematical moniker for ``many''. % \end{enumerate} % % %\section{User Guide} %\label{sec:ug} % % %\subsection{Usage Summary} %\label{sec:ug_usage} % % The simplest way to use the package is the following: % \begin{enumerate} % \item Add to the preamble of your |.tex| file % \begin{verbatim} % \usepackage{nmbib} % \multibibliography{FILE1, FILE2, ...} % \multibibliographystyle{timeline}{STYLE1} % \multibibliographystyle{sequence}{STYLE2} % \multibibliographystyle{authors}{STYLE3} % \end{verbatim} % % \item Use |natbib| commands such as |\cite|, |\citep|, |\citet|, % |\citeauthor|, |\citeyear|, and |\citenum|. The command |\citeall| % creates a ``full citation'', showing the author, year, and % number of the citation. % \item Put in your document at the places where you want the % bibliography the commands |\printbibliography{timeline}|, % |\printbibliography{sequence}|, and |\printbibliography{authors}|. % % \item Run |latex| on the |tex| file. This will create, besides the % standard auxiliary file |FILE.aux|, three new files: % |FILE-timeline.aux|, |FILE-sequence.aux| and |FILE-authors.aux|. % \item Run |bibtex| on each of the three auxiliary files mentioned % above: % \begin{verbatim} % bibtex FILE-timeline % bibtex FILE-sequence % bibtex FILE-authors % \end{verbatim} % \item Run |latex| on the |tex| file at least twice (this is a % |natbib| requirement). % \end{enumerate} % % Below we discuss these commands in more detail as well as % customization commands. % % %\subsection{Options} %\label{sec:ug_options} % % The |nmbib| package internally uses |natbib| \cite{Daly:Natbib} for citation % formatting. The options used for |nmbib| are sent to |natbib|. % %\subsection{Setting up} %\label{sec:ug_setting} % % \DescribeMacro{\multibibliography}% % The list of \BibTeX\ databases to be used for references is set by % the command \cs{multibibliography}\marg{bibfile1, bibfile2, \dots}. % Note that the similar command \cs{bibliography} in standard % \LaTeX\ performs \emph{two} functions: % it sets up the databases and prints the % bibliography. The command \cs{multibibliography}, on the other % hand, performs only one function: the setting up of the databases. % The bibliographies themselves are printed by the command % \cs{printbibliography}, discussed below. Therefore the \cs{multibibliography} command % can be issued anywhere in the file, including % the preamble. % % \DescribeMacro{\multibibliographystyle} % The standard \cs{bibliographystyle} command sets the bibliography % style of the reference list. Since |nmbib| generates several % bibliographies, the corresponding command is more versatile: % \cs{multibibliographystyle}\marg{type}\marg{style}, % where |type| is the type of the bibliography % \begin{description} % \item[timeline:] Chronologically ordered list. % \item[sequence:] Sequentially ordered list. % \item[authors:] Alphabetic list, ordered according to % authors' names. % \end{description} % and \marg{style} is the corresponding \BibTeX\ style. The style, of % course, must sort the entries in the proper order. % % The package can accommodate any |natbib| \BibTeX\ style, % including |unsrtnat|, |plainnat|, and |abbrvnat|. It may work with other % styles, but success is not guaranteed. The \BibTeX\ styles % supplied with the package offer additional hyperlink features; if % you do not use |hyperref| or do not care for the links between the % different reference lists, you probably do not need these features. % % There are three citation styles provided with the package: % \begin{description} % \item[chronoplainnm:] Similar to |plainnat|, but sorting % entries in chronological order (using year, month and day if the % latter two are available) and providing links to other lists from the % body of the entries. % \item[plainnm:] Similar to |plainnat|, but providing links to other % lists from the body of the entries. The sorting is alphabetical % by authors' names, as in |plainnat|. % \item[unsrtnm:] Similar to |unsrtnat|, but providing links to other % lists from the body of the entries. The order of entries is the % order of citations, as in |unsrtnat|. % \end{description} % % %\subsection{Citation commands} %\label{sec:ug_commands} % % All citations commands defined in |natbib| can be used: \cs{cite}, % \cs{citenum}, \cs{citealt}, \cs{citet}, \cs{Citet}, etc. The |nmbib| package % adds a couple of new commands, described here. % % \DescribeMacro{\citealn}% % The commands \cs{citealn}\marg{keys} is the alternative \cs{citenum} % command: it puts square brackets around its argument. % % \DescribeMacro{\citeall}% % The command \cs{citeall}\marg{keys} produces citations with % authors' names, years, and sequence numbers, similar to that % produced by the \cs{cite} command in the |multibibliography| package. % To reproduce the behavior of that package, just put in % the preamble of your document % \begin{verbatim} % \let\cite\citeall % \end{verbatim} % % The starred command \cs{citeall*} is similar to \cs{citeall} with % the following difference: if \cs{citeall} prints the shortened author % list for papers with multiple authors (``Jones et.\ al.''), % \cs{citeall*} prints the full list (``Jones, Smith, and Brown''). % % %\subsection{Printing the bibliographies} %\label{sec:ug_print} % % % \DescribeMacro{\printbibliography}% % The command \cs{printbibliography}\marg{type} prints the % bibliography. The argument is the type of bibliography--- % |timeline|, |sequence|, or |authors| (see the explanation above). % % % You can put this command anywhere in your file; the corresponding % bibliography will be printed in this place. You can use all three % possible lists, any two, or even one. The only limitation is % that the ``base type'' list must be included. % (See Section~\ref{sec:ug_customization} for the discussion of base type.) % % %\subsection{Hyperlinks} %\label{sec:ug_hyperlinks} % % The |nmbib| package tries to fully exploit features of |hyperref| package % \cite{Rahtz:Hyperref}. Links from and between % citations should work ``smartly'': links from authors' names go % into the alphabetic list, links from the publication years go into the % chronological list, and links from the citation numbers go into the % sequential list. % % \DescribeMacro{\nmbibRedirectLinks}% % Of course, the user might include only some of the three possible % lists. In this case some links become ``dangling.'' The command % \cs{nmbibRedirectLinks}\penalty0\marg{source\_type}% % \penalty0\marg{target\_type} redirects the links that otherwise go to % the list \marg{source\_type} to the list \marg{source\_type}. For % example, if a chronological list is not included, the % command |\nmbibRedirectLinks{timeline}{authors}| makes the links % from the publication year go into the alphabetical list of % publications. % % \DescribeMacro{\nmbibLink}% % The clickable links themselves are created with the help of the % command \cs{nmbibLink}\marg{citation}\marg{type}\marg{text}. This % command is available to the user, which enables constructions like % \begin{verbatim} % The idea was proposed by \citet{Thor10}. Note the assumption of % differentiability in \nmbibLink{Thor10}{authors}{his paper}. % \end{verbatim} % In this example ``his paper'' becomes a hyperlink to the paper in % the alphabetical list. % % The links created with \cs{nmbibLink} respect the redirections set % by the command \cs{nmbibRedirectLinks}. % % %\subsection{Advanced customization} %\label{sec:ug_customization} % % \DescribeMacro{\timelinerefname}% % \DescribeMacro{\sequencerefname}% % \DescribeMacro{\authorsrefname}% % \DescribeMacro{\timelinebibname}% % \DescribeMacro{\sequencebibname}% % \DescribeMacro{\authorsbibname}% % The commands \cs{refname} (for article-like classes) and % \cs{bibname} (for book-like classes) retain the names of the % bibliography. The |nmbib| package defines three macros |\TYPErefname| and % three commands |\TYPEbibname|, |TYPE| being |timeline|, |sequence|, % or |authors|. These macros can be redefined with the usual % \cs{renewcommand}. % For example, for a German article, one might use % \begin{verbatim} % \renewcommand{\timelinerefname}{Chronologische Referenzliste} % \renewcommand{\sequencerefname}{Sequenzielle Referenzliste} % \renewcommand{\authorsrefname}{Alphabetische Referenzliste} % \end{verbatim} % % % % \DescribeMacro{\multibibliographyfilename} % By default the package creates three auxillary files with the % following file names: |FILE-timeline.aux|, % |FILE-sequence.aux|, and |FILE-authors.aux|. The command % \cs{multibibliograpyfilename}\marg{type}\marg{name} changes this % default. Here \marg{type} is |timeline|, |sequence|, or |authors|, and % \marg{name} is the file name. The default setting is equivalent to % \begin{verbatim} % \multibibliograpyfilename{timeline}{\jobname-timeline} % \multibibliograpyfilename{sequence}{\jobname-sequence} % \multibibliograpyfilename{authors}{\jobname-authors} % \end{verbatim} % This command may be present only in the preamble of a document. % % % % \DescribeMacro{\nmbibBasetype}% % Suppose an author published several works in the same year. They % need to be distinguished in the text and bibliography. In the % standard author-year styles this is done by adding a suffix after % the year: if we want to cite three works by A.\,U.\ Thor published % in 2013, they are respectively cited as Thor~(2013a), Thor~(2013b), and % Thor~(2013c). When we have only one reference list, % the choice of suffixes is simple: the first work becomes 2013a, the % second 2013b, etc. But how should we deal with the situation of % several subbibliographies? The order of these references in different % lists could be different, so the same work could get different labels in % different lists. % % To prevent this confusion, only one reference list is used to % construct the labels. We call the corresponding list type the % \emph{base type}. By default it is |sequence|, but this might be % changed (and should be chaged if the user does not include % sequential list) with the command \cs{nmbibBasetype}\marg{type}, with % \marg{type} being |timeline|, |sequence|, or |authors|. The list % chosen as a base type must be included with the % \cs{printbibliography} macro. % % Package |natbib| defines citation aliases: you can use ``Paper~I'' % or ``Paper~II'' as aliases for some papers. Normally hyperlinks % from aliases go into the alphabetic list; however, you can change % it with the special type |alias| in \cs{nmbibRedirectLinks}, for % example, % \begin{verbatim} % \nmbibRedirectLinks{alias}{timeline} % \end{verbatim} % % % % \DescribeMacro{\nmbibSetCiteall}% % The format of the \cs{citeall} and \cs{citeall*} macros can be % changed by the command \cs{nmbibSetCiteall}\marg{pattern}, where % \marg{pattern} sets the citation format. The pattern can use any % punctuation, \cs{nmbibLink} command and the special tokens % \cs{nmbibKEY}, \cs{nmbibNAME}, \cs{nmbibDATE} and \cs{nmbibNUM}, % which are substituted by the citation information. For example, the % default format is established by the command % \begin{verbatim} % \nmbibSetCiteall{\nmbibLink{\nmbibKEY}{authors}{\nmbibNAME} % (\nmbibLink{\nmbibKEY}{timeline}{\nmbibDATE}) % [\nmbibLink{\nmbibKEY}{sequence}{\nmbibNUM}]} % \end{verbatim} % which produces the following result: \citeall{Daly:Natbib}. % % \DescribeMacro{\nmbibSetBiblabel}% % The command \cs{nmbibSetBiblabel}\marg{type}{pattern} is used to set % the format of the label in the reference list of the given type. % The \marg{pattern} parameter uses the same tokens as \cs{nmbibSetCiteall}. % The default is % \begin{verbatim} %\nmbibSetBiblabel{timeline}{[\nmbibDATE: % \nmbibLink{\nmbibKEY}{authors}{\nmbibNAME}; % \nmbibLink{\nmbibKEY}{sequence}{\nmbibNUM}]} %\nmbibSetBiblabel{authors}{[\nmbibNAME\ % (\nmbibLink{\nmbibKEY}{timeline}{\nmbibDATE}); % \nmbibLink{\nmbibKEY}{sequence}{\nmbibNUM}]} %\nmbibSetBiblabel{sequence}{[\nmbibNUM: % \nmbibLink{\nmbibKEY}{authors}{\nmbibNAME} % (\nmbibLink{\nmbibKEY}{timeline}{\nmbibDATE})]} % \end{verbatim} % To suppress the label for any type, use an empty pattern: % |\nmbibSetBiblabel{authors}{}|. To use numerical labels only for a % sequential list, issue |\nmbibSetBiblabel{sequence}{[\nmbibNUM]}| % etc. % % \DescribeMacro{nmbibYearSuffixOff}% % \DescribeMacro{nmbibYearSuffixOn}% % If there are several works with the same authors and year, the % package adds suffixes to the year numbers, like 2003a and 2003b. By % default these suffixes are printed both in the labels \emph{and} in % the bibliographic entries themselves. The command % \cs{nmbibYearSuffixOff} deletes these suffixes from the bibliography % entries (but not from labels). The command \cs{nmbibYearSuffixOff} % restores them. % % %\subsection{Auxillary script} %\label{sec:script} % % To integrate the package with IDEs like \TeX Shop, we provide a % simple script |nmbibtex| which compiles all bibliographies. Its % usage is very simple: % \begin{verbatim} % nmbibtex FILE % \end{verbatim} % where |FILE| is the file name without prefixes. % % %\StopEventually{\clearpage\nmbibYearSuffixOff % \multibibliography{nmbib}% % \multibibliographystyle{timeline}{chronoplainnm}% % \multibibliographystyle{sequence}{unsrtnm}% % \multibibliographystyle{authors}{plainnm}% % \printbibliography{sequence}% % \printbibliography{authors}% % \printbibliography{timeline}} % % \clearpage % % \section{Implementation} % \label{sec:implementation} % % %\subsection{Declarations} %\label{sec:decl} % % We start with declaration, who we are: % % % \begin{macrocode} % % \end{macrocode} %\Finale %\clearpage % %\PrintChanges %\clearpage %\PrintIndex % \endinput