Perfect | Complete | In Progress | Ready | Searching | Missing Files

Project:Style Guide

Boris Ginsburgs, editor.
Jump to navigation Jump to search

Overarching Principles

  1. The goal with source material is to present the texts in as full and close-to-original form as possible while editing and typesetting it consistently and in a modern fashion, facilitating my research by making searching, navigating, and citing (and possibly machine translation) simple.
  2. Source material will generally be corrected to "normal but proper" American English, especially in regards to spelling and punctuation. Word order is not to be changed, with the exception of modernizing table layouts.
    1. Quoted material is presented as is (searches should lead to originals, not quotes/excerpts in another work)
    2. Words that are themselves terms in the Codex should never be edited; REDIRECT pages should be used to point to the unified form.
    3. Words that are of historical interest or dubious meaning should never be edited; the Terminology page can be used for modernizing place names.
  3. The following are authoritative guides, in order, for style, spelling, and usage:
    1. Chicago Manual of Style, 16th edition (with exceptions exist due to goals and presentation)
    2. Merriam-Webster's Unabridged Dictionary (follow main entry)
    3. Oxford English Dictionary (follow primary spelling)
    4. Wikipedia, only if all else fails or as standard for "internet English"

Text Guidelines

Creating New Pages

  1. Use {{subst:SrcNewPage}} (Source materials) or {{subst:SrcNewAuthor}} (Author page) to seed new pages.
    1. For government, law, and official publications, where author is unknown or inapplicable, file by department/branch whatever, abbreviations without periods: Source:USDA, Source:UK Letters Patent, Source:UK Parliament
    2. For court decisions, file under the case name and decision date; e.g., Source:Pidding v. How/1837
  2. Very large documents must be split into child pages of the comprising chapters, and the "top page" presents the table of contents with links and chapter guides, if present; see Source:Ukers/1935

Using Templates

Some items have templates which should always be used to standardize formatting; see templates for instructions.

  1. fractions use Template:frac
  2. Chinese/Japanese characters (kanji) use Template:kanji

Citation Format

A document's citation (in bibliography, long footnote, and short footnote forms) must be included into a Citation: page corresponding to the document. See Help:Chicago for citation formatting.

  1. General
    1. Choose the correct reference type as anal-retentively as possible, even if the citation "looks weird".
    2. Cities, names, etc., should be entered in their wiki standard forms (i.e., conforming to the English Wikipedia's naming conventions).
  2. Author
    1. should be full without being ridiculous (somewhat of a judgment call): Johann Philip Karl Franz von Winkelhofferstein, for example, should probably be Winkelhofferstein, J.P.K.F.v. (horrifying). But up to two names I can handle in full, as in Mozart, Wolfgang Amadeus (using "A." would just look so wrong).
    2. If there is a significant or jarring difference between an author's English and "native" versions, that closest to the heritage of the author in question is to be followed: von Mandelslo, Albert not de Mandelslo, Albert; Linnaeus, Carl, not von Linné, Carl
  3. City of publication should be in English (again, wiki standard).
  4. Title (as printed on the title page; punctuation and case should not be corrected, except that all-uppercase should be capitalized normally) should be entered in full (see Help:Chicago/14/106). Remove appended text that only describes the author (technically a byline), sponsor, etc. Remove "publication features", like "the whole illustrated with copper plates" and crap like that. Remove "add-on" works, such as "to which is appended An essay about something stupid".
  5. The correct Edition and Number of Volumes should be specified.
  6. On true excerpts (extremely small snippets or completely excerpted sections), specific Pages should be noted on the Citation page — do not use "p."! If a volume number is involved, per Chicago, it precedes the pages with a colon and no space: 2:113-115.
  7. Language is not specified.
  8. Chicago specifies use of n.p. for missing fields, but it's disconcerting to the eye. No placeholders for missing publisher, location, date information, etc.

Sections

  1. No matter how an original author may divide the work, use wiki headers starting at level 2 (==) to divide the content intelligently. Exception: Child Pages repeat the excerpt title in a level 2 header, and all subsequent headers are level 3, etc..
  2. Remove indices and marginal notes from documents (these are old data-searching tools and are unnecessary in the wiki), with the exception of chapter "what's in here" headers. These, in very large documents, should be included in the TOC page leading to child page chapters, italicized after the chapter number (see Source:Ball/1848).

TOCs, Indices, Marginal Guides, etc.

  1. TOCs, indices, and other such directional pointers that are now handled by Mediawiki should be omitted entirely, with the exception of very large works divided into Child Pages; in these cases, chapter guides should be included on the top page (the TOC page) to provide some visual reference to the reader.
  2. Marginal guides and other such area signposts tend to be converted to wiki headers.

Blockquotes

  1. No matter how an original author may quote large excerpts (margin quotes, indented paragraphs, bordered boxes), 'translate' those to HTML BLOCKQUOTE tags.
  2. BLOCKQUOTEs are not to be edited into modern English; we don't want any confusion in searching and finding a blockquoted, rather than an original source. Also, it is correct to view the quoted text as the currently-viewed source author saw it, as if they were writing today and quoting an older source in its original language.
  3. Remember that P tags must be used within BLOCKQUOTEs to ensure proper line breaks.

Links

Generally speaking, link everything, but not too much. Every word that any reader could potentially look at and say, "huh?", qualifies for linking. Same for other source documents for ease of research. That said, don't overlink — there's no need for multiple links to the same term within the same paragraph or small section, or maybe even within the same short document.

  1. Codex Links (links to Content)
    1. Links should be included within all body text, references, blockquotes, and table cells, except for:
      1. table header (TH) cells (looks funny with background formatting)
      2. image captions (small text already hard enough to read for these old eyes)
    2. Compound terms of any kind (including those using the word tea), particularly leaf grades or variety names, should be a single link ([[Bohea tea]], not [[Bohea]] [[tea]]). The compound page will direct readers to the appropriate pages using a nice template/subtemplate system breaking down the composite words... someday.
  2. Source Links (links to Sources)
    1. Within the Source: namespace, linking should be as accurate as possible, using 'drill-down' structure. So, if Linnaeus's 1762 publication is specifically cited, then the link should point to Source:Linnaeus/1762; if no publication is specified, then Source:Linnaeus must be used instead; it's inappropriate to "guess" what is being referenced without specific date or page information to confirm.
    2. Within the Main namespace, non-specific citation is not allowed - i.e., citing an author is not acceptable, while citing a specific publication is acceptable. In the long run, the goal is to use some kind of template or templates to pull a Source's citation and use it in the content articles. We'll see how that all works out.

Punctuation

In order to facilitate reading in an online format, punctuation should be edited to modern standards. The goal is "enter text in the form for which it is likely to be searched".

  1. colons and semicolons should abut their text and be followed by single spaces
  2. a colon-em-dash or semicolon-em-dash combination should have no space before or within it, but then be followed by a space
  3. em dashes should be input as — and, unless preceded by another punctuation mark, should be preceded and followed by single spaces
  4. no double whitespaces anywhere
  5. ellipses are normally spaced in Chicago style, but that contradicts this wiki's need to enforce "no space before punctuation" during automated clean-ups; therefore, ellipses should be unspaced (... not . . .). The usual rule, "3 for unfinished, 4 for finished", and capitalization of the following word, applies.

Spelling

Generally, spelling is determined by Merriam-Webster's Unabridged Dictionary, and we hold to their use of "main entry" as the default spelling. If a word cannot be located there, the next authority is the Oxford English Dictionary. A word that cannot be located in either of these should probably be typed as is.

Names and Terms

  1. Proper names, particularly those of people, places, and tea varietals, will be left as originally published, in body text.
    1. The link to a cited author should be the 'edited' version (authors don't use REDIRECTs): [[Source:Linnaeus|Carl von Linné]], not [[Source:von Linné|Carl von Linné]]
    2. Place names are to be verified and included in Terminology if necessary; locations within China are to include coordinates and have a back-index at the foot of the Terminology page.
  2. Ship names will be italicized. If a prefix is used (i.e., USS or HMS) it is not italicized, and does not include periods.

Numbers

We take the alternate rule of Chicago's style guide: whole numbers 1-9 are to be spelled out in words, all others are to be typed out in numerals. Numbers (but not years or codes) should be contained in a {{num}} call, in hopes of localization down the road.

Exceptions: numbers accompanied by symbols or units of measure (percentage, weights, masses, currencies, temperatures, etc.; including "days" "years" etc. when providing specific instructions or measurements of transit, etc.) must be in numerals. Numbers as parts of figures of speech, (e.g., "increased a hundred fold", "several thousand people") to be expressed in words.

one or two times        not 1 or 2 times a year (not specific)
a 3 days journey        not a three days journey (specific measurement)
2 lb.                   not two lb.
133,494                 not 133494
several hundred         not several 100 (general)
millions of people      not 1,000,000s of people (general, figure of speech)
$3,000,000              not three million dollars (specific measurement)
7%                      not seven %

Dates

  1. Enter using {{date|month|day|year}} if the date is of significance. Overlinking is way too easy. A date is:
  2. Centuries should be entered as 1400s, 1500s, etc.; decades should be entered as '90s, '00s, '10s, etc.

Geographic coordinates

  1. Geographic coordinates should be entered using Template:geo.
  2. Proper format of geographic coordinates should be 42°51′36″ N, 112°25′45″ W — but for now do not "convert" coordinates in source documents, as I'm not sure things haven't changed somehow in the history of latitude/longitude. Preserve the original information until sure of the conversion.

Foreign Characters, Phrases

  1. Mediawiki prefers rendered Unicode to HTML characters, so all extended characters must be entered "as is", except for kanji and fractions, which have templates.
  2. Botanical, legal, and other phrases in any foreign language (though primarily Latin and French) must be italicized. This includes abbreviations. Examples: per annum, in situ, i.e. and e.g., etc. (and technically the period should be within the italics).

Footnotes/Endnotes

  1. Footnote text will be edited into modern English, just as body text. No matter how the original author handled notes (symbols, endnotes, etc.), they are 'translated' into the Cite Extension's format: <ref>Footnote text.</ref>
  2. In documents with many references, references should be named. This is also required for back-references.
  3. Back-references, no matter how the original author handled them (ibid., loc. cit., q.v. and so on), are 'translated' extension's format: <ref name="ref1">Citation text.</ref> and <ref name="ref1"/>

Images

  1. Use Template:AddImage for presentation - don't substitute this, I'm still unsure about final presentation!

Image Guidelines

Since the scanner, software, and computer keep changing, it's worth noting down my "standards" for images somewhere so I don't lose them for the umpteenth time.

General Rules

The goal is to render images sufficient for casual research, but in no way to present a reasonable substitute for the original publication, or for easy republication. We are not trying to replace any books; we are trying preserve their information in a useful way while respecting copyright.

  1. Images should be black-and-white unless originally printed in color.
  2. Images should be cropped to the image's smallest natural size:
    1. If image is framed, the frame forms the outer border with no whitespace added.
    2. If image is content-only, trim to image content and then add 5-10% whitespace (based on canvas size). (This really should be standardized in some way.)
  3. Images should be 72dpi resolution, without exception.
  4. Image width should be a standard 800px, 400px, 200px, or 100px if possible. If original is smaller than 100px, a "round number" canvas size is best. Occasionally interesting images may be kept in extra large format (1200px), but this should be done cautiously.

Image Formatting

  1. Straighten skewed image if necessary/desirable.
  2. Crop selection to image, without including any printed text, unnecessary borders, artifacts, etc. Interspersing areas between photos or photo sections should also be selected and deleted to white background.
  3. Set Image Mode to Grayscale (i.e., strip all color information).
  4. Adjust Brightness/Contrast for near-white background and good detail.
    • Current setting is +80% brightness, +40% contrast.
    • Note that this is done before resizing or adjusting resolution.
  5. Adjust image resolution to 72dpi, and then adjust width to a standard size: 800, 400, 200 or 100 pixels.
    • 99% of the time, the correct width is approximately twice the original size after changing resolution.
  6. Save to archive by proper filename; no extra metadata to be saved with file!