summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/optex/base/usebib.opm
blob: cb38eea7e84b9ff65be035e0afbd39dff0b99979 (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
%% This is part of the OpTeX project, see http://petr.olsak.net/optex

\_codedecl \readbibs {Reading bib databases <2023-06-25>} % loaded on demand by \usebib

   \_doc -----------------------------
   First, we implement the scanner of `.bib` files. Unfortunately, the format of
   these files isn't \TeX/ friendly, so we must to do more work.
   \`\readbibs` `{<bib-bases>}` reads <bib-bases> files
   (i.e. the Bib\TeX/ format).
   \_cod -----------------------------

\_newcount\_aunum
\_newcount\_NameCount
\_def\_eaddto#1#2{\_ea\_addto\_ea#1\_ea{#2}}

\_def\_readbibs #1{%
   \_ifcsname _be:\_bibp*\_endcsname \_def\_citelist{}\_fi % \_citelist will be created
   \_begingroup
      \_everyeof{@{}}\_foreach#1,\_do##1,{\_ea\_nextat\_input{##1.bib}}%
   \_endgroup
}
\_public \readbibs ;

   \_doc -----------------------------
   The \`\_nextat` macro skips the text in the `.bib` file to the next `@`, and starts
   the \`\_bibentry` macro which reads `@<entry type>{<data>}` from the `.bib` file.
   Each reference entry is conveted to the \`\_entrydata`
   macro and then `\_glet \_be:<bib-part>/<label> = \_entrydata` is done.
   The \^`\_entrydata` includes key-value pairs, as described in the
   section~\ref[readbibs].
   \_cod -----------------------------

\_long\_def\_nextat#1@{\_bgroup\_catcode` =9 \_ea\_egroup\_bibentry}
\_def\_bibentry #1#{\_ifx^#1^\_else \_afterfi{\_bibentryA{#1}}\_fi}
\_def\_bibentryA #1#2{\_lowercase{\_def\_entrytype{#1}}%
   \_ismacro\_entrytype{comment}\_iffalse  % comment is ignored
   \_ismacro\_entrytype{texcode}\_iftrue   % TeX code is processed
      \_endgroup #2\_begingroup \_everyeof{@{}}\_else
   \_ismacro\_entrytype{string}\_iftrue    % string is reported as unsupported
      \_opwarning{\_string\usebib: @STRING entry isn't supported, try to use @TEXCODE}%
   \_else
      \_edef\_entrydata{[@]{\_entrytype}}%
      {\_bibentryB #2\_fin}%               % read a "normal" bib entry
   \_fi\_fi\_fi
   \_nextat
}
\_def\_bibentryB #1#2,#3\_fin{\_def\_citekey{#1#2}\_def\_bibentryC{\_nextfield #3,\_fin}%
   \_ifcsname _be:\_bibp*\_endcsname
      \_bibentryC
      \_global\_addto\_citelist{\_citeI[#1#2]}
   \_else
   \_ea\_ifx \_begincsname _be:\_bibp#1#2\_endcsname \_empty
      \_bibentryC
   \_fi\_fi
}
\_def\_bibentryF {% finalize entry
   \_preparebibsorting
   \_global\_ea\_let \_csname _be:\_bibp\_citekey\_endcsname = \_entrydata
}

   \_doc -----------------------------
   \`\_nextfield` reads next field name and saves it to the \`\_fieldname`
   and then reads field data and saves it to the \`\_fielddata`.
   \_cod -----------------------------

\_def\_nextfield #1{\_ifx,#1\_ea\_nextfield   % skip commas from previous field
   \_else \_ifx\_fin#1\_ea\_ea\_ea\_bibentryF % finalize bib entry
   \_else \_def\_fieldname{#1}\_ea\_ea\_ea\_nextfieldA % first letter of fieldname found
   \_fi\_fi
}
\_def\_nextfieldA #1{% next letters of field name until = is found
   \_ifx=#1\_afterfi{\_nospacefuturelet\_next\_nextfieldB}%
   \_else \_addto\_fieldname{#1}%
   \_ea\_nextfieldA \_fi
}
\_def\_nextfieldB {% reading field data
   \_casesof\_next
   "        {\_nextfieldC}%  name = "data",
   \_bgroup {\_nextfieldD}%  name = {data},
   \_finc   {\_nextfieldE}%  name = data,
}
\_def\_nextfieldC "#1"{\_nextfieldD{#1}}
\_def\_nextfieldD #1{\_def\_fielddata{#1}\_nextfieldF}
\_def\_nextfieldE #1,{\_nextfieldD{#1}}

\_def\_nextfieldF{% finalize field
   \_lowercase\_ea{\_ea\_def\_ea\_fieldname\_ea{\_fieldname}}% case insensitive field name
   \_ifcsname _fia:\_fieldname\_endcsname \_edef\_fieldname{\_cs{_fia:\_fieldname}}\_fi
   \_eaddto\_entrydata{\_ea[\_fieldname]}%
   \_ismacro\_fieldname{author}\_iftrue \_ea\_auscan\_ea{\_fielddata}[author]\_else
   \_ismacro\_fieldname{editor}\_iftrue \_ea\_auscan\_ea{\_fielddata}[editor]\_else
   \_eaddto\_entrydata{\_ea{\_fielddata}}\_fi\_fi
   \_sdef{_fd:\_fieldname\_ea}\_ea{\_fielddata}%
   \_nextfield
}

   \_doc -----------------------------
   \`\_fieldalias``{<new-name>}{<given-name>}`
   defines `\_fia:<new_name>` as <given-name>.
   \_cod -----------------------------

\_def\_fieldalias#1#2{\_lowercase{\_sxdef{_fia:#1}{#2}}}

   \_doc -----------------------------
   The \`\_auscan``{<authors/editors-names>}[<field-name>]` reads the specific Bib\TeX/
   format menitoned in section~\ref[readbibs] and converts them to
   `{<Lastname>}{<Firstname>}{<Von>}{<Junior>}` for each author/editor. The result
   includes $4k$ subfields (where $k$ is number of the authors/editors) and
   it is saved to the `\_entrydata` and the
   `[authornum]{`$k$`}` or `[editornum]{`$k$`}` is added.

   The \`\_auscanA` macro does the loop over authors separated by `and`.
   Each single author has its `\_tmpb` macro with `X` and `x`. Each letter
   corresponds to single word of the name (`X`: begins with uppercase, `x`:
   begins with lowercase). For example Leonardo Piero da Vinci has `\_tmpb`
   macro `XXxX.`. If there are commas in after some words, then these commas
   are in `\_tmpb` macro too, for example da Vinci, Piero Leonardo has its
   `\_tmpb` macro `xX,XX.`. The number of commas is saved to `\_tmpnum`.
   The \`\_auscanB` macro does a slight modifications of the `\_tmpb` macro as
   mentioned in comments. Then the macro
   \`\_auscanD``<tpmb-pattern>;{<WordA>}{<WordB>}{<WordC>}...` is executed.
   It saves given words due to the `\_tmpb` pattern to the macros
   `\_Lastname`, `\_Firstname`, `\_Von`, `\_Junior` in a loop. Finally, the contents of
   these macros are saved to `\_fiedldata` and then to the `\_entrydata`.
   \_cod -----------------------------

\_def\_auscan#1[#2]{\_def\_auname{}\_def\_fielddata{}\_def\_tmpb{}\_aunum=0\_tmpnum=0
   \_auscanA #1 and {}
   \_eaddto\_entrydata{\_ea{\_fielddata}[#2num]}%
   \_eaddto\_entrydata{\_ea{\_the\_aunum}}%
}
\_def\_auscanA #1 {%
   \_ifx^#1^\_else
      \_isequal{#1}{and}\_iftrue
         \_incr\_aunum
         \_addto\_tmpb{.}%
         \_auscanB
         \_ea\_auscanX \_auname
         \_def\_auname{}\_def\_tmpb{}\_tmpnum=0
      \_else
         \_lowercase{\_isequal{#1}}{#1}\_iftrue \_addto\_tmpb{x}\_else \_addto\_tmpb{X}\_fi
         \_def\_tmp{#1^}\_isinlist\_tmp{,^}%
         \_iftrue
             \_ea\_auscanC\_tmp \_addto\_tmpb{,}\_incr\_tmpnum
         \_else
             \_def\_tmp{#1}%
         \_fi
         \_eaddto\_auname{\_ea{\_tmp}}%
      \_fi
      \_ea\_auscanA
   \_fi
}
\_def\_auscanB{%
   \_ifcase\_tmpnum  % 0 commas:  XXX. -> XX:X. ; XxxXX. -> X:xxXX. ;  xXX. -> :xXX. ; First:Last
      \_isinlist\_tmpb{x}\_iffalse \_replstring\_tmpb{X.}{:X.}\_else
      \_ea\_auscanT\_tmpb;\_iffalse \_replstring\_tmpb{Xx}{X:x}\_fi\_fi
   \_or             % 1 comma:  XX,XXX -> XX,,XXX, Junior part is empty
      \_replstring\_tmpb{,}{,,}\_tmpnum=2
   \_fi             % 2 commas: XX,XX,XXX no changes, generic format: Last, Junior, First
   \_def\_Firstname{}\_def\_Lastname{}\_def\_Von{}\_def\_Junior{}%
}
\_def\_auscanT #1#2;\_iffalse{\_ifx#1x\_def\_tmpb{:x#2}\_else} % xXX. -> :xXX.
\_def\_auscanX {\_ea\_auscanD\_tmpb;}
\_def\_auscanD #1#2;{%
   \_def\_tmpb{#2}%
   \_casesof #1
   . {\_auscanF}                              % dot is last character, do final job
   , {\_decr\_tmpnum \_auscanX}               % Lastname->Junior or Junior->Firstname
   : {\_tmpnum=2 \_auscanX}                   % Firstname->Lastname
   X {\_auscanE\_Firstname\_Junior\_Lastname} % add data due to the \tmpnum value
   x {\_auscanE\_Firstname\_Junior\_Von}      % Von instead Lastname
   \_finc {}%
}
\_def\_auscanE#1#2#3{\_ifcase\_tmpnum \_ea\_auscanS\_ea#1\_or \_ea\_auscanS\_ea#2\_else
                                  \_ea\_auscanS\_ea#3\_fi}
\_def\_auscanS#1#2{% #1=\Firstname or \Lastname or etc., #2=word to be inserted
   \_ifx#1\_empty \_def#1{#2}\_else \_addto#1{ #2}\_fi
   \_auscanX
}
\_def\_auscanF{% final work of \auscanX
   \_eaddto\_fielddata{\_ea{\_Lastname}}\_eaddto\_fielddata{\_ea{\_Firstname}}%
   \_eaddto\_fielddata{\_ea{\_Von}}\_eaddto\_fielddata{\_ea{\_Junior}}%
}
\_def\_auscanC #1,^{\_def\_tmp{#1}}  % removing final comma: Word,^ -> Word

   \_doc -----------------------------
   The \^`\_citelist` includes \`\_citeI``[<label>]`
   commands. The \^`\usebib` macro runs this lists in order to print references.
   Each \^`\_citeI``[<label>]` prints single bib entry given by the <label>.
   It opens a group, sets macros `\_fd:<field-name>` to `<field-data>` and runs
   \^`\_printentry`. Finally, it closes \TeX/ group,
   so all macros `\_fd:<field-name>` have their initial (undefined) value.\nl
   The \`\_getfield``[<field-name>]\macro` does `\def\macro{<field-data>}`.
   If the field isn't declared then the `\macro` is empty.
   \_cod -----------------------------

\_def\_citeI[#1]{%
   \_begingroup
      \_ea\_ifx \_begincsname _be:\_bibp#1\_endcsname \_empty
         \_opwarning{\_string\usebib: entry [#1] isn't found in .bib}%
         \_global\_slet{_bes:#1}{_relax}%
      \_else
         \_ea\_ea\_ea\_foreach \_csname _be:\_bibp#1\_endcsname \_do[##1]##2{\_sdef{_fd:##1}{##2}}%
         \_def\_entrykey{#1}%
         \_printentry
      \_fi
   \_endgroup
}
\_def\_getfield[#1]#2{%
   \_ifcsname _fd:#1\_endcsname
       \_ea\_ea\_ea \_def \_ea\_ea\_ea #2\_ea\_ea\_ea {\_csname _fd:#1\_endcsname}%
   \_else \_def#2{}%
   \_fi
}

   \_doc -----------------------------
   \`\_preparebibsorting` is called repeatedly for each bib entry when its reading from
   `.bib` file is finished. Its main goal is to do
   `\gdef\_bes:<citekey> {\;<sorting-rule>^^^<citekey>}`.
   Note that the part of the control sequence name after `^^^` is ignored during sorting.
   The default \^`\_preparebibsorting`
   macro creates <sorting-rule> in the form: <Lastnames> <Firstnames> <Von>
   <Junior> of the first author followed by <year> from `year` field.\nl
   \`\_dobibsorting``\_citelist` sorts the \^`\_citelist` and runs it.
   \_cod -----------------------------

\_def\_preparebibsorting{%
   \_getfield[sortedby]\_sortedby
   \_ifx\_sortedby\_empty   % explicitly given [sortedby] field has precedence
      \_def\_sortedby{}%
      \_getfield[author]\_tmp  % sorting by author firstly
      \_ifx\_tmp\_empty \_else \_ea\_preparebibsortingA\_tmp \_fin \_fi
      \_getfield[year]\_tmp    % soering by year secondly
      \_ifx\_tmp\_empty \_else \_eaddto\_sortedby{\_tmp}\_fi
      \_edef\_sortedby{\_sortedby}%  we need to run macros aka \"e etc.
      \_edef\_sortedby{\_ea\_removeoutbraces\_sortedby {\_fin}}% remove braces
   \_fi
   \_sxdef{_bes:\_citekey\_ea}\_ea{\_csname;\_detokenize\_ea{\_sortedby}^^^\_citekey\_endcsname}%
}
\_def\_preparebibsortingA#1#2#3#4#5\_fin {% names of the first author used by sorting:
   \_def\_sortedby{#1 }%                         Lastname
   \_ifx^#2^\_else \_addto\_sortedby{#2 }\_fi  % Firstname
   \_ifx^#3^\_else \_addto\_sortedby{#3 }\_fi  % Von
   \_ifx^#4^\_else \_addto\_sortedby{#4 }\_fi  % Junior
}
\_def\_dobibsorting{%
   {\_def\_citeI[##1]{\_ea\_citeIs\_csname _bes:##1\_endcsname{##1}}%
    \_edef\_citelist{\_ea}\_citelist % converting \_citelist
    \_dosorting\_citelist \_ea}%
}
\_def\_citeIs#1#2{\_eaddto\_citelist{#1}%
   \_ea\_gdef#1{\_citeI[#2]\_ea\_glet#1=\_undefined \_glet#1=\_undefined}%
}

   \_doc -----------------------------
   The \`\_printentry` macro prints bibliographic reference entry.
   It prints <bibnum> or <bimark> (including hyperlinks) and they are
   followed by printing the entry data. The format is given by the \^`\_printbib`
   macro and by `\_print:<entrytype>` declared in the bib-style file.
   \_cod -----------------------------

\_def\_printentry {\_par \_bibskip
  \_bibgl\_incr\_bibnum
  \_isdefined{_bim:\_bibp\_the\_bibnum}\_iftrue
     \_edef\_tmpb{\_csname _bim:\_bibp\_the\_bibnum\_endcsname}%
     \_bibmark=\_ea{\_tmpb}%
  \_else \_bibmark={}\_fi
  \_edef\_tmpb{\_entrykey}%
  \_noindent \_dbib\_entrykey
  \_printbib
  {%
     \_getfield[@]\_entrytype
     \_csname _print:BEGIN\_endcsname
     \_isdefined{_print:\_entrytype}\_iftrue
        \_csname _print:\_entrytype\_endcsname
     \_else
        \_ifx\_entrytype\_empty \_else
           \_opwarning{Entrytype @\_entrytype\_space from [\_entrykey] undefined}%
           \_csname _print:misc\_endcsname
     \_fi\_fi
     \_csname _print:END\_endcsname
     \_wbib \_entrykey {\_the\_bibnum}{\_the\_bibmark}%
  }\_par
}

   \_doc -----------------------------
   The \`\_bprinta`, \`\_bprintb`, \`\_bprintc`, \`\_bprintv`
   commands used in the style files:
   \_cod -----------------------------

\_def\_bprinta {\_bprintb*}
\_def\_bprintb #1[#2#3]{%
   \_def\_bibfieldname{#2#3}%
   \_if!#2\_relax
      \_def\_bibfieldname{#3}%
      \_getfield[#3]\_bibfield
      \_getfield[#3num]\_namecount % total persons in the author/editor fields
      \_ifx\_bibfield\_empty\_else
         \_def\_bibfield{\_loopauthors{#3}}% read author/edior field in a loop
      \_fi
   \_else
      \_getfield[#2#3]\_bibfield
   \_fi
   \_if^#1^%
      \_ifx\_bibfield\_empty \_ea\_ea\_ea \_doemptyfield
      \_else \_ea\_ea\_ea \_dofullfield \_fi
   \_else \_ea \_bprintaA
   \_fi
}
\_def\_dofullfield#1#2{\_def\_dofield##1{#1}\_ea\_dofield\_ea{\_bibfield}}
\_def\_doemptyfield#1#2{\_def\_dofield##1{#2}\_ea\_dofield\_ea{\_bibfield}}
\_def\_bprintaA #1#2{\_ifx\_bibfield\_empty #2\_else\_bprintaB #1**\_fin\_fi}
\_def\_bprintaB #1*#2*#3\_fin{\_ifx^#3^#1\_else\_ea\_bprintaC\_ea{\_bibfield}{#1}{#2}\_fi}
\_def\_bprintaC #1#2#3{#2#1#3}
\_def\_bprintc#1#2{\_bprintcA#1#2**\_relax}
\_def\_bprintcA#1#2*#3*#4\_relax{\_ifx#1\_empty \_else \_if^#4^#2\_else#2#1#3\_fi\_fi}
\_def\_bprintv [#1]#2#3{\_def\_tmpa{#2}\_def\_tmpb{#3}\_bprintvA #1,,}
\_def\_bprintvA #1,{%
   \_if^#1^\_tmpb\_else
      \_getfield[#1]\_tmp
      \_ifx \_tmp\_empty
      \_else \_tmpa \_def\_tmpb{}\_def\_tmpa{}%
      \_fi
   \_ea \_bprintvA
   \_fi
}

   \_doc -----------------------------
   \`\_loopauthors``{<field-name>}` does a loop over all authors/editors in
   the `author` or `editor` field. The \`\_namecount`
   (total nuber of authors/editors) was defined in
   \^`\_bprintb`. Then for each author/edtor it do:
   \begitems
   * Set \`\_NameCount` to the position number of the currently processed author/editor.
   * Define \`\_Lastname`, \`\_Firstname`, \`\_Junior`, \`\_Von`, \`\_After` macros.
   * Run \^`\_authorname` or \^`\_editorname` macro (defined in the bib style file).
   \enditems
   \_cod -----------------------------

\_def\_loopauthors #1{%
   \_NameCount=0
   \_ea\_ea\_ea\_foreach\_csname _fd:#1\_endcsname \_do ##1##2##3##4{%
      \_advance\_NameCount by1
      \_def\_Lastname{##1}\_def\_Firstname{##2}\_def\_Von{##3}\_def\_Junior{##4}%
      \_csname _#1ini\_endcsname \_csname _#1name\_endcsname
}}
\_def\_authorini{} % ready for \_AbbreviateFirstname or similar...
\_def\_editorini{}

   \_doc -----------------------------
   \`\_bibwarning` can be used if the manatory field is missing.
   Note that \`\_nobibwarnlist` is used here, it is set by \^`\nobibwarning` macro.
   \_cod -----------------------------

\_def\_bibwarning{%
   \_ea\_isinlist \_ea\_nobibwarnlist\_ea{\_ea,\_entrykey,}\_iffalse
       \_opwarning{Missing field "\_bibfieldname" in [\_entrykey]}\_fi}

   \_doc -----------------------------
   \`\_AbbreviateFirstname`, \`\_RetrieveFieldIn`, \`\_RetrieveField` are here only for
   backward comaptibility with previous macros based on the librarian package.
   The \`\_CreateField`, \`\_SortingOrder`, and \`\_SpecialSort` are dummy
   macros because the sorting is implemented by a slightly different way
   than in librarian package.
   \_cod -----------------------------

\_def\_AbbreviateFirstname{\_addto\_authorini{\_abbrevnames\_Firstname}}
\_def\_abbrevnames#1{% Karolina Pondelickova-Maslova -> K. P.-M.
   \_edef#1{\_ea\_foreach #1 \_do ##1##2 {##1.%
                \_foreach ##2-{}\_do ####1-####2{\_ifx^####2^\_else-####2.\_fi} }^%
   }\_replstring#1{ ^}{}%
}
\_def\_RetrieveFieldIn#1{\_getfield[#1]}
\_def\_RetrieveField#1{\_trycs{_fd:#1}{}}
\_def\_CreateField#1{}
\_def\_SortingOrder#1#2{}
\_def\_SpecialSort#1{}

   \_doc -----------------------------
   The \^`\usebib` command is defined as `\input{usebib.opm}\_usebib` in the
   format. So, the command is re-defined here and it is run again with the new
   meaning.\nl
   The \^`\usebib` macro defined here reads `\_ctlst:<bibpart>/` and `\_ctlstB:<bibpart>/`
   (they include a list of `\_citeI[<label>]`) and merges them to a single \`\_citelist`.
   The `\_be:<bibpart>/<label>` is set to empty for each member of the `\_citelist`.
   Then the style file is read in a group,
   the \^`\readbibs` macro reads given `.bib` files and resulting `\_citelist`
   is processed: i.e.\ the macros \^`\_citeI` print desired entries.
   \_cod -----------------------------

\_def\_usebib/#1 (#2) #3 {%
   \_ifcsname _ctlst:\_bibp\_endcsname
       \_slet{_citelist}{_ctlst:\_bibp}\_else \_def\_citelist{}\_fi
   \_ea \_foreach\_citelist \_do ##1[##2]{\_sdef{_be:\_bibp##2}{}}%
   \_ifcsname _ctlstB:\_bibp\_endcsname
     \_ea\_ea\_ea\_foreach \_csname _ctlstB:\_bibp\_endcsname \_do ##1[##2]{%
         \_ifcsname _be:\_bibp##2\_endcsname
         \_else \_addto\_citelist{\_citeI[##2]}\_sdef{_be:\_bibp##2}{}%
         \_fi
     }%
   \_fi
   \_global \_ea\_let \_csname _ctlst:\_bibp\_endcsname =\_write
   \_ifx\_citelist\_empty
     \_opwarning{No cited items. \_noexpand\usebib ignored}%
   \_else
     \_bgroup
        \_par
        \_emergencystretch=.3\_hsize
        \_def\_optexbibstyle{#2}%
        \_setctable\_optexcatcodes
        \_input bib-#2.opm
        \_the \_bibtexhook
        \_ifcsname _mt:bib.and:\_cs{_lan:\_the\_language}\_endcsname \_else
           \_opwarning{\_string\usebib: No phrases for language
                       "\_cs{_lan:\_the\_language}" (using "en")}%
           \_language=0 \_chardef\_documentlanguage=0
        \_fi
        \_ifx#1c\_def\_preparebibsorting{}\_def\_dobibsorting{}\_fi
        \_readbibs {#3}%
        \_dobibsorting\_citelist
        \_restorectable
     \_egroup
   \_fi
}

\_endcode

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The file `usebib.opm` implements the command
\~`\usebib/<sorttype> (<style>) <bibfiles>`
where `<sorttype>` is one letter `c` (references ordered by citation order in
the text) or `s` (references sorted usually by authors and years),
`<style>` is the part of the name `bib-<style>.opm` of the style file
and `<bibfiles>` are one or more `.bib` file names without suffix separated by
comma without space. Example:

\begtt
\usebib/s (simple) mybase,yourbase
\endtt
This command reads the `<bibfiles>` directly and creates the list of
bibliographic references (only those declared by \~`\cite[]` or
\~`\nocite[]` in the document). The formatting of such references is defined in
the style~file.

The principle \"first entry wins" is used. Suppose `\usebib/s (simple) local,global`.
If an entry with the same label is declared in `local.bib` and in
`global.bib` too then the first wins. So, you can set exceptions in your
`local.bib` file for your document.

The `bib-<style>.opm` declares entry types (like `@BOOK`, `@ARTICLE`) and declares
their mandatory and optional fields (like `author`, `title`). When
a mandatory field is missing in an entry in the `.bib` file then a warning is printed on the
terminal about it. You can suppress such warnings by command
\^`\nobibwarning`~`[<bib-labels>]`, where <bib-labels> is a comma-separated list
of labels (without spaces) where missing mandatory fields will be no warned.

Old `.bib` files may use the obscure notation for accents like `{\"o}`.
Recommendation: convert such old files to Unicode encoding. If you are
unable to do this then you can set \^`\bibtexhook={`\^`\oldaccents}`.


\secc Notes for bib-style writers

The `.bib` files include records in the format:

\begtt \catcode`\<=13
@<entry-type>{<label>,
   <field-name> = "<field-data>",
   <field-name> = "<field-data>",
   ...etc
}
\endtt
%
see the file `demo/op-biblist.bib` for a real example. The <entry-types> and
<field-names> are case insensitive. More field-names can behave equally if the
\^`\_fieldalias``{<new-field-name>}{<given-field-name>}` is used in a style
file. If a <new-field-name> is declared by this command and it is used in the `.bib`
file then the effect is the same as if it was used the <given-field-name>.

Ancient Bib\TeX/ has read such files and has generated files appropriate for
reading by \LaTeX. It has worked with a set of <entry-types>, see the www
page \url{http://en.wikipedia.org/wiki/BibTeX}. The set of entry types
listed on this www page is de facto the Bib\TeX/ standard. The \OpTeX/ bib
style writer must \"declare" all such entry types and more non-standard
entry types can be declared too if there is a good reason for doing it. The
word \"declare" used in the previous sentence means that a bib-style writer must
define the printing rules for each <entry-type>.
The printing rules for <entry-type> include: which fields will be printed, in
what order, by what format they will be printed on (italic, caps, etc.),
which fields are mandatory, which are optional, and which are ignored in
`.bib` records.

The style writer can be inspired by two styles already done: `bib-simple.opm`
and `bib-iso690.opm`. The second one is documented in detail in
section~\ref[isobib].

The printing rules for each <entry-type> must be declared by
`\_sdef{_print:<entry-type>}` in `bib-<style>.opm` file.
The `<entry-type>` has to be lowercase here. \OpTeX/ supports following
macros for a more comfortable setting of printing rules:

\begitems
* \^`\_bprinta` `[<field-name>]  {<if defined>} {<if not defined>}`. The part <if defined>
    is executed if <field-name> is declared in .bib file for the entry which is
    currently processed. Else the part <if not defined> is processed.
    The part <if defined> can include the `*` parameter which is replaced
    by the value of the <field-name>.
*   The part <if not defined> can include
    the \^`\_bibwarning` command if the <field-name> is mandatory.
* \^`\_bprintb` `[<field-name>]  {<if defined>} {<if not defined>}`. The same as
    \^`\_bprinta`, but the `##1` parameter is used instead `*`. Differences: `##1`
    parameter can be used more than once and can be enclosed in nested
    braces. The `*` parameter can be used at most once and cannot be enclosed
    in braces. Warning: if the \^`\_bprintb` commands are nested (`\_bprintb` in
    \^`\_bprintb`), then you need to write the `####1` parameter for internal `\_bprintb`.
    But if \^`\_bprinta` commands are nested then the parameter is not duplicated.
* \^`\_bprintc` `\macro {<if non-empty>}`. The <if non-empty> part is executed if
    `\macro` is non-empty. The `*` parameter can be used, it is replaced by
    the `\macro`.
* \^`\_bprintv` `[<field1>,<field2>,...] {<if defined>} {<if not defined>}`.
    The part <if defined> is executed if <field1> or <filed2> or ...
    is defined, else the second part <if not defined> is executed.
    There is one filed name or the list field names separated by commas.
    The parts cannot include any parameters.
\enditems

There are two special field-names: `!author` and `!editor`. The processed list of
authors or editors are printed here instead of raw data, see the commands
\~`\_authorname` and \~`\_editorname` below.

The bib-style writer can define `_print:BEGIN` and/or `_print:END`.
They are executed at the beginning or
end of each `<entry-type>`. The formatting does not solve the numbering and
paragraph indentation of the entry. This is processed by \^`\_printbib` macro
used in \OpTeX/ (and may be redefined by the author or document designer).

The \^`\bibmark={something}` can be declared, for instance in the `_print:END` macro.
Such \"bibmark" is saved to the `.ref` file and used in next \TeX/ run as
`\cite` marks when `\nonumcitations` is set.

Moreover, the bib-style writer must declare the format of
special fields `author` and `editor`. These fields include a
list of names, each name is precessed individually in a loop. The
\^`\_authorname` or \^`\_editorname` is called for each name on the list.
The bib-style writer must define
the \`\_authorname` and \`\_editorname` commands
in order to declare the format of printing each individual name.
The following control sequences can be used in these macros:

\begitems
* \^`\_NameCount`: the number of the currently processed author in the list
* \^`\_namecount`: the total number of the authors in the list
* \^`\_Lastname`, \^`\_Firstname`, \^`\_Von`, \^`\_Junior`: the parts of the name.
\enditems

The whole style file is read in the group during the \^`\usebib` command is executed
before typesetting the reference list. Each definition or setting is local
here.

The auto-generated phrases (dependent on current language) can be used in
bib-style files by `\_mtext{bib.<identifier>}`, where <identifier> is an identifier of
the phrase and the phrase itself is defined by
`\_sdef{_mt:bib.<identifier>:<language>}{<phrase>}`. See section~\ref[langphrases]
for more detail. Phrases for <identifiers>:
and, etal, edition, citedate, volume, number, prepages, postpages, editor,
editors, available, availablealso, bachthesis, masthesis, phdthesis
are defined already, see the end of section~\ref[langphrases].

The `sortedby` field is declared by \~`\readbibs` as a special field where
sorting phrase can be specified. If it is present then it has precedence
before default sorting phrase generated by \~`\_preparebibsorting` from the
lastname, firstnames of the first author and from the year.
Suppose that the .bib file includes:
\begtt
author   = "Jan Chadima",
sortedby = "Hzzadima Jan",
\endtt
Now, this author is sorted between H and I, because the Ch digraph in this
name has to be sorted by this rule.

If you need (for example) to place the auto-citations before other citations,
then you can mark your entries in `.bib` file by `sortedby = "@"`, because this
character is sorted before `A`.

If you want to declare a different sorting rule, you can re-define the
\^`\_preparebibsorting` macro. The example is in the
\ulink[http://petr.olsak.net/optex/optex-tricks.html\#reverseyear]{\OpTeX/ trick 0113}.

\secc[readbibs] Direct reading of `.bib` files

\^`\readbibs` `{<bib-bases>}` is internally used (by \^`\usebib`)
for reading `.bib` databases in Bib\TeX/ format. The <bib-bases> is
comma separated list of file names (without `.bib` extension, without
spaces). These files are read and \^`\readbibs` defines macros
`\_be:<bibpart>/<label>`, where <label> is the label of the reference record.
These macros include key-value pairs `[<field name>]{<field data>}`.
The first pair is `[@]{<entry type>}`.
For example, if we have in the `.bib` file:
\begtt
@Book { tbn,
   author = "Petr Olšák",
   TITle  = {\TeX{}book naruby},
   publisher = "Konvoj",
   year      = 2001,
}
\endtt
and the \^`\bibpart` is empty (default value)
then the `\_be:/tbn` macro is defined with the content:
\begtt
[@]{BOOK}[author]{{Olšák}{Petr}{}{}}[authornum]{1}[title]{\TeX{}book naruby}%
[publisher]{Konvoj}[year]{2001}
\endtt
If you do `\slet{tmp}{_be:/tbn}` then you can print the data (for example) by:
\begtt
\ea\foreach \tmp \do [#1]#2{\wterm{field-name: "#1", data: "#2"}}
\endtt
or you can do `\ea\foreach \tmp \do [#1]#2{\sdef{bib-field:#1}{#2}}` to enable
direct acces to the scanned data.

Note that entry type and field names are converted lower-case by the `\readbibs` macro.

There are two special entry types: `@COMMENT{<ignored text>}` and
`@TEXCODE{<processed text>}`. The <ignored text> is ignored, the
<processed text> is executed by \TeX/. The definitions of macros used in other
entries in data of fields can be here. If the `\usebib` is used then
the <processed text> is executed inside a
\TeX/ group, so the assignment is locally valid only during creating the
reference list. The BiB\TeX/'s `@STRING{}` isn't supported. All others entry
types are interpreted as a {\em reference entry} and they are interpreted as
described above. An optional balanced text between entries in `.bib` files
is ignored.

If the macro `\_be:<bibpart>/*` is defined then the \^`\readbibs` macro reads
all entries from `.bib` files and creates \~`\_citelist`. If the
`\_be:<bibpart>/*` is undefined then
the \^`\readbibs` macro reads only entries with <label> where
`\_be:<bibpart>/<label>` is set to the empty macro. After reading, the
macros `\_be:<bibpart>/<label>` are globally re-defined as described above.

The \^`\readbibs` macro doesn't convert fields data, but there are two exceptions:
author and editor fields. These fields have very specific format with
various alternatives, see \url{https://nwalsh.com/tex/texhelp/bibtx-23.html}.
Shortly speaking, more authors are divided by the `and` keyword and names of a single
author must be separated to four subfields: <Lastnames>, <Firstnames>, <Von>,
<Junior>. Only the <Lastnames> subfield must be nonempty. The input can look like
\begtt
Leonardo Piero da Vinci
or
da Vinci, Leonardo Piero
\endtt
and both these variants are converted to `{Vinci}{Leonardo Piero}{da}{}`.
The <Von> part is rekognized as a word with only lowercase letters. In
general, the name can be written without commas: <Firstnames> <Von>
<Lastnames> or with single comma: <Von> <Lastnames>, <Firstnames> or with two
commas: <Von> <Lastnames>, <Junior>, <Firstnames> and all these variants are
converted to the quaternion `{<Lastnames>}{<Firstnames>}{<Von>}{<Junior>}`
by the \^`\readbibs` macro.
If there are more than single author, then each author is saved in four
subfields side by side, so you have 4 or 8 or 12 etc.\ subfildeds in the
author/editor data field. You can read them by
`\foreach <author-data>\do #1#2#3#4{...}`.

\_endinput

History:
--------
2023-06-25: \_fieldalias introduced
2023-06-07: bug fix (\_namecount declaration)
2023-06-06: \_slet{_bes:#1}{_relax}: bugfix when label not found and sorting
2023-06-05: @TEXCODE introduced + more consistent doc
2023-06-02: macros re-implemeted, librarian package no more needed.
2018 - 2023-06-01  usebib.opm based on librarian package, like in OPmac.