summaryrefslogtreecommitdiff
path: root/EDITING
blob: adc5532d2a10d32a800e86cfb4058ff7b43a7193 (plain)
  1. # Editing guide
  2. This is a guide for reliably editing text-heavy documents.
  3. ## Definitions
  4. In this guide,
  5. *"master text"* means an edited document with only semantic markup,
  6. and *"final document"* means a document with presentational markup.
  7. An *"author"* is the creator and owner of master texts,
  8. A *"designer"* is the creator and owner of presentation for master texts.
  9. An *"editor"* selects and prepares master texts for further processing,
  10. and is responsible for coherence of content and of its presentation.
  11. ## Editing
  12. Authors and editors may refine markup in quotations
  13. (e.g. replace "ASCII art" styling of lists with semantic equivalent),
  14. while preserving their verbatim representation.
  15. Editors may fix typos and wrong or weak markup of master texts,
  16. while preserving their communication style.
  17. ## Editing markup
  18. Editing markup serves 2 purposes:
  19.   * Allow designer to recognize semantics of master text.
  20.   * Allow (author and) editor to proof-read and refine master text.
  21. Consequently, editing markup should be semantic and unambiguous.
  22. In particular, do *not* trust visual presentation in authoring tools.
  23. ## Wiki-like editing markup
  24. Editing markup suitable for Markdown or Mediawiki.
  25. Below syntaxes may not be used for any other semantic purpose.
  26. ### Dash
  27.   * Use `--` (hyphen-minus x 2) for sentence break or parenthetical statement.
  28.   * Use `-` (hyphen-minus) for ranges or minus.
  29.   * Use `-` (hyphen-minus) for regular hyphen.
  30.   * Avoid soft-hyphen - i.e. break at end-of-line.
  31.   * Avoid fancy dash or hyphen (difficult to proof-read or process).
  32. ### Emphasis
  33.   * Surround `*` `*` or `''` `''` (emphasis) in general.
  34.   * Surround `*"` `"*` or `''"` `"''` (emphasis + doublequote) for foreign term.
  35.   * Surround `"*` `*"` or `"''` `''"` (doublequote + emphasis) for title.
  36.   * Surround `**` `**` or `'''` `'''` (strong emphasis) for essential keyword.
  37. ### Links
  38.   * Use canonical URL (not relative, wiki-URL, redirection or backup).
  39.   * Surround `<` `>` (angle bracket) for bare URL.
  40.   * Avoid archive URL (except as such: archiveurl keyword in citation).
  41.   * Avoid relative or redirection URL.
  42. ### Comment or note
  43.   * Surround `[` `]` (square bracket) for meta comment.
  44.   * Surround `[^`[note][] `]` or `<`[ref][] `>` for foot-/end-/sidenote.
  45. [note]: http://johnmacfarlane.net/pandoc/README.html#footnotes
  46. [ref]: https://meta.wikimedia.org/wiki/Help:Footnotes
  47. ### Quotation
  48.   * Surround `"` `"` (doublequote) in general.
  49.   * Use `<blockquote>` for full paragraph or when crossing paragraphs.
  50.   * Surround `'` `'` (singlequote) within another `"`-surrounded quote.
  51.   * Surround `'` `'` (singlequote) within citation sections.
  52.   * Use `[...]` (dot x 3 in square brackets) to indicate skipped chunk.
  53.   * Append citation immediately after each quote.
  54.   * Avoid curly quotes (difficult to proof-read or process).
  55. ### Citation
  56.   * Prepend `---` (hyphen-minus x 3) on separate line for simple citation.
  57.   * Use `{{`[cite][] `}}` to embed bibliography.
  58.   * Avoid fancy dash (difficult to proof-read or process).
  59. [cite]: https://en.wikipedia.org/wiki/Help:Citation_Style_1
  60.  -- Jonas Smedegaard <dr@jones.dk>  Tue, 13 Jan 2015 02:13:31 +0100