flesh out document style guide

3 files changed, 67 insertions, 13 deletions

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 (<code>&#96</code>)
+- Both single and double quotes are opened using backtick(s)
+  (<code>&#96</code>) and closed using single quote(s) (`'`), i.e.
+  <code>&#96&#96like this''</code> or <code>&#96this'</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
 
@@ -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.
 
-<!--
-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
 
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