diff options
Diffstat (limited to 'contributing.md')
| -rw-r--r-- | contributing.md | 55 |
1 files changed, 43 insertions, 12 deletions
diff --git a/contributing.md b/contributing.md index 770d02e..c11c834 100644 --- a/contributing.md +++ b/contributing.md @@ -10,12 +10,17 @@ other document. - Indent using tabs - Wrap long lines at column 80 -- Diacritical marks should be represented in ASCII using LaTeX syntax instead - of using UTF-8 (i.e. `fa\c{c}ade` instead of `façade`) +- ASCII only (LaTeX syntax should be used instead of UTF-8, i.e. `fa\c{c}ade` + instead of `façade`, `---` instead of `—`) - Images should be placed in the img/ folder - Labels and bibliography keys should only consist of characters from the following set: `[a-z0-9:-]` (lower-case, numbers, colon, dash). -- Quotes are opened with the tilde (<code>`</code>) +- Both single and double quotes are opened using backtick(s) + (<code>`</code>) and closed using single quote(s) (`'`), i.e. + <code>``like this''</code> or <code>`this'</code> +- Only environments indent the LaTeX source code +- Insert a non-breaking space (`~`) after (Latin) abbreviations such as "i.e." + or "e.g.". Never place a comma after either of these. # Banned practices @@ -27,7 +32,7 @@ other document. command should be used instead. - **Using `\href`** - Add the source in sources.bib and cite this source instead. + Add the source in [sources.bib](#sources) and cite this source instead. - **Using `\textbf` or `\textit` to emphasize** Use `\emph`, single quotes or an em dash (`---`) instead. @@ -51,21 +56,47 @@ Please use prefixes to 'namespace' `\label`s: |Sections|`sec:`| |List items (i.e. `enumerate`/`itemize`)|`item:`| +These items can be referenced using the `\cref` command. + ## Sources Bibliography entries work with a similar label system (usually called *keys*). Since these exist in a registry separate from `\label` entries, these do not -need to be prefixed. +need to be prefixed. All sources are stored in [sources.bib](./sources.bib). +There is a very helpful [cheat sheet][biblatex-cheat-sheet] online that +showcases different entry types and their fields. -For consistency, the following format is preferred: `authority:topic`. The -`authority` part refers to a company, website or author, and `topic` refers to -a title, chip model number, etc. depending on the type of document being +For consistency, the following format for keys is preferred: `authority:topic`. +The `authority` part refers to a company, website or author, and `topic` refers +to a title, chip model number, etc. depending on the type of document being referenced. -<!-- -TODO -- Cross-references and citations should be handled using cleveref ---> +## Glossary + +Glossary entries are stored in [glossary.bib](./glossary.bib). This file has +the same structure as the bibliography, but with different key types: + +|type|usage| +|-|-| +|`@abbreviation`|Abbreviations (long version inserted on first occurrence)| +|`@acronym`|Acronyms (long version only in glossary)| +|`@entry`|Generic entries / words| + +The keys in the glossary do not have to be prefixed, and should be short as +they should be inserted frequently. Glossary entries can be used with the +following commands: + +|command|usage| +|-|-| +|`\gls{<key>}`|regular| +|`\glspl{<key>}`|plural| +|`\Gls{<key>}`|capitalized (at start of sentence)| +|`\Glspl{<key>}`|capitalized plural| + +> [!NOTE] +> Glossary entries should not be inserted in figure captions or section +> headings! [crepe-engine-contrib]: https://github.com/lonkaars/crepe/blob/master/contributing.md +[biblatex-cheat-sheet]: https://tug.ctan.org/info/biblatex-cheatsheet/biblatex-cheatsheet.pdf |