Writing form

Prefer Markdown unless the community for which the work is written has a strong other preference. Markdown is assumed for the rest of this document.

The raw version of this document is a fairly good example of the principles documented herein.

Wrapping

The rule of thumb is hard wrap at 79 characters. A tool to automate this is recommended (e.g. fmt or Vim’s gq/gw with textwidth=79). No wrapping should be done for the reference of reference-style links (see Links) or link dumps.

Space sentences

Some locales prefer to join sentences with two spaces. We use one space (e.g. Vim’s nojoinspaces).

Quotations and attributions

Use Markdown blockquotes and an em dash-prefixed attribution (encoded as --- and followed by a space), separated by an empty line. If possible make the attribution a link to the original source. Since the attribution is not interspersed in other prose, inline links are permitted.

Example:

> Some quote.

--- Some [author](link).

References:

Text templates

Text templates should be enclosed in Markdown code spans and use (only) one of

  • Literal variables: variable. Preferred when other content consists solely of punctuation.
  • Shell Paramater Expansion: $variable or ${variable}. Preferred when other content includes text and no formatting is required.
  • Python Formatted String Literals: {variable:formatting}. Preferred when other content includes text and formatting is necessary.

Alternative expansion

Use Bash Brace Expansion: {a,b}{,c}d expands to ad, bd, acd, bcd.

In general, a reference to a concept or work should be a link (only) the first time is referenced.

Prefer singular forms, perhaps adding a plural “s” outside of the link ([link][]s). Also prefer to use the target page title or section name verbatim (for Wikipedia, an alternate name that better matches the context is preferable to the canonical name). Some reworking of the enclosing sentence may be needed to make it grammatically correct while conforming to this recommendation.

In order to keep markup to a minimum in flowing text, use, in falling order of preference:

  • Reference style links

    The references should be placed (only) at the end of the first (sub)section that uses the reference.

    The order of the references should be the same as the order they are referenced.

    Do not use URL encoding for the link targets.

    • Implicit reference: [text][], [text]: https://target

    • Explicit reference: [text][reference], [reference]: https://target

  • Inline style links: [text](https://target)

    This is preferable (only) for:

    • Targets that are relative to the current document (note the lowercase, slugified link targets):
      • Sections: [Some section](#some-section).
      • Documents: [Some document](some-document.md).
      • Directories: [`some-dir`](some-dir/).
      • Query strings: [Some query](?some_query) (note the underscore instead of hyphen to better match valid programming language variable names).
    • Link dumps.

  • Automatic links: <https://target>

    Avoid these. Should only be used when the URL in itself is important and in rare cases in link dumps.

See also:

A Markdown list whose entries are all links.

Common examples are “See also” and “References” which can be included either as the last paragraphs of a section or as the last subsection of a section.

Text

For textual works, follow the Chicago style:

Use *-style Markdown emphasis (*work*) for italics.

For programs and other technical works, the text should be a Markdown code span ([`work`][] or [`work`](...)).

Targets

Man pages

Use the man pages at https://www.mankier.com, i.e. link to https://www.mankier.com/$section/$topic#$subsection.

Note that $section can end with a p for the POSIX versions, but prefer the POSIX targets in that case.

Prefer other targets (such as a program website or GNU Manuals) if a man page is not explicitly wanted.

The text should be a code span and include the manual section number (man(1)).

POSIX

The Open Group publishes POSIX.1-2017 online at https://pubs.opengroup.org/onlinepubs/9699919799/.

Shell

There is a POSIX index of the Shell Command Language which links to places of the form https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_{section:02d}_{subsection:02d}.

The sh utility is documented at https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sh.html#tag_20_117_{section:02d}.

Utilities

There is a POSIX index of utilities which links to places of the form https://pubs.opengroup.org/onlinepubs/9699919799/utilities/$utility.html.

GNU

Link to https://www.gnu.org/software/$package if a general overview is wanted. For more technical documentation, see GNU Manuals.

GNU Manuals

Links to manuals can be found on https://www.gnu.org/manual/ and https://www.gnu.org/software/$package/manual.

Use the “HTML” version, i.e. https://www.gnu.org/software/$package/manual/html_node/$section.html. It seems to be preferred by other authors because it is quicker to load and usually easier to navigate.

Note that “HTML - entirely on one web page”, https://www.gnu.org/software/$package/manual/$package.html#$section, may have a more semantic URL but is not preferred for the reasons stated above.

Vim’s :help

Link to the one at https://vimhelp.org, i.e. https://vimhelp.org/$file.txt.html#$section, since it seems to be the most comprehensive at the time of writing with a nice URL. Do not include the :h/:help part in the text if not explicitly wanted. The helplink.vim plugin with the let g:helplink_default_format = 'markdown_nt' setting may help with this.

The Vim FAQ includes “Where can I get the Vim user manual in HTML/PDF/PS format?” where other resources are listed.

See also

TODO

See also