summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJonas Smedegaard <dr@jones.dk>2015-01-13 02:13:52 +0100
committerJonas Smedegaard <dr@jones.dk>2015-01-13 02:13:52 +0100
commit4e4ee1a4ff270e52f11ccfd2270df7098005a845 (patch)
tree6064a9985aa3b816aff37364d81e5e5a5413d2e3
parent4bc43678e9b3311b0b6b4b7f7a77a91c3ca346ac (diff)
Rewrite EDITING.
-rw-r--r--EDITING132
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