diff options
| author | Robin Jarry <robin@jarry.cc> | 2022-11-22 20:39:21 +0100 |
|---|---|---|
| committer | Robin Jarry <robin@jarry.cc> | 2022-11-24 19:19:10 +0100 |
| commit | af63bd0188d13ecf00628c30f88d0ee06c07e500 (patch) | |
| tree | fe5bc06823aa372fbc209d8dea9cbce05a63e03e /CONTRIBUTING.md | |
| parent | fa294ef76fa015c090d1543630b147f2dca0b49a (diff) | |
| download | aerc-af63bd0188d13ecf00628c30f88d0ee06c07e500.tar.gz | |
doc: homogenize scdoc markup
For consistent rendering, it is best if every man page uses the same
conventions. These are completely arbitrary and I only did some trial
& error until I found something that looked visually OK.
Update CONTRIBUTING.md with guidelines for scdoc markup conventions.
Update all man pages according to these guidelines.
Suggested-by: Inwit <inwit@sindominio.net>
Signed-off-by: Robin Jarry <robin@jarry.cc>
Acked-by: Koni Marti <koni.marti@gmail.com>
Acked-by: Inwit <inwit@sindominio.net>
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 27 |
1 files changed, 27 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a291ee3d..4b93682f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -240,6 +240,32 @@ by running `make fmt`. If gofumpt accepts your code it's most likely properly formatted. +### Man pages + +All `doc/*.scd` files are written in the [scdoc][scdoc] format and compiled to +man pages. + +For consistent rendering, please respect the following guidelines: + +- use `*:command*` to reference commands +- use `*-x*` for flags +- use `_<arg>_` argument placeholders that must be replaced by a suitable value +- use `_foobar.conf_` for file paths +- use `_true_`, `_0_`, `_constant_` for literal constants that must be typed as is +- use `[*-x*]` or `[_<arg>_]` for optional flags/arguments +- use `*-x*|*-y*` for mutually exclusive flags/arguments +- use `*[section]*` to reference sections in configuration files +- use `*foo*` or `*[section].foo*` to reference settings +- if an option does **not** have a default value, simply omit it +- use `*FOO*` and `*$FOO*` for environment variables +- only use `_"quoted values"_` when white space matters +- put command alternatives/aliases on separate lines with `++` suffixes +- use `*<c-x>*` or `*<enter>*` to reference key strokes +- use `# UPPER CASE` for man page sections +- use `*aerc-config*(5)` to reference other man pages +- use `aerc` (instead of `*aerc*` or `_aerc_`) to reference the aerc project or + the aerc program + [git-send-email-tutorial]: https://git-send-email.io/ [git-trailers]: https://git.wiki.kernel.org/index.php/CommitMessageConventions [godoc-comments]: https://go.dev/blog/godoc @@ -247,3 +273,4 @@ If gofumpt accepts your code it's most likely properly formatted. [linux-coding-style]: https://www.kernel.org/doc/html/v5.19-rc8/process/coding-style.html [linux-review]: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes [linux-signoff]: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin +[scdoc]: https://git.sr.ht/~sircmpwn/scdoc |