# Editing guide

This is a guide for reliably editing text-heavy documents.


## Definitions

In this guide,
*"master text"* means an edited document with only semantic markup,
and *"final document"* means a document with presentational markup.

An *"author"* is the creator and owner of master texts,

A *"designer"* is the creator and owner of presentation for master texts.

An *"editor"* selects and prepares master texts for further processing,
and is responsible for coherence of content and of its presentation.

## Editing

Authors and editors may refine markup in quotations
(e.g. replace "ASCII art" styling of lists with semantic equivalent),
while preserving their verbatim representation.

Editors may fix typos and wrong or weak markup of master texts,
while preserving their communication style.


## Editing markup

Editing markup serves 2 purposes:

  * Allow designer to recognize semantics of master text.
  * Allow (author and) editor to proof-read and refine master text.

Consequently, editing markup should be semantic and unambiguous.

In particular, do *not* trust visual presentation in authoring tools.


## Wiki-like editing markup

Editing markup suitable for Markdown or Mediawiki.

Below syntaxes may not be used for any other semantic purpose.

### Dash

  * Use `--` (hyphen-minus x 2) for sentence break or parenthetical statement.
  * Use `-` (hyphen-minus) for ranges or minus.
  * Use `-` (hyphen-minus) for regular hyphen.
  * Avoid soft-hyphen - i.e. break at end-of-line.
  * Avoid fancy dash or hyphen (difficult to proof-read or process).

### Emphasis

  * Surround `*` `*` or `''` `''` (emphasis) in general.
  * Surround `*"` `"*` or `''"` `"''` (emphasis + doublequote) for technical or foreign term.
  * Surround `"*` `*"` or `"''` `''"` (doublequote + emphasis) for title.
  * Surround `**` `**` or `'''` `'''` (strong emphasis) for essential keyword.

### Links

  * Use canonical URL (not relative, wiki-URL, redirection or backup).
  * Surround `<` `>` (angle bracket) for bare URL.
  * Avoid archive URL (except as such: archiveurl keyword in citation).
  * Avoid relative or redirection URL.

### Comment or note

  * Surround `[` `]` (square bracket) for meta comment.
  * Surround `[^`[note][] `]` or `<`[ref][] `>` for foot-/end-/sidenote.

[note]: http://johnmacfarlane.net/pandoc/README.html#footnotes
[ref]: https://meta.wikimedia.org/wiki/Help:Footnotes

### Quotation

  * Surround `"` `"` (doublequote) in general.
  * Use `<blockquote>` for full paragraph or when crossing paragraphs.
  * Surround `'` `'` (singlequote) within another `"`-surrounded quote.
  * Use `[...]` (dot x 3 in square brackets) to indicate skipped chunk.
  * Append citation immediately after each quote.
  * Avoid curly quotes (difficult to proof-read or process).

### Citation

  * Prepend `---` (hyphen-minus x 3) on separate line for simple citation.
  * Use `{{`[cite][] `}}` to embed bibliography.
  * Avoid fancy dash (difficult to proof-read or process).

[cite]: https://en.wikipedia.org/wiki/Help:Citation_Style_1

 -- Jonas Smedegaard <dr@jones.dk>  Tue, 13 Jan 2015 02:13:31 +0100