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