summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/biblatex-contrib/biblatex-manuscripts-philology/documentation/biblatex-manuscripts-philology.tex
blob: b67c426528daf9e2ed90773bf7642ef7b1d493a3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
\documentclass{ltxdockit}[2011/03/25]
\usepackage{btxdockit}
\usepackage{metalogo}
\usepackage{fontspec}
\usepackage[mono=false]{libertine}
\usepackage{microtype}
\usepackage[american]{babel}
\usepackage[strict]{csquotes}
\setmonofont[Scale=MatchLowercase]{DejaVu Sans Mono}
\usepackage{shortvrb}
\usepackage{pifont}
\usepackage{minted}
% Useful commands
\newcommand{\biblatex}{biblatex\xspace}
\pretocmd{\bibfield}{\sloppy}{}{}
\pretocmd{\bibtype}{\sloppy}{}{}
\newcommand{\meta}[1]{\texttt{<#1>}}
% Meta-datas
\titlepage{%
	title={Manuscripts description for philology with biblatex},
	subtitle={New data types},
	email={maieul <at> maieul <dot> net},
	author={Maïeul Rouquette},
	revision={2.1.2},
	date={07/01/2020},
	url={https://github.com/maieul/biblatex-manuscripts-philology}}


\begin{document}

\printtitlepage
\tableofcontents
\section{Introduction}
\subsection{Goals}
The \biblatex package defines some standard fields for entry, and allows the use
of extra fields, like \bibfield{usera}, \bibfield{userb}. However, the number of
extra fields needed to describe manuscripts in an introduction of a critical edition
of classical texts is too great to use these fields' names without mistake.

The aim of this package is twofold:

\begin{itemize}
\item Provides new datatype: \bibtype{manuscripts} with appropriate fields.
\item Provides new bibliography styles to print the list of manuscripts:
\begin{itemize}
	\item As a detailed list of witnesses of a text.
	\item As a \emph{conspectus siglorum}.
\end{itemize}
\end{itemize}

You can see minimal example in the file \href{file:example.pdf}{example.pdf}.
\subsection{Credits}

This package was created for Maïeul Rouquette's
PhD\footnote{\url{http://apocryphes.hypothese.org}.} in 2014. It is licenced on
the \emph{\LaTeX\ Project Public
Licence}\footnote{\url{http://latex-project.org/lppl/lppl-1-3c.html}.}.

All issues can be submitted, in French or English, in the GitHub issues page\footnote{\url{https://github.com/maieul/biblatex-manuscripts-philology/issues}.}.

\section{Requirement}

This package needs \biblatex~3.3 or later.

\section{New type and fields}

This package defines one new bibtype \bibtype{manuscript}, which is to be used to define a manuscript.

\subsection{Mandatory}
This bibtype has these mandatory fields:

\begin{fieldlist}

\fielditem{collection}{literal} the collection in the library. For example:
\verb+Supplément grec+ or \verb+Vaidyaka+.

\fielditem{location}{literal} the city or place where the manuscript is kept. For
example: \verb+Paris+ or \verb+Oxford+ or \verb+Varanasi+.

\fielditem{library}{literal} the library where the manuscript is kept. For example:
\verb+Bibliothèque nationale de France+ or \verb+Sarasvatī Bhavan Library+.


\fielditem{shelfmark}{literal} the shelfmark in the collection. For example:
\verb+241+.  Do not prefix with \enquote{MS}.
\end{fieldlist}

\subsection{Optional}
This bibtype can use the optional fields:

\begin{fieldlist}

\fielditem{bookpagination}{key} the pagination or foliation of the manuscript
which is studied. The standard \biblatex pagination keys are allowed, but the
package adds a new key: \texttt{folio}.

The value of this field will be used
when printing the \bibfield{pages} and \bibfield{pagetotal}.
E.g., ``ff.~3--5'' (when  \bibfield{bookpagination} =
\enquote{folio}) or ``pp.~88--99'' (\enquote{page}).  See the \biblatex manual for details.

\fielditem{columns}{integer} the number of column by pages. Basically, only two numbers are allowed: \verb+1+ or \verb+2+.

\fielditem{dating}{literal} the dating of the manuscript. It can be for example a
century.


\label{field:layer}\fielditem{layer}{key} for palimpsests, the layer which is studied. There is two possibility:
	\begin{description}
		\item[inf] for the inferior layer.
		\item[sup] for the superior layer
	\end{description}

\fielditem{shortcollection}{literal} the abreviated form of the collection. Not used by the default style.\label{field:shortcollection}


\fielditem{shortlibrary}{literal} the abreviated form of the library. Not used by the default style.


\fielditem{pages}{range} the pages which are studied in the manuscript. In this
field, you can use the macros \cs{recto} and \cs{verso}.  This value will be used
when formatting citations.

Use this field also for manuscript folio numbers.  E.g., \enquote{3\cs{verso}--5\cs{recto}}.

\fielditem{pagetotal}{integer} the number of pages or folios in the manuscript.


\fielditem{pagination}{key} the pagination of part of manuscript which is studied.
The standard pagination keys are allowed, but the package adds a new key:
\verb+folio+.  This value will control the formatting the
$\langle$\emph{postnote}$rangle$ argument of a citation command (see the
\biblatex manual for details).


\fielditem{shorthand}{literal} the shorthand of the manuscript. If this field is empty, the entry key will be used as shorthand, except if the version \opt{manuscript-noautoshorthand} is loaded. See \secref{noautoshorthand}.

\listitem{script}{key or literal} the script, i.e. the \emph{writing system} of the
manuscript (for example Devanāgarī, Śāradā, Cyrillic).
 You can use or a key-value system, or just use literal value. No default keys are defined.
 To define your own key, see \secref{key-definition}.


 \fielditem{support}{key or literal} the support of the manuscript, which will be translated into your work language. These keys are defined: \begin{itemize}
  \item \texttt{birch-bark};
  \item \texttt{palm-leaf};
  \item \texttt{papyrus};
  \item \texttt{paper};
  \item \texttt{parchment}.\footnote{Historically,
  the keyword was \texttt{pergament}, which is kept only for ascendant compatibility.}
\end{itemize}
 To define your own key, see \secref{key-definition}.
\end{fieldlist}

\subsection{Special}\label{fields:special}
There are also many special fields, which are printed only if we ask for them explicitly:

\begin{fieldlist}
\fielditem{annotation}{literal} some annotation about the manuscript and its contents. If you want to add paragraphs inside it, you must use the \cs{par} command between each paragraph.


\fielditem{catalog}{special} a list of catalogues which describe the manuscript. You must fill this field with arguments of a \cs{cites} command. For example:

\begin{minted}{tex}
@manuscript{key,
  field1 = {value1},
  field2 = {value2},
  catalog = {[prenote1][postnote1]{key1}[prenote2][postnote2]{key2}}
\end{minted}

\fielditem{contents}{literal} description of the manuscript's contents, can be used
with or instead of \bibfield{annotation}. It starts a new block into the description
output. If you want to add paragraphs inside it, you must use the \cs{par}
command between each paragraph.  E.g., ``Covers chapters 1--3 only.''


\fielditem{origin}{list} the places where the manuscript was written.

\fielditem{owner}{name} the name(s) of the owner(s) of the manuscript in the past.

\fielditem{scribe}{list} the name(s) of the scribe(s).

\end{fieldlist}

\section{Use}
\subsection{Loading}

When loading the \biblatex package, use the option \opt{bibstyle} with value equal to \opt{manuscripts}.

\begin{minted}{latex}
\usepackage[bibstyle=manuscripts,otheroption…]{biblatex}
\end{minted}

\label{noautoshorthand}If you don't want the \bibfield{shorthand} of the manuscript be auto-defined from the entry key, use \opt{manuscripts-noautoshorthand instead}.

\begin{minted}{latex}
\usepackage[bibstyle=manuscripts-noautoshorthand,otheroption…]{biblatex}
\end{minted}

The bibliographic style for other type entries is \enquote{verbose}, which call \enquote{authortitle} . However, if you need other bibliographic style, use the \verb+biblatex-multiple-dm+ package.

\subsection{Citation of one manuscript}

The manuscript description is supposed to be used with a \opt{citestyle} of the \emph{verbose} family (see the \biblatex handbook), but you can use any other \opt{citestyle}. The only problematic point is that the manuscript citation will be verbose.

So, if you use:
\begin{minted}{latex}
\cite{manuscriptkey}
\end{minted}

the full reference of the manuscript will be printed (see the example file). However, you can use \cs{shcite} to print directly the shorthand of the manuscript:

\begin{minted}{latex}
\shcite{manuscriptkey}
\end{minted}

You can also use \cs{detailscite} to print the description of the manuscript including the \enquote{special} fields (\ref{fields:special}), like \bibfield{owner} and \bibfield{annotation}.

\begin{minted}{latex}
\detailscite{manuscriptkey}
\end{minted}


A \cs{detailscites} version of the commands does the same thing, but for multiple manuscripts.

\begin{minted}{latex}
\detailscites{manuscriptkey1}{manuscriptkey2}{…}{manuscriptkeyn}
\end{minted}

\subsection{List of manuscripts: \emph{conspectus siglorum}}

You can use the standard command \cs{printshorthands} with appropriate options:

\begin{minted}{latex}
\printshorthands[type=manuscript,title=Conspectus siglorum]
\end{minted}

In the previous example, with use one option to print shorthands only for manuscripts entries, and we set the title to the classical one \enquote{Conspectus siglorum}.

\subsection{List of manuscripts with detailed fields}

If you want to print a list of manuscripts with detailed fields listed in \secref{fields:special}, just use the \opt{env} option, with value equals to
\cnt{details}.

\begin{minted}{latex}
\printshorthands[type=manuscript,env=details,title=Description of manuscripts]
\end{minted}

In this case, you must run two times biber: one after the first run of \LaTeX\ and one after the second run, to add in the \file{.bbl} the catalogues. After that, run a third time \LaTeX.

If you use \opt{manuscripts-noautoshorthand} bibstyle, this list could contain manuscripts without shorthand. By default, the descriptions of such manuscripts will be aligned on the left of the shorthands column.

\label{bibcheck}Another solution is to make two lists: one containing the manuscripts which have shorthand and one containing the manuscripts which have not shorthand. You can add to your \cmd{printbiblography} or \cmd{printshorthands}  commands a \opt{bibcheck} option, equal to \opt{withshorthand} or \opt{withoutshorthand}. As you:
\begin{minted}{latex}
\printshorthands[
  type=manuscript,
  env=details,
  title=Description of used manuscripts,
  check=withshorthand
]
\printbibliography[
  type=manuscript,
  env=details,
  title=Description of other manuscripts,
  check=withoutshorthand
]
\end{minted}

Maybe, you want to print the details but not the shorthand, even if the manuscripts have shorthands.
In this case, use \cs{printbibliography} with  the \opt{env} option equals to
\cnt{details-noshorthand}.
\begin{minted}{latex}
\printbibliography[
  type=manuscript,
  env=details-noshorthand,
  title=Description of manuscripts,
]
\end{minted}
\subsection{Sorting list of manuscripts without shorthand}

\label{sorting} If you doesn't use the shorthands' feature, you can want to print a list of manuscripts, sorted by Town, Library, Collection, Shelfmark.

For this purpose, you can use, the option \opt{sorting=manuscripts} of a \env{refcontext} environment.

\begin{minted}{latex}
\begin{refcontext}[sorting=manuscripts]{}
\printbibliography[
  type=manuscript,
  title=Description of other manuscripts,
]
\end{refcontext}
\end{minted}

You can use the special field \bibfield{sortshelfmark} if the way you shelf marks are sorted is not the way they are printed (like in normal entry type, you can use \bibfield{sorttitle}.

However, using different sorting scheme for different bibliography in the same document implies that biber will insert many time the bibliographic entries in the \verb+.bbl+ file, once by sorting scheme.
If you have a bib bibliography, that could make \LaTeX\ finishing the next run by a\\ \verb`TeX capacity exceeded, sorry [main memory size=<something>]`
\\
because this will full the memory\footnote{The problem should not happen if you use \LuaLaTeX, because, contrary to \XeLaTeX\ and \LaTeX, \LuaLaTeX\ has no limit in memory, except the limit of the computer\ldots\ which should be enough with recent computer.}.

In order to prevent this, the package also provides sorting schemes to get the same sorting scheme for manuscripts and other entries, even if separated in the final bibliography.
The following sorting schemes are adapted for the standard \biblatex\ sorting schemes:
\begin{itemize}
  \item \verb`nty+manuscripts`, adapted from \verb+nty+;
  \item \verb-nyt+manuscripts-, adapted from \verb-nyt-;
  \item \verb-nyvt+manuscripts-, adapted from \verb-nyvt-.
\end{itemize}

To use these scheme, don't use \env{recontext} environment, but simply the global option when loading \biblatex:
\begin{minted}{tex}
\usepackage[sorting=nty+manuscripts,…]{biblatex}
\end{minted}

If you need more sorting scheme, please contact us, we could integrate them easily.

\section{Customization}

\subsection{Create your own keys}\label{key-definition}

The \bibfield{support} and \bibfield{script} fields can contains either literal string, either key that \biblatex will transform to a value.

That use only standard \biblatex  localization string.

To define your owns key, add into your preamble:
\begin{minted}{tex}
  \NewBibliographyString{<key1>}
  \NewBibliographyString{<key2>}
  …
  \NewBibliographyString{<keyn>}
  \DefineBibliographyStrings{%
    <key1> = {<value1},
    <key2> = {<value2>},
    …,
    <keyn> = {<valuen>}
  }

\end{minted}

Where \meta{key1}, \meta{key2} \ldots\ \meta{keyn} must be replaced by the keys, and \meta{value1}, \meta{value2} \ldots\ \meta{valuen} by the value.


\subsection{Commands}

You can redefine, with \cs{renewcommand} some commands defined in \file{manuscripts.bbx}. The commands starting with \cs{mk...} take one argument, the other take no argument. In these command, use the punctuation commands of \biblatex.

\begin{ltxsyntax}
\csitem{collectionshelfmarkpunct} the punctuation between \bibfield{collection} and \bibfield{shelfmark}. By default \cs{addspace}.

\csitem{columnslayerpunct} the punctuation between \bibfield{columns} and \bibfield{layer}. By default \cs{addsemicolon}\cs{addspace}.

\csitem{datingpagespunct} the punctuation between \bibfield{dating} and \bibfield{pages}. By default \cs{addcomma}\cs{addspace}. The \cs{isdot} is automatically called when printing \bibfield{dating} field.

\csitem{librarycollectionpunct} the punctuation between \bibfield{library} and \bibfield{collection}. By default \cs{addcomma}\cs{addspace}.

\csitem{mkcolumns} the way the \bibfield{columns} are printed. By default, in parens.

\csitem{mkcolumnslayer} the way the \bibfield{columns} and \bibfield{layer} fields are printed together. By default, in parens.

\csitem{mklocation} the way the \bibfield{location} is printed. By default, with the command \cs{mkbibnamefamily}.

\csitem{mkmanuscriptdescriptionlabel} the way the label are printed before the special fields. By default, in bold, followed with \cs{manuscriptdescriptionlabelpunct}.

\csitem{mkmanuscriptdescriptionlabelparagraphed} the way the label are printed before the special fields which can contains paragraph (e.g. \bibfield{content}.
B default, in bold, followed with \cs{par}.

\csitem{mkshcite} the way the shorthand is printed when using \cs{shcite}. By default, no special formatting.

\csitem{locationlibrarypunct} the punctuation between \bibfield{location} and \bibfield{library}.  By default \cs{addcolon}\cs{addspace}.

\csitem{manuscriptdescriptionlabelpunct} the punctuation between label and text, for the special fields. By default \cs{addcolon}\cs{addspace}.

\csitem{moreinterpunct} the punctuation between each special fields when printing in the same paragraph. By default \cs{addcolon}\cs{addspace}.

\csitem{pagetotalpagespunct} the punctuation between \bibfield{pagetotal} and \bibfield{pages}. By default \cs{addcolon}\cs{addspace}.
\end{ltxsyntax}

\subsection{Commands to use in the \bibfield{pages} field}

In the pages field, you can use \cs{recto} and \cs{verso} command when you speak of folios. Default value are \cnt{r} and \cnt{v} but you can change them.

\subsection{Localization strings}

Some specific localization strings are defined in the \file{manucripts-xxx.lbx} files. Read the \biblatex handbook to know how to customize it.

\subsection{Macros and field formats}

The \file{manuscripts-shared.bbx} file defines bibmacros and field formats (read the \biblatex handbook to know more about bibmacro and field format). We can't list all of them, but you can look on them to know how to customize more finely the manuscripts description.

\section{Use with biblatex-realauthor}\label{biblatex-multiple-dm}

To use this package with the features of \verb+biblatex-realauthor+, you must use the package \verb+biblatex-multiple-dm+.

\section{Migration to v.2.0.0}

The version 2.0.0 adds some modification which could require modifications in your own customization.

\begin{enumerate}
  \item We have decided to prefix all bibmacros concerning manuscript with \verb+manuscript:+.
    If you have redefined one of the following macros, or if you have created your own macros which call them, you should adapt your code:
    \begin{itemize}
      \item \verb+annotation+;
      \item \verb+catalog+;
      \item \verb|collection+shelfmark|;
      \item \verb+date/dating+;
      \item \verb|more+annotation+catalog|;
    \end{itemize}
  \item The \verb|support+dating| does not exist anymore.
  \item Now, the annotation field is introduced with a label.
 If you don't want this label, add into your preamble/custom style:
 \begin{minted}{tex}
   \DeclareFieldFormat{annotation}{#1}
 \end{minted}
\end{enumerate}
\section{Change history}

\begin{changelog}

\begin{release}{2.1.2}{2019-01-07}
\item Fix bug when changing language in the middle of an handbook.
\end{release}

\begin{release}{2.1.1}{2019-10-02}
\item Fix warning with sorting schemes.
\end{release}

\begin{release}{2.1.0}{2018-09-30}
  \item Add \cs{detailcite} and \cs{detailscites} commands.
  \item Add \opt{env}=\cnt{details-noshorthand} option to \cs{printbibliography}.
\end{release}

\begin{release}{2.0.0}{2018-09-19}
  \item Add \bibfield{contents} and \bibfield{script} fields.
  \item Add new support types.
  \item Improve handbook (thanks to Dominik Wujastyk).
  \item Really add italian translation.
\end{release}

\begin{release}{1.12.3}{2017-11-26}
  \item Add compatibility with biblatex 3.8.
\end{release}
\begin{release}{1.12.2}{2017-01-31}
  \item Fix spurious space after citation of a manuscript.
\end{release}

\begin{release}{1.12.1}{2016-10-28}
  \item Move url after folio and columns data.
\end{release}

\begin{release}{1.12.0}{2016-10-23}
  \item New sorting schemes.
\end{release}

\begin{release}{1.11.0}{2016-09-21}
  \item Fix typographical bug when using both \bibfield{layer} and \bibfield{columns} fields without \bibfield{pages} field.
\end{release}

\begin{release}{1.10.1}{2016-09-07}
  \item Use \cs{mkbibnamefamily} instead of \cs{mkbibnamelast} (biblatex 3.3 and later).
\end{release}

\begin{release}{1.10.0}{2016-06-07}
  \item Add error message to know more quickly break compatibility with new releases of biblatex.
\end{release}
\begin{release}{1.8.0}{2016-03-11}
	\item Fix compatibility with \biblatex~3.3.
\end{release}

\begin{release}{1.7.0}{2016-02-10}
	\item Add italian translation.
\end{release}

\begin{release}{1.6.2}{2015-11-01}
	\item Fix missing line break before \bibfield{scribe} or \bibfield{owner} fields when \bibfield{origin} field is empty.
\end{release}

\begin{release}{1.6.1a}{2015-05-06}
	\item Fix typo in handbook
	\item Insert good version number in the \cmd{ProvidesFile} commands.
\end{release}

\begin{release}{1.6.1}{2014-10-21}
  	\item Add \cs{isdot} after each printing of the \bibfield{dating} field, to allow to use abbreviations with a dot (like \enquote{c.}) without adding a uppercase after. Consequently, \cs{isdot} is deleted from \cs{datingpagespunct}.
\end{release}

\begin{release}{1.6.0}{2014-10-16}
  	\item Patching some bibmacros to prevent lost of manuscript descriptions when using  op. cit abreviation.
\end{release}

\begin{release}{1.5.0}{2014-10-08}
  	\item Formating of collection+shelfmark defined in a FielFormat.
	\item Compatibility with \verb+chicago-notes+ styles.
\end{release}

\begin{release}{1.4.0}{2014-06-23}
	\item Compatibility with \verb+biblatex-multiple-dm+.\see{biblatex-multiple-dm}
\end{release}


\begin{release}{1.3.0}{2014-06-16}
	\item Add sorting description.\see{sorting}
\end{release}

\begin{release}{1.2.0}{2014-04-07}
	\item Add \bibfield{layer}.\see{field:layer}
\end{release}

\begin{release}{1.1.1}{2014-03-20}
	\item Delete \opt{msnoautoshorthand} option and replace it by the \opt{manuscripts-noautoshorthand} style. \see{noautoshorthand}
\end{release}

\begin{release}{1.1.0}{2014-03-15}
\item Add \opt{msnoautoshorthand} option.
\item Add \bibfield{shortcollection} field.\see{field:shortcollection}
\item Add \opt{withshorthand} and \opt{withoutshorthand} bibcheck. \see{bibcheck}
\end{release}

\begin{release}{1.0.0}{2014-01-20}
\item First public release.
\end{release}
\end{changelog}
\end{document}