Help:Formatting conventions

From Wikisource
Jump to navigation Jump to search
Formatting conventions

Standard formatting conventions used for proofreading on Wikisource.

The following conventions are considered best practices for pages in the Page: namespace (DjVu, PDF and other files which use the ProofreadPage extension). For general article formatting conventions and guidelines see Wikisource:Style guide.

Running headers[edit]

A scanned page's header and footer often include page number and titles, which are not transcluded. Place this information in the header and footer edit boxes, accessed by clicking the which appears above the edit window, in the Proofread tools section.

The {{RunningHeader}} template is useful for formatting these headers, and is used as follows:

  • {{RunningHeader|left=|center=|right=}}
  • Text in the left, center, or right parameters will appear on the same line.
  • Five-entry style headers, such as those that appear in certain encyclopedias and dictionaries can also be entered with {{RunningHeader}}.

Line breaks[edit]

  • Remove end-of-line hyphens and line breaks.
It was a dark and stormy night, the rain fell in tor-⏎
rents—except at occasional intervals, when it was⏎
checked by a violent gust of wind which⏎
...
It was a dark and stormy night, the rain fell in torrents—except at occasional intervals, when it was checked by a violent gust of wind which...
  • To start a new paragraph, MediaWiki pages use two line breaks (i.e., press return twice and leave one line blank):
...this is the end of one paragraph.

This is the start of the next paragraph...
  • Poetry and other texts presented on a line-by-line basis should have their line breaks preserved. See H:POEM for how to format them.

Hyphenated end of page words[edit]

Shortcut:
H:HYPHEN

  • When a word is hyphenated onto two consecutive pages of the scans, the software will automatically remove the hyphen and join the words together when transcluded into the main namespace.
    First page: Sometimes words are hyphen-
    Second page: ated across page breaks.
    Final result: "Sometimes words are hyphenated across page breaks."
    • Note: Some older works use the templates {{hws}} and {{hwe}}: these are no longer required for newly created pages.
  • If you wish to keep the hyphen (e.g., in the word "over-eager"), use {{peh}} (a.k.a. {{page end hyphen}}) and the software will not remove it:
    First page: Sometimes removal of hyphens is over{{peh}}
    Second page eager: you wish to keep the hyphen.
    Final result: "Sometimes removal of hyphens is over-eager: you wish to keep the hyphen."
  • If a link goes across a page break, use {{lps}} and {{lpe}}. See the documentation of those templates for the various cases that they support.
  • If a hyphenated word is bold or in italics, and the hyphen is not to be kept, put the hyphen outside the bold/italic markup:
    First page: Sometimes hyphenated words are ''ita''-
    Second page: ''lic'' or bold.
    Final result: "Sometimes hyphenated words are italic or bold."

Paragraph ending at the bottom of a page[edit]

Binder's marks[edit]

  • If a binder's mark appears at the bottom of a print page do not reproduce it. These are an artefact of the publishing process for print books. As our works are digital, such marks are not relevant. The marks take various forms, but all indicate the sequence in which printed sections of pages should be bound together.

Templates[edit]

  • Using standard templates instead of other types of markup, gives Wikisource protection from undesirable external changes. e.g., Use {{right}} instead of <p align="right">.
    • If you need to indicate a word/phrase should be in Small Caps, use the {{small-caps}} template.
    • If you need to indicate a word/phrase should be in a smaller (or larger) font, use the {{smaller}} template. Similarly, the {{xx-smaller}}, {{x-smaller}}, {{larger}}, {{x-larger}}, {{xx-larger}}, and {{font-size}} templates can be used to modify text size.

Footnotes[edit]

  • Footnotes in the print version of the book should be implemented using the <ref></ref> and <references/> ( or {{smallrefs}} ) mark up. The {{reflist}} mark-up is for Author and Main namespaces.

Obsolete markup[edit]

Some markup is obsolete in modern HTML and will eventually be removed from browsers and MediaWiki. This is not a MediaWiki or Wikisource decision: the HTML constructs are deprecated by the official web standards body, the W3C.

Generally, there are two kinds of deprecation:

  • Obsolete tags (tags look like <this>) that represent "non-semantic" content and are more correctly done using semantically-meaningful tags and styles via CSS
  • Obsolete attributes on tags (attributes look like <tag attribute=this orthis>) which encode stylistic information that is more correctly implemented in CSS

In some cases, for example, in EPUB exports, such deprecated HTML can cause client problems and the exporter will attempt to strip the problematic code and replace with a best-effort replacement. This does not always work.

Some deprecations that are common, and their resolutions

  • Obsolete HTML tags. Use of these tags triggers linter errors.
    • <center>: use {{center}}
    • <big>: use {{larger}}
    • <small>: use {{smaller}}
    • <font>: use templates like {{blackletter}}, {{red}}, etc., as appropriate
    • <tt>: use {{monospace}}, Alternatively, if it's a supported language, <syntaxhighlight lang="foo" inline=yes>code example</syntaxhighlight>
  • The use of the align attribute is also deprecated and should be replaced with CSS:
    • For table positioning[1]
      • align=center: use style="margin: auto;"
      • align=left/right: use style="margin-right/margin-left: auto;" (the margin is on the "blank" side of the table)
      • align=left/right: use style="float: left/right;" (this allows surrounding content to "flow" around the table)
    • For text alignment (e.g., in table cells)[2]:
      • align=left/center/right: use style="text-align: left/center/right;"
  • The use of the valign attribute should be replaced with CSS[3]:
    • valign=topvertical-align: top;
    • valign=middlevertical-align: middle;
    • valign=bottomvertical-align: bottom;
  • All other table-specific attributes on tables are deprecated [4]:
    • width: use CSS width
    • frame: use CSS border
    • cellpadding: use CSS padding on the cells, and set border-collapse: collapse
    • cellspacing: use CSS border-spacing and do not border-collapse (both apply to the table, not the cells)
    • bgcolor: use CSS background-color

If there are a lot of similar rows (such as a work with numerous tables showing numerical statistical data), consider creating specfic CSS for that work, which should be placed as an Indexstyle for that work.

Tagging[edit]

Some, but not all, deprecations are automatically tagged by an edit filter. If your edits are so tagged, you may wish to adjust the content to avoid a deprecated construction. You do not have to do so, but it will avoid creating a backlog if/when such deprecations cause technical issues in the future. Recent changes with this tag can be seen here. Sometimes, your edits may be tagged not because of your contributions, but because of pre-existing deprecated markup.

Notes[edit]

  1. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#attr-align
  2. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td#attr-align
  3. in tables, in table cells
  4. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#attributes