Skip to content

Commit

Permalink
Add docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@reknih
reknih committed Oct 31, 2023
1 parent f837f72 commit b4d304f
Show file tree
Hide file tree
Showing 4 changed files with 158 additions and 63 deletions.
102 changes: 102 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# 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.

Refer to the updated
[file format](https://github.com/typst/hayagriva/blob/main/docs/file-format.md)
docs for examples.

### 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!
109 changes: 51 additions & 58 deletions docs/file-format.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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` |

Expand Down Expand Up @@ -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:** | <pre>affiliated:<br> - role: Director<br> names: Cameron, James<br> - role: CastMember<br> names: ["Schwarzenegger, Arnold", "Hamilton, Linda", "Patrick, Robert"]<br></pre> |

#### `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`

| | |
Expand All @@ -214,55 +222,55 @@ 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` |

#### `issue`

| | |
|------------------|-----------------------------------------------------------|
| **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` |

#### `volume`

| | |
|------------------|-----------------------------------------------------------|
| **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` |

#### `volume-total`

| | |
|------------------|-----------------------------------------------------------|
| **Data type:** | integer |
| **Data type:** | numeric |
| **Description:** | Total number of volumes/parts/seasons this item consists of |
| **Example:** | `volume-total: 12` |

#### `edition`

| | |
|------------------|-----------------------------------------------------------|
| **Data type:** | integer or string |
| **Data type:** | numeric or string |
| **Description:** | published version of an item |
| **Example:** | `edition: expanded and revised edition` |

#### `page-range`

| | |
|------------------|-----------------------------------------------------------|
| **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` |

#### `page-total`

| | |
|------------------|-----------------------------------------------------------|
| **Data type:** | integer |
| **Data type:** | numeric |
| **Description:** | total number of pages the item has |
| **Example:** | `page-total: 1103` |

Expand Down Expand Up @@ -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 <pre>serial-number:<br> doi: "10.22541/au.148771883.35456290"<br> arxiv: "1906.00356"</pre> |

#### `language`

Expand Down Expand Up @@ -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` |

Expand Down Expand Up @@ -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.
Expand All @@ -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](https://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 form 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
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion src/csl/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 4 additions & 4 deletions src/types/strings.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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()
})
}
}
Expand Down

0 comments on commit b4d304f

Please sign in to comment.