diff options
| -rw-r--r-- | contributing.md | 54 | ||||
| -rw-r--r-- | style.md | 25 | ||||
| -rw-r--r-- | time.txt | 1 |
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>`</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 @@ -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 @@ -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. + @@ -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 |