blob: 9ee52473ce72cf84fbb786ddc45d4c687fc2b822 (
plain)
- # Editing guide
- This is a guide for reliably editing text-heavy documents.
- ## Definitions
- In this guide,
- *"master text"* means an edited document with only semantic markup,
- and *"final document"* means a document with presentational markup.
- An *"author"* is the creator and owner of master texts,
- A *"designer"* is the creator and owner of presentation for master texts.
- An *"editor"* selects and prepares master texts for further processing,
- and is responsible for coherence of content and of its presentation.
- ## Editing
- 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.
- * Use `-` (hyphen-minus) for regular hyphen.
- * Avoid soft-hyphen - i.e. break at end-of-line.
- * Avoid fancy dash or hyphen (difficult to proof-read or process).
- ### Emphasis
- * Surround `*` `*` or `''` `''` (emphasis) in general.
- * Surround `*"` `"*` or `''"` `"''` (emphasis + doublequote) for 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 `<` `>` (angle bracket) for bare URL.
- * Avoid archive URL (except as such: archiveurl keyword in citation).
- * Avoid relative or redirection URL.
- ### Comment or note
- * Surround `[` `]` (square bracket) 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.
- * Surround `'` `'` (singlequote) within citation sections.
- * 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][] `}}` to embed bibliography.
- * Avoid fancy dash (difficult to proof-read or process).
- * Surround `{...}` for proper names in cite title
- * Surround `{...}` for always-lowercase or camelCase words in cite title
- [cite]: https://en.wikipedia.org/wiki/Help:Citation_Style_1
- -- Jonas Smedegaard <dr@jones.dk> Tue, 13 Jan 2015 02:13:31 +0100
|