diff --git a/classes/resilient/book.lua b/classes/resilient/book.lua index a9d468f..64f8b68 100644 --- a/classes/resilient/book.lua +++ b/classes/resilient/book.lua @@ -48,8 +48,19 @@ function class:_init (options) self:loadPackage("labelrefs") self:loadPackage("struts") self:loadPackage("resilient.headers") + self:loadPackage("markdown") self:loadPackage("djot") + -- Once Djot is loaded, we can register custom pre-defined symbols + self.packages["markdown.commands"]:registerSymbol("_BIBLIOGRAPHY_", true, function (opts) + if not self.packages.bibtex then + SU.warn("Bibliography support is not available") + return {} + end + return { + createCommand("printbibliography", opts) + } + end) -- Override document.parindent default to this author's taste SILE.settings:set("document.parindent", "1.25em") diff --git a/examples/manual-masterdoc/bibliographies.dj b/examples/manual-masterdoc/bibliographies.dj new file mode 100644 index 0000000..08d183c --- /dev/null +++ b/examples/manual-masterdoc/bibliographies.dj @@ -0,0 +1,59 @@ +# Using bibliographies + +For scholarly works, you may want to include bibliographic references in your book. +The master document is where you can configure the bibliography style, language, and files to use. + +## Configuring the bibliography + +In you master document, you can set up the global bibliography configuration as follows: + +```yaml +bibliography: + style: chicago-author-date + language: en-US + files: + - somebibfile.bib +``` + +The `style` key specifies the citation style to use. +It should be referring to a CSL (Citation Style Language) file, located where SILE expects to find it.[^csl-location] +If left absent, the default style is whatever SILE has set as default, normally `chicago-author-date` (Chicago Manual of Style author-date format). + +The `language` key specifies the language to use for the bibliography. +By default, it is the same as the main language as defined in your master document, but you can override it here if needed. +Why would you need to do that? +CSL locale files are not always available for all languages and variants, or may need to be specified as a specific BCP 47 language tag (i.e. `en-US`), possibly diffent from the main language set in your master document. + +The `files` key is a list of bibliography files to use. +You can specify multiple files, which will be merged into a single bibliography. +The files must be in BibTeX format (in the subset supported by SILE), and located relative to your working directory. + +[^csl-location]: Whatever CSL files are bundled with SILE, any style supported by the Citation Style Language can be used. +You can find lots of styles for a wide range of journals and publishers on the [CSL Styles Repository](https://github.com/citation-style-language/styles). +The same applies to language files, which are used to localize the style to a specific language, see the [CSL Locales Repository](https://github.com/citation-style-language/locales). +You will need to download the files you want to use and place them in a location where SILE can find them. +Refer to _The SILE Book_ for more information on how to do this. + +## Printing the bibliography + +The **resilient.book** class registers a Djot symbol, `_BIBLIOGRAPHY_`, which you can use in a standalone paragraph to print the bibliography.[^bibliography-symbol] +Attributes are passed through to the underlying implementation. +For example, to print all the bibliography including uncited references, you can use: + +``` +:_BIBLIOGRAPHY_:{cited=false} +``` + +By default, only cited references (up to the point where the bibliography is printed) are included. +After printing the bibliography, the list of cited entries will be cleared. +This allows you to start fresh for subsequent uses (e.g., in a different chapter). + +## Citing references + +This is not covered here. +Refer to the _Markdown and Djot to PDF with SILE_ user guide, or to _The SILE Book_ for more information on how to cite references depending on the format you are using to author your content. + + +[^bibliography-symbol]: Obviously, this needs to be used in a Djot content file. +If you are using Markdown, you will need to switch to Djot for this part. +In SIL, you can use the `\printbibliography` command. diff --git a/examples/sile-resilient-manual.silm b/examples/sile-resilient-manual.silm index a07c960..9d4af7c 100644 --- a/examples/sile-resilient-manual.silm +++ b/examples/sile-resilient-manual.silm @@ -53,6 +53,7 @@ parts: content: - manual-masterdoc/masterdoc.dj - manual-masterdoc/bookmatters.dj + - manual-masterdoc/bibliographies.dj - file: manual-parts/part-layouts.dj content: - manual-layouts/layouts.sil diff --git a/inputters/silm.lua b/inputters/silm.lua index 0cf177b..b7bdbae 100644 --- a/inputters/silm.lua +++ b/inputters/silm.lua @@ -120,6 +120,20 @@ local BookSchema = { } } +local BibliographySchema = { + type = "object", + properties = { + style = { type = "string" }, + language = { type = "string" }, + files = { + type = { -- oneOf + { type = "string" }, + { type = "array", items = { type = "string" } }, + }, + }, + } +} + local MasterSchema = { type = "object", additionalProperties = true, -- Allow unknown property for extensibility @@ -208,6 +222,7 @@ local MasterSchema = { } }, book = BookSchema, + bibliography = BibliographySchema, -- parts and chapters are exclusive, but we don't enforce it here. -- We will check it later in the inputter parts = ContentSchema, @@ -509,6 +524,28 @@ function inputter:parse (doc) if metadata.title then content[#content+1] = createCommand("has:book-title-support", {}, { metadata.title }) end + if master.bibliography then + local bibfiles = master.bibliography.files + if type(bibfiles) == "string" then + bibfiles = { bibfiles } + end + content[#content+1] = createCommand("use", { + module = "packages.bibtex" + }) + if #bibfiles > 0 then + local lang = master.bibliography.language or master.language or "en-US" + local style = master.bibliography.style or "chicago-author-date" + content[#content+1] = createCommand("bibliographystyle", { + style = style, + lang = lang + }) + for _, bibfile in ipairs(bibfiles) do + content[#content+1] = createCommand("loadbibliography", { + file = bibfile + }) + end + end + end end local metadataOptions = handleDjotMetadata(metadata)