Rewrite EDITING.

1 files changed, 107 insertions, 25 deletions

diff --git a/EDITING b/EDITING
index 8d0f6a7..b0e4dff 100644
--- a/EDITING
+++ b/EDITING
@@ -1,25 +1,107 @@
-Wiki editing guideline
-======================
-
-Ideally, text authors should apply only semantic (not visual) markup.
-Unfortunately, Markdown and Mediawiki formats only cover visual markup.
-
-These are suggestions for pseudo-semantic Markdown/Mediawiki markup,
-suitable for post-processing into both web-based and print formats.
-
-  * Use -- (dash dash) for sentence break or parenthetical statement.
-  * Use - (hyphen-minus) for ranges or minus (nothing else).
-  * Use doublequote (") for short quote (e.g. max. 3 lines or 50 words).
-  * Use singlequote (') for short quote within short quote.
-  * Use blockquote (alone) for long quote (nothing else).
-  * Use cite or --- (dash dash dash) after each short or long quote.
-  * Use hyperlink or footnote for non-citation related info.
-  * Use emphasis + doublequote for technical or foreign term.
-  * Use doublequote + emphasis for title.
-  * Use strong emphasis for essential keyword (nothing else).
-  * Use canonical URL (not wikilink or relative URL) in hyperlink.
-  * Use square brackets (not paranthesis) for meta comment.
-  * Use verbatim for code or shell command (nothing else).
-  * Fix or remove visual markup in quoted text (e.g. punctuation abuse).
-
- -- Jonas Smedegaard <dr@jones.dk>  Mon, 15 Dec 2014 15:28:48 +0100
+# Editing guide
+
+This is a guide for reliably editing text-heavy documents.
+
+
+## Works
+
+This guide distinguishes between the following works:
+
+Master text:
+ : document with semantic markup.
+Final document:
+ : document with presentational markup.
+
+
+## Roles
+
+This guide distinguishes between the following roles:
+
+Author:
+ : Write master texts.
+Editor:
+ : Select and prepare master texts for further processing.
+Designer:
+ : Compose visual presentation from master texts.
+
+Each role is distinct.
+Participants may have multiple roles, but only one at a time.
+
+
+## Responsibility
+
+Authors are responsible for master texts they write.
+
+Designers are responsible for visual presentations they compose.
+
+Editors are responsible for coherence of content and its presentation.
+
+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.
+  * Avoid fancy dash or hyphen (difficult to proof-read or process).
+
+### Emphasis
+
+  * 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 `<>` for bare URL.
+
+### Comment or note
+
+  * Surround `[]` (square brackets) 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 }}` ([Citation Style 1][]) to embed bibliography.
+  * Avoid fancy dash (difficult to proof-read or process).
+
+[Citation Style 1]: https://en.wikipedia.org/wiki/Help:Citation_Style_1
+
+ -- Jonas Smedegaard <dr@jones.dk>  Tue, 13 Jan 2015 02:13:31 +0100