From eecaf177ea63fe1da21644427f1388428744205d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 9 Sep 2024 14:49:23 +0200 Subject: add glossary + format LaTeX code --- contributing.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index 770d02e..dd51532 100644 --- a/contributing.md +++ b/contributing.md @@ -15,7 +15,8 @@ other document. - 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 (`) +- Quotes are opened with a backtick (`) +- Only environments indent the LaTeX source code # Banned practices -- cgit v1.2.3 From ec881fd9ce58f09e0be598e11c5f5820d8431eda Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 9 Sep 2024 15:19:51 +0200 Subject: flesh out document style guide --- contributing.md | 54 ++++++++++++++++++++++++++++++++++++++++++------------ style.md | 25 ++++++++++++++++++++++++- time.txt | 1 + 3 files changed, 67 insertions(+), 13 deletions(-) (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index dd51532..c11c834 100644 --- a/contributing.md +++ b/contributing.md @@ -10,13 +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 a backtick (`) +- Both single and double quotes are opened using backtick(s) + (`) and closed using single quote(s) (`'`), i.e. + ``like this'' or `this' - 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 @@ -28,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. @@ -52,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. - +## 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{}`|regular| +|`\glspl{}`|plural| +|`\Gls{}`|capitalized (at start of sentence)| +|`\Glspl{}`|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 diff --git a/style.md b/style.md index bbddddf..c518e7c 100644 --- a/style.md +++ b/style.md @@ -1,3 +1,9 @@ +This document contains requirements for all project documentation. Specific +LaTeX commands and LaTeX source style requirements are detailed in +[contributing.md](./contributing.md), and [example.tex](./example.tex) contains +a number of frequently used snippets that may be used as a cheat-sheet style +reference. + # Fonts The documents use the following fonts. All of these are free and open source, @@ -23,7 +29,9 @@ workshop and VimTeX. # Spelling -All documentation is written in U.S. English +- All documentation is written in U.S. English +- Section headers are in sentence case (i.e. only the first word and proper + nouns are capitalized) # Grammar @@ -51,3 +59,18 @@ converted to PDF (e.g. using `svg2pdf` on linux). Raster images should only be used when the source is already in a raster format (e.g. for photos) or when otherwise impractical. +# References + +- When a library or piece of software is introduced in a document, reference + the project homepage using the bibliography. +- Direct quotations or paraphased text must be cited. +- Acronyms, abbreviations and jargon reference the glossary. +- All figures and tables must be referenced in the body text. Don't write + paragraphs that 'lead up' to figures, as this forces LaTeX to not break the + page between the paragraph and figure. + +# Document structure + +- Use `\section`, `\subsection`, `\subsubsection` and `\paragraph` to insert + headings. + diff --git a/time.txt b/time.txt index 5d4cc0a..086197a 100644 --- a/time.txt +++ b/time.txt @@ -13,6 +13,7 @@ loek: 2024-09-05 1h24m time report script loek: 2024-09-06 55m time report script loek: 2024-09-09 30m feedback :: niels code style guide loek: 2024-09-09 45m review :: wouter research PR#5 +loek: 2024-09-09 25m documentation style guide max: 2024-09-02 1h project meeting :: project kickoff max: 2024-09-02 45m project meeting -- cgit v1.2.3