diff --git a/.vitepress/theme/custom.css b/.vitepress/theme/custom.css index 07afccf0..91dfca6e 100644 --- a/.vitepress/theme/custom.css +++ b/.vitepress/theme/custom.css @@ -1,5 +1,14 @@ /* Custom styles for Libation documentation */ +/* Naming Templates page: monospace in the doc column + outline only. + pageClass is applied to .Layout in VitePress; limit scope to #VPContent + so the top nav, sidebar, and site footer keep the default font. */ +.Layout.naming-templates-mono #VPContent, +.Layout.naming-templates-mono #VPContent * { + font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, + "Liberation Mono", "Courier New", monospace; +} + /* Hide certain nav items on tablet devices to prevent horizontal scroll */ @media (min-width: 640px) and (max-width: 959px) { /* Target specific nav items by their position */ diff --git a/docs/features/naming-templates.md b/docs/features/naming-templates.md index f5d74e33..72654909 100644 --- a/docs/features/naming-templates.md +++ b/docs/features/naming-templates.md @@ -1,3 +1,7 @@ +--- +pageClass: naming-templates-mono +--- + # Naming Templates File and Folder names can be customized using Libation's built-in tag template naming engine. To edit how folder and file names are created, go to Settings \> Download/Decrypt and edit the naming templates. If you're splitting your audiobook into multiple files by chapter, you can also use a custom template to set each chapter's title metadata tag by editing the template in Settings \> Audio File Options. @@ -130,7 +134,7 @@ Text formatting can change length and case of the text. Use \<#\>, \<#\>\ | Formatter | Description | Example Usage | Example Result | |----------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |--------------------------------------------- | ---------------------------------------------| | separator() | Specify the text used to join
multiple entries.

Default is ", " | `` | Tag1_Tag2_Tag3_Tag4_Tag5 | -| format(\{S\}) **†** | Formats the entries by placing their values into the specified template.
Use \{S:[Text_Formatter](#text-formatters)\} to place the entry and optionally apply a format. | ``separator(;)]>` | Tag=tag1;Tag=tag2;Tag=tag3;Tag=tag4;Tag=tag5 | +| format(\{S\}) **†** | Formats the entries by placing their values into the specified template.
Use \{S:[Text formatters](#text-formatters)\} to place the entry and optionally apply a format. | ``separator(;)]>` | Tag=tag1;Tag=tag2;Tag=tag3;Tag=tag4;Tag=tag5 | | sort(S) | Sorts the elements by their value.

*Sorting direction:*
uppercase = ascending
lowercase = descending

Default is unsorted | ``separator(;)]>` | Tag5;Tag4;Tag3;Tag2;Tag1 | | max(#) | Only use the first # of entries | `` | Tag1 | | slice(#) | Only use the nth entry of the list | `` | Tag2 | @@ -145,7 +149,7 @@ Text formatting can change length and case of the text. Use \<#\>, \<#\>\ | Formatter | Description | Example Usage | Example Result | |-------------------------| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| \{N \| # \| ID\} **†** | Formats the series using
the series part tags.
\{N:[Text_Formatter](#text-formatters)\} = Series Name
\{#:[Number_Formatter](#number-formatters)\} = Number order in series
\{ID:[Text_Formatter](#text-formatters)\} = Audible Series ID

Formatter parts are optional and introduced by the colon. If specified the string will be used to format the part using the corresponding formatter.

Default is \{N\} | ``\``\``\`` | Sherlock Holmes\sherlock holmes\Sherlock Holmes, 1-6, B08376S3R2\SHERLOCK H, B08376S3R2, 01.0-06.0 | +| \{N \| # \| ID\} **†** | Formats the series using
the series part tags.
\{N:[Text_Formatter](#text-formatters)\} = Series Name
\{#:[Number_Formatter](#number-formatters)\} = Number order in series
\{ID:[Text_Formatter](#text-formatters)\} = Audible Series ID

Formatter parts are optional and introduced by the colon. If specified the string will be used to format the part using the corresponding formatter.

Default is \{N\} | ``
``
``
`` | Sherlock Holmes
sherlock holmes
Sherlock Holmes, 1-6, B08376S3R2
SHERLOCK H, B08376S3R2, 01.0-06.0 | **†** For further information on format templates, please refer to the [Format templates](#format-templates) section. @@ -154,7 +158,7 @@ Text formatting can change length and case of the text. Use \<#\>, \<#\>\ | Formatter | Description | Example Usage | Example Result | |---------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | separator() | Specify the text used to join
multiple series names.

Default is ", " | `` | Sherlock Holmes; Some Other Series | -| format(\{N \| # \| ID\}) **†** | Formats the series properties
using the name series tags.
See [Series Formatter Usage](#series-formatters) above. | ``separator(; )]>`\`` | Sherlock Holmes, 1-6; Book Collection, 1\B08376S3R2-Sherlock Holmes, 01.0-06.0, B000000000-Book Collection, 01.0 | +| format(\{N \| # \| ID\}) **†** | Formats the series properties
using the name series tags.
See [Series Formatter Usage](#series-formatters) above. | ``separator(; )]>`
`` | Sherlock Holmes, 1-6; Book Collection, 1
B08376S3R2-Sherlock Holmes, 01.0-06.0, B000000000-Book Collection, 01.0 | | sort(N \| # \| ID) | Sorts the series by name, number or ID.

These terms define the primary, secondary, tertiary, … sorting order.
You may combine multiple terms in sequence to specify multi‑level sorting.

*Sorting direction:*
uppercase = ascending
lowercase = descending

Default is unsorted | ``separator(; )]>` | Book Collection, 1; Sherlock Holmes, 1-6 | | max(#) | Only use the first # of series | `` | Sherlock Holmes | | slice(#..#) | Only use entries of the series list starting from # and ending at # (inclusive)

See [Text List Formatter Usage](#Text-List-Formatters) above for details on all the variants of `slice()` | `` | Sherlock Holmes | @@ -165,7 +169,7 @@ Text formatting can change length and case of the text. Use \<#\>, \<#\>\ | Formatter | Description | Example Usage | Example Result | |----------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------- | -| \{T \| F \| M \| L \| S \| ID\} **†** | Formats the human name using
the name part tags.
\{T:[Text_Formatter](#text-formatters)\} = Title (e.g. "Dr.")
\{F:[Text_Formatter](#Text-Formatters)\} = First name
\{M:[Text_Formatter](#text-formatters)\} = Middle name
\{L:[Text_Formatter](#text-formatters)\} = Last Name
\{S:[Text_Formatter](#text-formatters)\} = Suffix (e.g. "PhD")
\{ID:[Text_Formatter](#text-formatters)\} = Audible Contributor ID

Formatter parts are optional and introduced by the colon. If specified the string will be used to format the part using the correspoing formatter.

Default is \{T\} \{F\} \{M\} \{L\} \{S\} | ``\`` | Fry, S.\DOYLE, Arthur \_B000AQ43GQ\_ | +| \{T \| F \| M \| L \| S \| ID\} **†** | Formats the human name using
the name part tags.
\{T:[Text_Formatter](#text-formatters)\} = Title (e.g. "Dr.")
\{F:[Text_Formatter](#Text-Formatters)\} = First name
\{M:[Text_Formatter](#text-formatters)\} = Middle name
\{L:[Text_Formatter](#text-formatters)\} = Last Name
\{S:[Text_Formatter](#text-formatters)\} = Suffix (e.g. "PhD")
\{ID:[Text_Formatter](#text-formatters)\} = Audible Contributor ID

Formatter parts are optional and introduced by the colon. If specified the string will be used to format the part using the correspoing formatter.

Default is \{T\} \{F\} \{M\} \{L\} \{S\} | ``
`` | Fry, S.
DOYLE, Arthur \_B000AQ43GQ\_ | **†** For further information on format templates, please refer to the [Format templates](#format-templates) section. @@ -174,8 +178,8 @@ Text formatting can change length and case of the text. Use \<#\>, \<#\>\ | Formatter | Description | Example Usage | Example Result | |------------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | separator() | Specify the text used to join
multiple people's names.

Default is ", " | `` | Arthur Conan Doyle; Stephen Fry | -| format(\{T \| F \| M \| L \| S \| ID\}) **†** | Formats the human name using
the name part tags.
See [Name Formatter Usage](#name-formatters) above. | ``separator(; )]>`\``_{ID}_) separator(; )]>` | DOYLE, Arthur; FRY, Stephen\Doyle, A. \_B000AQ43GQ\_;
Fry, S. \_B000APAGVS\_ | -| sort(T \| F \| M \| L \| S \| ID) | Sorts the names by title,
first, middle, or last name,
suffix or Audible Contributor ID

These terms define the primary, secondary, tertiary, … sorting order.
You may combine multiple terms in sequence to specify multi‑level sorting.

*Sorting direction:*
uppercase = ascending
lowercase = descending

Default is unsorted | ``\``\`` | Stephen Fry, Arthur Conan Doyle\Stephen King, Stephen Fry\John P. Smith \_B000TTTBBB\_, John P. Smith \_B000TTTCCC\_, John S. Smith \_B000HHHVVV\_ | +| format(\{T \| F \| M \| L \| S \| ID\}) **†** | Formats the human name using
the name part tags.
See [Name Formatter Usage](#name-formatters) above. | ``separator(; )]>`
``_{ID}_) separator(; )]>` | DOYLE, Arthur; FRY, Stephen
Doyle, A. \_B000AQ43GQ\_;
Fry, S. \_B000APAGVS\_ | +| sort(T \| F \| M \| L \| S \| ID) | Sorts the names by title,
first, middle, or last name,
suffix or Audible Contributor ID

These terms define the primary, secondary, tertiary, … sorting order.
You may combine multiple terms in sequence to specify multi‑level sorting.

*Sorting direction:*
uppercase = ascending
lowercase = descending

Default is unsorted | ``
``
`` | Stephen Fry, Arthur Conan Doyle
Stephen King, Stephen Fry
John P. Smith \_B000TTTBBB\_, John P. Smith \_B000TTTCCC\_, John S. Smith \_B000HHHVVV\_ | | max(#) | Only use the first # of names

Default is all names | `` | Arthur Conan Doyle | | slice(#..#) | Only use entries of the names list starting from # and ending at # (inclusive)

See [Text List Formatter Usage](#Text-List-Formatters) above for details on all the variants of `slice()` | `` | Arthur Conan Doyle | @@ -262,44 +266,36 @@ You can specify which part of a language you are interested in. ### Format Templates -Depending on which property is to be displayed, one or more placeholders can be used in a format template. The placeholders are defined in the form {A} (a single-letter placeholder). For example: +Depending on which property is to be displayed, one or more placeholders can be used in a format template. The placeholders are defined in the form `{A}`: -```text - -``` +`` The format template must sometimes be enclosed in square brackets and sometimes in round brackets. In addition to placeholders, the format template may also contain arbitrary text. To prevent this text from being mistaken for a bracket at the end of the template or a placeholder, escapes can be used within the text: +* `\x` - Escapes the next character. +* `\\` - Escapes a backslash. +* `"text"` - encloses text that may contain special characters. To include a double quote in the text, escape it by doubling it: `"She said ""Hello"""` will output `She said "Hello"`. +* `'text'`- encloses text that may contain special characters. To include a single quote in the text, escape it by doubling it: `'It''s a test'` will output `It's a test`. -* `\x` — Escapes the next character. -* `\\` — Escapes a backslash. -* `"text"` — encloses text that may contain special characters. To include a double quote in the text, escape it by doubling it: `` `"She said ""Hello"""` `` will output `` `She said "Hello"` ``. -* `'text'` — encloses text that may contain special characters. To include a single quote in the text, escape it by doubling it: `` `'It''s a test'` `` will output `` `It's a test` ``. - -```text - -``` +`` Not all elements of a property are always present or have content. In this case, format templates would contain gaps after substitution. Groups of spaces are automatically merged. Other characters, however, remain unchanged. By doubling the curly brackets, you can specify text fragments before and after the placeholder, which are only used if the placeholder is replaced with content. -```text - -``` - -→ `Neil Gaiman, Christopher (Evan) Welch` + +<narrator[format({{F} }{\({M}'\) '}{L})]> ? Neil Gaiman, Christopher (Evan) Welch ### Checks There are two formats for checks, with slightly different syntax for specifying parameters: -`...\<-is\>` +`...<-is>` -`...\<-cmp\>` +`...<-cmp>` For `CHECK-with-value`, the value (2nd parameter) is specified directly after the check operator (e.g., `=`). This may be a number or a string with escaped characters like `\]`. Single backslashes must be doubled if they are part of the string. -`1st-PROPERTY` and `2nd-PROPERTY` may be any of the properties listed in the [Properties](#properties) section, or they +`1st-PROPERTY` and `2nd-PROPERTY` may be any of the properties listed in the [Property tags](#property-tags) section, or they may be string or number literals. Use digits only for numbers. To specify a string literal, enclose it in single or double quotes. If the string contains a single or double quote, escape it by doubling it. For example, to specify the string literal `O'Reilly`, you can use either `'O''Reilly'` or `"O'Reilly"`.