diff options
| -rw-r--r-- | EDITING | 132 |
1 files changed, 107 insertions, 25 deletions
@@ -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 |