From 275e7bd70ec8122117418dbec2a8efef972741c8 Mon Sep 17 00:00:00 2001 From: Martin Haug Date: Tue, 31 Oct 2023 00:55:23 +0100 Subject: [PATCH] Add docs --- CHANGELOG.md | 98 ++++++++++++++++++++++++++++++++++++++ docs/file-format.md | 109 ++++++++++++++++++++----------------------- src/csl/mod.rs | 2 +- src/types/strings.rs | 8 ++-- 4 files changed, 154 insertions(+), 63 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..8a567506 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,98 @@ +# 0.4.0 + +## Breaking changes: + +Hayagriva now uses the [Citation Style Language](https://citationstyles.org) to +encode formatting styles. This means that Hayagriva's own formatting styles have +been deprecated. + +### For users: +- The YAML input format has changed. + - Titles and formattable strings have been merged into one type. All + formattable strings can have a shorthand now. + - Formattable Strings do not have `title-case` and `sentence-case` keys + anymore. `shorthand` has been renamed to `short`. To prevent changes of + the text case of formattable strings, you can use braces. Enclose a part + of a formattable string (or `short`) in `{braces}` to print it as-is. + - The fields `doi`, `isbn`, and `issn` have been moved to `serial-number` + which can now be a dictionary containing these and arbitrary other serial + numbers like a `pmid` (PubMed ID) and `arxiv` (ArXiv Identifier). + - The `tweet` entry type has been renamed to `post`. + - All numeric variables can now also contains strings. Numbers can have + string affixes. + +### For developers: +- To use a CSL style, you can either supply a CSL file or use an archive of + provided styles with the `archive` feature. +- The `from_yaml_str` function will now return the new `Library` struct, with the + entries within. +- The `Database` struct has been replaced by the easier to handle + `BibliographyDriver`. +- We switched from `yaml_rust` to `serde_yaml`. The `Entry` now implement's + `serde`'s `Serialize` and `Deserialize` traits. Hence, the `from_yaml` and + `to_yaml` functions have been deleted. +- Brackets are no longer individually overridable. Instead, use the new + `CitePurpose`. +- `Entry::kind` has been renamed to `Entry::entry_type`. + - The citation styles `AuthorTitle` and `Keys` have been removed but can be + realized with CSL. + +This release fixes many bugs and makes Hayagriva a serious contender for +reference management. + +## Other changes + +- We added the entry types `Performance` and `Original`. +- We added the field `call-number`. + + +# 0.3.2 + +Fixes a title case formatting bug introduced in the previous release. + +# 0.3.1 + +_Bug Fixes:_ +- Added an option to turn off abbreviation of journals (thanks to @CMDJojo) +- Fixed bugs with title case formatting (thanks to @jmskov) +- Fixed off-by-one error with dates in APA style (thanks to @bluebear94) +- Fixed supplements in the Alphanumeric and AuthorTitle styles (thanks to @lynn) +- Fixed bugs with sentence case formatting +- Fixed `verbatim` option +- Fixed terminal formatting +- Fixed some typos (thanks to @kianmeng and @bluebear94) + +# 0.3.0 + +*Breaking:* +- Updated to `biblatex` 0.8.0 + +*Bug Fixes:* +- Fixed string indexing for titles, removed panic +- More permissive BibLaTeX parsing + +# 0.2.1 + +*Bug Fixes:* +- Fixed APA bibliography ordering + +# 0.2.0 + +*Breaking:* +- Replaced `NoHyphenation` formatting with `Link` formatting +- Switched to newest BibLaTeX (which is part of the public API) + +*Bug Fixes:* +- Fixed IEEE bibliography ordering +- Fixed A, B, C, ... suffixes for Author Date citations +- Removed `println` calls + +# 0.1.1 + +🐞 This release fixes the documentation of the CLI in the `README.md` file. +✨ There are new options for bracketed citations in the CLI. +✅ No breaking changes. + +# 0.1.0 + +🎉 This is the initial release! \ No newline at end of file diff --git a/docs/file-format.md b/docs/file-format.md index 09cb6fe9..23936b4a 100644 --- a/docs/file-format.md +++ b/docs/file-format.md @@ -150,7 +150,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | title | +| **Data type:** | formattable string | | **Description:** | title of the item | | **Example:** | `title: Rick Astley: How An Internet Joke Revived My Career` | @@ -194,6 +194,14 @@ This section lists all possible fields and data types for them. | **Description:** | persons involved with the item that do not fit `author` or `editor` | | **Example:** | 
affiliated:
    - role: Director
      names: Cameron, James
    - role: CastMember
      names: ["Schwarzenegger, Arnold", "Hamilton, Linda", "Patrick, Robert"]
| +#### `call-number` + +| | | +|------------------|-----------------------------------------------------------| +| **Data type:** | formattable string | +| **Description:** | The number of the item in a library, institution, or collection. Use with `archive`.| +| **Example:** | `call-number: "F16 D14"` | + #### `publisher` | | | @@ -214,7 +222,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | string | +| **Data type:** | formattable string | | **Description:** | Organization at/for which the item was produced | | **Example:** | `organization: Technische Universität Berlin` | @@ -222,7 +230,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | integer or string | +| **Data type:** | numeric or string | | **Description:** | For an item whose parent has multiple issues, indicates the position in the issue sequence. Also used to indicate the episode number for TV. | | **Example:** | `issue: 5` | @@ -230,7 +238,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | integer or range of integers | +| **Data type:** | numeric or string | | **Description:** | For an item whose parent has multiple volumes/parts/seasons ... of which this item is one | | **Example:** | `volume: 2-3` | @@ -238,7 +246,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | integer | +| **Data type:** | numeric | | **Description:** | Total number of volumes/parts/seasons this item consists of | | **Example:** | `volume-total: 12` | @@ -246,7 +254,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | integer or string | +| **Data type:** | numeric or string | | **Description:** | published version of an item | | **Example:** | `edition: expanded and revised edition` | @@ -254,7 +262,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | integer _(single page)_ or integer range | +| **Data type:** | numeric or string | | **Description:** | the range of pages within the parent this item occupies | | **Example:** | `page-range: 812-847` | @@ -262,7 +270,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | integer | +| **Data type:** | numeric | | **Description:** | total number of pages the item has | | **Example:** | `page-total: 1103` | @@ -302,25 +310,9 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | string | -| **Description:** | any serial number or version describing the item that is not appropriate for the fields `doi`, `edition`, `isbn` or `issn` (may be assigned by the author of the item; especially useful for preprint archives) | -| **Example:** | `serial-number: 2003.13722` | - -#### `isbn` - -| | | -|------------------|-----------------------------------------------------------| -| **Data type:** | string | -| **Description:** | International Standard Book Number (ISBN), prefer ISBN-13 | -| **Example:** | `isbn: 978-0-20189683-1` | - -#### `issn` - -| | | -|------------------|-----------------------------------------------------------| -| **Data type:** | string | -| **Description:** | International Standard Serial Number (ISSN) | -| **Example:** | `issn: 0014-1704` | +| **Data type:** | string or dictionary of strings | +| **Description:** | Any serial number. If you have serial numbers of well-known schemes like `doi`, you can put them into the serial number as a dictionary like in the second example. Hayagriva will recognize and specially treat `doi`, `isbn` `issn`, `pmid`, `pmcid`, and `arxiv` | +| **Example:** | `serial-number: 2003.13722` or 
serial-number:
    doi: "10.22541/au.148771883.35456290"
    arxiv: "1906.00356"
| #### `language` @@ -350,7 +342,7 @@ This section lists all possible fields and data types for them. | | | |------------------|-----------------------------------------------------------| -| **Data type:** | string | +| **Data type:** | formattable string | | **Description:** | additional description to be appended after reference list entry | | **Example:** | `note: microfilm version` | @@ -378,8 +370,10 @@ Needs a keyword with one of the following values: - `newspaper`. The issue of a newspaper that was published on a given day. - `legislation`. Legal document or draft thereof that is, is to be, or was to be enacted into binding law (default parent: `anthology`). - `manuscript`. Written document that is submitted as a candidate for publication. -- `tweet`. A post on a micro-blogging platform like Twitter (default parent: `tweet`). +- `original`. The original container of the entry before it was re-published. +- `post`. A post on a micro-blogging platform like Twitter (default parent: `post`). - `misc`. Items that do not match any of the other Entry type composites. +- `performance`. A live artistic performance. - `periodical`. A publication that periodically publishes issues with unique content. This includes scientific journals and news magazines. - `proceedings`. The official published record of the events at a professional conference. - `book`. Long-form work published physically as a set of bound sheets. @@ -397,49 +391,46 @@ The field is case insensitive. It defaults to `Misc` or the default parent if th #### Formattable String -A formattable string is a string that may run through a sentence or title case transformer when used in a reference or citation. You can disable these transformations or provide your own title and sentence case versions of the string. +A formattable string is a string that may run through a text case transformer when used in a reference or citation. You can disable these transformations on segments of the string or the whole string. -The simplest scenario for a formattable string is to provide a string: +The simplest scenario for a formattable string is to provide a string that can be case-folded: ```yaml publisher: UN World Food Programme ``` -To disable formatting altogether and instead preserve the casing as it appears in the source string, put the string in the `value` sub-field and specify another sub-field as `verbatim: true`: +If you want to preserve a part of the string but want to go with the style's +behavior otherwise, enclose the string in braces like below. You must wrap the +whole string in quotes if you do this. ```yaml -publisher: - value: UN World Food Programme - verbatim: true +publisher: "{imagiNary} Publishing" ``` -If you instead want to provide a custom sentence- or title-cased version of the string, you can write them in their own sub-fields (note that the sub-field value with the canonical name always has to be specified): + +To disable formatting altogether and instead preserve the casing as it appears +in the source string, put the string in the `value` sub-field and specify +another sub-field as `verbatim: true`: ```yaml publisher: - value: imagiNary Publishing - title-case: Imaginary Publishing - sentence-case: imagiNary publishing + value: UN World Food Programme + verbatim: true ``` -A `sentence-case` or `title-case` sub-field will take precedence over `verbatim`. +Title and sentence case folding will always be deactivated if your item has set +the `language` key to something other than English. -#### Title +You can also include mathematical markup evaluated by [Typst](typst.app) by +wrapping it in dollars. -A title is a formattable string that can have two additional sub-fields: `translation` (the translated name of the item) and `shorthand` (shortened name of the item used if a citation style requires it). Both of these fields are formattable strings themselves. Just like a formattable string, a title can be just a string. +Furthermore, every formattable string can include a short from that a citation +style can choose to render over the longer form. ```yaml -title: The Nutcracker -``` - -Example with translation and shorthand: - -```yaml -title: - value: Щелкунчик - verbatim: true - translation: The Nutcracker - shorthand: Nutcracker +journal: + value: International Proceedings of Customs + short: Int. Proc. Customs ``` #### Person @@ -523,13 +514,15 @@ time-range: "03:35:21-03:58:46" Strings are sequences of characters as a field value. In most cases you can write your string after the colon, but if it contains a special character (`:`, `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `\`) it should be wrapped with double-quotes. If your string contains double-quotes, you can write those as this escape sequence: `\"`. If you instead wrap your string in single quotes, most YAML escape sequences such as `\n` for a line break will be ignored. -#### Integer - -Integers are whole numbers that can be negative, e. g. `53789` or `-3`. +#### Numeric -#### Integer range +Numeric variables are one or more numbers that are delimited by commas, +ampersands, and hyphens. Numeric variables can express a single number or a +range and contain only integers, but may contain negative numbers. Numeric variables can have a non-numeric prefix and suffix. -Integer ranges are two integers within a string, separated by a hyphen and optionally spaces (`6 - 18`). Both integers must be positive. +```yaml +page-range: S10-15 +``` #### Unicode Language Identifier diff --git a/src/csl/mod.rs b/src/csl/mod.rs index e726ded5..2ecef4ae 100644 --- a/src/csl/mod.rs +++ b/src/csl/mod.rs @@ -1417,7 +1417,7 @@ impl<'a> BibliographyRequest<'a> { } } -/// A reference to an [`Entry`] within a [`CitationRequest`]. +/// A reference to an [`crate::Entry`] within a [`CitationRequest`]. #[derive(Debug, Clone, PartialEq, Eq, Hash)] pub struct CitationItem<'a, T: EntryLike> { /// The entry to format. diff --git a/src/types/strings.rs b/src/types/strings.rs index c15dad0a..2a9d242a 100644 --- a/src/types/strings.rs +++ b/src/types/strings.rs @@ -224,13 +224,13 @@ impl<'de> Deserialize<'de> for ChunkedString { Deserialize::deserialize(serde::de::value::MapAccessDeserializer::new( map, )) - .map(|inner: Inner| { + .and_then(|inner: Inner| { if inner.verbatim { - StringChunk::verbatim(inner.value) + Ok(StringChunk::verbatim(inner.value).into()) } else { - StringChunk::normal(inner.value) + Self::Value::from_str(&inner.value) + .map_err(|e| serde::de::Error::custom(e.to_string())) } - .into() }) } }