summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/base/usebib.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/optex/base/usebib.opm')
-rw-r--r--macros/luatex/optex/base/usebib.opm169
1 files changed, 110 insertions, 59 deletions
diff --git a/macros/luatex/optex/base/usebib.opm b/macros/luatex/optex/base/usebib.opm
index 7f772b09d2..e278774c97 100644
--- a/macros/luatex/optex/base/usebib.opm
+++ b/macros/luatex/optex/base/usebib.opm
@@ -32,8 +32,14 @@
\_ifx\_bibpart\_undefined \_def\_bibpart{none}\_fi
\_def\_optexbibstyle{#2}%
\_setctable\_optexcatcodes
+ \_ea \_skiptoendinput \_input languages.opm
\_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
\_let\_citeI=\_relax \_xdef\_citelist{\_citelist\_citelistB}%
\_global\_let\_addcitelist=\_writeXcite
\_def\_tmp##1[*]##2\_relax{\_def\_tmp{##2}}\_expandafter\_tmp\_citelist[*]\_relax
@@ -50,6 +56,7 @@
\_egroup
\_fi
}
+\_long\_def\_skiptoendinput#1\_endinput{}
\_def\_readbibentry#1#{\_readbibentryA}
\_def\_readbibentryA#1{\_readbibentryB#1,,\_relax!.}
\_def\_readbibentryB#1#2,#3\_relax!.{\_addto\_citelist{\_citeI[#1#2]}}
@@ -64,7 +71,7 @@
\_unless\_ifx\lb@temp\lb@eoe
\lb@ifcs{#1}{fields}%
{}%
- {\_opwarning{\_string\_usebib: entry [#1] isn't found in .bib file(s)}}%
+ {\_opwarning{\_string\usebib: entry [#1] isn't found in .bib}}%
\_ea\lb@checkmissingentries
\_fi
}
@@ -183,23 +190,20 @@
}
\_doc -----------------------------
- Various macros + multilinguas.
+ Various macros + multilinguas. Note that \`\_nobibwarnlist` is used in
+ \`\_bibwarning` and it is set by \^`\nobibwarning` macro.
\_cod -----------------------------
-\_def\_bibwarning{\_opwarning{Missing field "\_bibfieldname" in [\EntryKey]}}
-
-\_def\_mtdef#1#2#3#4{\_sdef{_mt:#1:en}{#2} \_sdef{_mt:#1:cs}{#3}
- \_if$#4$\_slet{_mt:#1:sk}{_mt:#1:cs}
- \_else \_sdef{_mt:#1:sk}{#4}
- \_fi
-}
+\_def\_bibwarning{%
+ \_ea\_isinlist \_ea\_nobibwarnlist\_ea{\_ea,\EntryKey,}\_iffalse
+ \_opwarning{Missing field "\_bibfieldname" in [\EntryKey]}\_fi}
\_endcode
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
The file `usebib.opm` implements the command
-`\usebib/<sorttype> (<style>) <bibfiles>`
+\~`\usebib/<sorttype> (<style>) <bibfiles>`
where `<sorttype>` is one letter `c` (references ordered by citation order in
the text) or `s` (references ordered by key in the style file),
`<style>` is the part of the name `bib-<style>.opm` of the style file
@@ -211,89 +215,136 @@ comma without space. Example:
\endtt
This command reads the `<bibfiles>` directly and creates the list of
-bibliographics references (only those declared by by `\cite[]` or
-`\nocite[]` in the text). The formatting of such references is defined in the style
-file. The usage is mentioned in user documentation too.
+bibliographics references (only those declared by by \~`\cite[]` or
+\~`\nocite[]` in the text). 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 an exceptions in your
`local.bib` file for your document.
-\seccc Notes for style writers
+The `bib-<style>.opm` declares entry types (like `@BOOK`, `@ARTICLE`) and declares
+their mandatory and optionals fields (like `author`, `title`). When
+mandatory field is missing in an entry in the `.bib` file then warning is printed on the
+terminal about it. You can suppress such warnings by command
+\^`\nobibwarning`~`[<bib-labels>]`, where <bib-labels> is comma separated list
+of labels (without spaces) where missing mandatory fields will be no warned.
+
+Old `.bib` files may use 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-<style>.opm` file must define the commands:
+The `.bib` files include records in the format:
+
+\begtt
+@<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.
+
+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 previous sentence means that 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 oder, by what format they will printed on (italic, caps, etc.),
+which fields are mandatory, which are optional and which are ingnored in
+`.bib` records.
+
+The style writer can be inspired by two styles alredy 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>` have to be lowercase here. \OpTeX/ supports following
+macros for more comfortable setting of printing rules:
\begitems
-* `\_authorname` ... formatting of one name in the authors list. The macro can
- use the following data: `\_NameCount` (the number of the currently
- processed author name in the list), `0\_namecount` (the total number of the
- authors in the list), `\_Lastname`, `\_Firstname`, `\_Von`, `\_Junior`
- (the parts of the name). See the documentation of the librarian package
- for more info.
-* `\_editorname` ... the same as `\_authorname`, but for editors list.
-* `_print:<entrytype>` (defined by `\_sdef`) for formatting the entry of `<entrytype>`.
- The `<entrytype>` have to be lowercase. This command can use the command:
-* `\_bprinta [<fieldname>] {<if defined>} {<if not defined>}`. The part <if defined>
- is executed if <fieldname> is declared in .bib file for the entry which is
+* \^`\_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 <fieldname>. The part <if not defined> can include
- the `\_bibwarning` command if the <fieldname> is mandatory.
-* `\_bprintb [<fieldname>] {<if defined>} {<if not defined>}`. The same as
+ 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
+ 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 `####1` parameter for internal `\_bprintb`.
But if `\_bprinta` commands are nested then the parameter is not duplicated.
-* `\_pbprintc \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
+* \^`\_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>}`.
+* \^`\_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 parameter.
\enditems
-%
-There are two special fieldnames: `!author` and `!editor`. The processed list of
-authors or editors (by repeatedly calling `\_authorname` or `\_editorname`) are
-used here instead of raw data.
-You can define `_print:BEGIN` and/or `_print:END` which is executed at the begin or
-end of each `<entrytype>`. The formatting does not solve the numbering and
-paragraph indentation of the entry. This is processed by `\_printbib` macro
+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 begin 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).
-You can declare `\_bimark={something}` in the `_print:END` macro. This bibmark is
-saved to the `.ref` file (created by \OpTeX/) and used in the next \TeX/ run as
+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
+printing 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 in 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 currently processed author in the list
+* `\_namecont`: 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 `\usebib` command is executed
before typesetting the reference list. Each definition or setting is local
here.
-If you are using non-standard fieldnames in .bib database and bib. style,
-you has to declare them by `\_CreateField {<fieldname>}`.
-
-You can declare `\_SortingOrder` in the manner documented by librarian package.
+The auto-generated phrases (dependent on current language) can be used in
+bib style files by `\_mtext{bib.<identifier>}`, where <ident> 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].
-If your style adds some words or abbreviations you can make them
-multilingual by saying `\_mtext{<label>}` instead such word and
-`\_mtdef{<label>} {<English>} {<Czech>} {<Slovak>}` declaration.
-The right part is printed by current value of the `\language` regiter.
-You can add more languages by re-defining the `\_mtdef` command.
-See the section \ref[langphrases] for more information.
+If you are using non-standard field-names in .bib database and bib style,
+you have to declare them by `\_CreateField {<fieldname>}`.
-If you are using `\nonumcitations`, then the `\_bibmark` tokens register have to be
-prepared in the style file (in `_print:BEGIN`, `_print:END`, in
-`\_authorname` etc.) This value will be used in the `\cite[]` places
-in the document.
-
-The example of the style file is in `bib-simple.opm`.
+You can declare `\_SortingOrder` in the manner documented by librarian package.
-User or author of the `bib.` style can create the hidden field which has a
+User or author of the bib style can create the hidden field which has a
precedence while sorting names. Example:
\begtt