From aa80bd19d2242636ffb20bb7a384a97e436bd6dc Mon Sep 17 00:00:00 2001
From: Loek Le Blansch <loek@pipeframe.xyz>
Date: Sat, 21 Sep 2024 15:13:38 +0200
Subject: update writing and code style

---
 contributing.md |  2 ++
 style.md        | 61 +++++++++++++++++++++++++++++----------------------------
 2 files changed, 33 insertions(+), 30 deletions(-)

diff --git a/contributing.md b/contributing.md
index db58388..46cfeca 100644
--- a/contributing.md
+++ b/contributing.md
@@ -17,6 +17,8 @@ other document.
 - 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.
+- Multiple references (both `\cref` and `\autocite`) should be done in a single
+  command (i.e. `\cref{fig:a,fig:b}` and `\autocite{source1,source2}`)
 
 # Banned practices
 
diff --git a/style.md b/style.md
index c518e7c..8dca81b 100644
--- a/style.md
+++ b/style.md
@@ -4,6 +4,28 @@ LaTeX commands and LaTeX source style requirements are detailed in
 a number of frequently used snippets that may be used as a cheat-sheet style
 reference.
 
+# General rules
+
+- 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)
+- Section headers should not contain punctuation (e.g. no question marks, "or"
+  instead of a slash, etc.)
+- Quotes are closed before punctuation marks.
+- Do not use contractions, modal adverbs or rhetorical questions.
+
+# References
+
+- Citations are inserted before the full stop at the end of a sentence.
+- 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.
+- Figures from third-party sources must be cited.
+
 # Fonts
 
 The documents use the following fonts. All of these are free and open source,
@@ -27,15 +49,18 @@ workshop and VimTeX.
 [texgyreschola-math]: https://www.gust.org.pl/projects/e-foundry/tg-math/download/index_html#Schola_Math
 [jetbrains-mono]: https://www.jetbrains.com/lp/mono
 
-# Spelling
+# Figures
 
-- 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)
+Non-raster figures are preferred over rasterized figures (where applicable).
+Please note that LaTeX does not support SVG images, and these need to be
+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.
 
-# Grammar
+# Specific rules
 
-## Comma And
+## Comma and
 
 **In lists**, the last element is mentioned using the word 'and', *without* a
 comma.
@@ -50,27 +75,3 @@ consistency.
 >
 > Action X was performed, and this had Y impact.
 
-# Figures
-
-Non-raster figures are preferred over rasterized figures (where applicable).
-Please note that LaTeX does not support SVG images, and these need to be
-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.
-
-- 
cgit v1.2.3