summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/librarian/librarian-doc.tex
blob: 1beb373e016821a59ba6c1bbf635589a748c6c62 (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
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
% This is the source of the documentation for the librarian package.
% Proper compilation requires: luatex (v.0.51 or later), a recent
% version of luaotfload, not to mention the Adobe Garamond Pro font,
% which however might be replaced by URW's Garamond. The required format 
% is plain TeX in its modified luatex version.
% Three compilations are needed to get examples right.
%
% Author: Paul Isambert.
% E-mail: zappathustra AT free DOT fr
% Comments and suggestions are welcome.
% Date: April 2010.


%%%%%%%%%%%%%%%%%
%%%%% FONTS %%%%%
%%%%%%%%%%%%%%%%%

\input luaotfload.sty
\pdfadjustspacing=2
\directlua{%
% From otfl-font-dum.lua
  local byte = string.byte
  fonts.expansions.setups['threepercent'] = {

    stretch = 3, shrink = 3, step = .5, factor = 1,

    [byte('A')] = 0.5, [byte('B')] = 0.7, [byte('C')] = 0.7, [byte('D')] = 0.5, [byte('E')] = 0.7,
    [byte('F')] = 0.7, [byte('G')] = 0.5, [byte('H')] = 0.7, [byte('K')] = 0.7, [byte('M')] = 0.7,
    [byte('N')] = 0.7, [byte('O')] = 0.5, [byte('P')] = 0.7, [byte('Q')] = 0.5, [byte('R')] = 0.7,
    [byte('S')] = 0.7, [byte('U')] = 0.7, [byte('W')] = 0.7, [byte('Z')] = 0.7,
    [byte('a')] = 0.7, [byte('b')] = 0.7, [byte('c')] = 0.7, [byte('d')] = 0.7, [byte('e')] = 0.7,
    [byte('g')] = 0.7, [byte('h')] = 0.7, [byte('k')] = 0.7, [byte('m')] = 0.7, [byte('n')] = 0.7,
    [byte('o')] = 0.7, [byte('p')] = 0.7, [byte('q')] = 0.7, [byte('s')] = 0.7, [byte('u')] = 0.7,
    [byte('w')] = 0.7, [byte('z')] = 0.7, [byte('2')] = 0.7, [byte('3')] = 0.7, [byte('6')] = 0.7,
    [byte('8')] = 0.7, [byte('9')] = 0.7,
    }
  	}

\def\currentstyle{rm}
\def\currentweight{rg}
\def\currentcase{lc}
\def\makecurrentfont{%
  \csname\currentfont @\currentstyle @\currentweight @\currentcase\endcsname
  }

\def\fontfeatures{+trep;+onum;+tlig;+liga;expansion=threepercent}
\def\mainfont{%
    \def\currentfont{Garamond}%
    \csname\currentfont @\currentstyle @\currentweight @\currentcase\endcsname
  }
\expandafter\font\csname Garamond@rm@rg@lc\endcsname="AGaramondPro-Regular.otf:\fontfeatures" at 10pt
\expandafter\font\csname Garamond@rm@bf@lc\endcsname="AGaramondPro-Bold.otf:\fontfeatures" at 10pt
\expandafter\font\csname Garamond@rm@rg@sc\endcsname="AGaramondPro-Regular.otf:+smcp;\fontfeatures" at 10pt
\expandafter\font\csname Garamond@rm@bf@sc\endcsname="AGaramondPro-Bold.otf:+smcp;\fontfeatures" at 10pt
\expandafter\font\csname Garamond@it@rg@lc\endcsname="AGaramondPro-Italic.otf:\fontfeatures" at 10pt
\expandafter\font\csname Garamond@it@bf@lc\endcsname="AGaramondPro-BoldItalic.otf:\fontfeatures" at 10pt
\expandafter\font\csname Garamond@it@rg@sc\endcsname="AGaramondPro-Italic.otf:+smcp;\fontfeatures" at 10pt
\expandafter\font\csname Garamond@it@bf@sc\endcsname="AGaramondPro-BoldItalic.otf:+smcp;\fontfeatures" at 10pt
\mainfont

\font\titlefont="AGaramondPro-Italic.otf:\fontfeatures" at 20pt

\def\codefont{%
    \def\currentfont{Inconsolata}%
    \csname\currentfont @\currentstyle @\currentweight @\currentcase\endcsname
  }
\expandafter\font\csname Inconsolata@rm@rg@lc\endcsname="Inconsolata.Otf:\fontfeatures;-trep" at 8.5pt
\expandafter\font\csname Inconsolata@rm@bf@lc\endcsname="Inconsolata.Otf:\fontfeatures;-trep" at 8.5pt
%\expandafter\font\csname Inconsolata@rm@rg@sc\endcsname="Inconsolata.Otf:+smcp;\fontfeatures;-trep" at 8.5pt
%\expandafter\font\csname Inconsolata@rm@bf@sc\endcsname="Inconsolata.Otf:+smcp;\fontfeatures;-trep" at 8.5pt
\expandafter\font\csname Inconsolata@it@rg@lc\endcsname="Inconsolata.Otf:slant=.2;\fontfeatures;-trep" at 8.5pt
\expandafter\font\csname Inconsolata@it@bf@lc\endcsname="Inconsolata.Otf:slant=.2;\fontfeatures;-trep" at 8.5pt
%\expandafter\font\csname Inconsolata@it@rg@sc\endcsname="Inconsolata.Otf:slant=.2;+smcp;\fontfeatures;-trep" at 8.5pt
%\expandafter\font\csname Inconsolata@it@bf@sc\endcsname="Inconsolata.Otf:slant=.2;+smcp;\fontfeatures;-trep" at 8.5pt

\def\it{%
  \def\currentstyle{it}%
  \makecurrentfont
  }
\def\bf{%
  \def\currentweight{bf}%
  \makecurrentfont
  }  
\def\sc{%
  \def\currentcase{sc}%
  \makecurrentfont
  }
\def\rm{%
  \def\currentstyle{rm}%
  \makecurrentfont
  }
\def\textit#1{{\it#1}}



%%%%%%%%%%%%%%%%%%%%%%%
%%%%% PAGE LAYOUT %%%%%
%%%%%%%%%%%%%%%%%%%%%%%

\baselineskip=12pt
\topskip=\baselineskip
\vsize=41\baselineskip
\hsize=21pc
\parfillskip=.5\hsize plus 1fil minus .4\hsize
\pdfpagewidth=3\hsize
\pdfpageheight=\pdfpagewidth
\pdfhorigin=\dimexpr((\pdfpagewidth-2\hsize-1em)/2)
\pdfvorigin=\pdfhorigin
\parskip0pt \parindent0pt
\frenchspacing

\newbox\leftside
\newif\ifleftside \leftsidetrue
\output{%
  \ifleftside
    \global\setbox\leftside=\box255
    \global\leftsidefalse
  \else
    \global\leftsidetrue
    \shipout\hbox{%
        \box\leftside\kern1em\box255 
      }%
    \advancepageno
  \fi
  }



%%%%%%%%%%%%%%%%%%%%
%%%%% SECTIONS %%%%%
%%%%%%%%%%%%%%%%%%%%

\def\title#1{%
  \hbox to \hsize{%
    \vbox to 2\baselineskip{%
      \vfill
      \hbox{\titlefont\inred{#1}}%
      \vfill
      }%
    \hfil
    \vbox{%
      \setbox0=\hbox{\texttt{zappathustra@free.fr}}%
      \hbox to\wd0{\hfil\textit{Paul Isambert}}%
      \box0}%
    }%
  }
\newcount\sectioncount
\def\onelineskip{\vskip\baselineskip}
\def\makebookmarks{%
  \def\lib{librarian}%
  \def\TeX{TeX}}%
\def\section#1{%
  \onelineskip
  \advance\sectioncount1
  \subsectioncount=0
  \expandafter\gdef\csname\the\sectioncount sub\endcsname{0}%
  \xdef\makebookmarks{%
    \unexpanded\expandafter{\makebookmarks
    \pdfoutline goto name}{section\the\sectioncount}%
                count -\unexpanded\expandafter{\csname\the\sectioncount sub\endcsname{#1}}%
    }%
  \pdfdest name{section\the\sectioncount} xyz\penalty10000
  \noindent
    {%
    \parfillskip0pt plus 1fil
    \hfil\inred{\sc#1}\par}\penalty10000
  \everypar\expandafter{%
    \expandafter\parindent\the\parindent
    \everypar={}}%
  \parindent=0pt
  }
\newcount\subsectioncount
\newif\iflefttitle
\def\subsection#1{%
  \advance\subsectioncount1
  \expandafter\xdef\csname\the\sectioncount sub\endcsname{%
    \the\numexpr(1+\csname\the\sectioncount sub\endcsname)}%
  \xdef\makebookmarks{%
    \unexpanded\expandafter{\makebookmarks
    \pdfoutline goto name}{section\the\sectioncount.\the\subsectioncount}%
                \unexpanded{{#1}}%
    }%
  \onelineskip
  \pdfdest name{section\the\sectioncount.\the\subsectioncount} xyz\penalty10000
  \noindent
  {%
  \penalty0
  \ifdim\pagetotal<\dimexpr(\pagegoal-\baselineskip)\relax
    \ifleftside \lefttitletrue
    \else \lefttitlefalse \fi
  \else
    \ifleftside \lefttitlefalse
    \else \lefttitletrue \fi 
  \fi
  \iflefttitle
    \parfillskip0pt plus 1fil
    \inred{\hbox to0pt{\hss\char"E09D\kern1em}\textit{#1}}
  \else
    \parfillskip0pt
    \inred{\textit{#1}\hfill\hbox to0pt{\kern1em \char"E09D\hss}}
  \fi
  \par\penalty10000
  }%
  }



%%%%%%%%%%%%%%%%%%%%
%%%%% VERBATIM %%%%%
%%%%%%%%%%%%%%%%%%%%

\def\do#1{\catcode`#1=12}
\def\verbatim{%
  \bgroup
  \parfillskip0pt plus 1fill
  \onelineskip
  \obeylines \dospecials
  \def\par{\leavevmode\endgraf}%
  \parindent=0pt
  \codefont \getcode
  }%
\bgroup
\catcode`\|=0
\catcode`\\=12
|long|gdef|getcode#1\endverbatim{#1|egroup|onelineskip}%
|egroup
\newbox\cmdbox
\def\command#1{%
  \bgroup
    \codefont
    \string#1%
  \egroup
  }
\def\cmd#1{%
  \inred{\command{#1}}%
  }
\def\tcmd#1{%
  \command{#1}%
  }
\def\cmddef{%
  \onelineskip\subcmddef
  }
\def\subcmddef#1{%
  \noindent{\bf\cmd{#1}\parfillskip0pt plus 1fil \par}%
  \penalty10000\noindent\ignorespaces
  }
\def\arg#1{%
  \bgroup
  \codefont
    \textit{\lower.08em\hbox{\char"003C}#1\lower.08em\hbox{\char"003E}}%
  \egroup
  }
\def\marg#1{%
  \char"007B\arg{#1}\char"007D
  }
\def\targ#1{%
  \texttt{\char"007B #1\char"007D}%
  }
\def\field#1{\texttt{\inred{#1}}}



%%%%%%%%%%%%%%%%%%%%%%%
%%%%% SOME MACROS %%%%%
%%%%%%%%%%%%%%%%%%%%%%%

\def\texttt#1{{\codefont#1}}
\def\inred{\incolor{.7 0 .1}}
\long\def\incolor#1#2{%
  \pdfliteral{#1 rg}%
  #2%
  \pdfliteral{0 0 0 rg}%
  }
\def\lib{\textit{librarian}}
\def\LaTeX{La\TeX} \def\ConTeXt{Con\TeX t}
\long\def\citation#1\endcitation{%
  \onelineskip
  \bgroup
    \advance\leftskip2em \rightskip\leftskip
    \incolor{.1 0 .5}{#1}\par
  \egroup
  \onelineskip
}


\pdfinfo{%
  /Title (librarian-doc.pdf)
  /Author (Paul Isambert)
  }
\pdfcatalog{%
  /PageMode /UseOutlines
  }

\input librarian
\title{Librarian}

\section{Introduction}

\textit{Librarian} is a set of macros that handles bibliographic
references without Bib\TeX. It reads bibliographic files, extracts
information about entries, and sorts lists of entries according to
that informa\-tion and the user's specifications. \TeX\ code can then
be written to typeset citations and bibliographies or more generally
to write the equivalent of \texttt{bst} files, and absolutely
no knowledge of the Bib\TeX\ language is needed, nor is Bib\TeX\ itself.

The package is low-level in the sense that it doesn't do much more
than what's said above and offers little syntactic sugar to typeset
bibliographies. It is meant to make as few meaningful decisions as
possible, where `meaningful decisions' means operations that influence
the output or what the user can do. The way \lib\ extracts information
is immaterial (barring efficiency, of course) to the typesetting of
a bibliography, which depends strictly on the user's knowledge in
\TeX\ programming. On the contrary, predefined styles, for instance,
would be easier indeed but also more limited.

Besides, \lib\ is format-independent, relying on plain \TeX's usual
allocation macros only (which are similar in other formats, as far
as I can tell). Thus, a well-written bibliographic style should 
work equally well in all formats; by `well written' I mean that it does
not use any format-specific commands, and at worst defines aliases
to those commands at the beginning of the file.

The first part of this document is a reference manual where \lib\
is explained thoroughly. The second part spells out a pair of
examples of bibliographic styles; the second example gives details
on the important parts of the file \texttt{authoryear.tex}, which
is distributed with the package and can be used as is.





\section{Reference manual}

\subsection{How to load \lib}

In plain, the package is loaded in the good old way:

\verbatim
\input librarian
\endverbatim

\noindent In La\TeX\ you must use the associated style file:

\verbatim
\usepackage{librarian}
\endverbatim

\noindent And in Con\TeX t you must load \lib\ with the
third-party file:

\verbatim
\usemodule[librarian]
\endverbatim

\subsection{Commands}

\cmddef{\Cite\marg{entry key}\marg{list}\marg{code1}\marg{code2}}
This adds  \arg{entry key} to \arg{list} (if the latter doesn't exist,
it is created on the fly), unless it has already been added previously. If \arg{entry key}
has already been read in the bibliography (most likely in a previous
compilation), \cmd\EntryKey\ is set to \arg{entry key} and \arg{code1} is
executed. Otherwise, \lib\ will read the bibliographic files to retrieve information
about \arg{entrykey}, and for the moment \arg{code2} is executed (without
redefining \tcmd\EntryKey). With complex bibliographic styles, this command is
better embedded in macros.

\cmddef{\BibFile\marg{list of files}}
The \arg{list of files} is a comma-sepa\-rated list of bibliographic
files in which \lib\ will dig information about the requested entries.
The \texttt{.bib} extension is implicit, but you can give another
one, as in \tcmd{\BibFiles\targ{mybib,myotherbib.tex}}. The information
is passed to the next compilation thanks to an external file called
\texttt{\arg{jobname}.lbr} (the culprit to delete if things seem wrong to you).
If there remains no requested entry then the
files aren't read. \tcmd\BibFile\ can occur several times in a document,
but on each call, only those entries that have been \tcmd\Cite'd before
will be searched for in the bibliographic files, because calls
to \tcmd\Cite\ aren't passed from one compilation to the next. Most
complex bibliographic styles generally require three compilations to
get everything right.

%%%% Pour la page suivante:
\advance\vsize-\baselineskip
%%%% Clumsy but I had no time to implement
%%%% my own widow-killer here...

\cmddef{\SortingOrder\marg{list of fields}\marg{name parts}}
This sets the order in which lists will be sorted. The fields in
\arg{list of fields} are the ones you find in Bib\TeX\ entries,
plus the ones \lib\ adds to entries (like \texttt{name}), and they should
be separated by commas. Any field can be prefixed with `\texttt{-}',
which indicates that when it comes to this field entries will be
sorted in reverse order. The sorting works as follows: when comparing
two entries, \lib\ compares their values for the first field; if they
are the same, it tries the second field, and so on. If \arg{list of fields}
is exhausted, the entries are sorted according to the order of citation
in the document relative to the list that's being scanned (i.e. the value
of \tcmd\EntryNumber). The \arg{name parts}
are concatenated letters, with `\texttt{f}' denoting first name, `\texttt{l}'
denoting last name, `\texttt{v}' referring to the von part and `\texttt{j}'
referring to the junior part; it sets how names are compared, and although
there seems to be only two meaningful orders (\texttt{vlfj} and \texttt{lfvj}),
differing in how the von part is taken into account, you can do whatever you
want. Thus, \tcmd{\SortingOrder\targ{name,year,title}\targ{vlfj}} sorts entries in
the `author year' style, with titles differentiating entries by the same
author(s) written the same year, and with the von part taking precedence in
the last name. Instead, \tcmd{\SortingOrder\targ{name,-year}\targ{lfvj}} 
will produce a bibliography sorted by names, with most recent references first,
and similar references sorted according to their order in the document, while
the von part doesn't matter in last names (and thus Ludwig van Beethoven is
sorted before Franz Schubert). In any case, \arg{name parts} have nothing
to do with how names are typeset in the bibliography. (In these examples,
\texttt{name} is used instead of \texttt{author} or \texttt{editor} on purpose.
See below about the \texttt{name} field.) By default, \lib\ doesn't sort entries.

\cmddef{\SortList\marg{list}}
This sorts \arg{list} according to the latest value of \tcmd\SortingOrder.
Thus different lists can be sorted with different orders. If \tcmd\SortList\
is called before \tcmd\BibFile, then new entries will be sorted on the
next compilation only. From one compilation to the next, \lib\ retains
the previous sorted entries and sorts only new entries, and entries that
are equal according to \tcmd\SortingOrder\ (because their relative order
may have changed). This saves time (especially in Lua\TeX\ where the many
calls to \tcmd\directlua\ are quite time-consuming). However, if the value
of \tcmd\SortingOrder\ when \tcmd\SortList\ is called has changed from the
previous compilation, all entries are sorted again.

\cmddef{\ReadList\marg{list}}
This loops over entries in \arg{list}, and for each it stores its key
in \cmd\EntryKey\ and calls \cmd\MakeReference, which by default does nothing,
and should be redefined to typeset the entry. For each entry you can use
the \cmd\ifequalentry\ conditional, which is true if the current entry
is part of a set of entries that are equal with regard to \tcmd\SortingOrder\
and are thus distinguished by citation order only, and false otherwise.
If the list is unsorted (i.e. \tcmd\SortingOrder\ is empty), then \tcmd\ifequalentry\
is always false, even though all entries are equal.



\cmddef{\SortDef\marg{command}\marg{definition}}
This defines \arg{command} as \arg{defi\-nition} at sorting time.
Indeed, macros shouldn't hinder sorting. However, \tcmd\TeX\ won't
be read as `TeX' and \textit{\TeX book} won't be sorted after
\textit{Tao Te Ching} but rather after \textit{Typographic Investigations},
because macros separate letters. So
\tcmd{\SortDef\tcmd\TeX\targ{tex}} is the proper way to get good sorting
(everything is sorted in lowercase, so no need to use `\texttt{TeX}').
\tcmd\SortDef\ can't define with parameter text, but a macro can
be defined to another one taking arguments, although it is generally
unnecessary: all braces are removed at sorting time. It is probably
very important to redefine accents (\lib\ doesn't), e.g. \tcmd{\SortDef\string\'\targ{}}
is vital if you want to see B\char"00E9 zier between Bernoulli and Boole.

\cmddef{\WriteInfo\marg{arg}}
\subcmddef{\WriteImmediateInfo\marg{arg}}
Since \lib\ reads and rewrites an external file on each compilation,
you can use it too. This writes \arg{arg} to that file, so that it is
made available for the next compilation; \arg{arg} is expanded as in
any \tcmd\write\ statement. \tcmd\WriteInfo\ writes at output time,
whereas \tcmd\WriteImmediateInfo\ writes immediately.

\cmddef\Preamble
This holds everything that has been encountered in \texttt{@preamble}
entries when reading bibliographies. It isn't passed from one compilation
to the next.

%%%% Pour la page suivante:
\advance\vsize\baselineskip
\cmddef{\CreateField\marg{field}}
If a field is unknown to \lib\ (there is no restriction in bibliographic entries),
\lib\ complains when asked to retrieve it with the commands below. This command
just enables it to work with unknown fields. By default, \lib\ knows the common
Bib\TeX\ fields and its own, of course.

\cmddef{\AbbreviateFirstname}
This turns first names into initials, e.g. \textit{John} into \textit{J.} and
\textit{Jean-Luc} into \textit{J.-L.} In order to get \textit{Ch.} from
\textit{Charles}, the name in the bibliographic file should be
`\texttt{\char`\{Ch\char`\}arles}', which is already the case for Bib\TeX.
Note that \lib\ sorts full names  and thus \textit{J(ohn) Doe} and \textit{J(ack) Doe}
are different in this respect, even though they'll be indistinguishable in your
bibliography.






\onelineskip
The following macros all come in pairs made of \tcmd\Command\ and \tcmd\CommandFor,
where \tcmd\Command\ is \tcmd\CommandFor\ with \arg{entry key} set to \tcmd\EntryKey.
All along, I refer to bibliographic entries, naturally, and \textit{field\/} and \textit{value\/}
are to be understood in that context (see the next two sections for details).

\cmddef{\RetrieveField\marg{field}}
\subcmddef{\RetrieveFieldFor\marg{field}\marg{entry key}}
This produces the value of \arg{field} for \arg{entry key}. The command
uses \tcmd\lowercase, so you should use it with care, and basically avoid it
unless for typesetting fields. The following command should be preferred
if anything must be manipulated.

\cmddef{\RetrieveFieldIn\marg{field}\marg{command}}
\subcmddef{\RetrieveFieldInFor\marg{field}\marg{entry key}\marg{command}}
This one defines \arg{command} as the value of \arg{field} for \arg{entry key}.
If \arg{field} doesn't exist in \arg{entry key}, or else if \arg{entry key}
doesn't exist, then \arg{command} is defined as an empty command and
is equivalent to \tcmd\empty\ if the latter is defined as
\tcmd\def\tcmd\empty\texttt{\char`\{\char`\}}. Quite convenient for testing.

\cmddef{\EntryNumber\marg{list}}
\subcmddef{\EntryNumberFor\marg{entry key}\marg{list}}
This returns \textit{n} if \arg{entry key} is the \textit{n}th entry
in \arg{list}, i.e. if it is the \textit{n}th entry to be cited for the
first time in \arg{list}.

\cmddef{\EntryNumberIn\marg{list}\marg{command}}
\subcmddef{\EntryNumberInFor\marg{entry key}\marg{list}\marg{command}}
This defines \arg{command} as \textit{n}, where \textit{n} is defined
as above. (Beware that \arg{command} is a macro whose expansion produces
a number, not an integer denotation.) This is safer than the previous command
for the same reason as with \tcmd\RetrieveFieldFor, and is emptily defined
under the same circumstances.

\cmddef{\ReadName\marg{code}}
\subcmddef{\ReadNameFor\marg{entry key}\marg{code}}
For each person in the \texttt{name} field  for \arg{entry key}, this stores the first name
in \cmd\Firstname\ (abbreviated if \tcmd\AbbreviateFirstname\ was called),
the last name in \cmd\Lastname, the von part in
\cmd\Von\ and the junior part in \cmd\Junior. There is also a 
number \cmd\NameCount, which holds the place of the person in the
\texttt{name} field (i.e. the first author has \tcmd\NameCount\texttt{=1}).
Finally, \arg{code} is called with those values. There are aliases
\cmd\ReadNames\ and \cmd\ReadNamesFor. \cmd\ReadAuthor, \cmd\ReadAuthorFor,
\cmd\ReadEditor\ and \cmd\ReadEditorFor, and the versions with plural as well,
are defined equivalently for the \texttt{author} and
\texttt{editor} fields respectively. You can still use \tcmd{\RetrieveField
\targ{author}}, for instance, but those fields aren't designed
for typesetting in their basic form, hence this command.

\cmddef{\TypesetField\marg{field}\marg{command}\marg{code}}
\subcmddef{\TypesetFieldFor\marg{field}\marg{entry key}\marg{command}\marg{code}}
If \arg{field} isn't empty in \arg{entry key}, \arg{command} is
executed with the value of \arg{field} as its argument. So
\arg{command} should be a macro that takes one (and only one) argument.
If \arg{field} is empty, \arg{code} is executed instead.








\subsection{Fields}
Beside the fields that are found in bibliographic entries, \lib\ adds
some of its own, which can be convenient for dealing with references.
Here they are.

The \field{entrytype} field contains the type of the entry as recorded
in \texttt{bib} files at the beginning of each entry after the
\texttt{@} sign. Thus

\verbatim
@Book{Coover2002,
  ...
}
\endverbatim

\noindent has `\texttt{book}' as the value for \texttt{entrytype}. Note
that lowercase is always used, whatever the actual case in the \texttt{bib} file.
The number of authors in the \texttt{author} field is the value of the \field{authornumber}
field, each author being distinguished from the next by the customary `\texttt{and}'.
An equivalent field, \field{editornumber}, does the same for \texttt{editor}.
Most importantly, the \field{name} field holds the same value as \texttt{author}
if there is such a field in the entry, or the value of \texttt{editor}
it it exists and there is no \texttt{author}. Thus edited books can be
cited along with normal books. That's why \texttt{name} appeared in
\tcmd\SortingOrder\ above: if it had been \texttt{author}, then collective
works wouldn't have been sorted correctly. Along with \texttt{name},
\field{namenumber} holds the value either of \texttt{authornumber} or
of \texttt{editornumber}, according to the same rule. Finally, \field{nametype}
takes one out of two values: \texttt{author} or \texttt{editor}. It
takes the former if the \texttt{name} field is set to the value of the \texttt{author}
field, and the latter if it is set to the value of the \texttt{editor} field.
Thus, when referencing collective works in a bibliography, you can add
`(ed.)' for instance after the value of \texttt{name} if \texttt{nametype}
is \texttt{editor}.




\subsection{A crash course in bibliographic entries (and how \lib\ reads them)}
This section is not necessary to the understanding of \lib\ but it can be
useful if in trouble. Suppose you have the following entry:

\verbatim
@Book{Coover2002,
  author = {Coover, Robert},
  title = {The Adventures of Lucky Pierre},
  subtitle = {Director's Cut},
  publisher = "Grove Press",
  Address = {New York},
  year = 2002,
}
\endverbatim

\noindent Then \lib\ stores all the fields for the `\texttt{coover2002}' entry key.
This key is in lowercase, and thus you can't distinguish two entries by case only
(this is how Bib\TeX\ works). This doesn't mean that you can't use
\tcmd{\Cite\targ{Coover2002}\targ{list}}: \lib\ does the necessary conversion.
The \texttt{entrytype} field is set to `\texttt{book}', in lowercase once again, and
this time you must be careful: `\texttt{book}' is a value, and since you'll probably
test it to know how the reference should be typeset in the bibliography, you
shouldn't compare it to, say, `\texttt{Book}', of course. And to finish with
lowercase, `\texttt{New York}' is the value of the \texttt{address} field,
not \texttt{Address}, but once again \lib\ does the conversion so you can call
\tcmd{\RetrieveField\targ{Address}\targ{cooVEr2002}}. Finally, the \texttt{subtitle}
field is no customary field, but you can use it. Up to there, \lib\ works
exactly like Bib\TeX.

But there are differences too. For one thing, \lib\ has no restriction on the type
of the entry, so you could have:

\verbatim
@novel{Coover2002,
  author = {Coover, Robert},
  title = {The Adventures of Lucky Pierre},
  subtitle = {Director's Cut},
  publisher = "Grove Press",
  Address = {New York},
  year = 2002,
}
\endverbatim

\noindent That's perfectly fine with \lib, although not with Bib\TeX.
There are no restrictions on fields either, and unlike Bib\TeX\ fields
aren't labelled as required or optional or ignored; in a bibliographic
style you can issue an error message if a field is missing, but \lib\
won't do it for you. And there are
annoying differences too. They occur in the way \lib\ reads the values of
fields. Here's how it works: if the first character (disregarding space) after
the `\texttt{=}' sign is a~\texttt{\string{}, then everything up to the next
balanced~\texttt{\string}} is taken as the value, and everything up to the comma
is discarded. (The last value of the entry may have no comma, but \lib\ adds one
before reading the entry.) If the first character is a~\texttt{\string"}, then
everything up to the next~\texttt{\string"}, with balanced braces, is taken
as the value, and everything up to the comma is discarded once again. Finally,
if the first character is none of the above, then \lib\ takes everything up
to the next comma as the value (while balancing braces, of course). The latter
case differs from Bib\TeX. Normally, only numerical values (like the value of
\texttt{year} in our example) can be given as such, unless strings are used.
But \lib\ is totally unable to understand strings. The following

\verbatim
@string{ny = "New York"}
@Book{Coover2002,
  author = {Coover, Robert},
  title = {The Adventures of Lucky Pierre},
  subtitle = {Director's Cut},
  publisher = "Grove Press",
  Address = ny,
  year = 2002,
}
\endverbatim

\noindent would yield `\texttt{New York}' as the value of \texttt{address} in
Bib\TeX, whereas with \lib\ it gives `\texttt{ny}' (and the \texttt{@string}
entry is simply ignored). In a situation as simple as the present one, you can
make do with macros in you document, i.e. a macro which when fed with `\texttt{ny}'
returns `\texttt{New York}' (problems arise if `\texttt{ny}' is the \textit{real}
value of a field, though), but it becomes more serious when you concatenate strings
with the \texttt{\string#} operator. No way to hide the truth: \lib\ will get
everything wrong. So if you're heavy on strings, better stick to Bib\TeX.






\section{Examples}
Although \lib\ doesn't use many commands, it might be hard to understand them
from scratch. This section details a pair of example styles so you can get
familiar with how things work. The first example is stripped to the minimum
just to learn the basic use of \lib's macros.
The second example is an \textit{Author~(Year)} style
with some refinements, dealing in particular with entries that have the same
author and the same year and should thus be distinguished by a suffix, and it
also shows how to handle cross-references. This style is thoroughly defined
in the file \texttt{authoryear.tex}, distributed with \lib.

Remember, though, that what you can do in \lib\ is what you can do in \TeX.
There's nothing arcane in \lib, and what you can achieve depends really
on your skill in \TeX. So don't feel limited; for instance, suppose you
want to make a list of your publications like:

\citation
{\it2010}\par
`My fascinating paper', {\it Journal of Science}, volume 55 (22), 210--224.\par
{\it The book I finally wrote}, Good Publishing House: City\-ville.\par
{\it2009}\par
`A talk on something', presented at...
\endcitation

\noindent That is, you want the year to be set above the entries, not
repeated each time: then, for each entry, retrieve its \texttt{year}
in a macro, and on the next one, compare with the current year. If it
has changed, print the new value. (Of course entries should be sorted
by date, otherwise it doesn't make sense.)

Another example: \lib\ doesn't abbreviate journal titles. But if you think
in \TeX, it is easily solved: just create a function from a journal title
to its abbreviation (if any), and call it on the value of the \texttt{journal}
field... and so on and so forth...



\subsection{A simple unsorted list with numerical references, which gets sorted later}
Our first example simply doesn't sort entries, and they are cited with
the number they get when they appear. To make things a little funnier,
though, we'll have a case of multiple bibliographies, e.g. one bibliography
per chapter. In each chapter we set \tcmd\currentchapter, and \tcmd\cite\
is as follows:

\verbatim
\def\cite#1{%
  \Cite{#1}{\currentchapter}%
       {[\EntryNumber{\currentchapter}]}{[??]}%
  }
...  
\def\currentchapter{chapter1}
\endverbatim

\noindent And at the end of the chapter we'll have:

\verbatim
\ReadList{\currentchapter}
\endverbatim

\noindent whereas the \tcmd\BibFile\ command will appear
at the end of the book. What \tcmd\cite\ does is: store
the entry in the list associated with the chapter, print
`[??]' if there's no information associated with that entry (probably
because it hasn't been read in the bibliographic file yet) and
`[n]' instead, where \textit{n} is its number in that list, e.g.
`[3]' if that's the third entry in that chapter.

When \tcmd\ReadList\ is called, we need to have \tcmd\MakeReference\
ready, so here it is:

\verbatim
\def\empty{}
\def\MakeReference{%
  \par \noindent
  \llap{[\EntryNumber{\currentchapter}]~}%
  \RetrieveFieldIn{namenumber}\tempcount
  \ifx\tempcount\empty
    \def\tempcount{0}%
  \fi
  \ReadName\makerefname.
  \RetrieveField{title}.
  \RetrieveField{year}.\par
  }
\endverbatim

This produces `[n]' in the left margin (with plain \TeX's \tcmd\llap\
macro), and prints the name, the title, the year, separated by dots
and a space. To put it simply, that's an utterly boring citation style,
which doesn't take the entry type into account. The thing about \tcmd\tempcount\
is: we'll need it in \tcmd\ReadName\ with \tcmd\makerefname\ to check
whether we're at the last author. So we need it as a number; however,
on the first compilation, since \tcmd\BibFile\ appears after \tcmd\ReadList,
entries have no \texttt{namenumber} field, and thus \tcmd\tempcount\ is
empty... which is a very bad idea in an \tcmd\ifnum\ test. In that case
we set it to 0. Now here how names are typeset: 

\verbatim
\def\space{ }
\def\makerefname{%
  \ifnum\NameCount>1
    \ifnum\NameCount=\tempcount\relax \space and \else , \fi
  \fi
  \Firstname
  \unless\ifx\Von\empty \Von\space \fi
  \space\Lastname
  \unless\ifx\Junior\empty , \Junior \fi
  }
\endverbatim

\noindent We check for the existence of the von and junior parts and
put them conditionally. Names are separated by a comma except the last
one which takes `and' instead. Note the crucial \tcmd\relax\ after
\tcmd\tempcount: the latter is a macro expanding to a number, and it
would gobble the next \tcmd\space\ if \tcmd\relax\ wasn't there.
I could have swapped \tcmd\NameCount\ and \tcmd\tempcount, since the
former is a real integer denotation, but we would have missed this
fascinating conversation.

Now we're done with that style. Suppose however we want sorted entries.
For instance:

\verbatim
\SortingOrder{name,year,title}{lfvj}
\endverbatim

Now, citing entries with the citation number isn't very convenient.
Instead, we want a number associated with the entry in the sorted
list. We need a new count, and on each chapter it should be reset to
0. For instance:

\verbatim
\newcount\entrycount
...
\def\currentchapter{chapter24}
\entrycount=0
\endverbatim

\noindent Next, we redefine \tcmd\cite\ as follows:

\verbatim
\def\cite#1{%
  \Cite{#1}{\currentchapter}%
  {[\csname\EntryKey @\currentchapter\endcsname]}%
  {[??]}%
  }
\endverbatim

\noindent Now \tcmd\cite\ calls a command associated with the key
(note that \tcmd\EntryKey\ is useless, we could have used \texttt{\#1}
directly) and the chapter, which holds the number we want. The latter
was set in \tcmd\MakeCitation, redefined as:

\verbatim
\def\MakeReference{%
  \par \noindent
  \advance\entrycount1
  \WriteImmediateInfo{%
    \noexpand\expandafter\def
      \noexpand\csname\EntryKey @\currentchapter
      \noexpand\endcsname{\the\entrycount}%
    }%
  \llap{[\the\entrycount]~}%
% ... same as before
  }
\endverbatim

\noindent This means: on each entry, advance \tcmd\entrycount\ and
store its value as the expansion of the command seen above, thanks
to \tcmd\WriteImmediateInfo. The rather clumsy code in the latter
just means that the following will be written to the external file:

\verbatim
\expandafter\def\csname coover2002@chapter24\endcsname{13}
\endverbatim

And of course, it is the value of \tcmd\entrycount\ that we put into the left margin.
Note that this style takes three compilations to get everything right:
in the first one, a new entry can't be sorted, because \tcmd\SortList\
appears before \tcmd\BibFile. In the second compilation, the entry is
sorted and its number is written to the external file. In the last one,
that number is read and used when the entry is cited. Here's the style
it produces:


%\input unsorted
%\Cite{Wallace2004}{\currentchapter}{}{} \Cite{Wallace1996}{\currentchapter}{}{}
%\citation
%Wallace's last book \cite{Wallace2004} was published eight years after his cult
%novel \cite{Wallace1996}.\par
%...\par
%\SortList{\currentchapter}
%\ReadList{\currentchapter}
%\endcitation

\Cite{Wallace2004}{empty}{}{} \Cite{Wallace1996}{empty}{}{}
\citation
Wallace's last book [2] was published eight years after his cult
novel [1].\par
...\par
\quitvmode\llap{[1]~}David Foster Wallace. \RetrieveFieldFor{title}{Wallace1996}. \RetrieveFieldFor{year}{Wallace1996}.\par
\quitvmode\llap{[2]~}David Foster Wallace. \RetrieveFieldFor{title}{Wallace2004}. \RetrieveFieldFor{year}{Wallace2004}.\par
\endcitation





\subsection{An Author (Year) style, with similar entries and cross-references}
The basic idea here is to have a command \tcmd{\cite\targ{entry key}}
that produces an \textit{Author~(Year)} citation in the main document
(rather \textit{Name~(Year)}, but whatever). References are thus sorted
according to names and then year, and if two entries are equal with
regard to these fields, they should be sorted according to their relative
order of appearance in the document and distinguished with a suffixes,
e.g. `Wallace~(2003a)' and `Wallace~(2003b)'. To do so we'll use \tcmd\ifequalentry\
and \tcmd\WriteImmediateInfo.

However, such a simple \tcmd\cite\ is definitely not very fun. So let's
make it harder: it will take any number of entry keys and separate them
with commas (e.g. `Wallace~(1996), Coover~(2002)') unless the \texttt{name}
field is identical, in which case it won't be repeated and the year
will be put between the same parentheses as the previous entry
(e.g. `Wallace~(1996, 2003)'). So \tcmd\cite\ actually calls a
recursive macro (\tcmd\readcite) on its argument. Here's how it goes.
(Since \lib\ requires e\TeX, we can use it too; if you don't know anything
about it, the only important thing is that you can prefix a conditional
with \tcmd\unless\ to reverse its evaluation; i.e.
\tcmd{\unless\tcmd\ifwhatever\ A\tcmd\else\ B\tcmd\fi} is the same as
\tcmd{\ifwhatever\ B\tcmd\else\ A\tcmd\fi}. It's useful to write
\tcmd{\unless\tcmd\ifwhatever} instead of \tcmd{\ifwhatever\tcmd\else}
when you're interested in the false condition only.)

\verbatim
\def\terminator{\terminator} \def\empty{}
\def\cite#1{%
  \def\prevauthor{}%
  \readcite#1,\terminator,%
  }
\def\readcite#1,{%
  \def\temp{#1}%
  \ifx\temp\terminator
    )%
    \let\tail\relax
  \else
    \let\tail\readcite
    \unless\ifx\temp\empty
      \Cite{#1}{main}\makecitation{}%
    \fi
  \fi\tail
  }
\endverbatim

\noindent Since we don't know what the next entry will be, if any,
the final parenthesis is typeset when \tcmd\readcite\ meets the
terminator. (We take care of empty entries in case one writes
`\tcmd{\cite\targ{entry1,entry2,}}' by mistake, which becomes
`\texttt{entry1,entry2,,\string\terminator,}' for \tcmd\readcite.)
Note that in \texttt{authoryear.tex}, `(' and `)' are actually
replaced by macros (\tcmd\leftcitemark\ and \tcmd\rightcitemark)
that are defined as parentheses; it simply makes the switch to
another style easier.

All entries are added to the \texttt{main} list, and at the end
of the document we'll have to write:

\verbatim
% Perhaps some \SortDef's?
\BibFile{myfiles}
\SortingOrder{name,year}{lfvj}
\SortList{main}
\ReadList{main}
\endverbatim

But back to citation. \tcmd\readcite\ calls \tcmd\makecitation\
in case there are fields for the entry. Here it is. If the current
author is the same as in the previous entry (recorded in
\tcmd\prevauthor), then we just add a command and a space
to the previous date:

\verbatim
\def\makecitation{%
  \RetrieveFieldIn{name}\temp
  \ifx\temp\prevauthor ,
\endverbatim

\noindent On the other hand, if authors differ (unless the previous
one is empty, which means we're on the first citation), we close
the parenthesis (always added by the next entry to the previous
one, remember?), adds a comma and a space to separate entries,
and typeset the name with \tcmd\ReadName\ (which will make
use of \tcmd\tempcount). We also typeset an opening parenthesis
preceded by a hard space to welcome the upcoming year.

\verbatim
  \else
    \unless\ifx\prevauthor\empty ),\fi
    \RetrieveFieldIn{namenumber}\tempcount
    \ReadName\makecitename~(%
  \fi
\endverbatim

\noindent And in any case we set \tcmd\prevauthor\ to the
current value of \texttt{name}, typeset the year and
add the suffix associated with that entry if it exists
(it is created when we use \tcmd\ReadList), somehow like
the entry number in the previous example.

\verbatim
  \RetrieveFieldIn{name}\prevauthor
  \RetrieveField{year}\csname\EntryKey @suffix\endcsname
  }
\endverbatim

Now here's how names are typeset: they are separated by
commas, except the last one which is separated by \textit{and}
(e.g. `Jackson, Jameson and Johnson~(1980)'). Besides, if there
are more than 3 authors, only the first one is typeset,
followed by \textit{et alii}. The number 3 is of course
totally arbitrary. Finally, each name is typeset as
\texttt{\string\Von\string~\string\Lastname} with the \tcmd\Von\
part optional, of course (maybe that makes too many hard
spaces, though). Remember that \tcmd\tempcount\ holds the value of
the \texttt{namenumber} field and that \tcmd\NameCount\ is
the place of the author under investigation in the entire field.
Hence, if they are more authors than allowed:

\verbatim
\chardef\namelimit=3
\def\makecitename{%
  \ifnum\tempcount>\namelimit
    \ifnum\NameCount=1
      \unless\ifx\Von\empty \Von~\fi
      \Lastname\space {\italics{et alii}}%
    \fi
\endverbatim

\noindent Otherwise we typeset all names preceded by
different markers: nothing for the first author, \textit{and}
for the last one, and commas in between.

\verbatim
  \else
    \unless\ifnum\NameCount=1
      \ifnum\NameCount=\tempcount\relax \space and 
      \else , \fi
    \fi
    \unless\ifx\Von\empty \Von~\fi
    \Lastname
  \fi
  }
\endverbatim

\noindent And we're done with the \tcmd\cite\ command. We could
add variation, e.g. \tcmd\citeauthor\ to typeset the \texttt{name}
field, \tcmd\citeyear\ for the date, remove parentheses when needed,
etc., but basically we've done the hardest part. The \tcmd\makecitename\
macro shown here is slightly simpler than the real one in
\texttt{authoryear.tex}. The latter first checks whether \tcmd\Lastname\
is `\texttt{others}', in which case it typesets the \textit{et alii}
phrase (a basic feature of Bib\TeX).

Now we have to define \tcmd\MakeCitation. It begins with \tcmd\ReadName\
called with \tcmd\makerefname\ as in the previous example. Even though
\tcmd\makrefname\ is slightly different (the first author is typeset
as \textit{von Last, Jr, First} whereas the other authors remain in the
\textit{First von Last, Jr} style), I won't show it here,
because there's nothing much to learn.

\verbatim
\def\MakeReference{%
  \par\noindent
  \RetrieveFieldIn{namenumber}\tempcount
  \ReadName\makerefname
\endverbatim

\noindent In \tcmd\MakeReference\ still, we add a usual marker for collective
works (\tcmd\editor\ is simply defined as `\texttt{editor}' elsewhere).

\verbatim
  \RetrieveFieldIn{nametype}\temp
  \ifx\temp\editor
    \RetrieveFieldIn{namenumber}\temp
    \ifnum\temp>1 \space (eds.)\else \space (ed.)\fi
  \fi
\endverbatim

\noindent Then we typeset the date between parentheses with a suffix,
which will be set by \tcmd\comparentries\ (and actually probably empty).
This suffix is meant to distinguish entries that are equal according to
\tcmd\SortingOrder.

\verbatim
  \space (\RetrieveField{year}%
          \csname\EntryKey @suffix\endcsname)
  \compareentries
\endverbatim

\noindent Typesetting the rest of the entry depends on the entry type,
which is fed to \tcmd\typesetref. At the end of the entry we call
\tcmd\conditionalstop, a stop that appears if and only if there was no
stop before (see \texttt{authoryear.tex} for details).


\verbatim
  \RetrieveFieldIn{entrytype}\temp
  \typesetref\temp \conditionalstop
  }
\endverbatim

The \tcmd\comparentries\ macro tests whether we are in equal entries
relative to sorting and if so gives them a suffix.

\verbatim
\newcount\sameentrycount
\def\compareentries{%
  \ifequalentry
    \advance\sameentrycount1
    \WriteImmediateInfo{%
      \noexpand\expandafter\def
        \noexpand\csname\EntryKey @suffix\noexpand\endcsname
        {\toletter}}%
  \else \sameentrycount=0 \fi
  }
\endverbatim

\noindent The \tcmd\toletter\ macro turns \tcmd\sameentrycount\
into a letter and is quite uninteresting, so it isn't shown here.
Note that this version of \tcmd\compareentries\ works because 
the first argument of \tcmd\SortOrder\ is set to `\texttt{name,year}',
and hence two references written the same year by the same author
are equal according to \lib, which can set the \tcmd\ifequelentry\
conditional to the requested value. However, if \tcmd\SortOrder\
was `\texttt{name,year,title}', then not only would the same two 
entries be sorted according to their titles,
but most importantly they wouldn't be equal at all as far as \lib\
is concerned (unless they have identical titles, of course),
although in this bibliographic style they should be
seen as such. In that case, \tcmd\compareentries\ should be more
refined and store each entry's \texttt{name} and \texttt{year} fields
in a macro to be compared to the next one.

But we were calling \tcmd\typesetref\ on the \texttt{entrytype} field.
It launches a macro which typesets the rest of the entry according
to its type, and \tcmd\createtype\ is meant to define such a macro:

\verbatim
\def\typesetref#1{%
  \ifcsname#1@entrytype\endcsname
    \csname#1@entrytype\endcsname
  \else
    \errmessage{Unknown entry type: `#1'}%
  \fi
  }
\def\createtype#1{%
  \expandafter\def\csname#1@entrytype\endcsname
  }
\endverbatim

Before creating entries, here are some useful macros to be used with
\tcmd\TypesetField. Indeed, to typeset references properly, punctuation
should be added if and only if the corresponding field exists.

\verbatim
\def\booktitle#1{\setbooktitle{\RetrieveField{#1}}}
\def\setbooktitle#1{\italics{#1}}
\def\articletitle#1{\setarticletitle{\RetrieveField{#1}}}
\def\setarticletitle#1{`#1'}
\def\addcomma#1{, #1}
\def\addjournal#1{\addcomma{{\setbooktitle{#1}}}}
\def\addcolon#1{: #1}
\def\addpar#1{(#1)}
\def\addbook#1{, in \setbooktitle{#1}}
\def\addeditor#1{%
  \RetrieveFieldIn{editornumber}\tempcount
  , edited by \ReadEditor\makeedname}
\endverbatim

\noindent The \tcmd\italics\ macro in \tcmd\setbooktitle\ should
be set to whatever you use to typeset italics. Now, we can create
entries:

\verbatim
\createtype{book}{%
  \booktitle{title}%
  \TypesetField{publisher}\addcomma{}%
  \TypesetField{address}\addcolon{}%
  }
\createtype{article}{%
  \articletitle{title}%
  \TypesetField{journal}\addjournal{}%
  \TypesetField{volume}\addcomma{}%
  \TypesetField{number}\addpar{}%
  \TypesetField{pages}\addcomma{}%
  }
\createtype{incollection}{%
  \articletitle{title}%
  \TypesetField{crossref}\crossref{%
    \TypesetField{booktitle}\addbook{}%
    \TypesetField{editor}\addeditor{}%
    \TypesetField{pages}\addcomma{}%
    \TypesetField{publisher}\addcomma{}%
    \TypesetField{address}\addcolon{}%  
    }%
  }
\endverbatim

\noindent ... and many more! That's the basic job of a bibliographic
style. Note that we make good use of \tcmd\TypesetField, but not with
the \texttt{title} field, because it is very unlikely to be missing.
Now, give a look at the \texttt{incollection} entry; once the title
is typeset, it reads as follows: call the \tcmd\crossref\ macro on the
value of the \texttt{crossref} field if it has any, otherwise, typeset
the information about the book. And \tcmd\crossref\ is:

\verbatim
\def\crossref#1{%
  , in \cite{#1}%
  \WriteImmediateInfo{\noexpand\Cite{#1}{main}{}{}}%
  }
\endverbatim

\noindent Since the value of the \texttt{crossref} field is an entry key,
we simply \tcmd\cite\ that entry. However, this is not enough; \tcmd\SortList\
can deal with entries if and only if they are cited before it is called; on the
other hand, \tcmd\ReadList, where the cross-reference happens, must appear after
\tcmd\SortList. That's why we pass a \tcmd\Cite\ command to the next compilation;
note that the third argument does nothing.

Thus, supposing the reference `\texttt{Gaddis1994}' has a \texttt{crossref} field to `\texttt{Gass2000}',
\tcmd{\cite\targ{Gaddis1994}} in a document will produce the following in the
bibliography:

\input authoryear
\Cite{Gaddis1994}{main}{}{}
\citation
\SortList{main}
\ReadList{main}
\endcitation

What if we don't want to see the `\texttt{Gass2000}' reference in the bibliography
and instead want something like this:

\citation
\def\EntryKey{gaddis1994}
\RetrieveFieldIn{namenumber}\tempcount
\ReadName\makerefname~(\RetrieveField{year})
`\RetrieveField{title}', in
\def\EntryKey{gass2000}
\RetrieveFieldIn{namenumber}\tempcount
\booktitle{title}, edited by \ReadName\makeedname, 
\RetrieveField{publisher}: \RetrieveField{address},
\RetrieveField{year}.
\endcitation

\noindent Then \tcmd\crossref\ should be something like this:

\verbatim
\def\crossref#1{%
  \bgroup
    \lowercase{\def\EntryKey{#1}}%
    \TypesetField{title}\addbook{}%
    \TypesetField{editor}\addeditor{}%
    \TypesetField{pages}\addcomma{}%
    \TypesetField{publisher}\addcomma{}%
    \TypesetField{address}\addcolon{}% 
    \TypesetField{year}\addcomma{}%
  \egroup
  \WriteImmediateInfo{\noexpand\Cite{#1}{crossref}{}{}}%
  }
\endverbatim

\noindent That is: we apply the same macros to a different entry
by redefining \tcmd\EntryKey\ temporarily (hence the group). Note
that this redefinition must happen in \tcmd\lowercase, because there
we're away from \lib's handling of entry keys. Note also that we
still \tcmd\Cite\ the entry in the external file, because the citation
is necessary to retrieve fields in the bibliographic files; however
the entry is added to a secondary list `\texttt{crossref}' that we'll never
sort nor read.

\vskip 0pt plus 1filll
\parfillskip0pt
\noindent\hfill {\it Typeset with Lua\TeX\ v.0.6}\par
\noindent\hfill {\it in Garamond Pro (Robert Slimbach)}\par
\noindent\hfill {\it and Inconsolata (Raph Levien)}\par

\makebookmarks

\BibFile{librarian}
\bye