diff --git a/config/apache/standardebooks.org.conf b/config/apache/standardebooks.org.conf index 2c110b35..890f64ab 100644 --- a/config/apache/standardebooks.org.conf +++ b/config/apache/standardebooks.org.conf @@ -165,6 +165,9 @@ Define domain standardebooks.org # Favicon rewrites RewriteRule ^/(apple-touch|android-chrome|favicon|mstile|safari-pinned|browserconfig|manifest)([^/]+)$ /images/favicons/$1$2 [L] + # Redirect latest version of the manual + RewriteRule ^/manual/latest(.*) /manual/index.php?url=$1 [L] + # List of specific URL rewrites RewriteRule ^/ebooks/aristotle/the-nicomachean-ethics(.+)$ /ebooks/aristotle/nicomachean-ethics$1 [R=301,L] RewriteRule ^/ebooks/sir-arthur-conan-doyle(.+)$ /ebooks/arthur-conan-doyle$1 [R=301,L] diff --git a/config/apache/standardebooks.test.conf b/config/apache/standardebooks.test.conf index 63d64c7e..14331f75 100644 --- a/config/apache/standardebooks.test.conf +++ b/config/apache/standardebooks.test.conf @@ -164,6 +164,9 @@ Define domain standardebooks.test # Favicon rewrites RewriteRule ^/(apple-touch|android-chrome|favicon|mstile|safari-pinned|browserconfig|manifest)([^/]+)$ /images/favicons/$1$2 [L] + # Redirect latest version of the manual + RewriteRule ^/manual/latest(.*) /manual/index.php?url=$1 [L] + # List of specific URL rewrites RewriteRule ^/ebooks/aristotle/the-nicomachean-ethics(.+)$ /ebooks/aristotle/nicomachean-ethics$1 [R=301,L] RewriteRule ^/ebooks/sir-arthur-conan-doyle(.+)$ /ebooks/arthur-conan-doyle$1 [R=301,L] diff --git a/templates/Header.php b/templates/Header.php index 2f88c28d..793a7ab1 100644 --- a/templates/Header.php +++ b/templates/Header.php @@ -16,10 +16,6 @@ if(!isset($manual)){ $manual = false; } -if(!isset($js)){ - $js = false; -} - ?> @@ -40,11 +36,6 @@ if(!isset($js)){ - - - - - diff --git a/www/contribute/a-basic-standard-ebooks-source-folder.php b/www/contribute/a-basic-standard-ebooks-source-folder.php index 9b768743..7ed0a34a 100644 --- a/www/contribute/a-basic-standard-ebooks-source-folder.php +++ b/www/contribute/a-basic-standard-ebooks-source-folder.php @@ -1,6 +1,6 @@ 'A Basic Standard Ebooks Source Folder', 'highlight' => 'contribute', 'description' => 'All Standard Ebooks source folders have the same basic structure, described here.']) ?> +?> 'A Basic Standard Ebooks Source Folder', 'manual' => true, 'highlight' => 'contribute', 'description' => 'All Standard Ebooks source folders have the same basic structure, described here.']) ?>

A Basic Standard Ebooks Source Folder

diff --git a/www/contribute/art.php b/www/contribute/art.php deleted file mode 100644 index c571d92c..00000000 --- a/www/contribute/art.php +++ /dev/null @@ -1,569 +0,0 @@ - 'Art Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Art Manual, containing details on cover and titlepage images, cover art requirements, and public domain research requirements and tips.']) ?> -
-
-

Art Manual

- -
-

General notes

-
    -
  • -

    When you create a new Standard Ebooks draft using se create-draft, you’ll already have templates for the cover and titlepage images present in DRAFT-ROOT/images/. The text in the SVG files is represented as text, not paths, so you can edit them using a text editor and not an SVG editor. Then, se build-images converts these text-based source images into path-based compiled images, for distribution in the final epub file. We do this so to avoid having to distribute the font files along with the epub.

    -
    • -
  • -

    To develop cover and titlepage images, you must have the free League Spartan and Sorts Mill Goudy fonts installed on your system.

    -
    • -
-
-
-

Complete list of files

-

A complete set of image source files consists of:

-
    -
  • -

    DRAFT-ROOT/images/cover.source.jpg: The full source image used for the cover art, in as high a resolution as possible. Can be of any image format, but typically we end up with JPGs.

    -
    • -
  • -

    DRAFT-ROOT/images/cover.jpg: A cropped part of the source image that will serve as the actual image file we use in the cover. Must be exactly 1400w × 2100h.

    -
    • -
  • -

    DRAFT-ROOT/images/cover.svg: The SVG source file for the cover, with any text represented as actual, editable text. Must be exactly 1400w × 2100h pixels. Since the final cover image SVG has the text converted to paths, we keep this file around to make it easier to make changes to the cover in the future.

    -
    • -
  • -

    DRAFT-ROOT/src/epub/images/cover.svg: The final SVG cover image. This image should be exactly like DRAFT-ROOT/images/cover.svg, but with the text converted to paths.

    -

    This image is generated by se build-images.

    -
    • -
  • -

    DRAFT-ROOT/images/titlepage.svg: The SVG source file for the titlepage, with any text represented as actual, editable text. Must be exactly 1400 pixels wide, but the height must exactly match the text height plus some padding (described below).

    -
    • -
  • -

    DRAFT-ROOT/src/epub/images/titlepage.svg: The final SVG titlepage image, with text converted to paths just like the cover page.

    -

    This image is generated by se build-images.

    -
    • -
-
-
-

The cover image

- -

There are three cover image templates available to you based on how long the ebook’s title is. create-draft tries to guess which one to use, but it may not be correct. If your novel title is too long to fit in the template create-draft picked for you, you can try a different cover image template. They’re located in the Standard Ebooks toolset TOOLSET-ROOT/se/data/templates/ folder.

-

To edit DRAFT-ROOT/images/cover.svg, simply open it with your favorite text editor. Replace “NOVEL” with your novel’s title and “AUTHOR” with the author.

-

Only use a text editor to edit cover.svg, not an SVG editing program like Inkscape. SVG editors like Inkscape often reformat SVGs and insert all sorts of useless metadata.

-

You must have the free League Spartan font installed on your system for the cover to render and build correctly.

-

Cover image SVG rules

-
    -
  • -

    Both the title and author are in League Spartan font with 5px letter spacing in ALL CAPS.

    -
    • -
  • -

    The left and right sides of the black title box must have at least 40px padding. More padding is preferrable over cramming the title in.

    -
    • -
  • -

    For the title lines:

    -
      -
    • -

      One-line titles: the line is 80px tall. Example.

      -
      • -
    • -

      Two-line titles: each line is 80px tall, and the second title line is 20px below the first line. Example.

      -
      • -
    • -

      Two-line, very long titles: each line is 60px tall, and the second line is 20px below the first line. Example.

      -
      • -
    • -

      Two-line, extremely long titles: each line is 50px tall, and the second line is 20px below the first line. Example.

      -
      • -
    -
    • -
  • -

    For the author lines:

    -
      -
    • -

      The first author line begins 60px below the last title line.

      -
      • -
    • -

      One-line authors: the line is 40px tall.

      -
      • -
    • -

      Two-line authors: each line is 40px tall, and the second author line is 20px below the first line.

      -
      • -
    -
    • -
  • -

    Once the author and title lines are the correct distance from each other, the group of both should be horizontally centered in the black title box.

    -
    • -
  • -

    cover.svg uses cover.jpg as the canvas background.

    -
    • -
  • -

    cover.jpg is exactly 1400w × 2100h pixels, and should be compressed to be no larger than one megabyte. This might not always be possible while maintining an acceptable level of image quality, but keeping the file size of cover.jpg as small as possible is desirable.

    -
    • -
  • -

    Because cover.jpg is a large image, you should source it from a high-quality scan. This might not always be possible, so it’s allowed to upscale the source image a small amount. But, for example, don’t use a 300w × 500h image as a source; that wouldn’t scale up well.

    -
    • -
-

Cover image artwork rules

-

Once you’ve set up cover.svg, it’s time to find a suitable fine art painting to use for the cover image.

-

The paintings we use are all in the U.S. public domain (PD). Your task is to locate a painting suitable for the kind of book you’re producing, and then demonstrate that the painting is indeed in the U.S. public domain.

-

U.S. copyright law is complicated. Because of this, we require that you provide a link to a page scan of a 1924-or-older book that reproduces the painting you selected. This is a hard requirement to demonstrate that the painting you selected is in fact in the U.S. public domain. Just because a painting is very old, or Wikipedia says it’s PD, or it’s PD in a country besides the U.S., doesn’t necessarily mean it actually is PD in the U.S.

-

The painting you select must be a fine-art oil painting. We require this to maintain a consistency in the overall style of all of our covers.

-

Tips for location 1924-or-older reproductions of cover art

-

To actually demonstrate that a painting is PD, you must locate a reproduction of that painting in a 1924-or-older book.

-

This can be quite difficult. Many people find this to be the most time-consuming part of the ebook production process.

-

Because of the difficulty, finding suitable cover at is all about compromise. You’re unlikely to find the perfect cover image. You’ll find a lot of paintings that would be great matches, but that you can’t find reproductions of and thus we can’t use. So, be ready to compromise.

-

General tips

-
    -
  • -

    Before you can go looking for a reproduction of a specific painting to prove its PD status, you have to find a suitable painting to begin with. Wikiart.org is a great resource to search paintings by keyword. Museum online collections are another good place to look for inspiration. Once you find a potential candidate, then you can start researching its PD status.

    -
    • -
  • -

    When searching for cover art, remember that artist names and painting titles may be spelled in many different ways. Often a painting went by multiple titles, or if the title was not in English, by many different translations. Your best bet is to simply search for an artist’s last name, and not the painting title.

    -
    • -
  • -

    Once you locate a book with reproductions, open the book up in thumbnail view and quickly eyeball the pages to see if the artwork is reproduced there.

    -
    • -
  • -

    Note that if your IP address is not in the U.S., many book archives like Google Books and HathiTrust may disable book previews.

    -
    • -
  • -

    Many museum online catalogs have a “bibliography” or “references” section for each painting in their collection. This is usually a list of books in which the painting was either mentioned or reproduced. This is a good shortcut to finding the names of books in which a painting was reproduced, and if you’re lucky, a search for the book title in Google Books will turn up scans.

    -
    • -
  • -

    In cover.svg, the black title and author box always goes in the lower half of the work. Thus, paintings in which some important detail would be obscured by the box cannot be used.

    -
    • -
-

Gotchas

-
    -
  • -

    Sometimes the catalog record for a book has an incorrect publication year. Please verify the page scan of the copyright page to ensure the book is 1924 or older.

    -
    • -
  • -

    In older books it was common to have etchings of paintings. Etchings are not strict reproductions, and so we cannot count them when researching PD status.

    -
    • -
  • -

    Oftentimes painters would produce several different versions of the same artwork. You must carefully compare the reproduction in the page scan with the high-resolution artwork scan you found to ensure they are the same painting. Small details like the position of trees, clouds, reflections, or water are good ways to check if the painting is identical, or if you’re looking at a different version.

    -
    • -
-

PD research step-by-step

-
    -
  1. -

    Your first stop should be Google Books. Google Books allows you to filter results so that you only see 1924-or-older books. You can use this shortcut to search Google Books for 1924-or-older books.

    -

    Google Books is a convenient first stop because its thumbnail view is very fast, and it does a better job of highlighting search results than HathiTrust or Internet Archive.

    -
    2. -
  2. -

    If you can’t find anything on Google Books, next go to HathiTrust. HathiTrust’s thumbnail view is much slower, but it has a different catalog than Google Books does. You can use this shortcut to search HathiTrust for 1924-or-older books.

    -
    3. -
  3. -

    Lastly, try the Internet Archive. IA has a similar catalog as Google Books, but you may still find something there. You can use this shortcut to search the Internet Archive for 1924-or-older books.

    -
    4. -
  4. -

    Once you’ve found a reproduction of your artwork in a 1924-or-older book, you need to find a high-resolution color scan that we can use for the cover. Various museum sites can be good for this, along with Wikimedia Commons, Google Art Project, and Wikiart.org.

    -
    5. -
-

PD research resources

-

Evan Hall has begun compiling a spreadsheet of artwork for use in our ebooks. You can view it here.

-

You may find these resources helpful in your PD research:

- -

Cover art FAQs

-
    -
  • -

    I found a great painting, and Wikipedia says it’s public domain, but I can’t find a reproduction in a book. Can I use it?

    -

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    -
    • -
  • -

    I found a great painting, and it’s really old, and the author died a long time ago, but I can’t find a reproduction in a book. Can I use it?

    -

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    -
    • -
  • -

    I’ve found a reproduction in a book, but the book was published in 1924. Is that OK?

    -

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    -
    • -
  • -

    I’ve found a scan on a museum site. Is that OK?

    -

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    -
    • -
  • -

    But...

    -

    No. You must find a reproduction of your selected painting in a book published in 1924 or earlier.

    -
    • -
-

Museums with explicit CC0 collections

-

Images that are explicitly marked as CC0 from these museums can be used without further research. Not all of their images are CC0, you must confirm the presence of a CC0 license on the specific image you want to use.

-
    -
  • -

    Rijksmuseum (Open the "Object Data" section and check they "Copyright" entry under the "Acquisition and right" section to confirm CC0)

    -
    • -
  • -

    Finnish National Gallery via Europeana (Use the "View at" link under the "Find out more" header to confirm CC0 license at the museum's site)

    -
    • -
  • -

    Met Museum (CC0 items have the CC0 logo under the image)

    -
    • -
  • -

    National Museum Sweden (CC-PD items have the CC-PD mark in the lower left of the item's detail view)

    -
    • -
  • -

    The Walters Art Museum (Public domain items are listed as "CC Creative Commons License" which links to a CC0 rights page)

    • -
  • -

    Art Institute of Chicago (CC0 items say CC0 in the lower left of the painting in the art detail page)

    -
    • -
  • -

    Cleveland Museum of Art (CC0 items have the CC0 logo near the download button.)

    -
    • -
  • -

    Paris Musées (CC0 items have the CC0 logo near the download button.)

    -
    • -
  • -

    The Smithsonian (CC0 items say CC0 under the Usage header in the item details.)

    -
    • -
  • -

    Birmingham Museums (CC0 items say CC0 in the Usage Rights section.)

    -
    • -
-

Cover image step-by-step

-
    -
  1. -

    Locate an appropriate high-resolution public domain work to use as the cover image background. Name this unchanged file DRAFT-ROOT/images/cover.source.jpg (or .png, or .bmp, or whatever the original file format is).

    -
    2. -
  2. -

    Crop or scale the source image to create a 1400w × 2100h image that will be the actual cover background. Name this file DRAFT-ROOT/images/cover.jpg and save it at 75% compression (if that looks good enough).

    -
    3. -
  3. -

    If you used se create-draft to initialize your repository, then DRAFT-ROOT/images/cover.svg is initialized with the work title and author and what should be the correct font size. If not, copy the cover image template from TOOLSET-ROOT/se/data/templates/cover.svg into the same directory as cover.jpg. Open your working copy of DRAFT-ROOT/images/cover.svg with a text editor and edit the work name and author, and remove any unused template CSS.

    -
    4. -
  4. -

    Finally, generate DRAFT-ROOT/src/epub/images/cover.svg by running se build-images. (This script also generates the titlepage images, if available.)

    -
    5. -
-
-
-

The titlepage image

-

create-draft creates a titlepage image template for you that is correctly sized and arranged, and no more editing should be necessary. If you prefer to create one by hand, here are the various requirements for titlepage images.

-

To edit DRAFT-ROOT/images/titlepage.svg, simply open it with your favorite text editor.

-

Only use a text editor to edit cover.svg, not an SVG editing program like Inkscape. SVG editors like Inkscape often reformat SVGs and insert all sorts of useless metadata.

-

You must have the free League Spartan and Sorts Mill Goudy Italic font installed on your system for the titlepage to render and build correctly.

-

Titlepage image SVG rules

-
    -
  • -

    The title, author, and the names of other contributors are in League Spartan font with 5px letter spacing in ALL CAPS.

    -
    • -
  • -

    Do not include subtitles in the titlepage. For example, the titlepage would contain “THE MAN WHO WAS THURSDAY”, but not “THE MAN WHO WAS THURSDAY: A NIGHTMARE”.

    -
    • -
  • -

    If there are other contributors besides the author (for example a translator or illustrator), their names are preceded by “translated by” or “illustrated by”, set in lowercase Sorts Mill Goudy Italic font.

    -
    • -
  • -

    Only include the author, translator, and illustrator on the titlepage. Do not include other contributors like writers of introductions or annotators.

    -
    • -
  • -

    The titlepage canvas must have a padding of 50px vertically and 100px horizontally. Text must not enter the padding area.

    -
    • -
  • -

    The titlepage viewbox width must be exactly 1400px wide.

    -
    • -
  • -

    The titlepage viewbox height must precisely fit the titlepage contents, plus 50px padding. Don’t simply edit the template titlepage and leave the viewbox the same; you must customize the viewbox to fit. You can do this by either copying-and-pasting a viewbox from a completed Standard Ebooks ebook that has the same dimensions as yours, or by doing some simple math to calculate the correct height.

    -
    • -
  • -

    Title lines:

    -
      -
    • -

      Title lines are each 80px tall.

      -
      • -
    • -

      You may split the title into as many lines as necessary to fit.

      -
      • -
    • -

      Title lines are separated by a 20px margin between each line.

      -
      • -
    -
    • -
  • -

    Author lines:

    -
      -
    • -

      The first author line begins 100px below the last title line.

      -
      • -
    • -

      Each author line is 60px tall.

      -
      • -
    • -

      If an author line must be split, the next line begins 20px below the previous one.

      -
      • -
    • -

      For works with multiple authors, subsequent author lines begin 20px below the last author line.

      -
      • -
    -
    • -
  • -

    Contributor lines (like translator, illustrator):

    -
      -
    • -

      Contributors are both a “contributor descriptor”, like “translated by”, followed by the name on a new line.

      -
      • -
    • -

      The first contributor descriptor line begins 150px below the last author line.

      -
      • -
    • -

      Contributor descriptor lines are 40px tall, all lowercase, in the Sorts Mill Goudy Italic font.

      -
      • -
    • -

      The contributor name begins 20px below the contributor descriptor line.

      -
      • -
    • -

      The contributor name is 40px tall, ALL CAPS, in the League Spartan font.

      -
      • -
    • -

      If there is more than one contributor of the same type (like multiple translators), they are listed on one line. If there are two, separate them with AND. If there are more than two, separate them with commas, and AND after the final comma. Example.

      -
    • -

      If there is more than one contributor type (like both a translator and an illustrator), the next contributor descriptor begins 80px after the last contributor name.

      -
      • -
    -
    • -
-

Titlepage diagram

-
- Spacing in a Standard Ebooks titlepage image -
- -
-
-
- diff --git a/www/contribute/index.php b/www/contribute/index.php index a9c2fa61..5af7b9e9 100644 --- a/www/contribute/index.php +++ b/www/contribute/index.php @@ -26,7 +26,7 @@ require_once('Core.php');
-

Editors and readers of existing ebooks

+

Readers of existing ebooks

@@ -55,29 +55,17 @@ require_once('Core.php');

A technical step-by-step guide to producing a new ebook, from start to finish.

  • -

    The Standard Ebooks Typography Manual.

    -
    • -
  • -

    The Standard Ebooks XHTML Structure and Semantics Manual.

    -
    • -
  • -

    The Standard Ebooks Metadata Manual.

    -
    • -
  • -

    The Standard Ebooks Art Manual for cover art and titlepages.

    +

    The Standard Ebooks Manual of Style.

  • Descriptions of the files in a fresh Standard Ebooks source folder.

  • -

    Guidelines for contributing to the Standard Ebooks toolset.

    +

    The Standard Ebooks toolset on GitHub.

  • All Standard Ebooks ebook source files on GitHub.

    • -
  • -

    The Standard Ebooks toolset on GitHub.

    -
    • diff --git a/www/contribute/manual.php b/www/contribute/manual.php deleted file mode 100644 index e8e03650..00000000 --- a/www/contribute/manual.php +++ /dev/null @@ -1,808 +0,0 @@ - 'Style Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The working draft of the new Standard Ebooks Style Manual.']) ?> -
    -
    -

    Style Manual

    - - -

    Table of Contents

    -

    Coming soon...

    - -
    -

    XHTML and CSS code formatting style

    -

    The clean tool in the Standard Ebooks toolset formats XHTML code according to our style guidelines. The vast majority of the time its output is correct and no further modifications to code style are necessary.

    -
    -

    XHTML formatting

    -
      -
    1. -

      The first line of all XHTML files is:

      -
      - <?xml version="1.0" encoding="utf-8"?> -
      -
      2. -
    2. -

      The second line of all XHTML files is (replace LANG with the appropriate language tag for the file):

      -
      - <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="LANG"> -
      -
      3. -
    3. -

      Tabs are used for indentation.

      -
      4. -
    4. -

      Tag names are lowercase.

      -
      5. -
    5. -

      Tags whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content.

      -
      - <p> -It was a dark and stormy night... -</p> -
      -
      - <p>It was a dark and stormy night...</p> -
      -
      6. -
    -
    -

    Attributes

    -
      -
    1. -

      Attributes are in alphabetical order.

      -
      2. -
    2. -

      Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags, where subtags are capitalized.

      -
      - <section EPUB:TYPE="CHAPTER" XML:LANG="EN-US">...</section> -
      -
      - <section epub:type="chapter" xml:lang="en-US">...</section> -
      -
      3. -
    3. -

      The string utf-8 is lowercase.

      -
      4. -
    -
    -
    -
    -

    CSS formatting

    -
      -
    1. -

      The first two lines of all CSS files are:

      -
      - @charset "utf-8"; -@namespace epub "http://www.idpf.org/2007/ops"; -
      -
      2. -
    2. -

      Tabs are used for indentation.

      -
      3. -
    3. -

      Selectors, properties, and values are lowercase.

      -
      4. -
    -
    -

    Selectors

    -
      -
    1. -

      Selectors are each on their own line, directly followed by a comma or a brace with no whitespace inbetween.

      -
      2. -
    2. -

      Complete selectors are separated by exactly one blank line.

      -
      - abbr.name{ -white-space: nowrap; -} - - - -strong{ -font-weight: normal; -font-variant: small-caps; -} -
      -
      - abbr.name{ -white-space: nowrap; -} - -strong{ -font-weight: normal; -font-variant: small-caps; -} -
      -
      3. -
    3. -

      Closing braces are on their own line.

      -
      4. -
    -
    -
    -

    Properties

    -
      -
    1. -

      Properties are each on their own line (even if the selector only has one property) and indented with a single tab.

      -
      - abbr.name{ white-space; nowrap; } -
      -
      - abbr.name{ -white-space: nowrap; -} -
      -
      2. -
    2. -

      Properties are in alphabetical order, where possible.

      -

      This isn’t always possible if you’re attempting to override a previous style in the same selector, and in some other cases.

      -
      3. -
    3. -

      Properties are directly followed by a colon, then a single space, then the property value.

      -
      4. -
    4. -

      Property values are directly followed by a semicolon, even if it's the last value in a selector.

      -
      5. -
    -
    -
    -
    -
    -

    Filesystem layout

    -
    -

    How to name files

    -
      - -
    1. -

      Works that are divided into larger parts (sometimes called "parts", "books", "volumes", "sections", etc.) have their part divisions contained in individual files named after the type of part, followed by a number starting at 1.

      -
      -

      book-1.xhtml

      -

      book-2.xhtml

      -

      part-1.xhtml

      -

      part-2.xhtml

      -
      -
      2. -
    2. -

      Works that are composed of chapters, short stories, essays, or other short- to medium-length sections have each of those sections in an individual file.

      -
        -
      1. -

        Chapters not contained in separate volumes are named chapter-N.xhtml, where N is the chapter number starting at 1.

        -
        2. -
      2. -

        Chapters contained in separate volumes, where the chapter number starts at 1 for each separate volume, are named chapter-X-N.xhtml, where X is the part number starting at 1, and N is the chapter number within the part, starting at 1.

        -
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

        Example

        Filename

        Part 1part-1.xhtml
        Chapter 1chapter-1-1.xhtml
        Chapter 2chapter-1-2.xhtml
        Chapter 3chapter-1-3.xhtml
        Part 2part-2.xhtml
        Chapter 1chapter-2-1.xhtml
        Chapter 2chapter-2-2.xhtml
        Chapter 3chapter-2-3.xhtml
        -
        -
        3. -
      3. -

        Chapters contained in separate volumes, where the chapter number does not re-start at 1 in each volume, are named chapter-N.xhtml, where N is the chapter number, starting at 1.

        -
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

        Example

        Filename

        Part 1part-1.xhtml
        Chapter 1chapter-1.xhtml
        Chapter 2chapter-2.xhtml
        Chapter 3chapter-3.xhtml
        Part 2part-2.xhtml
        Chapter 4chapter-4.xhtml
        Chapter 5chapter-5.xhtml
        Chapter 6chapter-6.xhtml
        -
        -
        4. -
      -
    3. -

      Files containing a short story, essay, or other short work in a larger collection, are named with the URL-safe title of the work, excluding any subtitles.

      -
      - - - - - - - - - - - - - - - - - -

      Example

      Filename

      A short story named "The Variable Man"

      		the-variable-man.xhtml

      A short story named "The Sayings of Limpang-Tung (The God of Mirth and of Melodious Minstrels)"

      		the-sayings-of-limpang-tung.xhtml
      -
      -
      4. -
    4. -

      Works that are composed of extremely short sections, like a volume of short poems, are in a single file containing all of those short sections. The filename is the URL-safe name of the work.

      -
      -

      north-of-boston.xhtml

      -
      -
      5. -
    5. -

      Frontmatter and backmatter sections have filenames that are named after the type of section, regardless of what the actual title of the section is.

      -
      - - - - - - - - - - - - - -

      Example

      Filename

      A preface titled "Note from the author"

      		preface.xhtml
      -
      -
        -
      1. -

        If an ebook contains more than one section of the same type (for example multiple prefaces), the filename is followed by -N, where N is a number representing the order of the section, starting at 1.

        -
        - - - - - - - - - - - - - - - - - -

        Example

        Filename

        The first preface in an ebook, titled "Preface to the 1850 Edition"

        		preface-1.xhtml

        The second preface in an ebook, titled "Preface to the Charles Dickens Edition"

        		preface-2.xhtml
        -
        -
        2. -
      -
      6. -
    -
    -
    -
    -

    Semantic inflection

    -

    The epub spec allows for semantic inflection, which is a way of adding pertinent semantic metadata to certain elements. For example, you may want to convey that the contents of a certain <section> are actually a part of a chapter. You would do that by using the epub:type attribute:

    -
    - <section epub:type="chapter">...</section> -
    -
      -
    1. -

      The epub spec includes a list of supported keywords that you can use in the epub:type attribute. Use this vocabulary first, even if other vocabularies contain the same keyword.

      -
      2. -
    2. -

      If there's no appropriate keyword in the epub spec, next consult the z3998 vocabulary.

      -

      Keywords using this vocabulary are preceded by the z3998 namespace.

      -
      - <blockquote epub:type="z3998:letter">...</blockquote> -
      -
      3. -
    3. -

      If the z3998 vocabulary doesn't have an appropriate keyword, next consult the Standard Ebooks vocabulary.

      -

      Keywords using this vocabulary are preceded by the se namespace.

      -

      Unlike other vocabularies, the Standard Ebooks vocabulary is organized heirarchically. A complete vocabulary entry begins with the root vocabulary entry, with subsequent children separated by ..

      -
      - The <i epub:type="se:name.vessel.ship"><abbr class="initialism">HMS</abbr> Bounty</i>. -
      -
      4. -
    4. -

      The epub:type attribute can have multiple keywords separated by spaces, even if the vocabularies are different.

      -
      - <section epub:type="chapter z3998:letter">...</section> -
      -
      5. -
    -
    -
    -

    General XHTML patterns

    -
    -

    The id attribute

    -
    -

    ids of <section>s

    -
      -
    1. -

      Each <section> has an id attribute identical to the filename containing the <section>, without the trailing extension.

      -
      2. -
    2. -

      In files containing multiple <section>s, each <section> has an id attribute identical to what the filename would be if the section was in an individual file, without the trailing extension.

      -
      3. -
    -
    -
    -

    ids of other elements

    -

    Generally, elements that are not <section>s do not have an id attribute. However an id attribute might be necessary if a particular element is referenced in a link in a different location in the ebook; for example, if a certain paragraph is linked from an endnote.

    -
      -
    1. -

      If an element requires an id attribute, the attribute's value is the name of the tag followed by -N, where N is the sequence number of the tag start at 1.

      -
      - <p>See <a href="#p-4">this paragraph</a> for more details.</p> -<p>...</p> -<p>...</p> -<p id="p-4">...</p> -<p>...</p> -
      -
      2. -
    -
    -
    -
    -

    <title> tags

    -
      -
    1. -

      The <title> tag contains an appropriate description of the local file only. It does not contain the book title.

      -
      2. -
    -
    -

    Titles of files that are an individual chapter or part division

    -
      -
    1. -

      Convert chapter or part numbers that are in Roman numerals to decimal numbers. Do not convert other Roman numerals that may be in the chapter title.

      -
      - <title>Chapter 10</title> -
      -
      2. -
    2. -

      If a chapter or part has no subtitle, the <title> tag contains Chapter followed by the chapter number.

      -
      - <title>Chapter 4</title> -
      -
      3. -
    3. -

      If a chapter or part has a subtitle, the <title> tag contains Chapter, followed by the chapter number, followed by a colon and a single space, followed by the subtitle.

      -
      - <title>Chapter 4: The Reign of Louis XVI</title> -
      -
      4. -
    -
    -
    -

    Titles of files that are not chapter or part divisions

    -
      -
    1. -

      Files that are not a chapter or a part division, like a preface, introduction, or epigraph, have a <title> tag that contains the complete title of the section.

      -
      - <title>Preface</title> -
      -
      2. -
    2. -

      If a file contains a section with a subtitle, the <title> tag contains the title, followed by a colon and a single space, followed by the subtitle.

      -
      - <title>Quevedo and His Works: With an Essay on the Picaresque Novel</title> -
      -
      3. -
    -
    -
    -
    -

    Ordered/numbered and unordered lists

    -

    All <li> children of <ol> and <ul> tags have at least one direct child block-level tag. This is usually a <p> tag. (But not necessarily; for example, a <blockquote> tag might also be appropriate.)

    -
    - <ul> -<li>Don’t forget to feed the pigs.</li> -</ul> -
    -
    - <ul> -<li> - <p>Don’t forget to feed the pigs.</p> -</li> -</ul> -
    -
    -
    -
    -

    Sectioning

    -
      -
    1. -

      Structural divisions in an ebook are each contained in their own <section> tag.

      -
      2. -
    2. -

      In <section>s that have titles, the first child element is an <h#> or a <header> element containing the section's title.

      -
      3. -
    3. -

      Typically an epub is divided into many different files. However, these files must be "recomposable" into a single HTML file by the recompose-epub tool.

      -

      To achieve recomposability, individual files that contain subsections also contain all of the direct parent <section> tags, with id and epub:type attributes identical to those parents.

      -

      For example, consider an ebook containing both a file named part-1.xhtml, the first part, and a file named chapter-1-1.xhtml, the first chapter of the first part. chapter-1-1.xhtml contains a <section> element for both the parent part, and the actual chapter:

      -
      - <section id="part-1" epub:type="part"> -<section id="chapter-1-1" epub:type="chapter"> - <h3 epub:type="title z3998:roman">I</h3> - ... -</section> -</section> -
      -
      4. -
    -
    -
    -

    Parts of an ebook and their order

    -
    -

    Frontmatter

    -

    Frontmatter includes these parts of a book, in no particular order:

    -
      -
    • -

      Titlepage: An SE template containing an image with the title, author, and translator.

      -
      • -
    • -

      Imprint: An SE template containing information about Standard Ebooks and links to the source transcription and scans used to produce this ebook.

      -
      • -
    • -

      Dedication: A dedication from the author.

      -
      • -
    • -

      Epigraph: An opening poem or quotation.

      -
      • -
    • -

      Acknowledgements: A list of people that the author wishes to thank.

      -
      • -
    • -

      Foreword: An introduction to the text, written by someone besides the author.

      -
      • -
    • -

      Preface: An introduction to the text but standing outside of the text itself, written by the author. Often describes how a book came into being or to establish the author's credentials. "About the book as a book."

      -
      • -
    • -

      Introduction: An introduction to the text written, by the author. "About the content of the book."

      -
      • -
    • -

      Prologue: An opening to the text that establishes setting or mood, usually in the voice of the text.

      -
      • -
    -

    Note that in a Standard Ebooks ebook, the copyright page is part of the backmatter and not the frontmatter.

    -
    -
    -

    Backmatter

    -

    Backmatter includes these parts of a book, in no particular order:

    -
      -
    • -

      Epilogue: A conclusion to the text, usually in the voice of the text..

      -
      • -
    • -

      Afterword: A note from the author to conclude the text, outside of the text itself.

      -
      • -
    • -

      Endnotes: Any supplementary notes referenced in the text.

      -
      • -
    • -

      Colophon: A description of publishing details regarding the specific edition of the text, including credits or contributors.

      -
      • -
    • -

      Copyright page: Usually considered frontmatter in print texts, but considered backmatter in Standard Ebooks ebooks.

      -
      • -
    -
    -
    -

    Ordering of sections

    -
      -
    1. -

      The first section of an ebook is titlepage.xhtml. This file is auto-generated by create-draft.

      -
      2. -
    2. -

      The second section of an ebook is imprint.xhtml. The imprint contains links to the source transcription and scans used to produce the Standard Ebooks edition.

      -
      3. -
    3. -

      Any frontmatter relevant to the text follows.

      -
      4. -
    4. -

      If there is frontmatter, then a half title page follows.

      -
      -

      Half title page patterns

      -

      The half title page contains the work title and subtitle.

      -
        -
      1. -

        Half title pages without subtitles:

        -
        - <?xml version="1.0" encoding="utf-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> -<head> - <title>Half Title</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> -</head> -<body epub:type="frontmatter"> - <section id="halftitlepage" epub:type="halftitlepage"> - <h1 epub:type="fulltitle">Don Quixote</h1> - </section> -</body> -</html> -
        -
        2. -
      2. -

        Half title pages with subtitles:

        -
        - section[epub|type~="halftitlepage"] span[epub|type~="subtitle"]{ -display: block; -font-size: .75em; -font-weight: normal; -} - <?xml version="1.0" encoding="utf-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> -<head> - <title>Half Title</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> -</head> -<body epub:type="frontmatter"> - <section id="halftitlepage" epub:type="halftitlepage"> - <h1 epub:type="fulltitle"> - <span epub:type="title">The Book of Wonder</span> - <span epub:type="subtitle">A Chronicle of Little Adventures at the Edge of the World</span> - </h1> - </section> -</body> -</html> -
        -
        3. -
      -
      -
      5. -
    5. -

      Bodymatter (the main text) follows the frontmatter and half title page.

      -
      6. -
    6. -

      After the bodymatter, backmatter within the text follows, for example an afterword, epilogue, or conclusion.

      -
      7. -
    7. -

      Endnotes follow the text's backmatter. Endnotes files are named endnotes.xhtml.

      -
      8. -
    8. -

      The colophon follows.

      -
      9. -
    9. -

      The uncopyright page follows the colophon.

      -
      10. -
    -
    -
    -
    -

    Headers

    -
      -
    1. -

      <h#> tags (i.e., <h1>–<h6>) are used for headers of sections that are structural divisions of a document.

      -

      <h#> tags are not used for headers of components that are not in the table of contents. For example, they would not be used to mark up the title of a short poem in a chapter, where the poem itself is not a structural component of the larger ebook.

      -
      2. -
    2. -

      A section containing an <h#> appears in the table of contents.

      -
      3. -
    3. -

      The book's title is implicitly at the <h1> level, even if not present in the ebook. Because of the implicit <h1>, all other sections begin at <h2>.

      -
      4. -
    4. -

      Each <h#> tag uses the correct number for the section's heading level in the overall book, not the section's heading level in the individual file.

      -

      For example, given an ebook with a file named part-2.xhtml containing:

      -
      - <section id="part-2" epub:type="part"> -<h2 epub:type="title">Part <span epub:type="z3998:roman">II</span></h2> -</section> -
      -

      Consider this example for the file chapter-2-3.xhtml:

      -
      - <section id="part-2" epub:type="part"> -<section id="chapter-2-3" epub:type="chapter"> - <h1 epub:type="title z3998:roman">III</h1> - ... -</section> -</section> -
      -
      - <section id="part-2" epub:type="part"> -<section id="chapter-2-3" epub:type="chapter"> - <h3 epub:type="title z3998:roman">III</h3> - ... -</section> -</section> -
      -
      5. -
    5. -

      Each <h#> tag has a direct parent <section> tag.

      -
      6. -
    -
    -

    Header HTML patterns

    -
      -
    1. -

      Sections without titles:

      -
      - <h2 epub:type="title z3998:roman">XI</h2> -
      -
      2. -
    2. -

      Sections with titles but no ordinal (i.e. chapter) numbers:

      -
      - <h2 epub:type="title">A Daughter of Albion</h2> -
      -
      3. -
    3. -

      Sections with titles and ordinal (i.e. chapter) numbers:

      -
      - span[epub|type~="subtitle"]{ -display: block; -font-weight: normal; -} - <h2 epub:type="title"> -<span epub:type="z3998:roman">XI</span> -<span epub:type="subtitle">Who Stole the Tarts?</span> -</h2> -
      -
      4. -
    4. -

      Sections titles and subtitles but no ordinal (i.e. chapter) numbers:

      -
      - span[epub|type~="subtitle"]{ -display: block; -font-weight: normal; -} - <h2 epub:type="title"> -<span>An Adventure</span> -<span epub:type="subtitle">(A Driver’s Story)</span> -</h2> -
      -
      5. -
    5. -

      Sections that require titles, but that are not in the table of contents:

      -
      - header{ -font-variant: small-caps; -margin: 1em; -text-align: center; -} - <header> -<p>The Title of a Short Poem</p> -</header> -
      -
      6. -
    -
    -
    - - - - - -
    - Play CSS: - - - [epub|type~="z3998:drama"]{ - border-collapse: collapse; - } - - [epub|type~="z3998:drama"] tr:first-child td{ - padding-top: 0; - } - - [epub|type~="z3998:drama"] tr:last-child td{ - padding-bottom: 0; - } - - [epub|type~="z3998:drama"] td{ - vertical-align: top; - padding: .5em; - } - - [epub|type~="z3998:drama"] td:last-child{ - padding-right: 0; - } - - [epub|type~="z3998:drama"] td:first-child{ - padding-left: 0; - } - - [epub|type~="z3998:drama"] td[epub|type~="z3998:persona"]{ - hyphens: none; - text-align: right; - width: 20%; - } - - [epub|type~="z3998:drama"] td p{ - text-indent: 0; - } - - table[epub|type~="z3998:drama"], - [epub|type~="z3998:drama"] table{ - margin: 1em auto; - } - - [epub|type~="z3998:stage-direction"]{ - font-style: italic; - } - - [epub|type~="z3998:stage-direction"]::before{ - content: "("; - font-style: normal; - } - - [epub|type~="z3998:stage-direction"]::after{ - content: ")"; - font-style: normal; - } - - [epub|type~="z3998:persona"]{ - font-variant: all-small-caps; - } - -
    -
    -
    - diff --git a/www/contribute/metadata.php b/www/contribute/metadata.php deleted file mode 100644 index 01a920b1..00000000 --- a/www/contribute/metadata.php +++ /dev/null @@ -1,323 +0,0 @@ - 'title', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Metadata Manual, containing requirements and directives for the epub metadata file.']) ?> -
    -
    -

    Metadata Manual

    - -

    General principles

    -

    Metadata in a Standard Ebooks epub is stored in the ./src/epub/content.opf file. The file contains some boilerplate that you won’t have to touch, and a lot of information that you will have to touch as you produce your ebook.

    -

    You should follow the general structure of the content.opf file created by se create-draft. Don't rearrange the order of anything in there and you should be fine.

    -

    The <dc:identifier> element

    -

    The <dc:identifier> element contains the unique identifier for this ebook. That identifier is always the Standard Ebooks URL for that ebook, prefaced by url:.

    -
    - <dc:identifier id="uid">url:https://standardebooks.org/ebooks/anton-chekhov/short-fiction/constance-garnett</dc:identifier> -
    -

    Forming the SE identifier

    -

    The SE identifier is formed by the following algorithm. A string can be made URL-safe using the make-url-safe tool.

    -
      -
    1. -

      Start with the URL-safe author of the work, as it appears on the titlepage. If there is more than one author, continue appending subsequent URL-safe authors, separated by an underscore. Do not alpha-sort the author name.

      -
      2. -
    2. -

      Append a forward slash, then the URL-safe title of the work. Again, do not alpha-sort the title.

      -
      3. -
    3. -

      If the work is translated, append a forward slash, then the URL-safe translator. If there is more than one translator, continue appending subsequent URL-safe translators, separated by an underscore. Do not alpha-sort translator names.

      -
      4. -
    4. -

      If the work is illustrated, append a forward slash, then the URL-safe illustrator. If there is more than one illustrator, continue appending subsequent URL-safe illustrators, separated by an underscore. Do not alpha-sort illustrator names.

      -
      5. -
    5. -

      Finally, do not append a trailing forward slash.

      -
      6. -
    -

    The <dc:date>, <meta property="dcterms:modified">, and <meta property="se:revision-number"> elements

    -

    There are several elements in the metadata describing the publication date, updated date, and revision number of the ebook. Generally you don’t have to update these by hand; instead, use the prepare-release tool to update them automatically both in content.opf and in colophon.xhtml.

    -
      -
    • -

      <dc:date> is a timestamp representing the first publication date of this ebook file. Once the ebook is released to the public, this value doesn’t change.

      -
      • -
    • -

      <meta property="dcterms:modified"> is a timestamp representing the last time this ebook file was modified. This changes often.

      -
      • -
    • -

      <meta property="se:revision-number"> is a special SE extension representing the revision number of this ebook file. During production, this number will be 0. When the ebook is first released to the public, the number will increment to 1. Each time <meta property="dcterms:modified"> changes, the revision number must be incremented.

      -
      • -
    -

    The ebook title

    -

    Usually titles are fairly easy to represent with the <dc:title> element.

    -

    Books without subtitles

    -
      -
    • -

      Add a <dc:title> element to contain the title.

      -
      • -
    • -

      Add an accompanying file-as element with the title alpha-sorted, even if the file-as value is the same as the title.

      -
      • -
    -

    These examples shows how to mark up a simple title like The Moon Pool or Chekhov’s Short Fiction.

    <dc:title id="title">The Moon Pool</dc:title> <meta property="file-as" refines="#title">Moon Pool, The</meta> <dc:title id="title">Short Fiction</dc:title> <meta property="file-as" refines="#title">Short Fiction</meta> -

    Books with subtitles

    -
      -
    • -

      Add a <meta property="title-type"> element with the value of main to identify the main part of the title.

      -
      • -
    • -

      Add a second <dc:title> element to contain the subtitle, and refine it with <meta property="title-type"> set to subtitle.

      -
      • -
    • -

      Add a third <dc:title> element to contain the complete title on one line, with the main title and subtitle separated by a colon and space. Refine it with <meta property="title-type"> set to extended.

      -
      • -
    • -

      All three of these <dc:title> elements must have an accompanying file-as element, even if the file-as value is the same as the title.

      -
      • -
    -

    This example shows how to mark up The Man Who Was Thursday: A Nightmare.

    <dc:title id="title">The Man Who Was Thursday</dc:title> <meta property="file-as" refines="#title">Man Who Was Thursday, The</meta> <meta property="title-type" refines="#title">main</meta> <dc:title id="subtitle">A Nightmare</dc:title> <meta property="file-as" refines="#subtitle">Nightmare, A</meta> <meta property="title-type" refines="#subtitle">subtitle</meta> <dc:title id="fulltitle">The Man Who Was Thursday: A Nightmare</dc:title> <meta property="file-as" refines="#fulltitle">Man Who Was Thursday, The</meta> <meta property="title-type" refines="#fulltitle">extended</meta> -

    Books with a more popularly-known alternative title

    -

    Some books are commonly referred to by a shorter name than their actual title. For example, The Adventures of Huckleberry Finn is often simply known as Huck Finn.

    -
      -
    • -

      Add an additional <dc:title> element to contain the common title, and refine it with <meta property="title-type"> set to short.

      -
      • -
    • -

      Do not include a file-as element for the short title.

      -
      • -
    <dc:title id="title-short">Huck Finn</dc:title> <meta property="title-type" refines="#title-short">short</meta> -

    Ebook subjects

    -

    The <dc:subject> elements allow us to categorize the ebook. We use the Library of Congress categories assigned to the book for this purpose.

    -

    If you’re working on a book that has a Project Gutenberg transcription, you can almost always find these categorizations in the ebook’s “bibrec” tab, saving you effort.

    -

    If your ebook doesn’t have a Project Gutenberg page, then you can search the Library of Congress catalog to find the categories for your ebook.

    -
      -
    • -

      Each <dc:subject> has the id attribute set to subject-#, where # is a number starting at 1, without leading zeros, that increments with each subject.

      -
      • -
    • -

      Arrange the <dc:subject> elements sequentially in a block.

      -
      • -
    • -

      After the block of <dc:subject> elements, include a block of <meta property="authority"> and <meta property="term"> elements with values representing the source and particular ID of the subject. authority is almost always LCSH (Library of Congress Subject Heading).

      -
      • -
    • -

      The <meta property="authority"> element must refine each individual <dc:subject> element.

      -
      • -
    -

    This example shows how to mark up the subjects for A Voyage to Arcturus:

    <dc:subject id="subject-1">Science fiction</dc:subject> <dc:subject id="subject-2">Psychological fiction</dc:subject> <dc:subject id="subject-3">Quests (Expeditions) -- Fiction</dc:subject> <dc:subject id="subject-4">Life on other planets -- Fiction</dc:subject> <meta property="meta-auth" refines="#subject-1">https://www.gutenberg.org/ebooks/1329</meta> <meta property="meta-auth" refines="#subject-2">https://www.gutenberg.org/ebooks/1329</meta> <meta property="meta-auth" refines="#subject-3">https://www.gutenberg.org/ebooks/1329</meta> <meta property="meta-auth" refines="#subject-4">https://www.gutenberg.org/ebooks/1329</meta> -

    SE subjects

    -

    Along the Library of Congress categories, we include a custom list of SE subjects in the ebook metadata. Unlike Library of Congress categories, SE subjects are purposefully broad. They’re more like subject categories you’d find a medium-sized bookstore, as opposed to the precise, detailed, heirarchical Library of Congress categories.

    -

    It’s your task to select appropriate SE subjects for your ebook. Usually just one or two of these categories will suffice.

    -

    If you strongly feel like your book deserves a new category, please contact us to discuss it.

    -

    Below is a list of all of the recognized SE subjects:

    -
      -
    • -

      Adventure

      -
      • -
    • -

      Autobiography

      -
      • -
    • -

      Childrens

      -
      • -
    • -

      Comedy

      -
      • -
    • -

      Drama

      -
      • -
    • -

      Fantasy

      -
      • -
    • -

      Fiction

      -
      • -
    • -

      Horror

      -
      • -
    • -

      Memoir

      -
      • -
    • -

      Mystery

      -
      • -
    • -

      Nonfiction

      -
      • -
    • -

      Philosophy

      -
      • -
    • -

      Poetry

      -
      • -
    • -

      Satire

      -
      • -
    • -

      Science Fiction

      -
      • -
    • -

      Shorts

      -
      • -
    • -

      Spirituality

      -
      • -
    • -

      Travel

      -
      • -
    -

    Required subjects for specific kinds of ebooks

    -
      -
    • -

      Ebooks that are collections of short stories must have the SE subject Shorts.

      -
      • -
    • -

      Ebooks that are young adult or children’s books must have the SE subject Childrens.

      -
      • -
    -

    Ebook descriptions

    -

    An ebook has two kinds of descriptions: a short <dc:description> element, and a much longer <meta property="se:long-description"> element.

    -

    The short description

    -

    The <dc:description> element contains a short, single-sentence summary of the ebook.

    -
      -
    • -

      The description must be a single complete sentence ending in a period, not a sentence fragment or restatment of the title. Do not use more than one sentence.

      -
      • -
    • -

      The description must be typogrified, i.e. it must contain Unicode curly quotes, em-dashes, and the like.

      -
      • -
    -

    The long description

    -

    The <meta property="se:long-description"> element contains a much longer description of the ebook.

    -
      -
    • -

      The long description must be a non-biased, encyclopedia-like description of the ebook, including any relevant publication history, backstory, or historical notes. It must be as detailed as possible, without giving away plot spoilers. It must not impart the producer’s opinions of the book. Think along the lines of a Wikipedia-like summary of the book and its history, but under no circumstances can you copy and paste from Wikipedia!

      -
      • -
    • -

      The long descriptions must be typogrified, i.e. it must contain Unicode curly quotes, em-dashes, and the like.

      -
      • -
    • -

      The long description must be in escaped HTML, with the HTML beginning on its own line after the <meta property="se:long-description"> element.

      -

      An easy way to escape your HTML is to compose your long description in regular HTML, then insert it into the <meta property="se:long-description"> element surrounded by a <![CDATA[ ... ]]> element. Once you’re done, run the clean tool, which will remove the <![CDATA[ ... ]]> element and escape the contained HTML for you.

      -
      • -
    -

    The <dc:language> element

    -

    The <dc:language> element follows the long description block. It contains the IETF language tag for the language that the work is in. Usually this is either en-US or en-GB.

    -

    The <dc:source> elements

    -

    The <dc:source> elements represent URLs to sources for both the transcription we based this ebook off of, and page scans of the print sources used to correct or work on the transcriptions.

    -
      -
    • -

      Where possible, these URLs should use https.

      -
      • -
    • -

      A Standard Ebooks ebook typically contains more than one <dc:source> element, and can contain more than one such element if multiple sources for page scans were used.

      -
      • -
    -

    The <meta property="se:production-notes"> elements

    -

    This element can be used by the ebook producers to convey production notes relevant to the production process. For example, a producer might note that page scans were not available, so an editorial decision was made to add commas to sentences deemed to be transcription typos.

    -

    If there are no production notes, remove this element.

    -

    The <meta property="se:word-count"> and <meta property="se:reading-ease.flesch"> elements

    -

    These elements are automatically computed by the prepare-release tool. Don’t compute them by hand.

    -

    SE-specific metadata for the ebook

    -

    Next, Standard Ebooks also includes two additional custom metadata items about the ebook:

    -
      -
    1. -

      <meta property="se:url.encyclopedia.wikipedia"> contains the Wikipedia URL for this ebook. If there isn’t one, remove this element.

      -
      2. -
    2. -

      <meta property="se:url.vcs.github"> contains the GitHub URL for this ebook. This is calculated by taking the string “https://github.com/standardebooks/” and appending the ebook identifier (calculated above), without “https://standardebooks.org/ebooks/”, and with forward slashes replaced by underscores.

      -
      3. -
    -

    Author metadata

    -

    Next, we include the author metadata block.

    -

    The author metadata block always has the ID of “author”. If there is more than one author, the first author is “author-1”, the second “author-2”, and so on. Each block of the following, in this order:

    -
      -
    1. -

      <dc:creator id="author">: the author’s name as it appears on the cover.

      -
      2. -
    2. -

      <meta property="file-as" refines="#author">: the author’s name as filed alphabetically. Include this even if it’s identical to <dc:creator>.

      -
      3. -
    3. -

      <meta property="se:name.person.full-name" refines="#author">: the author’s full name, with any initials or middle names expanded. If this is identical to <dc:creator>, remove this element.

      -
      4. -
    4. -

      <meta property="alternate-script" refines="#author">: the author’s name as it appears on the cover, but transliterated into their native alphabet if applicable. For example, Anton Chekhov’s name would be contained here in the Cyrillic alphabet. Remove this element if not applicable.

      -
      5. -
    5. -

      <meta property="se:url.encyclopedia.wikipedia" refines="#author">: the URL of the author’s Wikipedia page. Remove this element if not applicable.

      -
      6. -
    6. -

      <meta property="se:url.authority.nacoaf" refines="#author">: the URL of the author’s Library of Congress Names Database page.

      -
        -
      • -

        This is easily found by visiting the person’s Wikipedia page and looking at the very bottom in the “Authority Control” section, under “LCCN”.

        -
        • -
      • -

        If you can’t find it in Wikipedia, you can find it directly by visiting http://id.loc.gov/authorities/names.html.

        -
        • -
      • -

        Note that the canonical URLs do not include a trailing .html (the LoC site performs a silent redirect when you load it to append .html to the URL it considers canonical). Remove this element if not applicable.

        -
        • -
      -
      7. -
    7. -

      <meta property="role" refines="#author" scheme="marc:relators">: the MARC relator tag for the roles the author played in creating this book. You will always have one element with the value of aut. You can have additional elements for additional values, if applicable. For example, if the author also illustrated the book, you would include an additional element with the value of ill.

      -
      8. -
    -

    An example of a complete author metadata block

    <dc:creator id="author">Anton Chekhov</dc:creator> <meta property="file-as" refines="#author">Chekhov, Anton</meta> <meta property="se:name.person.full-name" refines="#author">Anton Pavlovich Chekhov</meta> <meta property="alternate-script" refines="#author">Анто́н Па́влович Че́хов</meta> <meta property="se:url.encyclopedia.wikipedia" refines="#author">https://en.wikipedia.org/wiki/Anton_Chekhov</meta> <meta property="se:url.authority.nacoaf" refines="#author">http://id.loc.gov/authorities/names/n79130807</meta> <meta property="role" refines="#author" scheme="marc:relators">aut</meta> -

    Translator metadata

    -

    If the work is translated, the translator metadata block follows.

    -

    The translator metadata block always has the ID of “translator”. If there is more than one translator, the first translator is “translator-1”, the second “translator-2”, and so on. Each block is identical to the author metadata block, but using <dc:contributor id="translator"> instead of <dc:creator>. The MARC relator tag will be trl. Translators often annotate the work; if this is the case, also include the MARC relator tag ann.

    -

    Illustrator metadata

    -

    If the work is illustrated by a person who is not the author, the illustrator metadata block follows.

    -

    The illustrator metadata block always has the ID of “illustrator”. If there is more than one author, the first illustrator is “illustrator-1”, the second “illustrator-2”, and so on. Each block is identical to the author metadata block, but using <dc:contributor id="illustrator"> instead of <dc:creator>. The MARC relator tag will be ill.

    -

    Cover artist metadata

    -

    The cover artist metadata block follows.

    -

    The cover artist metadata block always has the ID of “artist”. Each block is identical to the author metadata block, but using <dc:contributor id="artist"> instead of <dc:creator>. The MARC relator tag will be art.

    -

    Transcriber metadata

    -

    If you based this ebook on a transcription by someone else, like Project Gutenberg, then transcriber blocks follow. The first transcriber is “transcriber-1”, the second “transcriber-2”, and so on. Usually, trancribers only have the following two elements:

    -
      -
    1. -

      <meta property="file-as" refines="#transcriber-1">

      -
      2. -
    2. -

      <meta property="role" refines="#transcriber-1" scheme="marc:relators"> with the value of trc.

      -
      3. -
    -

    Producer metadata

    -

    This block is for information about you, the producer of this Standard Ebook. It contains the same type of elements as the author block, but with <dc:contributor id="producer-1">.

    -
      -
    1. -

      You can include the <meta property="se:url.homepage" refines="#producer-1"> element with a link to your personal homepage. This must be a link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.

      -
      2. -
    2. -

      Your MARC relator roles will usually be the following:

      -
        -
      • -

        bkp: you are the producer of this ebook.

        -
        • -
      • -

        blw: you wrote the blurb (the long description).

        -
        • -
      • -

        cov: you selected the cover art.

        -
        • -
      • -

        mrk: you wrote HTML markup for this ebook.

        -
        • -
      • -

        pfr: you proofread the ebook.

        -
        • -
      • -

        tyg: you reviewed the typography of the ebook.

        -
        • -
      -
      3. -
    -

    The <manifest> element

    -

    The <manifest> element is a required part of the epub spec. This should usually be generated by the print-manifest tool and copy-and-pasted into the content.opf file. It must be in alphabetical order, which is handled for you by the print-manifest-and-spine tool.

    -

    The <spine> element

    -

    The <spine> element is a required part of the epub spec that defines the reading order of the files in the ebook. You can use the print-spine tool to generate a draft of the spine. The tool makes a best guess as to the spine order, but it cannot be 100% correct; please review the output and adjust the reading order accordingly.

    -
    -
    - diff --git a/www/contribute/producers.php b/www/contribute/producers.php index a3b6d30e..4ec9d13e 100644 --- a/www/contribute/producers.php +++ b/www/contribute/producers.php @@ -19,7 +19,7 @@ require_once('Core.php');

    Contact the Standard Ebooks mailing list to pitch the ebook you’ve selected, before you begin production.

  • -

    Carefully review the entirety of the Standard Ebooks Typography Manual, Semantics Manual, and Metadata Manual.

    +

    Carefully review the entirety of the Standard Ebooks Manual of Style.

  • Once we’ve OK’d your selection and you’ve read the style manuals, you can get started! Follow the steps in our step-by-step guide to producing an ebook to take your ebook from start to finish.

    • diff --git a/www/contribute/producing-an-ebook-step-by-step.php b/www/contribute/producing-an-ebook-step-by-step.php index 1b7ce3f1..9a7530c2 100644 --- a/www/contribute/producing-an-ebook-step-by-step.php +++ b/www/contribute/producing-an-ebook-step-by-step.php @@ -1,25 +1,22 @@ 'Producing an Ebook, Step by Step', 'js' => true, 'highlight' => 'contribute', 'description' => 'A detailed step-by-step description of the complete process of producing an ebook for the Standard Ebooks project, start to finish.']) ?> -
    +?> 'Producing an Ebook, Step by Step', 'manual' => true, 'highlight' => 'contribute', 'description' => 'A detailed step-by-step description of the complete process of producing an ebook for the Standard Ebooks project, start to finish.']) ?> +

    Producing an Ebook, Step by Step

    -

    This guide is meant to take you step-by-step through the creation of a complete Standard Ebook. While it might seem a little long, most of the text is a description of how to use various automated scripts. It can take just an hour or two for an experienced producer to produce a draft ebook for proofreading (depending on the complexity of the ebook, of course).

    +

    Our toolset is GNU/Linux-based, and producing an ebook from scratch currently requires working knowledge of the epub file format and of Unix-like systems like Mac or Linux.

    +

    Our toolset doesn’t yet work natively on Windows, but there are many ways to run Linux from within Windows.

    +

    If you don’t have this kind of technical expertise, you can still contribute! Check out our contributors page for details.

    1. -

      Download and set up the Standard Ebooks production toolset

      -

      The Standard Ebooks project has a toolset that will help you produce an ebook. Read how to install them here.

      -

      Make sure you take a moment to put the se executable that’s installed with the toolset on your shell’s $PATH. How to do that varies depending on what shell you’re using.

      -
      2. -
    2. -

      Make sure the toolset is up-to-date

      -

      The toolset changes frequently. If this isn’t your first ebook production, always make sure to update the toolset before you start a new ebook, so that you’re working with the latest version of the tools.

      - pipx upgrade standardebooks +

      Set up the Standard Ebooks toolset and make sure it’s up-to-date

      +

      The Standard Ebooks project has a toolset that will help you produce an ebook. The toolset installs the se command, which has various subcommands related to creating Standard Ebooks. You can read the complete installation instructions, or if you already have pipx installed, run:

      + pipx install standardebooks +

      The toolset changes frequently, so if you’ve installed the toolset in the past, make sure to update the toolset before you start a new ebook:

      + pipx upgrade standardebooks +

      Once the toolset is installed, you can check which version you have with:

      + se --version

    3. Select an ebook to produce

      @@ -29,7 +26,7 @@ require_once('Core.php');

      There may be different versions of the same publication on Gutenberg, and the best one might not be the one with the most downloads. In particular, there could be a better translation that has fewer downloads because it was produced later, or there could be a version with better HTML markup. A great example of this phenomenon is the Gutenberg version of 20,000 Leagues Under the Seas. The most-downloaded version is an old translation widely criticized as being slapdash and inaccurate. The less popular version is a fresh, modern translation dedicated to the public domain.

    4. -

      Gutenberg usually offers both an HTML version and an epub version of the same ebook. Note that one is not always exactly the same as the other! A casual reader might assume that the HTML version is generated from the epub version, or the other way around; but for some reason the HTML and epub versions often differ in important ways, with the HTML version typically using fewer useless CSS classes, and including <em> tags that the epub version is often missing.

      +

      Gutenberg usually offers both an HTML version and an epub version of the same ebook. Note that one is not always exactly the same as the other! A casual reader might assume that the HTML version is generated from the epub version, or the other way around; but for some reason the HTML and epub versions often differ in important ways, with the HTML version typically using fewer useless CSS classes, and including <em> elements that the epub version is often missing.

      5. Picking either the HTML or the epub version is fine as a starting point, but make sure to pick the one that appears to be the most accurate.

      @@ -61,26 +58,26 @@ require_once('Core.php');

      Often you’ll find different editions, published at different times by different publishers, for the same book. It’s worth the effort to quickly browse through each different one to get an idea of the kinds of changes the different publishers introduced. Maybe one edition is better than another!

      -

      You’ll enter a link to the page scans you used in the content.opf metadata as a <dc:source> element.

      +

      You’ll enter a link to the page scans you used in the content.opf metadata as a <dc:source> element.

    5. Create a Standard Ebooks epub skeleton

      An epub file is just a bunch of files arranged in a particular folder structure, then all zipped up. That means editing an epub file is as easy as editing a bunch of text files within a certain folder structure, then creating a zip file out of that folder.

      -

      You can’t just arrange files willy-nilly, though—the epub standard expects certain files in certain places. So once you’ve picked a book to produce, create the basic epub skeleton in a working directory. se create-draft will create a basic Standard Ebooks epub folder structure, initialize a git repository within it, and prefill a few fields in content.opf (the file that contains the ebook’s metadata).

      +

      You can’t just arrange files willy-nilly, though—the epub standard expects certain files in certain places. So once you’ve picked a book to produce, create the basic epub skeleton in a working directory. se create-draft will create a basic Standard Ebooks epub folder structure, initialize a Git repository within it, and prefill a few fields in content.opf (the file that contains the ebook’s metadata).

      1. -

        With the --pg-url option

        -

        You can pass se create-draft the URL for the Project Gutenberg ebook, and it’ll try to download the ebook into ./src/epub/text/body.xhtml and prefill a lot of metadata for you:

        se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde" --pg-url="https://www.gutenberg.org/ebooks/43" cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/ -

        Because Project Gutenberg ebooks are produced in different ways by different people, se create-draft has to make some guesses and it might guess wrong. Make sure to carefully review the data it prefills into ./src/epub/text/body.xhtml, ./src/epub/text/colophon.xhtml, and ./src/epub/content.opf.

        +

        With the --pg-url option

        +

        You can pass se create-draft the URL for the Project Gutenberg ebook, and it’ll try to download the ebook into ./src/epub/text/body.xhtml and prefill a lot of metadata for you:

        se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde" --pg-url="https://www.gutenberg.org/ebooks/43" cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/ +

        Because Project Gutenberg ebooks are produced in different ways by different people, se create-draft has to make some guesses and it might guess wrong. Make sure to carefully review the data it prefills into ./src/epub/text/body.xhtml, ./src/epub/text/colophon.xhtml, and ./src/epub/content.opf.

        In particular, make sure that the Project Gutenberg license is stripped from ./src/epub/text/body.xhtml, and that the original transcribers in ./src/epub/text/colophon.xhtml and ./src/epub/content.opf are presented correctly.

      2. -

        Without the --pg-url option

        -

        If you prefer to do things by hand, that’s an option too.

        se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde" cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/ -

        Now that we have the skeleton up, we’ll download Gutenberg’s HTML file for Jekyll directly into text/ folder and name it body.xhtml.

        wget -O src/epub/text/body.xhtml https://www.gutenberg.org/files/43/43-h/43-h.htm -

        Many Gutenberg books were produced before UTF-8 became a standard, so we may have to convert to UTF-8 before we start work. First, check the encoding of the file we just downloaded. (Mac OS users, try file -I.)

        file -bi src/epub/text/body.xhtml -

        The output is text/html; charset=iso-8859-1. That’s the wrong encoding!

        -

        We can convert that to UTF-8 with iconv:

        iconv --from-code="ISO-8859-1" --to-code="UTF-8" < src/epub/text/body.xhtml > src/epub/text/tmp mv src/epub/text/tmp src/epub/text/body.xhtml +

        Without the --pg-url option

        +

        If you prefer to do things by hand, that’s an option too.

        se create-draft --author="Robert Louis Stevenson" --title="The Strange Case of Dr. Jekyll and Mr. Hyde" cd robert-louis-stevenson_the-strange-case-of-dr-jekyll-and-mr-hyde/ +

        Now that we have the skeleton up, we’ll download Gutenberg’s HTML file for Jekyll directly into text/ folder and name it body.xhtml.

        wget -O src/epub/text/body.xhtml "https://www.gutenberg.org/files/43/43-h/43-h.htm" +

        Many Gutenberg books were produced before UTF-8 became a standard, so we may have to convert to UTF-8 before we start work. First, check the encoding of the file we just downloaded. (Mac OS users, try file -I.)

        file -bi src/epub/text/body.xhtml +

        The output is text/html; charset=iso-8859-1. That’s the wrong encoding!

        +

        We can convert that to UTF-8 with iconv:

        iconv --from-code="ISO-8859-1" --to-code="UTF-8" < src/epub/text/body.xhtml > src/epub/text/tmp mv src/epub/text/tmp src/epub/text/body.xhtml
      6. @@ -101,57 +98,60 @@ require_once('Core.php');

      This edition of Jekyll includes a table of contents; remove that too. Standard Ebooks uses the ToC generated by the ereader, and doesn’t include one in the readable text.

    6. -

      Remove any footer text and markup after the public domain text ends. This includes the Gutenberg license—but don’t worry, we’ll credit Gutenberg in the colophon and metadata later. If you invoked se create-draft with the --pg-url option, then it may have already stripped the license for you and included some Gutenberg metadata.

      +

      Remove any footer text and markup after the public domain text ends. This includes the Gutenberg license—but don’t worry, we’ll credit Gutenberg in the colophon and metadata later. If you invoked se create-draft with the --pg-url option, then it may have already stripped the license for you and included some Gutenberg metadata.

      7. Now our source file looks something like this:

      - <h2> STORY OF THE DOOR </h2> -<p> Mr. Utterson the lawyer was a man of a rugged countenance that was never lighted by a smile; cold, scanty and embarrassed in discourse; backward in <!--snip all the way to the end...--> proceed to seal up my confession, I bring the life of that unhappy Henry Jekyll to an end. </p> +
      <h2> STORY OF THE DOOR </h2> +<p> Mr. Utterson the lawyer was a man of a rugged countenance that was never lighted by a smile; cold, scanty and embarrassed in discourse; backward in +<!--snip all the way to the end...--> +proceed to seal up my confession, I bring the life of that unhappy Henry Jekyll to an end. </p>
      +

      Now that we’ve removed all the cruft from the top and bottom of the file, we’re ready for our first commit.

      -

      Please use the following commit message for consistency with the rest of our ebooks:

      git add -A git commit -m "Initial commit" +

      Please use the following commit message for consistency with the rest of our ebooks:

      git add -A git commit -m "Initial commit"

    7. Split the source text at logical divisions

      The file we downloaded contains the entire work. Jekyll is a short work, but for longer work it quickly becomes impractical to have the entire text in one file. Not only is it a pain to edit, but ereaders often have trouble with extremely large files.

      The next step is to split the file at logical places; that usually means at each chapter break. For works that are contain their chapters in larger “parts,” the part division should also be its own file. For example, see Treasure Island.

      -

      To split the work, we use se split-file. se split-file takes a single file and breaks it in to a new file every time it encounters the markup <!--se:split-->. se split-file automatically includes basic header and footer markup in each split file.

      -

      Notice that in our source file, each chapter is marked with an h2 tag. We can use that to our advantage and save ourselves the trouble of adding the <!--se:split--> markup by hand:

      perl -pi -e "s/<h2/<\!--se:split--><h2/g" src/epub/text/body.xhtml +

      To split the work, we use se split-file. se split-file takes a single file and breaks it in to a new file every time it encounters the markup <!--se:split-->. se split-file automatically includes basic header and footer markup in each split file.

      +

      Notice that in our source file, each chapter is marked with an <h2> tag. We can use that to our advantage and save ourselves the trouble of adding the <!--se:split--> markup by hand:

      perl -pi -e "s|<h2|<\!--se:split--><h2|g" src/epub/text/body.xhtml

      (Note the slash before the ! for compatibility with some shells.)

      -

      Now that we’ve added our markers, we split the file. se split-file puts the results in our current directory and conveniently names them by chapter number.

      se split-file src/epub/text/body.xhtml mv chapter* src/epub/text/ -

      Once we’re happy that the source file has been split correctly, we can remove it.

      rm src/epub/text/body.xhtml +

      Now that we’ve added our markers, we split the file. se split-file puts the results in our current directory and conveniently names them by chapter number.

      se split-file src/epub/text/body.xhtml mv chapter* src/epub/text/ +

      Once we’re happy that the source file has been split correctly, we can remove it.

      rm src/epub/text/body.xhtml

    8. Clean up the source text

      If you open up any of the chapter files we now have in the src/epub/text/ folder, you’ll notice that the code isn’t very clean. Paragraphs are split over multiple lines, indentation is all wrong, and so on.

      If you try opening a chapter in a web browser, you’ll also likely get an error if the chapter includes any HTML entities, like &mdash;. This is because Gutenberg uses plain HTML, which allows entities, but epub uses XHTML, which doesn’t.

      -

      We can fix all of this pretty quickly using se clean. se clean accepts as its argument the root of a Standard Ebook directory, and with the --single-lines option it’ll remove the hard line wrapping that Gutenberg is fond of. We’re already in the root, so we pass it ..

      se clean --single-lines . -

      Things look much better now, but we’re not perfect yet. If you open a chapter you’ll notice that the <p> and <h2> tags have a space between the tag and the text. We can clean that up with a few perl commands.

      perl -pi -e "s/<(p|h2)>\s+/<\1>/g" src/epub/text/chapter* perl -pi -e "s/\s+<\/(p|h2)>/<\/\1>/g" src/epub/text/chapter* -

      Finally, we have to do a quick runthrough of each file by hand to cut out any lingering Gutenberg markup that doesn’t belong. In Jekyll, notice that each chapter ends with some extra empty <div>s and <p>s. These were used by the original transcriber to put spaces between the chapters, and they’re not necessary anymore, so remove them before continuing.

      +

      We can fix all of this pretty quickly using se clean. se clean accepts as its argument the root of a Standard Ebook directory, and with the --single-lines option it’ll remove the hard line wrapping that Gutenberg is fond of. We’re already in the root, so we pass it ..

      se clean --single-lines . +

      Things look much better now, but we’re not perfect yet. If you open a chapter you’ll notice that the <p> and <h2> tags have a space between the tag and the text. We can clean that up with a few perl commands.

      perl -pi -e "s|<(p|h2)>\s+|<\1>|g" src/epub/text/chapter* perl -pi -e "s|\s+</(p|h2)>|</\1>|g" src/epub/text/chapter* +

      Finally, we have to do a quick runthrough of each file by hand to cut out any lingering Gutenberg markup that doesn’t belong. In Jekyll, notice that each chapter ends with some extra empty <div>s and <p>s. These were used by the original transcriber to put spaces between the chapters, and they’re not necessary anymore, so remove them before continuing.

      Now our chapter 1 source looks like this:

      - <?xml version="1.0" encoding="utf-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US"> -<head> - <title>Chapter 1</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> -</head> -<body epub:type="bodymatter z3998:fiction"> - <section id="chapter-1" epub:type="chapter"> - <h2>STORY OF THE DOOR</h2> - <p>Mr. Utterson the lawyer was a man of a rugged countenance...</p> - <!--snip all the way to the end...--> - <p>"With all my heart," said the lawyer. "I shake hands on that, Richard."</p> - </section> -</body> -</html> -

      If you look carefully, you’ll notice that the <html> tag has the xml:lang="en-US" attribute, even though our source text uses British spelling! We have to change the xml:lang attribute for the source files to match the actual language, which in this case is en-GB. Let’s do that now:

      perl -pi -e "s|en-US|en-GB|g" src/epub/text/chapter* +
      <?xml version="1.0" encoding="utf-8"?> +<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US"> +<head> + <title>Chapter 1</title> + <link href="../css/core.css" rel="stylesheet" type="text/css"/> + <link href="../css/local.css" rel="stylesheet" type="text/css"/> +</head> +<body epub:type="bodymatter z3998:fiction"> + <section id="chapter-1" epub:type="chapter"> + <h2>STORY OF THE DOOR</h2> + <p>Mr. Utterson the lawyer was a man of a rugged countenance...</p> + <!--snip all the way to the end...--> + <p>"With all my heart," said the lawyer. "I shake hands on that, Richard."</p> + </section> +</body> +</html>
      +

      If you look carefully, you’ll notice that the <html> tag has the xml:lang="en-US" attribute, even though our source text uses British spelling! We have to change the xml:lang attribute for the source files to match the actual language, which in this case is en-GB. Let’s do that now:

      perl -pi -e "s|en-US|en-GB|g" src/epub/text/chapter*

      Note that we don’t change the language for the metadata or front/back matter files, like content.opf, titlepage.xhtml, or colophon.xhtml. Those must always be in American spelling, so they’ll always have the en-US language tag.

    9. Typogrify the source text and perform the second commit

      -

      Now that we have a clean starting point, we can start getting the real work done. se typogrify can do a lot of the heavy lifting necessary to bring an ebook up to Standard Ebooks typography standards.

      -

      Like se clean, se typogrify accepts as its argument the root of a Standard Ebook directory.

      se typogrify . -

      Among other things, se typogrify does the following:

      +

      Now that we have a clean starting point, we can start getting the real work done. se typogrify can do a lot of the heavy lifting necessary to bring an ebook up to Standard Ebooks typography standards.

      +

      Like se clean, se typogrify accepts as its argument the root of a Standard Ebook directory.

      se typogrify . +

      Among other things, se typogrify does the following:

      • Converts straight quotes to curly quotes;

        @@ -166,124 +166,133 @@ require_once('Core.php');

        Normalizes spacing in em-, en-, and double-em-dashes, as well as between nested quotation marks, and adds word joiners.

      -

      You can run se typogrify as many times as you want on a source directory; it should always produce the same result, regardless of what state the source directory was in when you ran it.

      -

      While se typogrify does a lot of work for you, each ebook is totally different so there’s almost always more work to do that can only be done by hand. In Jekyll, you’ll notice that the chapter titles are in all caps. The SE standard requires chapter titles to be in title case, and se titlecase can do that for us.

      -

      se titlecase accepts a string as its argument, and outputs the string in title case. Many text editors allow you to configure external macros—perfect for creating a keyboard shortcut to run se titlecase on selected text.

      +

      You can run se typogrify as many times as you want on a source directory; it should always produce the same result, regardless of what state the source directory was in when you ran it.

      +

      While se typogrify does a lot of work for you, each ebook is totally different so there’s almost always more work to do that can only be done by hand. In Jekyll, you’ll notice that the chapter titles are in all caps. The SE standard requires chapter titles to be in title case, and se titlecase can do that for us.

      +

      se titlecase accepts a string as its argument, and outputs the string in title case. Many text editors allow you to configure external macros—perfect for creating a keyboard shortcut to run se titlecase on selected text.

      Typography checklist

      -

      There are many things that se typogrify isn’t well suited to do automatically. Check our complete typography manual to see exactly how to format the work. Below is a brief, but incomplete, list of common issues that arise in ebooks:

      +

      There are many things that se typogrify isn’t well suited to do automatically. Check our complete typography manual to see exactly how to format the work. Below is a brief, but incomplete, list of common issues that arise in ebooks:

      • -

        Typography rules for coordinates. Use the prime and double prime glyphs for coordinates. These regexes helps match and replace coordinates: |([0-9])+’|\1′|g, |([0-9])+”|\1″|g

        +

        Typography rules for coordinates. Use the prime and double prime glyphs for coordinates. These regexes helps match and replace coordinates: |([0-9])+’|\1′|g, |([0-9])+”|\1″|g

      • -

        Typography rules for ampersands in names. This regex helps match candidates: [a-zA-Z]\.?\s*&\s*[a-zA-Z]

        +

        Typography rules for ampersands in names. This regex helps match candidates: [a-zA-Z]\.?\s*&\s*[a-zA-Z]

      • -

        Typography rules for text in all caps. Text in all caps is almost never correct, and should either be converted to lowercase with the <em> tag (for spoken emphasis), <strong> (for extreme spoken emphasis), or <b> (for unsemantic small caps, like in storefront signs). This case-sensitive regex helps find candidates: (?<!en-)(?<!z3998:roman">)(?<![A-Z])[A-Z]{2,}(?!")

        +

        Typography rules for text in all caps. Text in all caps is almost never correct, and should either be converted to lowercase with the <em> tag (for spoken emphasis), <strong> (for extreme spoken emphasis), or <b> (for unsemantic small caps, like in storefront signs). This case-sensitive regex helps find candidates: (?<!en-)(?<!z3998:roman">)(?<![A-Z])[A-Z]{2,}(?!")

      • -

        Sometimes se typogrify doesn’t close quotation marks near em-dashes correctly. Try to find such instances with this regex: —[’”][^<\s]

        +

        Sometimes se typogrify doesn’t close quotation marks near em-dashes correctly. Try to find such instances with this regex: —[’”][^<\s]

      • -

        Two-em dashes should be used for elision.

        +

        Two-em dashes should be used for elision.

      • Commas and periods should generally be inside quotation marks, not outside. This regex helps find them: [’”][,.]

      The second commit

      -

      Once you’ve run se typogrify and you’ve searched the work for the common issues above, you can perform your second commit.

      git add -A git commit -m "Typogrify" +

      Once you’ve run se typogrify and you’ve searched the work for the common issues above, you can perform your second commit.

      git add -A git commit -m "Typogrify"

    10. Convert footnotes to endnotes and add a list of illustrations

      Works often include footnotes, either added by an annotator or as part of the work itself. Since ebooks don’t have a concept of a “page,” there’s no place for footnotes to go. Instead, we convert footnotes to a single endnotes file, which will provide popup references in the final epub.

      The endnotes file and the format for endnote links are standardized in the semantics manual.

      -

      If you find that you accidentally mis-ordered an endnote, never fear! se reorder-endnotes will allow you to quickly rearrange endnotes in your ebook.

      +

      If you find that you accidentally mis-ordered an endnote, never fear! se reorder-endnotes will allow you to quickly rearrange endnotes in your ebook.

      If a work has illustrations besides the cover and title pages, we include a “list of illustrations” at the end of the book, after the endnotes but before the colophon. The LoI file is also standardized in the semantics manual.

      Jekyll doesn’t have any footnotes, endnotes, or illustrations, so we skip this step.

    11. Converting British quotation to American quotation

      If the work you’re producing uses British quotation style (single quotes for dialog versus double quotes in American), we have to convert it to American style. We use American style in part because it’s easier to programmatically convert from American to British than it is to convert the other way around. Skip this step if your work is already in American style.

      -

      se british2american attempts to automate the conversion. Your work must already be typogrified (the previous step in this guide) for the script to work.

      se british2american . -

      While se british2american tries its best, thanks to the quirkiness of English punctuation rules it’ll invariably mess some stuff up. Proofreading is required after running the conversion.

      -

      After you’ve run the conversion, do another commit.

      git add -A git commit -m "Convert from British-style quotation to American style" +

      se british2american attempts to automate the conversion. Your work must already be typogrified (the previous step in this guide) for the script to work.

      se british2american . +

      While se british2american tries its best, thanks to the quirkiness of English punctuation rules it’ll invariably mess some stuff up. Proofreading is required after running the conversion.

      +

      After you’ve run the conversion, do another commit.

      git add -A git commit -m "Convert from British-style quotation to American style"

      This regex is useful for spotting incorrectly converted quotes next to em dashes: “[^”‘]+’⁠—(?=[^”]*?</p>;)

    12. Add semantics

      -

      Part of the Standard Ebooks project is adding meaningful semantics wherever possible in the text. se semanticate does a little of that for us—for example, for some common abbreviations—but much of it has to be done by hand.

      +

      Part of the Standard Ebooks project is adding meaningful semantics wherever possible in the text. se semanticate does a little of that for us—for example, for some common abbreviations—but much of it has to be done by hand.

      Adding semantics means two things:

      1. -

        Using meaningful tags to mark up the work: <em> when conveying emphatic speech instead of <i>, <abbr> to wrap abbreviations, <section> to mark structural divisions, using the xml:lang attribute to specify the language of a word or passage, and so on.

        +

        Using meaningful tags to mark up the work: <em> when conveying emphatic speech instead of <i>, <abbr> to wrap abbreviations, <section> to mark structural divisions, using the xml:lang attribute to specify the language of a word or passage, and so on.

      2. Using the epub3 semantic inflection language to add deeper meaning to tags.

        Currently we use a mix of epub3 structural semantics, z3998 structural semantics for when the epub3 vocabulary isn’t enough, and our own SE semantics for when z3998 isn’t enough.

      -

      Use se semanticate to do some common cases for you:

      se semanticate . -

      se semanticate tries its best to correctly add semantics, but sometimes it’s wrong. For that reason you should review the changes it made before accepting them:

      git difftool +

      Use se semanticate to do some common cases for you:

      se semanticate . +

      se semanticate tries its best to correctly add semantics, but sometimes it’s wrong. For that reason you should review the changes it made before accepting them:

      git difftool

      Beyond that, adding semantics is mostly a by-hand process. See our semantics manual for a detailed list of the kinds of semantics we expect in a Standard Ebook.

      Here’s a short list of some of the more common semantic issues you’ll encounter:

      • -

        Semantics for italics: <em> should be used for when a passage is emphasized, as in when dialog is shouted or whispered. <i> is used for all other italics, with the appropriate semantic inflection. Older transcriptions usually use just <i> for both, so you must change them manually if necessary.

        +

        Semantics for italics: <em> should be used for when a passage is emphasized, as in when dialog is shouted or whispered. <i> is used for all other italics, with the appropriate semantic inflection. Older transcriptions usually use just <i> for both, so you must change them manually if necessary.

      • -

        Semantics rules for chapter titles.

        +

        Semantics rules for chapter titles.

      • -

        Semantics rules for abbreviations. Abbreviations should always be wrapped in the <abbr> tag and with the correct class attribute.

        -

        Specifically, see the typography rules for initials. Wrap people’s initials in <abbr class="name">. This regex helps match initials: [A-Z]\.\s*([A-Z]\.\s*)+

        +

        Semantics rules for abbreviations. Abbreviations should always be wrapped in the <abbr> tag and with the correct class attribute.

        +

        Specifically, see the typography rules for initials. Wrap people’s initials in <abbr class="name">. This regex helps match initials: [A-Z]\.\s*([A-Z]\.\s*)+

      • -

        Typography rules for times. Wrap a.m. and p.m. in <abbr class="time"> and add a no-break space between digits and a.m. or p.m.

        +

        Typography rules for times. Wrap a.m. and p.m. in <abbr class="time"> and add a no-break space between digits and a.m. or p.m.

      • -

        Words or phrases in foreign languages should always be marked up with <i xml:lang="TAG">, where TAG is an IETF language tag. This app can help you look them up. If the text uses fictional or unspecific languages, use the “x-” prefix and make up a subtag yourself.

        +

        Words or phrases in foreign languages should always be marked up with <i xml:lang="TAG">, where TAG is an IETF language tag. This app can help you look them up. If the text uses fictional or unspecific languages, use the “x-” prefix and make up a subtag yourself.

      • -

        Semantics for poetry, verse, and song: Many Gutenberg productions use the <pre> tag to format poetry, verse, and song. This is, of course, semantically incorrect. See the Poetry section of our semantics manual for templates on how to semantically format poetry, verse, and song.

        +

        Semantics for poetry, verse, and song: Many Gutenberg productions use the <pre> tag to format poetry, verse, and song. This is, of course, semantically incorrect. See the Poetry section of our semantics manual for templates on how to semantically format poetry, verse, and song.

      -

      After you’ve added semantics according to the semantics manual, do another commit.

      git add -A git commit -m "Semanticate" +

      After you’ve added semantics according to the semantics manual, do another commit.

      git add -A git commit -m "Semanticate" +
      13. +
    13. +

      Set <title> elements

      +

      After you’ve added semantics and correctly marked up section headers, it’s time to update the <title> elements in each chapter to match their expected values.

      +

      The se print-title tool takes a well-marked-up section header from a file, and prints the expected value for the <title> element to the terminal. It also has the --in-place optoin, which will allow us to update all the chapters at once:

      + se print-title --in-place src/epub/text/* +

      Once you’ve verified the titles look good, commit:

      + git add -A git commit -m "Add titles" +

    14. Modernize spelling and hyphenation

      -

      Many older works use outdated spelling and hyphenation that would distract a modern reader. (For example, “to-night” instead of “tonight”). se modernize-spelling automatically removes hyphens from words that used to be compounded, but aren’t anymore in modern English spelling.

      -

      Do run this tool on prose. Don’t run this tool on poetry.

      se modernize-spelling . +

      Many older works use outdated spelling and hyphenation that would distract a modern reader. (For example, “to-night” instead of “tonight”). se modernize-spelling automatically removes hyphens from words that used to be compounded, but aren’t anymore in modern English spelling.

      +

      Do run this tool on prose. Don’t run this tool on poetry.

      se modernize-spelling .

      After you run the tool, you must check what the tool did to confirm that each removed hyphen is correct. Sometimes the tool will remove a hyphen that needs to be included for clarity, or one that changes the meaning of the word, or it may result in a word that just doesn’t seem right. Re-introducing a hyphen is OK in these cases.

      -

      Here’s a real-world example of where se modernize-spelling made the wrong choice: In The Picture of Dorian Gray chapter 11, Oscar Wilde writes:

      +

      Here’s a real-world example of where se modernize-spelling made the wrong choice: In The Picture of Dorian Gray chapter 11, Oscar Wilde writes:

      He possessed a gorgeous cope of crimson silk and gold-thread damask…

      -

      se modernize-spelling would replace the dash in gold-thread so that it reads goldthread. Well goldthread is an actual word, which is why it’s in our dictionary, and why the script makes a replacement—but it’s the name of a type of flower, not a golden fabric thread! In this case, se modernize-spelling made an incorrect replacement, and we have to change it back.

      -

      git provides a handy way for us to visualize these differences:

      git difftool +

      se modernize-spelling would replace the dash in gold-thread so that it reads goldthread. Well goldthread is an actual word, which is why it’s in our dictionary, and why the script makes a replacement—but it’s the name of a type of flower, not a golden fabric thread! In this case, se modernize-spelling made an incorrect replacement, and we have to change it back.

      +

      git provides a handy way for us to visualize these differences:

      git difftool

      After you’ve reviewed the changes that the tool made, do another commit. This commit is important, because it gives purists an avenue to revert modernizing changes to the original text.

      -

      Note how we preface this commit with “[Editorial]”. Any change you make to the source text that can be considered a modernization or editorial change should be prefaced like this, so that the git history can be easily searched by people looking to revert changes.

      git commit -am "[Editorial] Modernize hyphenation and spelling" +

      Note how we preface this commit with “[Editorial]”. Any change you make to the source text that can be considered a modernization or editorial change should be prefaced like this, so that the git history can be easily searched by people looking to revert changes.

      git commit -am "[Editorial] Modernize hyphenation and spelling"

    15. Modernize spacing in select words

      Over time, spelling of certain common two-word phrases has evolved into a single word. For example, “someone” used to be the two-word phrase “some one,” which would read awkwardly to modern readers. This is our chance to modernize such phrases.

      -

      Note that we use se interactive-sr to perform an interactive search and replace, instead of doing a global, non-interactive search and replace. This is because some phrases caught by the regular expression should not be changed, depending on context. For example, "some one" in the following snippet from Anton Chekhov’s short fiction should not be corrected:

      +

      Note that we use se interactive-sr to perform an interactive search and replace, instead of doing a global, non-interactive search and replace. This is because some phrases caught by the regular expression should not be changed, depending on context. For example, "some one" in the following snippet from Anton Chekhov’s short fiction should not be corrected:

      He wanted to think of some one part of nature as yet untouched...

      Use the following regular expression invocations to correct a certain set of such phrases:

      - se interactive-sr "/\v([Ss])ome one/\1omeone/" src/epub/text/* git commit -am "[Editorial] some one -> someone" - se interactive-sr "/\v(<[Aa])ny one/\1nyone/" src/epub/text/* git commit -am "[Editorial] any one -> anyone" - se interactive-sr "/\v([Ee])very one(\s+of)@\!/\1veryone/" src/epub/text/* git commit -am "[Editorial] every one -> everyone" - se interactive-sr "/\v([Ee])very thing/\1verything/" src/epub/text/* git commit -am "[Editorial] every thing -> everything" - se interactive-sr "/\v(<[Aa])ny thing/\1nything/" src/epub/text/* git commit -am "[Editorial] any thing -> anything" - se interactive-sr "/\v([Ff])or ever(>)/\1orever\2/" src/epub/text/* git commit -am "[Editorial] for ever -> forever" - se interactive-sr "/\v(in\s+)@<\!(<[Aa])ny way/\2nyway/" src/epub/text/* git commit -am "[Editorial] any way -> anyway" - se interactive-sr "/\v([Yy])our self/\1ourself/" src/epub/text/* git commit -am "[Editorial] your self -> yourself" - se interactive-sr "/\v([Mm])ean time/\1eantime/" src/epub/text/* git commit -am "[Editorial] mean time -> meantime" - se interactive-sr "/\v([Aa])ny how/\1nyhow/" src/epub/text/* git commit -am "[Editorial] any how -> anyhow" - se interactive-sr "/\v([Aa])ny body/\1nybody/" src/epub/text/* git commit -am "[Editorial] any body -> anybody" - se interactive-sr "/\v([Ee])very body/\1verybody/" src/epub/text/* git commit -am "[Editorial] every body -> everybody" + se interactive-sr "/\v([Ss])ome one/\1omeone/" src/epub/text/* git commit -am "[Editorial] some one -> someone" + se interactive-sr "/\v(<[Aa])ny one/\1nyone/" src/epub/text/* git commit -am "[Editorial] any one -> anyone" + se interactive-sr "/\v([Ee])very one(\s+of)@\!/\1veryone/" src/epub/text/* git commit -am "[Editorial] every one -> everyone" + se interactive-sr "/\v([Ee])very thing/\1verything/" src/epub/text/* git commit -am "[Editorial] every thing -> everything" + se interactive-sr "/\v(<[Aa])ny thing/\1nything/" src/epub/text/* git commit -am "[Editorial] any thing -> anything" + se interactive-sr "/\v([Ff])or ever(>)/\1orever\2/" src/epub/text/* git commit -am "[Editorial] for ever -> forever" + se interactive-sr "/\v(in\s+)@<\!(<[Aa])ny way/\2nyway/" src/epub/text/* git commit -am "[Editorial] any way -> anyway" + se interactive-sr "/\v([Yy])our self/\1ourself/" src/epub/text/* git commit -am "[Editorial] your self -> yourself" + se interactive-sr "/\v([Mm])ean time/\1eantime/" src/epub/text/* git commit -am "[Editorial] mean time -> meantime" + se interactive-sr "/\v([Aa])ny how/\1nyhow/" src/epub/text/* git commit -am "[Editorial] any how -> anyhow" + se interactive-sr "/\v([Aa])ny body/\1nybody/" src/epub/text/* git commit -am "[Editorial] any body -> anybody" + se interactive-sr "/\v([Ee])very body/\1verybody/" src/epub/text/* git commit -am "[Editorial] every body -> everybody"

    16. Create the cover image

      @@ -323,46 +332,46 @@ require_once('Core.php');

      cover.jpg is the scaled cover image that cover.svg links to. This file is exactly 1400 × 2100. For Jekyll, this is a crop of cover.source.jpg that includes just the lab equipment, and resized up to our target resolution.

    17. -

      cover.svg is the completed cover image with the title and author. se build-images will take cover.svg, embed cover.jpg, convert the text to paths, and place the result in ./src/epub/images/ for inclusion in the final epub.

      +

      cover.svg is the completed cover image with the title and author. se build-images will take cover.svg, embed cover.jpg, convert the text to paths, and place the result in ./src/epub/images/ for inclusion in the final epub.

    18. Create the titlepage image, build both the cover and titlepage, and commit

      Titlepage images for Standard Ebooks books are also standardized. See our the art manual for details.

      -

      se create-draft already created a completed titlepage for you. If the way it arranged the lines doesn’t look great, you can always edit the titlepage to make the arrangement of words on each line more aesthetically pleasing. Don’t use a vector editing program like Inkscape to edit it. Instead, open it up in your favorite text editor and type the values in directly.

      -

      The source images for both the cover and the titlepage are kept in ./images/. Since the source images refer to installed fonts, and since we can’t include those fonts in our final ebook without having to include a license, we have to convert that text to paths for final distribution. se build-images does just that.

      se build-images . -

      se build-images takes both ./images/cover.svg and ./images/titlepage.svg, converts text to paths, and embeds the cover jpg. The output goes to ./src/epub/images/.

      -

      Once we built the images successfully, perform a commit.

      git add -A git commit -m "Add cover and titlepage images" +

      se create-draft already created a completed titlepage for you. If the way it arranged the lines doesn’t look great, you can always edit the titlepage to make the arrangement of words on each line more aesthetically pleasing. Don’t use a vector editing program like Inkscape to edit it. Instead, open it up in your favorite text editor and type the values in directly.

      +

      The source images for both the cover and the titlepage are kept in ./images/. Since the source images refer to installed fonts, and since we can’t include those fonts in our final ebook without having to include a license, we have to convert that text to paths for final distribution. se build-images does just that.

      se build-images . +

      se build-images takes both ./images/cover.svg and ./images/titlepage.svg, converts text to paths, and embeds the cover jpg. The output goes to ./src/epub/images/.

      +

      Once we built the images successfully, perform a commit.

      git add -A git commit -m "Add cover and titlepage images"

    19. Complete content.opf

      content.opf is the file that contains the ebook metadata like author, title, description, and reading order. Most of it will be filling in that basic information, and including links to various resources related to the text.

      The content.opf is standardized. Please see our extensive Metadata Manual for details on how to fill out content.opf.

      -

      As you complete the metadata, you’ll have to order the spine and the manifest in this file. Fortunately, Standard Ebooks tools for that too: se print-manifest and se print-spine. Run these on our source directory and, as you can guess, they’ll print out the <manifest> and <spine> tags for this work.

      -

      If you’re using a Mac, and thus the badly-behaved Finder program, you may find that it has carelessly polluted your work directory with useless .DS_Store files. Before continuing, you should find a better file manager program, then delete all of that litter with the following command. Otherwise, se print-manifest and se print-spine will include that litter in its output and your epub won’t be valid.

      - find . -name ".DS_Store" -type f -delete -

      Since this is the first time we’re editing content.opf, we’re OK with replacing both the manifest and spine tags with a guess at the correct contents. We can do this using the --in-place option. If we have to update the manifest or spine later, we can omit the option to print to standard output instead of altering content.opf directly.

      +

      As you complete the metadata, you’ll have to order the spine and the manifest in this file. Fortunately, Standard Ebooks tools for that too: se print-manifest and se print-spine. Run these on our source directory and, as you can guess, they’ll print out the <manifest> and <spine> elements for this work.

      +

      If you’re using a Mac, and thus the badly-behaved Finder program, you may find that it has carelessly polluted your work directory with useless .DS_Store files. Before continuing, you should find a better file manager program, then delete all of that litter with the following command. Otherwise, se print-manifest and se print-spine will include that litter in its output and your epub won’t be valid.

      + find . -name ".DS_Store" -type f -delete +

      Since this is the first time we’re editing content.opf, we’re OK with replacing both the manifest and spine elements with a guess at the correct contents. We can do this using the --in-place option. If we have to update the manifest or spine later, we can omit the option to print to standard output instead of altering content.opf directly.

      - se print-manifest --in-place . - se print-spine --in-place . + se print-manifest --in-place . + se print-spine --in-place . -

      The manifest is already in the correct order and doesn’t need to be edited. The spine, however, will have to be reordered to be in the correct reading order. Once you’ve done that, commit!

      git add -A git commit -m "Complete content.opf" +

      The manifest is already in the correct order and doesn’t need to be edited. The spine, however, will have to be reordered to be in the correct reading order. Once you’ve done that, commit!

      git add -A git commit -m "Complete content.opf"

    20. Complete the table of contents

      The table of contents is a structured document that should let the reader easily navigate the book. In a Standard Ebook, it’s stored outside of the readable text directory with the assumption that the reading system will parse it and display a navigable representation for the user.

      -

      Once you’ve completed the <spine> element in content.opf, you can use se print-toc to generate a table of contents for this ebook. Since this is the first time we’re generating a ToC for this ebook, use the --in-place flag to replace the template ToC file with the generated ToC.

      - se print-toc --in-place . -

      Review the generated ToC in ./src/epub/toc.xhtml to make sure se print-toc did the right thing. se print-toc is valuable tool to discover structural problems in your ebook. If an entry is arranged in a way you weren’t expecting, perhaps the problem isn’t with se print-toc, but with your HTML code—be careful! You may have to make changes by hand for complex or unusual books.

      +

      Once you’ve completed the <spine> element in content.opf, you can use se print-toc to generate a table of contents for this ebook. Since this is the first time we’re generating a ToC for this ebook, use the --in-place flag to replace the template ToC file with the generated ToC.

      + se print-toc --in-place . +

      Review the generated ToC in ./src/epub/toc.xhtml to make sure se print-toc did the right thing. se print-toc is valuable tool to discover structural problems in your ebook. If an entry is arranged in a way you weren’t expecting, perhaps the problem isn’t with se print-toc, but with your HTML code—be careful! You may have to make changes by hand for complex or unusual books.

      Once you’re done, commit:

      - git add -A git commit -m "Add ToC" + git add -A git commit -m "Add ToC"

    21. Complete the colophon

      -

      se create-draft put a skeleton colophon.xhtml file in the ./src/epub/text/ folder. Now that we have the cover image and artist, we can fill out the various fields there. Make sure to credit the original transcribers of the text (generally we assume them to be whoever’s name is on the file we download from Gutenberg) and to include a link back to the Gutenberg text we used, along with a link to any scans we used (from archive.org or hathitrust.org, for example).

      +

      se create-draft put a skeleton colophon.xhtml file in the ./src/epub/text/ folder. Now that we have the cover image and artist, we can fill out the various fields there. Make sure to credit the original transcribers of the text (generally we assume them to be whoever’s name is on the file we download from Gutenberg) and to include a link back to the Gutenberg text we used, along with a link to any scans we used (from archive.org or hathitrust.org, for example).

      You can also include your own name as the producer of this Standard Ebooks edition. Besides that, the colophon is standardized; don’t get too creative with it.

      -

      The release and updated dates should be the same for the first release, and they should match the dates in content.opf. For now, leave them unchanged, as se prepare-releasegit add -A git commit -m "Complete the colophon" +

      The release and updated dates should be the same for the first release, and they should match the dates in content.opf. For now, leave them unchanged, as se prepare-release will automatically fill them in for you as we’ll describe later in this guide.

      git add -A git commit -m "Complete the colophon"

    22. Complete the imprint

      @@ -371,15 +380,15 @@ require_once('Core.php');

    23. Clean and lint before building

      Before you build the final ebook for you to proofread, it’s a good idea to check the ebook for some common problems you might run in to during production.

      -

      First, run se clean one more time to both clean up the source files, and to alert you if there are XHTML parsing errors. Even though we ran se clean before, it’s likely that in the course of production the ebook got in to less-than-perfect markup formatting. Remember you can run se clean as many times as you want—it should always produce the same output.

      - se clean . -

      Now, run se lint. If your ebook has any problems, you’ll see some output listing them. If everything’s OK, then se lint will complete silently.

      - se lint . +

      First, run se clean one more time to both clean up the source files, and to alert you if there are XHTML parsing errors. Even though we ran se clean before, it’s likely that in the course of production the ebook got in to less-than-perfect markup formatting. Remember you can run se clean as many times as you want—it should always produce the same output.

      + se clean . +

      Now, run se lint. If your ebook has any problems, you’ll see some output listing them. If everything’s OK, then se lint will complete silently.

      + se lint .

    24. Build and proofread, proofread, proofread!

      -

      At this point we’re just about ready to build our proofreading draft! se build does this for us. We’ll run it with the --check flag to make sure the epub we produced is valid, and with the --kindle and --kobo flag to build a file for Kindles and Kobos too. If you won’t be using a Kindle or Kobo, you can omit those flags.

      - se build --output-dir=$HOME/dist/ --kindle --kobo --check . +

      At this point we’re just about ready to build our proofreading draft! se build does this for us. We’ll run it with the --check flag to make sure the epub we produced is valid, and with the --kindle and --kobo flag to build a file for Kindles and Kobos too. If you won’t be using a Kindle or Kobo, you can omit those flags.

      + se build --output-dir=$HOME/dist/ --kindle --kobo --check .

      If there are no errors, we’ll see five files in the brand-new ~/dist/ folder in our home directory:

      • @@ -398,7 +407,7 @@ require_once('Core.php');

        thumbnail_xxxx_EBOK_portrait.jpg is a thumbnail file you can copy to your Kindle to have the cover art appear in your reader. A bug in Amazon’s software prevents the Kindle from reading cover images in side-loaded files; contact Amazon to complain.

      -

      This is the step where you read the ebook and make adjustments to the text so that it conforms to our typography manual.

      +

      This is the step where you read the ebook and make adjustments to the text so that it conforms to our typography manual.

      All Standard Ebooks productions must be proofread at this stage to confirm that there are no typos, formatting errors, or typography errors. It’s extremely common for transcriptions sourced from Gutenberg to have various typos and formatting errors (like missing italics), and it’s also not uncommon for one of Standard Ebook’s tools to make the wrong guess about things like a closing quotation mark somewhere. As you proofread, it’s extremely handy to have a print copy of the book with you. For famous books that might just be a trip to your local library. For rarer books, or for those without a library nearby, there are several sites that provide free digital scans of public domain writing:

      • @@ -408,27 +417,34 @@ require_once('Core.php');

        The Internet Archive is another collection of scans of public domain books.

      -

      If you end up using scans from one of these sources, you must mention it in the ebook’s colophon and as a <dc:source> item in content.opf.

      +

      If you end up using scans from one of these sources, you must mention it in the ebook’s colophon and as a <dc:source> item in content.opf.

      If you’re using a transcription from Project Gutenberg as the base for this ebook, you may wish to report typos you’ve found to them, so that they can correct their copy. Instructions for how to do so are here.

    25. Initial publication

      Now that we’ve proofread the work and corrected any errors we’ve found, we’re ready to release the finished ebook!

      -

      It’s a good idea to run se typogrify and se clean one more time before releasing. Make sure to review the changes with git difftool before accepting them—se typogrify is usually right, but not always!

      +

      It’s a good idea to run se typogrify and se clean one more time before releasing. Make sure to review the changes with git difftool before accepting them—se typogrify is usually right, but not always!

      • If you’re submitting your ebook to Standard Ebooks for review:

        -

        Don’t run se prepare-release on an ebook you’re submitting for review!

        +

        Don’t run se prepare-release on an ebook you’re submitting for review!

        Contact the mailing list with a link to your GitHub repository to let them know you’re finished. A reviewer will review your production and work with you to fix any issues. They’ll then release the ebook for you.

      • If you’re producing this ebook for yourself, not for release at Standard Ebooks:

        -

        Complete the initial publication by adding a release date, modification date, and final word count to content.opf and colophon.xhtml. se prepare-release does all of that for us.

        - se prepare-release . -

        With that done, we commit again using a commit message of “Initial publication” to signify that we’re all done with production, and now expect only proofreading corrections to be committed. (This may not actually be the case in reality, but it’s still a nice milestone to have.)

        git add -A git commit -m "Initial publication" +

        Complete the initial publication by adding a release date, modification date, and final word count to content.opf and colophon.xhtml. se prepare-release does all of that for us.

        + se prepare-release . +

        With that done, we commit again using a commit message of “Initial publication” to signify that we’re all done with production, and now expect only proofreading corrections to be committed. (This may not actually be the case in reality, but it’s still a nice milestone to have.)

        + + git add -A + git commit -m "Initial publication" +
      -

      Finally, build everything again.

      se build --output-dir=$HOME/dist/ --kindle --kobo --check . +

      Finally, build everything again.

      + + se build --output-dir=$HOME/dist/ --kindle --kobo --check . +

      If the build completed successfully, congratulations! You’ve just finished producing a Standard Ebook!

    diff --git a/www/contribute/semantics.php b/www/contribute/semantics.php deleted file mode 100644 index 6403d9dc..00000000 --- a/www/contribute/semantics.php +++ /dev/null @@ -1,836 +0,0 @@ - 'Structure and Semantics Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Structure and Semantics Manual, containing details on semantic patterns used in ebook production.']) ?> -
    -
    -

    Structure and Semantics Manual

    - -
    -

    General do’s and don’ts

    -
      -
    • -

      Don’t wrap source code to a certain column width. This makes it difficult to search through source code for a particular sentence, because a line break could be anywhere. Instead, use the clean tool in the Standard Ebooks toolset to format XHTML source code, and the word wrap feature in your text editor to make long paragraphs readable in the source code.

      -
      • - -

    • You have the full vocabulary of HTML5 at your disposal, so use semantically-appropriate elements whenever possible. Don’t settle for a <div> when a <blockquote> or <section> would be more descriptive.

      -
      -

      <div class="quotation">

      -

      <blockquote>

      -
      - -

    • Don’t style elements with inline CSS. Prefer clever CSS selectors first, then prefer CSS classes.

      • -

    • When styling with CSS classes, use semantic class names. Name classes based on what they’re styling, not based on a description of how their style looks.

      -
      -

      <div class="small-caps">

      -

      <blockquote class="inscription">

      -
      -
      • -
    • -

      Don’t use <pre> elements to format text requiring tricky spacing, like poetry. There should never be a <pre> element in a Standard Ebook. See the poetry section for patterns to use to format poetry. Anything can be formatted with CSS if you give it a little thought!

      -
      • - -
    -
    -
    -

    Semantic inflection

    -

    The epub spec allows for semantic inflection, which is a way of adding pertinent semantic metadata to certain elements. For example, you may want to convey that the contents of a certain <section> are actually a part of a chapter. You would do that by using the epub:type attribute:

    -
    - <section epub:type="chapter">...</section> -
    -

    The epub spec includes a list of supported keywords that you can use in the epub:type attribute. Many of these keywords apply to content divisions, like chapter breaks, prefaces, introductions, and so on.

    -

    An additional spec, the sexily-named z39.98-2012 Structural Semantics vocabulary, gives us a more robust vocabulary for adding semantic inflection. This vocabulary includes ways of marking fiction vs. non-fiction, letters, poetry, and so on. All Standard Ebooks include a reference to this vocabulary by default, so you should use it if the regular epub vocabulary isn’t enough.

    -

    Finally, Standard Ebooks has its own vocabulary to add even more finely grained semantics. For example, names of ships are italicized with the <i> element. But to convey that the otherwise-meaningless <i> element contains the name of a ship, we would add the Standard Ebooks semantic inflection of se:name.vessel.ship:

    -
    - They set sail on the <abbr class="initialism">HMS</abbr> <i epub:type="se:name.vessel.ship">Bounty</i>. -
    -

    In a perfect world, Standard Ebooks wouldn’t have to maintain its own list of semantic vocabulary. We’re actively looking for a suitable replacement—if you have a suggestion, get in touch!

    -

    Semantic inflection in Standard Ebooks

    -

    Part of the Standard Ebooks mission is to add as much semantic information to ebooks as possible. To that end, use semantic inflection liberally and in detail. Since we have so many vocabulary options to use, use them in this order of preference:

    -
      -
    1. -

      The built-in epub vocabulary. If what you’re trying to mark up is here, use this first.

      -
      2. -
    2. -

      The z3998 vocabulary. If something isn’t included in the regular epub vocabulary, stop here next.

      -
      3. -
    3. -

      The Standard Ebooks vocabulary. If neither the regular epub vocabulary nor the z33998 vocabulary have a keyword you’re looking for, check our own vocabulary. You can also suggest additions to this vocabulary.

      -
      4. -
    -
    -
    -

    XHTML and CSS code formatting style

    -

    In XHTML

    -

    The clean tool does a good job of pretty-printing your XHTML according to our requirements, so make sure to run it often. In case you want to review the style requirements, they are:

    -
      -

    • Use tabs for indentation.

      • -

    • Tags whose content is phrasing content should be on a single line. So, don’t open a <p> tag, then move to the next line for the tag’s contents; put it all on the same line.

      • -

    • Attributes should be in alphabetical order.

      • -
    -

    In CSS

    -
      -

    • Use tabs for indentation.

      • -

    • Always move to a new line for CSS properties. Even if the selector only has one property, don’t put the selector and the property on one line.

      • -

    • Where possible, properties should be in alphabetical order. (This isn’t always possible if you’re attempting to override a previous style in the same selector; in those cases that’s OK.)

      • -
    -
    -
    -

    Abbreviation semantic patterns

    -
      -
    • -

      There are three types of abbreviations:

      -

      An acronym is a term made up of initials and pronounced as one word: NASA, SCUBA, TASER.

      -

      An initialism is a term made up of initials in which each initial is pronounced separately: ABC, HTML, CSS.

      -

      A contraction is an abbreviation of a longer word: Mr., Mrs., lbs.

      -
      • -
    • -

      All abbreviations must be wrapped in an <abbr> element.

      -
      • -
    • -

      All abbreviations that include periods (for example, Latinisms) and terminate a clause must include the “eoc” (end-of-clause) class in the <abbr> element. Since a clause ending in an abbreviation omits the trailing period, it’s useful for us to know when such an abbreviation marks the end of a clause.

      - - - - - - - - - - - - - -
      ResultCode
      - He wanted to meet at 6:40  - p.m. I was excited to see him! - He wanted to meet at 6:40nbsp<abbr class="time eoc">p.m.</abbr> I was excited to see him! -
      -
      • -
    • -

      Certain abbreviations should be marked up with a semantic class:

      -
        -
      • -

        Acronyms

        -

        Any acronym (defined above) that doesn’t fit in the categories below.

        -
        <abbr class="acronym">NASA</abbr> received less funding than usual this year.
        -
        • -
      • -

        Initialisms

        -

        Any initialism (defined above) that doesn’t fit in the categories below.

        -
        There are harder languages than <abbr class="initialism">HTML</abbr>.
        -
        • -
      • -

        Abbreviated compass directions

        -

        For example: N., S., S.W.

        -
        He traveled <abbr class="compass">N. W.</abbr>, then <abbr class="compass eoc">E. S. E.</abbr>
        -

        This regex is helpful in finding compass directions: [NESW]\.([NESW]\.)*?

        -
        • -
      • -

        Compounds

        -

        Molecular compounds.

        -
        <abbr class="compound">H<sub>2</sub>O</abbr>
        -
        • -
      • -

        Academic degrees

        -

        Academic degrees, except ones that, like PhD, include a lowercase letter: BA, BD, BFA, BM, BS, DB, DD, DDS, DO, DVM, JD, LHD, LLB, LLD, LLM, MA, MBA, MD, MFA, MS, MSN.

        -
        Judith Douglas, <abbr class="degree">DDS</abbr>.
        -
        • -
      • -

        Eras

        -

        The abbreviations - AD, - BC, - CE, - BCE.

        -
        Julius Caesar was born around 100 <abbr class="era">BC</abbr>.
        -
        • -
      • -

        Initialized names

        -

        A person’s initials, either first name, last name, or both.

        -
        <abbr class="name">J. P.</abbr> Morgan was a wealthy man.
        -
        • -
      • -

        State names and postal codes

        -

        Abbreviated state names and postal codes: NY, Washington DC.

        -
        Washington <abbr class="postal">DC</abbr>
        -
        • -
      • -

        Temperatures

        -

        Abbreviated temperature scales: F, C. Also see the typography manual.

        -
        It was 5°hairsp<abbr class="temperature">C</abbr> last night.
        -
        • -
      • -

        Times

        -

        Time-related Latinisms: a.m., p.m. Also see the typography manual.

        -
        5nbsp<abbr class="time">p.m.</abbr>
        -
        • -
      • -

        Timezones

        -

        PST, CST, EST, etc.

        -
        5nbsp<abbr class="time">p.m.</abbr> <abbr class="timezone">PST</abbr>
        -
        • -
      -
      • -
    -
    -
    -

    The <title> tag

    -

    The <title> tag should contain an appropriate description of the local file only.

    -

    Titles for files that are an individual chapter

    -

    In most ebook productions, each chapter will be its own file. In that case, follow these rules:

    -
      -

    • Don’t include the book title in individual chapter <title> tags.

      • -

    • Convert chapter numbers that are in Roman numerals to decimal numbers:

      - <title>Chapter 10</title> -
      • - -

    • If a chapter has a subtitle, add a colon after the chapter number and place the subtitle after that:

      - <title>Chapter 10: A Dark and Stormy Night</title> -
      • -

    • Subtitles may often contain subtags, like <i>. Because <title> can’t contain subtags, simply remove them when copying into <title>:

      - <title>Chapter 8: Mobilis in Mobili</title>
      • -
    -
    -
    -

    Ids

    -

    Each <section> should have an id attribute corresponding to a URL-friendly version of the <section>’s name. For example:

    - <section id="introduction" epub:type="introduction"> -<h2 epub:type="title">Introduction</h2> -<!--snip--> -</section> -

    Occasionally you might need to give other elements IDs, for example when an endnote references a specific line or paragraph in the work. In these cases, name the IDs by their tag name, then a dash, then a number representing the tag’s sequential numerical order from the beginning of the containing document.

    - <section id="introduction" epub:type="introduction"> -<h2 epub:type="title">Introduction</h2> -<p>Some text...</p> -<!--snip 10 more <p> tags--> -<p id="p-12">Some text...</p> -</section> - -
    -
    -

    Ordered/numbered and unordered lists

    -

    All <li> children of <ol> and <ul> tags must have at least one direct child block-level tag. This is usually a <p> tag. (But not necessarily; for example, a <blockquote> tag might also be appropriate.)

    - <ul> -<li> - <p><b>Miss Oranthy Bluggage</b>, the accomplished Strong-Minded Lecturer, will deliver her famous Lecture on “<b>Woman and Her Position</b>,” at Pickwick Hall, next Saturday Evening, after the usual performances.</p> -</li> -</ul> -
    -
    -

    Blockquotes

    -

    In most prose works, we generally want to offset long quotations in the <blockquote> element. However, we want to be able to distinguish when a quotation is from a real-life source (like a quotation from a Shakespeare play), and when the quotation is fictional within the context of the work. To make this distinction, we assume that the <blockquote> inherits the z3998:fiction or z3998:non-fiction semantic inflection of its parent. Thus, if the <blockquote> contents differ from that inherited semantic inflection, we specify whether it’s z3998:fiction or z3998:non-fiction in the blockquote element itself.

    -

    For example, if a <blockquote> doesn’t have semantic inflection specified, and it’s within a <section epub:type="z3998:fiction"> parent, then the <blockquote> is also fictional within the context of the work.

    -

    In this first example from Dracula, we have a fictional character quoting a real-life source. Since Dracula is fiction but the quotation source exists in the real world, we include the z3998:non-fiction semantic inflection:

    - <section epub:type="chapter z3998:fiction"> -<p>One of my companions whispered to another the line from Burger’s “Lenore”:―</p> -<blockquote epub:type="z3998:non-fiction"> - <p>“<span xml:lang="de">Denn die Todten reiten schnell</span>”⁠—<br/> - (“For the dead travel fast.”)</p> -</blockquote> -</section> -

    In this second example from Twenty Thousand Leagues Under the Seas, a fictional character quotes another fictional character. We still use the <blockquote> element, but since the work itself is fiction, the <blockquote> “inherits” the semantic inflection of z3998:fiction:

    - <section epub:type="chapter z3998:fiction"> -<p>Every morning, it was repeated under the same circumstances. It ran like this:</p> -<blockquote xml:lang="x-nemo"> - <p>“Nautron respoc lorni virch.”</p> -</blockquote> -</section> -
    -
    -

    Half title pages

    -

    When a work contains frontmatter like an epigraph or introduction, a half title page is required before the body matter begins.

    -

    Half title pages without subtitles

    - <?xml version="1.0" encoding="utf-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> -<head> - <title>Half Title</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> -</head> -<body epub:type="frontmatter"> - <section id="halftitlepage" epub:type="halftitlepage"> - <h1 epub:type="fulltitle">Don Quixote</h1> - </section> -</body> -</html> - -

    Half title pages with subtitles

    - section[epub|type~="halftitlepage"] span[epub|type~="subtitle"]{ -display: block; -font-size: .75em; -font-weight: normal; -} - <?xml version="1.0" encoding="utf-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> -<head> - <title>Half Title</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> -</head> -<body epub:type="frontmatter"> - <section id="halftitlepage" epub:type="halftitlepage"> - <h1 epub:type="fulltitle"> - <span epub:type="title">The Book of Wonder</span> - <span epub:type="subtitle">A Chronicle of Little Adventures at the Edge of the World</span> - </h1> - </section> -</body> -</html> -
    -
    -

    Footnotes and endnotes

    -

    Since there’s no concept of a “page” in an ebook, the concept of “footnotes” isn’t very useful. (Where would a footnote go if there’s no bottom of the page?)

    -

    Modern ereading systems do, however, offer popup notes. Our task is to combine all footnotes present in a source text into a single endnotes file that provides popup notes to supported readers, and clearly listed notes for other readers.

    -

    Endnotes must be numbers that are sequential throughout the entire text. Since many books just used “*” to denote a footnote, when converting to endnotes we have to assign those a number.

    -

    Linking to endnotes

    -

    In the body text, you refer to an endnote using this pattern:

    - <p>This is some text followed by a reference to an endnote.<a href="endnotes.xhtml#note-1" id="noteref-1" epub:type="noteref">1</a></p> -
      -

    • The id attribute is always “noteref-N” where N is the number of the endnote.

      • -

    • The epub:type attribute is set to “noteref”.

      • -

    • The endnote goes after ending punctuation.

      • -
    -

    The endnotes file

    -

    The endnotes file is called endnotes.xhtml and looks like this:

    - <?xml version="1.0" encoding="utf-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> -<head> - <title>Endnotes</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> -</head> -<body epub:type="backmatter z3998:fiction"> - <section id="endnotes" epub:type="endnotes"> - <h2 epub:type="title">Endnotes</h2> - <ol> - <li id="note-1" epub:type="endnote"> - <p>The first endnote goes here.</p> - <p>Here's another line for the first endnote. <a href="chapter-1.xhtml#noteref-1" epub:type="backlink">↩</a></p> - </li> - <li id="note-2" epub:type="endnote"> - <p>The second endnote goes here. <a href="chapter-1.xhtml#noteref-2" epub:type="backlink">↩</a></p> - </li> - </ol> - </section> -</body> -</html> -

    An endnote dissected

    -
      -

    • Each individual endnote is a <li> element containing one or more <p> elements.

      • -

    • Each <li> requires the following attributes:

      -
        -

      • id is set to the string “note-” followed by the sequential endnote number, beginning with 1.

        • -

      • epub:type is set to “endnote”.

        • - -
      -

    • The href attribute points to the direct anchor reference to the endnote.

      • - -

    • If an endnote contains a citation offset with a dash (for example, “—Ed.”), separate the citation from the text with a single space and enclose it in the <cite> tag:

      - <li id="note-1" epub:type="endnote"> -<p>Here’s an endnote. <cite>—<abbr class="eoc">Ed.</abbr></cite> <a href="chapter-1.xhtml#note-1" epub:type="backlink">↩</a></p> -</li> -
      • - -

    • The final <p> element in an endnote contains a link back to the referring anchor. Don’t just point it to the file, make sure it points to the exact link that we came from. For example, chapter-1.xhtml#note-1, not chapter-1.xhtml. If the link is the last element in a longer <p> tag, it must be preceded by one space character; if it is the only child of a <p> tag (for example if the previous text was a <blockquote>) then it can be on its own line. It must have the epub:type set to backlink. The text of the link is always the “↩” character.

      • -
    -
    -
    -

    Thought and section breaks

    -

    In printed material, thought and section breaks are typically denoted with a large space between paragraphs, or by a symbol like “* * *”. In Standard Ebooks, use the <hr/> element to denote thought and section breaks.

    -
    -
    -

    Section header semantic patterns

    -

    There’s a lot of ways authors choose to format chapter headers. Below are patterns for all of the types of chapter headers we’ve encountered so far. If nothing in this list fits the book you’re producing, contact us and we’ll work on a new standard.

    -

    General outline

    -
      -

    • The title of the book is an implied <h1> element. Therefore, all chapters titles are <h2> elements or lower.

      • -

    • It’s extremely rare to go down to <h3> and below, but you may do so if, for example, the chapter is part of a volume whose title would occupy the <h2> level. Otherwise, if you feel the need to use <h3>, ask yourself if the header is a structural division of the document. For example, in a work of fiction where a fictional newspaper clipping is presented, the headline would not be set in an <h3> element, because the clipping is part of the body text, not a structural division of the book.

      • -
    -

    Sections without titles

    - <h2 epub:type="title z3998:roman">XI</h2> -

    Sections with titles but no chapter numbers

    - <h2 epub:type="title">A Daughter of Albion</h2> -

    Sections with titles and chapter numbers

    - <h2 epub:type="title"> -<span epub:type="z3998:roman">XI</span> -<span epub:type="subtitle">Who Stole the Tarts?</span> -</h2> - span[epub|type~="subtitle"]{ -display: block; -font-weight: normal; -} -

    Sections with unnumbered titles and subtitles

    - <h2 epub:type="title"> -<span>An Adventure</span> -<span epub:type="subtitle">(A Driver’s Story)</span> -</h2> - span[epub|type~="subtitle"]{ -display: block; -font-weight: normal; -} -

    Sections with bridgeheads

    -

    Note that we include trailing punctuation at the end of the bridgehead. If it’s not present in the source text, add it.

    -

    Since the text in the bridgehead is italicized, we include CSS to render actual <i> elements contained in the bridgehead as normal text.

    - - <header> -<h2 epub:type="title z3998:roman">I</h2> -<p epub:type="bridgehead">Which treats of the character and pursuits of the famous gentleman Don Quixote of La Mancha.</p> -</header> -[epub|type~="bridgehead"]{ -display: inline-block; -font-style: italic; -max-width: 60%; -text-align: justify; -text-indent: 0; -} - -[epub|type~="bridgehead"] i{ -font-style: normal; -} -

    Sections with epigraph in section headers

    - - - - <header> -<h2 epub:type="title z3998:roman">XXVIII</h2> -<blockquote epub:type="epigraph"> - <p>Brief, I pray for you; for you see, ’tis a busy time with me.</p> - <cite><i epub:type="se:name.publication.play">Much Ado About Nothing</i></cite> -</blockquote> -</header> -/* All epigraphs */ -[epub|type~="epigraph"]{ -font-style: italic; -hyphens: none; -} - -[epub|type~="epigraph"] em, -[epub|type~="epigraph"] i{ -font-style: normal; -} - -[epub|type~="epigraph"] cite{ -margin-top: 1em; -font-style: normal; -font-variant: small-caps; -} - -[epub|type~="epigraph"] cite i{ -font-style: italic; -} -/* End all epigraphs */ - -/* Epigraphs in section headers */ -section > header [epub|type~="epigraph"]{ -display: inline-block; -margin: auto; -max-width: 80%; -text-align: left; -} - -section > header [epub|type~="epigraph"] + *{ -margin-top: 3em; -} - -@supports(display: table){ -section > header [epub|type~="epigraph"]{ - display: table; -} -} -/* End epigraphs in section headers */ -
    -
    -

    Full-page epigraphs

    -

    Full-page epigraphs have the epigraph centered on the page, for ereaders who support advanced CSS. For all other ereaders, the epigraph is horizontally centered with a small margin above it.

    -

    Additional epigraphs on the same page can be represented with additional <blockquote> elements.

    - <body epub:type="frontmatter"> -<section id="epigraph" epub:type="epigraph"> - <blockquote> - <p>“I was born in Boston, New England, and owe my first instructions in literature to the free grammar-schools established there. I therefore give one hundred pounds sterling to my executors, to be by them … paid over to the managers or directors of the free schools in my native town of Boston, to be by them … put out to interest, and so continued at interest forever, which interest annually shall be laid out in silver medals, and given as honorary rewards annually by the directors of the said free schools belonging to the said town, in such manner as to the discretion of the selectmen of the said town shall seem meet.”</p> - </blockquote> -</section> -</body> - /* All epigraphs */ -[epub|type~="epigraph"]{ -font-style: italic; -hyphens: none; -} - -[epub|type~="epigraph"] em, -[epub|type~="epigraph"] i{ -font-style: normal; -} - -[epub|type~="epigraph"] cite{ -margin-top: 1em; -font-style: normal; -font-variant: small-caps; -} - -[epub|type~="epigraph"] cite i{ -font-style: italic; -} -/* End all epigraphs */ - -/* Full-page epigraphs */ -section[epub|type~="epigraph"]{ -text-align: center; -} - -section[epub|type~="epigraph"] > *{ -display: inline-block; -margin: auto; -margin-top: 3em; -max-width: 80%; -text-align: left; -} - -@supports(display: flex){ -section[epub|type~="epigraph"]{ - align-items: center; - box-sizing: border-box; - display: flex; - flex-direction: column; - justify-content: center; - min-height: calc(98vh - 3em); - padding-top: 3em; -} - -section[epub|type~="epigraph"] > *{ - margin: 0; -} - -section[epub|type~="epigraph"] > * + *{ - margin-top: 3em; -} -} -/* End full-page epigraphs */ - -
    -
    -

    Letters

    -

    Letters require particular attention to styling and semantic tagging. While you are not required to exactly match the formatting of a letter in the source scans, you should make some attempt to create a version in visual sympathy with the source.

    -
    -

    General Outline

    -
      -
    1. A letter, or portion of a letter, should be put in a <blockquote> element.
      2. -
    2. The enclosing blockquote is given the semantic inflection of z3998:letter, that is: <blockquote epub:type="z3998:letter"> ... </blockquote>.
      3. -
    3. Parts of a letter prior to the body of the text, for example the address from where it is written and the date, should be enclosed in a <header> element.
      4. -
    4. The location and date of a letter are given the semantic inflection of se:letter.dateline. The date can be tagged with a <time> tag with a computer-readable date, for example: <time datetime="1863-10-11">11th of October, 1863</time>.
      5. -
    5. The salutation (for example, “Dear Sir", or “My dearest Jane") is given the semantic inflection of z3998:salutation. If the salutation is on a separate line to the body of the letter and a header block already exists, place the salutation within the header.
      6. -
    6. If the salutation is included within the first line of the letter (for example “My dear Mother, I was so happy to hear from you."), put the salutation inflection in a <span> element, in this example: <span epub:type="z3998:salutation">Dear Mother</span>, I was so happy to hear from you.
      7. -
    7. If the name of the recipient of the letter is set out other than within a saluation (for example a letter headed “To: John Smith Esquire"), the name should be given the semantic inflection of z3998:recipient. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it should be placed within a footer block (see below).
      8. -
    8. The valediction and signature and any postscript should be contained in a <footer> element.
      9. -
    9. The valediction (for example, “Yours Truly" or “With best regards") is given the semantic inflection of z3998:valediction.
      10. -
    10. The sender’s name is given the semantic inflection of z3998:sender. If the name appears to be a signature to the letter, it should be given a class of “signature". This will eventually be deprecated and is retained for legacy reasons.
      11. -
    11. Any postscript should also be included within the footer, and given the semantic inflection of z3998:postscript.
      12. -
    12. If the letter is being read aloud by a character in a work of fiction, then each element and paragraph should begin with quotes, as is usual for the spoken word. If it is not being read aloud, then the quotes are not needed.
      13. -
    -
    -
    -

    Example Letter 1:

    -

    Here is a simple example, a child's letter drawn from The Enchanted Castle by E. Nesbit:

    - <blockquote epub:type="z3998:letter"> - <p epub:type="z3998:salutation">Dearest Auntie,</p> - <p>Please may we have some things for a picnic? Gerald will bring them. I would come myself, but I am a little tired. I think I have been growing rather fast.</p> - <footer> - <p epub:type="z3998:valediction">Your loving niece,</p> - <p class="signature" epub:type="z3998:sender">Mabel</p> - <p epub:type="z3998:postscript">P.S.⁠—Lots, please, because some of us are very hungry.</p> - </footer> -</blockquote> -

    And here is a slightly more complex example, loosely based on a letter from Pride and Prejudice by Jane Austen:

    - <blockquote epub:type="z3998:letter"> - <header> - <p epub:type="se:letter.dateline">Gracechurch-street, <time datetime="08-02">August 2</time>.</p> - </header> - <p><span epub:type="z3998:salutation">My dear Brother</span>, At last I am able to send you some tidings of my niece, and such as, upon the whole, I hope will give you satisfaction. Soon after you left me on Saturday, I was fortunate enough to find out in what part of London they were. The particulars, I reserve till we meet. It is enough to know they are discovered, I have seen them both⁠—</p> - <p>I shall write again as soon as anything more is determined on.</p> - <footer"> - <p epub:type="z3998:valediction">Yours, etc.</p> - <p class="signature" epub:type="z3998:sender">Edward Gardner</p> - </footer> -</blockquote> -

    CSS for letters:

    - [epub|type~="z3998:letter"] header{ - text-align: right; -} - -footer{ - margin-top: 1em; - text-align: right; -} - -[epub|type~="z3998:salutation"] + p, -[epub|type~="z3998:letter"] header + p{ - text-indent: 0; -} - -[epub|type~="z3998:sender"], -[epub|type~="z3998:recipient"], -[epub|type~="z3998:salutation"]{ - font-variant: small-caps; -} - -[epub|type~="z3998:postscript"]{ - margin-top: 1em; - text-indent: 0; - text-align: left; -} - -.signature{ - font-variant: small-caps; -} -
    -
    -
    -

    Poetry, verse, and song semantic patterns

    -

    Unfortunately there’s no great way to semantically format poetry in HTML. We have to conscript unrelated elements for use in poetry.

    -

    General outline

    -
      -

    • A stanza is represented by a <p> element.

      • -

    • Each stanza contains <span> elements, each one representing a line in the stanza. Delimiting lines in <span> elements allows us to use CSS to automatically indent long lines that wrap across the page.

      • -

    • Each line is followed by a <br/> element, except for the last line in a stanza. Since <span> is an inline element, unstyled <span>s don’t have line breaks. Including a <br/> emulates line breaks for readers that for some crazy reason might not support CSS.

      • -

    • For indented lines, add the i1 class to the <span> element. Do not use nbsp for indentation. You can indent to multiple levels by incrementing the class to i2, i3, and so on, and including the appropriate CSS.

      • -

    • If the poem is a shorter part of a longer work, like a novel, then wrap the stanzas in a <blockquote> element.

      • -

    • If the poem is a standalone composition and part of a larger collection of poetry, wrap it in an <article> element instead. The semantics of <article> imply that the poem can be pulled out of the collection as a standalone item.

      • -

    • Give the containing element the semantic inflection of z3998:poem, z3998:verse, or z3998:song.

      • -
    -

    Complete HTML and CSS markup examples

    -

    Note that below we include CSS for the i2 class, even though it’s not used in the example; it’s included to demonstrate how to adjust the CSS for indentation levels after the first.

    - [epub|type~="z3998:poem"] p{ -text-align: left; -text-indent: 0; -} - -[epub|type~="z3998:poem"] p > span{ -display: block; -text-indent: -1em; -padding-left: 1em; -} - -[epub|type~="z3998:poem"] p > span + br{ -display: none; -} - -[epub|type~="z3998:poem"] p + p{ -margin-top: 1em; -} - -[epub|type~="z3998:poem"] + p{ -text-indent: 0; -} - -p span.i1{ -text-indent: -1em; -padding-left: 2em; -} - -p span.i2{ -text-indent: -1em; -padding-left: 3em; -} - <blockquote epub:type="z3998:poem"> -<p> - <span>“How doth the little crocodile</span> - <br/> - <span class="i1">Improve his shining tail,</span> - <br/> - <span>And pour the waters of the Nile</span> - <br/> - <span class="i1">On every golden scale!</span> -</p> -<p> - <span>“How cheerfully he seems to grin,</span> - <br/> - <span class="i1">How neatly spread his claws,</span> - <br/> - <span>And welcome little fishes in</span> - <br/> - <span class="i1"><em>With gently smiling jaws!</em>”</span> -</p> -</blockquote> -

    Elision in poetry

    -

    If a poem is quoted with one or more lines removed, the removed lines are represented with a vertical ellipses (⋮, U+22EE) in <span class="elision">, styled like so:

    - <blockquote epub:type="z3998:verse"> -<p> - <span>O Lady! we receive but what we give,</span> - <br/> - <span>And in our life alone does nature live:</span> - <br/> - <span>Ours is her wedding garments, ours her shroud!</span> - <br/> - <span class="elision">⋮</span> - <br/> - <span class="i1">Ah! from the soul itself must issue forth</span> - <br/> - <span>A light, a glory, a fair luminous cloud,</span> -</p> -</blockquote> - span.elision{ -margin: .5em; -margin-left: 3em; -} - -/* If eliding within an epigraph, include this additional style: */ -[epub|type~="epigraph"] span.elision{ -font-style: normal; -} -
    -
    -

    Images

    -
      -

    • All <img> tags are required to have an alt attribute that uses prose to describe the image in detail; this is what screen reading software will be read aloud.

      -
        -

      • Describe the image itself in words, which is not the same as writing a caption or describing its place in the book.

        • -

      • Alt text must be full sentences ended with periods or other appropriate punctuation. Sentence fragments, or complete sentences without ending punctuation, are not acceptable.

        • -
      -

      For example:

      -
      -

      <img alt="The illustration for chapter 10" src="...">

      -

      <img alt="Pierre's fruit-filled dinner" src="...">

      -

      <img alt="An apple and a pear inside a bowl, resting on a table." src="...">

      -
      -

      Note that the alt text does not necessarily have to be the same as text in the image’s <figcaption> element. You can use <figcaption> to write a concise context-dependent caption.

      -
      • -

    • Include an epub:type attribute to denote the type of image. Common values are z3998:illustration or z3998:photograph.

      • -

    • For some images, it’s helpful to invert their colors when the ereader enters night mode. This is particularly true for black-and-white line art and woodcuts. (Note black-and-white, i.e. only two colors, not grayscale!) Include the se:image.color-depth.black-on-transparent semantic in the <img> tag’s epub:type to enable color inversion in some ereaders.

      -

      For that sort of art, save the images as PNG files with a transparent background. You can make the background transparent by using the “Color to alpha” tool available in many image editing programs, like the GIMP.

      • -

    • <img> tags that are meant to be aligned on the block level should be contained in a parent <figure> tag, with an optional <figcaption> sibling.

      -
        -

      • If contained in a <figure> tag, the image’s id attribute must be on the <figure> tag.

      -
      • -

    • Some sources of illustrations may have scanned them directly from the page of an old book, resulting in yellowed, dingy-looking scans of grayscale art. In these cases, convert the image to grayscale to remove the yellow tint.

      • -
    -

    Complete HTML and CSS markup examples

    -/* If the image is meant to be on its own page, use this selector... */ -figure.full-page{ -margin: 0; -max-height: 100%; -page-break-before: always; -page-break-after: always; -page-break-inside: avoid; -text-align: center; -} - -/* If the image is meant to be inline with the text, use this selector... */ -figure{ -margin: 1em auto; -text-align: center; -} - -/* In all cases, also include the below styles */ -figure img{ -display: block; -margin: auto; -max-width: 100%; -} - -figure + p{ -text-indent: 0; -} - -figcaption{ -font-size: .75em; -font-style: italic; -margin: 1em; -} - <figure id="image-10"> -<img alt="An apple and a pear inside a bowl, resting on a table." src="../images/image-10.jpg" epub:type="z3998:photograph"/> -<figcaption>The Monk’s Repast</figcaption> -</figure> - <figure class="full-page" id="image-11"> -<img alt="A massive whale breaching the water, with a sailor floating in the water directly within the whale’s mouth." src="../images/image-11.jpg" epub:type="z3998:illustration"/> -<figcaption>The Whale eats Sailor Jim.</figcaption> -</figure> -
    -
    -

    List of Illustrations (the LoI)

    -

    If an ebook has any illustrations that are major structural components of the work (even just one!), then we must include an loi.xhtml file at the end of the ebook. This file lists the illustrations in the ebook, along with a short caption or description.

    -

    An illustration is a major structural component if, for example: it is an illustration of events in the book, like a full-page drawing or end-of-chapter decoration; it is essential to the plot, like a diagram of a murder scene or a map; or it is a component of the text, like photographs in a documentary narrative.

    -

    Illustration that are not major structural components would be, for example: drawings used to represent a person's signature, like an X mark; inline drawings representing text in alien languages; drawings used as layout elements to illustrate diagrams.

    -

    If the image has a <figcaption> element, then use that caption in the LoI. If not, use the image’s alt tag, which should be a short prose description of the image used by screen readers.

    -

    Links to the images should go directly to their IDs, not just the top of the containing file.

    -

    The code below is the template for a basic LoI skeleton. Please copy and paste the entire thing as a starting point for your own LoI:

    - <?xml version="1.0" encoding="utf-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> -<head> - <title>List of Illustrations</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> -</head> -<body epub:type="backmatter"> - <section id="loi" epub:type="loi"> - <nav epub:type="loi"> - <h2 epub:type="title">List of Illustrations</h2> - <ol> - <li> - <a href="preface.xhtml#the-edge-of-the-world">The Edge of the World</a> - </li> - - <!--snip all the way to the end--> - </ol> - </nav> - </section> -</body> -</html> - -
    - -
    -
    - diff --git a/www/contribute/tips-for-editors-and-proofreaders.php b/www/contribute/tips-for-editors-and-proofreaders.php index 8367ce59..371f8a0c 100644 --- a/www/contribute/tips-for-editors-and-proofreaders.php +++ b/www/contribute/tips-for-editors-and-proofreaders.php @@ -1,13 +1,13 @@ 'Tips for Editors and Proofreaders', 'js' => true, 'highlight' => 'contribute', 'description' => 'A list of tips and tricks for people who’d like to proofread a Standard Ebooks ebook.']) ?> +?> 'Tips for Editors and Proofreaders', 'manual' => true, 'highlight' => 'contribute', 'description' => 'A list of tips and tricks for people who’d like to proofread a Standard Ebooks ebook.']) ?>

    Tips for Editors and Proofreaders

    Advances in ereading devices and software have made proofreading ebooks a whole lot easier than in the past.

    Most ereading software allows you to highlight text and add notes to those highlights. If you’re using a device like a Kindle or a phone or tablet with the Google Play Books app, try holding your finger on some text. It’ll become highlighted, and you can drag the highlight to include more text if you like.

    That means the quickest way for you to proofread an ebook is to transfer it to your ereader and start reading! Once you find an error, use the highlight feature to mark it, and keep on reading. Many errors, like mis-curled quotation marks or obvious spelling errors, don’t need a written note to accompany the highlight. But you should make a brief written note if the error wouldn’t be clear to a passing reader.

    -

    Once you’ve finished the ebook, use your ereader’s “view all notes” option to find all of your highlights in one place. Then you can either report them to us, or if you’re technically-minded, correct them directly in the ebook’s GitHub repository. Remember to read our typography manual to make sure the error you found is covered.

    +

    Once you’ve finished the ebook, use your ereader’s “view all notes” option to find all of your highlights in one place. Then you can either report them to us, or if you’re technically-minded, correct them directly in the ebook’s GitHub repository. Remember to read the Standard Ebooks Manual of Style to make sure the error you found is covered.

    Common errors to watch out for

    Lots of different errors can occur during the long and complex process of digitizing a print book, but here are some of the more common ones:

    @@ -20,7 +20,7 @@ require_once('Core.php');

  • Incorrect or archaic use of quotation marks

    -

    Older texts frequently use quotation marks for names of books and periodicals, or for the names of pubs, inns, and other places. Our typography manual requires that certain standalone media be in italics instead, and that place names not be set in quotes.

    +

    Older texts frequently use quotation marks for names of books and periodicals, or for the names of pubs, inns, and other places. Our typography manual requires that certain standalone media be in italics instead, and that place names not be set in quotes.

    He read “Candide” while having a pint at the “King’s Head.”

    He read Candide while having a pint at the King’s Head.

    @@ -29,10 +29,10 @@ require_once('Core.php');

  • Missing italics

    Often transcribers just don’t include italics at all in their work. A very quick visual scan of a HathiTrust or Google Books copy of the book you’re proofing should bring any sections in italics to your attention. Make sure to confirm them in the transcription, so that we’re not missing italics that should be there.

    - +

  • Ending dialog with a double-em-dash

    -

    Some authors were in the habit of showing a sudden break in dialog with an extra-wide double-em-dash. Our typography manual requires that these be replaced by single em-dashes, so mark them for correction.

    +

    Some authors were in the habit of showing a sudden break in dialog with an extra-wide double-em-dash. Our typography manual requires that these be replaced by single em-dashes, so mark them for correction.

    “Why, I never——” she cried.

    “Why, I never—” she cried.

    @@ -45,7 +45,7 @@ require_once('Core.php');

  • Using &c. instead of etc.

    “etc.” is an abbreviation of the Latin et cetera; In Latin, et means “and”, so older texts often abbreviated et cetera as “&c.”

    -

    Our typography manual requires a change from &c. to etc., so make sure to mark these corrections.

    +

    Our typography manual requires a change from &c. to etc., so make sure to mark these corrections.

  • Use of “ibid.” in footnotes or endnotes

    @@ -60,21 +60,16 @@ require_once('Core.php');

  • Section dividers as text instead of as markup

    There are lots of ways authors mark section breaks in text. A common way to do this is with three or more asterisks:

    -
    - <p>Some text in the first section...</p> -<p>***</p> -<p>The second section begins...</p> - -
    +
    <p>Some text in the first section...</p> +<p>***</p> +<p>The second section begins...</p>
    +

    In Standard Ebooks, sections must be marked with the <hr/> tag:

    -
    -<p>Some text in the first section...</p> -<hr/> -<p>The second section begins...</p> - -
    -

    As you’re reading, the <hr/> tag appears as a short black line dividing sections.

    -

    Mark for correction any section breaks that don’t use the <hr/> tag.

    +
    <p>Some text in the first section...</p> +<hr/> +<p>The second section begins...</p>
    +

    As you’re reading, the <hr/> element appears as a short black line dividing sections.

    +

    Mark for correction any section breaks that don’t use the <hr/> element.

    • diff --git a/www/contribute/toolset.php b/www/contribute/toolset.php deleted file mode 100644 index c056caf3..00000000 --- a/www/contribute/toolset.php +++ /dev/null @@ -1,14 +0,0 @@ - 'Toolset Guidelines', 'highlight' => 'contribute', 'description' => 'Guidelines for programming language and code style used in the Standard Ebooks toolset.']) ?> -
    -
    -

    Toolset Guidelines

    -

    You can view our toolset on GitHub.

    -

    Contributions should be in Python 3.

    -

    In general we follow a relaxed version of PEP 8. In particular, we use tabs instead of spaces, and there is no line length limit.

    -

    Always use the regex module instead of the re module.

    -

    At the minimum, scripts should use programs available for installation on Ubuntu 18.04 LTS systems, either via apt or pip3.

    -
    -
    - diff --git a/www/contribute/typography.php b/www/contribute/typography.php deleted file mode 100644 index 436af002..00000000 --- a/www/contribute/typography.php +++ /dev/null @@ -1,859 +0,0 @@ - 'Typography Manual', 'js' => true, 'highlight' => 'contribute', 'description' => 'The Standard Ebooks Typography Manual, containing details on specific typographic requirements for Standard Ebooks ebooks.']) ?> -
    -
    -

    Typography Manual

    - -

    The Standard Ebooks Style Philosophy

    -

    Standard Ebooks’ goal is to bring classic public domain literature into the digital era by making it accessible, attractive, and by maintaining a high standard of quality. To that end we’re not interested in slavishly reproducing the formatting quirks, transcription errors, publisher’s ephemera, or other inconsequential style decisions of the past. While we strive to be good custodians of the literature entrusted to the public, we recognize that the freedom of the public domain intersects with the Internet era in a way that allows us to present that literature in an attractive, modern, and high-quality way.

    -

    Your task

    -

    As an editor, proofreader, or producer of a Standard Ebook, part of your task is to take the source transcription of your ebook and apply this typography manual to it. This manual outlines various standardizations and modernizations to old typography practices, making older texts easier to read for modern readers.

    -

    Many of the rules below have been accepted standards for a hundred years or more. That means that many of the ebooks you produce may not need that much adjustment. The typogrify tool in the Standard Ebooks toolset also automatically takes care of some (but not all!) of these rules. Typically, the older the source, the more of these rules you’ll have to check during production.

    -

    Normalizing different formatting styles

    -

    Our general rule is: If it doesn’t affect the meaning of the work, then normalize it according to these standards.

    -
    -

    Common problems to keep an eye out for

    -
      -
    • -

      Some sources use a two-em-dash to interrupt dialog. You should replace such two-em-dashes with a single em-dash according to the section on dashes.

      -
      -

      “Why, I never——” she cried.

      -

      “Why, I never—” she cried.

      -
      -

      Note that a two-em-dash is also used to signify a missing or purposefully obscured word. This is correct, but you should ensure that instead of two consecutive em-dashes, you use the two-em-dash glyph (⸺ or U+2E3A) for partially-obscured words, the three-em-dash glyph (⸻ or U+2E3B) for completely-obscured words, and a single em-dash for partially-obscured years.

      -
      -

      Sally J⸺ walked through the town of ⸻ in the year 19—.

      -
      -
      • -
    • -

      Small caps are commonly used instead of italics for emphasis in older texts, and some transcriptions use all caps instead of italics. These should generally be converted to regular case and wrapped in <em> tags. If a text truly does call for extreme emphasis, the <strong> tag can be used—but think twice about using it, and use it sparingly. See the section on text in all caps.

      -
      -

      That donut was DELICIOUS!

      -

      That donut was <em>delicious</em>!

      -
      -
      • -
    -
    -
    -

    General

    -
      -
    • -

      Our general style guide is the Chicago Manual of Style, 16th edition, with a few tweaks outlined below. Work following a different style guide should be converted to conform to ours, unless it changes the meaning of the work.

      -
      • -
    • -

      Do convert from logical punctuation to American punctuation where possible.

      -
      • -
    • -

      Do convert from British quotation to American quotation where possible. The british2american script is helpful for automating most (but not all!) of this.

      -
      • -
    -
    -
    -

    Section endings

    -

    Some older books end with “The End”, “Fin”, or some other equivalent. Remove these.

    -

    Some books also end individual sections or chapters with “The end of such-and-such section”. Remove these as well.

    -
    -
    -

    Chapter names and titles

    -
      -
    • -

      In the body text, always use Roman numerals for chapter numbers instead of Arabic numerals. But in an individual file’s <title> tag, do use Arabic numbers instead of Roman numerals.

      -

      Do not use the Unicode Roman numeral glyphs, as they are deprecated; use regular letters.

      -
      • -
    • -

      Convert all-caps or small-caps titles to title case. Use the se titlecase script in the Standard Ebooks toolset for consistent titlecasing.

      -
      • -
    • -

      Remove trailing periods from chapter titles.

      -
      • -
    • -

      Omit the word “Chapter” from chapter titles.

      -

      Some ebooks should keep “Chapter” in titles if clarity is necessary: for example, Frankenstein has “Chapter” in titles to differentiate between the “Letter” sections.

      -
      -

      Chapter 33

      -

      XXXIII

      -
      -
      • -
    -
    -
    -

    Italicizing or quoting newly-used words

    -
      -
    • -

      When introducing new terms, italicize foreign or technical terms, but use quotation marks for terms composed of regular English.

      -
      -

      English whalers have given this the name “ice blink.”

      -

      The soil consisted of that igneous gravel called tuff.

      -
      -
      • -
    • -

      Don’t italicize English neologisms in works where a special vocabulary is a regular part of the narrative; specifically, science fiction works that may necessarily contain made-up English technology words. However, do italicize “alien” language in such works.

      -
      • -
    • -

      Including both italics and quotes, outside of the context of quoted dialog, is usually not necessary. Use one or the other based on the rules above.

      -
      • -
    -
    -
    -

    Names and titles: Italicize or quote?

    -
      -
    • -

      Names and titles are usually either italicized or quoted, but almost never both. Pick one or the other based on the rules below.

      -
      • -
    • -

      Older work may pick the opposite of the rules below; change such texts to match this manual.

      -
      • -
    • -

      Older work may use quotation marks around proper names, like pub, bar, building, or company names. Remove those quotes.

      -
      -

      He read “Candide” while having a pint at the “King’s Head.”

      -

      He read Candide while having a pint at the King’s Head.

      -
      -
      • -
    • -

      In general, italicize things that can stand alone. Specifically:

      -
        -
      • -

        Magazines

        -
        • -
      • -

        Plays

        -
        • -
      • -

        Books and novels except “holy texts,” like the Bible or books within the Bible

        -
        • -
      • -

        Long musical compositions, like operas

        -
        • -
      • -

        Music albums

        -
        • -
      • -

        Films

        -
        • -
      • -

        TV shows

        -
        • -
      • -

        Radio shows

        -
        • -
      • -

        Titles of artwork

        -
        • -
      • -

        Long poems and ballads, like the Iliad

        -
        • -
      • -

        Pamphlets

        -
        • -
      • -

        Journals

        -
        • -
      • -

        Newspapers

        -
        • -
      • -

        Names of ships

        -
        • -
      • -

        Names of sculptures

        -
        • -
      -
      • -
    • -

      In general, quote things that are short or parts of longer work. Specifically:

      -
        -
      • -

        Short musical compositions, like pop songs

        -
        • -
      • -

        Chapter titles

        -
        • -
      • -

        Short stories

        -
        • -
      • -

        Novellas

        -
        • -
      • -

        Individual newspaper or journal articles

        -
        • -
      • -

        Essays

        -
        • -
      • -

        Short films

        -
        • -
      • -

        Episodes in a TV or radio series

        -
        • -
      -
      • -
    -
    -
    -

    Capitalization

    -
    -

    General

    -
      -
    • -

      Some very old works frequently capitalize nouns that today we no longer capitalize. In general, only capitalize the beginnings of clauses, and proper nouns in the way that you would in modern English writing. Remove archaic capitalization unless doing so would change the meaning of the work.

      -
      • -
    -
    -
    -

    Text in all caps

    -
      -
    • -

      Text in all caps is almost never correct typography. Instead, convert such text to the correct case and surround it with a semantically-meaningful tag like <em> (for emphasis), <strong> (for strong emphasis, like shouting) or <b> (for unsemantic formatting required by the text). Then, use font-weight: normal; font-variant: small-caps; styling to render those tags in small caps.

      -
      • -
    -
    -

    The sign read <b>Bob’s Restaurant</b>.

    -

    “<strong>Charge!</strong>” he cried.

    -
    -
    -
    -

    Apostrophes

    -

    When addressing something as an apostrophe, “O” is capitalized.

    -
    -

    I carried the bodies into the sea, O walker in the sea!

    -
    -
    -
    -
    -

    Spacing

    -
      -
    • Sentences should be single-spaced. Convert double-spaced sentences to single-space.
      • -
    -
    -
    -

    Italics

    -
      -
    • -

      Italics should generally be used for emphasis. Some older texts make frequent use of small caps for emphasis; change these to italics. Italics indicating emphasis must be wrapped with the <em> tag.

      -
      • -
    • -

      Set individual letters that are read as letters in italics...

      -
      -

      He often rolled his r’s.

      -
      -

      Unless referring to a name that happens to be a single letter or composed of single letters, or if that letter is standing in for a name...

      -
      -

      ...due to the loss of what is known in New England as the “L”: that long deep roofed adjunct usually built at right angles to the main house...

      -

      She was learning her A B Cs.

      -
      -

      Or if the letter is meant to be a comparison to a shape:

      -
      -

      His trident had the shape of an E.

      -
      -

      When using the ordinal “nth,” italicize the n, and do not include a hyphen:

      -
      -

      The nth degree.

      -
      -
      • -
    • -

      Words written to be read as sounds are set in italics using <i>:

      -
      -

      He could hear the dog barking: Ruff, ruff, ruff!

      -
      -
      • -
    • -

      See here for italicizing names and titles.

      -
      • -
    -
    -

    Italics for foreign languages

    -
      -
    • -

      Set foreign words and phrases that are not in the Merriam-Webster dictionary in italics. If the foreign word or phrase is in Merriam-Webster, don’t set it in italics.

      -
      -

      The pièce de résistance of the dessert course was a mousse au chocolat.

      -
      -
      • -
    • -

      Don’t italicize foreign words in proper names, unless the name itself would be italicized according to the rules for italicizing or quoting names and titles.

      -
      -

      She got off the metro at the Place de Clichy stop, next to the Le Bon Petit Déjeuner restaurant.

      -

      “Où est le métro?” he asked, and she pointed to Place de Clichy, next to the Le Bon Petit Déjeuner restaurant.

      -
      -
      • -
    • -

      If a certain foreign word is used so frequently in the text that italicizing it would be distracting to the reader, then only italicize the first instance. However, wrap the following instances in <span xml:lang="LANGUAGE">.

      -
      • -
    • -

      Certain exceptions to italicizing foreign words can be made if a specific word is in Merriam-Webster, but in the producer’s opinion is still too obscure for the general reader and thus should be italicized anyway. In this case ask the Standard Ebooks editor-in-chief for how to proceed.

      -
      • -
    -
    -
    -

    Punctuation in italics

    -
      -
    • -

      If italicizing a short phrase within a longer clause, don’t italicize trailing punctuation that may belong to the containing clause.

      -
      -

      “Look at that!” she shouted.

      -

      “Look at that!” she shouted.

      -
      -
      • -
    • -

      However, if an entire clause is italicized for emphasis, then do include the trailing punctuation in the italics, unless that trailing punctuation is a comma at the end of some dialog.

      - - - - - - - - - - - - - - - - - -
      ResultCode
      -

      “Charge!” she shouted.

      -       		“<em>Charge!</em>” she shouted.
      -

      “But I want to,” she said.

      -       		“<em>But I want to</em>,” she said.
      -
      • -
    -
    -
    -

    Taxonomy

    -
      -
    • -

      Binomial names (generic, specific, and subspecific) are italicized with the <i> tag and with the z3998:taxonomy semantic inflection.

      - - - - - - - - - - - - - -
      ResultCode
      -

      A bonobo monkey is Pan paniscus.

      -       		A bonobo monkey is <i epub:type="z3998:taxonomy">Pan paniscus</i>.
      -
      • -
    • -

      Family, order, class, phylum or division, and kingdom names are capitalized but not italicized.

      -
      -

      A bonobo monkey is in the phylum Chordata, class Mammalia, order Primates.

      -
      -
      • -
    • -

      Modern usage requires that the second part in a binomial name be set in lowercase. Older texts may set it in uppercase. Use the style in the source text.

      -
      • -
    -
    -
    -
    -

    Indentation

    -
      -
    • -

      Body text in a new paragraph that directly follows earlier body text is indented by 1em.

      -
      • -
    • -

      The initial line of body text in a section, or any text following a visible break in text flow, like a header, a scene break, a figure, a block quotation, etc., is not indented.

      -

      For example: in a block quotation, there is a margin before the quotation and after the quotation. Thus, the first line of the quotation is not indented, and the first line of body text after the block quotation is also not indented.

      -
      • -
    -
    -
    -

    Punctuation

    - -
    -

    Spaces

    -
      -
    • -

      Use single spaces between sentences.

      -
      • -
    -
    -
    -

    Quotation marks

    -
      -
    • -

      “Curly” or typographer’s quotes should always be used.

      -
      -

      “Don’t do it!” she shouted.

      -
      -
      • -
    • -

      Quotation marks that are directly side-by-side must be separated by a hair space (U+200A) character.

      -
      -

      “hairsp‘Green?’ Is that what you said?” asked Dave.

      -
      -
      • -
    • -

      Words with missing letters should use the right single quotation mark (’ or U+2019) character to indicate ommission.

      -
      -

      He had pork ’n’ beans for dinner

      -
      -
      • -
    -
    -
    -

    Ellipses

    -
      -
    • -

      Use the ellipses (U+2026) glyph instead of consecutive or spaced periods.

      -
      • -
    • -

      When used as suspension points (for example, to indicate dialog that pauses or trails off), don’t precede the ellipses with a comma. Commas followed by ellipses were sometimes used in older texts, but are now redundant to modern readers; remove them.

      -

      Note that ellipses used to indicate missing words in a quotation still require keeping surrounding punctuation, including commas, because that punctuation is in the original quotation.

      -
      • -
    • -

      Place a hair space (U+200A) glyph before all ellipses that are not directly preceded by punctuation, or that are directly preceded by an em-dash or a two- or three-em-dash. Place a regular space after all ellipses that are not followed by punctuation. If the ellipses is followed by punctuation, place a hair space between the ellipses and punctuation, unless the punctuation is a quotation mark, in which case don’t put a space at all.

      -
      -

      “I’m so hungryhairsp… What were you saying about eatinghairsp…?”

      -
      -
      • -
    -
    -
    -

    Dashes

    -

    There are many kinds of dashes, and your run-of-the-mill hyphen is often not what you should use. In particular, don’t use the hyphen for things like date ranges, phone numbers, or negative numbers.

    -
      -
    • -

      Do not put spaces around em-dashes. Remove spaces if in the original text.

      -
      • -
    • -

      Use em-dashes (— or U+2014) to offset parenthetical phrases. These are usually the most common kind of dash.

      -
      • -
    • -

      Use an em-dash for partially-obscured years.

      -
      -

      It was the year 19— in the town of Metrolopis.

      -
      -

      Use a regular hyphen if only the last digit of the year is obscured.

      -
      -

      It was the year 186- in the town of Metrolopis.

      -
      -
      • -
    • -

      Some older texts use two em-dashes to indicate an interruption in thought or speech. Our style is to replace two em-dashes used as an interruption marker with a single em-dash. However, don’t replace two em-dashes used to indicate the omission of a word (like an anonymous name or an expletive); see below.

      -
      • -
    • -

      Use a two-em-dash glyph (⸺ or U+2E3A) to signify a purposefully partially obscured word. The two-em-dash glyph isn’t available in some fonts, but include it anyway; our build process will convert it later.

      -
      -

      Sally J⸺ walked through town.

      -
      -
      • -
    • -

      Use a three-em-dash glyph (⸻ or U+2E3B) for completely obscured words.

      -
      -

      It was night in the town of ⸻.

      -
      -
      • -
    • -

      En-dashes (– or U+2013) are used to indicate a numerical or date range; when you can substitute the word “to,” for example between locations; or to indicate a connection in location between two places.

      -
      -

      We talked 2–3 days ago.

      -

      We took the Berlin–Munich train yesterday.

      -

      I saw the torpedo-boat in the Ems⁠–⁠Jade Canal.

      -
      -
      • -
    • -

      Figure dashes (‒ or U+2012) are used to indicate a dash in numbers that aren’t a range, like phone numbers.

      -
      -

      His number is 555‒1234.

      -
      -
      • -
    • -

      Minus dashes (− or U+2212) are used to indicate negative numbers and are used in mathematical equations instead of hyphens.

      -
      -

      It was −5° out yesterday!

      -
      -
      • -
    • -

      Many older texts use archaic spelling and hyphenate compound words that are no longer hyphenated today. Use the modernize-spelling script to automatically find and correct candidates. Note that this script isn’t perfect, and proofreading is required after using it to make sure it didn’t wrongly remove a hyphen!

      -

      Do not use the modernize-spelling script on poetry.

      -
      • -
    -
    -
    -
    -

    Latinisms

    -
      -
    • -

      Don’t italicize Latinisms that can be found in a modern dictionary, like e.g., i.e., ad hoc, viz., ibid., etc. except sic, which should always be italicized. Some older works might italicize these kinds of Latinisms; remove the italics.

      -
      • -
    • -

      Do italicize whole passages of Latin language (as you would italicize any passages of foreign text in a work) and Latinisms that aren’t found in a modern dictionary.

      -
      • -
    • -

      Latinisms that are abbreviations should be set in lowercase with periods between words and no spaces between them, except:

      -
        -
      • -

        BC, AD, BCE, and CE should be set without periods and in small caps and wrapped with the <abbr class="era"> tag.

        - - - - - - - - - - - - - -
        ResultCode
        -

        Julius Caesar was born around 100 BC.

        -         		abbr.era{ -font-variant: all-small-caps; -} Julius Caesar was born around 100 <abbr class="era">BC</abbr>.
        -
        • -
      -
      • -
    • -

      Always use “etc.” instead of “&c;”. Some older works use the latter; convert them to the former.

      -
      • -
    • -

      For “Ibid.,” see endnotes.

      -
      • -
    -
    -
    -

    Initials and Abbreviations

    -
      -
    • -

      See here for temperatures.

      -
      • -
    • -

      See here for times.

      -
      • -
    • -

      See here for Latinisms including BC and AD.

      -
      • -
    • -

      “OK” is set without periods or spaces. It is not an abbreviation.

      -
      • -
    • -

      An acronym is a term made up of initials and pronounced as one word: NASA, SCUBA, TASER.

      -

      An initialism is a term made up of initials in which each initial is pronounced separately: ABC, HTML, CSS.

      -

      A contraction is an abbreviation of a longer word: Mr., Mrs., lbs.

      -
      • -
    • -

      In general, abbreviations ending in a lowercase letter should be set without spaces and followed by a period. Abbreviations without lowercase letters should be set without spaces and without a trailing period. Always use a no-break space after an abbreviation that describes the next word, like Mr., Mrs., Mt., St., etc. A few exceptions follow.

      -
      • -
    • -

      Initials of people’s names should be separated by periods and spaces. Wrap such initials in <abbr class="name">.

      - - - - - - - - - - - - - -
      ResultCode
      -

      H. P. Lovecraft

      -       		<abbr class="name">H. P.</abbr> Lovecraft
      -
      • -
    • -

      Compass directions should be wrapped in <abbr class="compass">, with periods and spaces.

      - - - - - - - - - - - - - -
      ResultCode
      -

      He traveled N. W., then E. S. E.

      -       		He traveled <abbr class="compass">N. W.</abbr>, then <abbr class="compass eoc">E. S. E.</abbr>
      -
      • -
    • -

      For acronyms, initialisms, postal codes, temperatures, and abbreviated US states, remove periods and spaces. All of these are set in caps, except for temperatures and acronyms, which are set in small caps. The source code should represent the abbreviations in caps, but wrapped in an <abbr> tag.

      -

      All acronyms are set in small caps. Because acroynms are capitalized in the source code, use the CSS style font-variant: all-small-caps; to properly set them in small caps.

      - - - - - - - - - - - - - -
      ResultCode
      -

      Dr. J. D. Ross, MD, served on the HMS Bounty as a NASA liaison.

      -       		abbr.acronym{ -font-variant: all-small-caps; -} <abbr>Dr.</abbr> <abbr class="name">J. D.</abbr> Ross, <abbr class="degree">MD</abbr>, served on the <abbr class="initialism">HMS</abbr> <i epub:type="se:name.vessel.ship">Bounty</i> as a <abbr class="acronym">NASA</abbr> laison.
      -
      • -
    • -

      Unless mentioned above, do not set initialisms in small caps.

      -
      • -
    -
    -
    -

    Chemicals and compounds

    -
      -
    • -

      Set molecular compounds in regular type without spaces.

      -
      • -
    • -

      Elements should be capitalized according to their listing in the periodic table.

      -
      • -
    • -

      Amounts of an element should be set in subscript using the <sub> tag.

      -
      • -
    - - - - - - - - - - - - - -
    ResultCode
    -

    H2O

    -     		H<sub>2</sub>O
    -
    -
    -

    Temperatures

    -
      -
    • -

      Use the minus glyph (− or U+2212), not the hyphen glyph, to indicate negative numbers.

      -
      • -
    • -

      Using either the degree glyph (° or U+00B0) or the word “degrees” is acceptable, but if a work uses both methods, normalize the work to use the dominant method.

      -
      • -
    • -

      If listing temperature as a digit followed by “F.”, “C.”, or another abbreviation, remove the trailing period and precede the letter by a hair space (U+200A). Wrap the letter in <abbr class="temperature"> styled with abbr.temperature{ font-variant: all-small-caps; }

      -
      • -
    - - - - - - - - - - - - - -
    ResultCode
    -

    It was −23.33° Celsius (or −10° F) last night.

    -     		abbr.temperature{ -font-variant: all-small-caps; -} It was −23.33° Celsius (or −10°hairsp<abbr class="temperature">F</abbr>) last night.
    -
    -
    -

    Epigraphs in chapter headers

    -
      -
    • -

      The source of the epigraph is set in small caps, without a leading em-dash and without a trailing period.

      -
      • -
    -
    -
    -

    Bridgeheads in chapter headers

    -
      -
    • -

      Bridgeheads are centered in the header.

      -
      • -
    • -

      Always include a trailing period at the end of the bridgehead.

      -
      • -
    -
    -
    -

    Times

    -
      -
    • -

      Times in a.m. and p.m. format should have the letters a.m. and p.m. set in lowercase, with periods, and without spaces. “a.m.” and “p.m.” should be wrapped in an <abbr class="time"> tag. If “a.m.” or “p.m.” are the last word in a sentence, omit a second period, but add the “eoc” (end-of-clause) class to the <abbr> tag.

      -
      • -
    • -

      Seperate times written in digits followed by a.m. or p.m. with a no-break space. If the time is written out in words, use a regular space.

      -
      • -
    • -

      Separate the hour and minute with a colon, not a period or comma.

      -
      • -
    • -

      Do not hyphenate times when spelled out, unless they appear before a noun.

      -
      -

      He arrived at five thirty.

      -

      They took the twelve-thirty train.

      -
      -
      • -
    • -

      Military time that is spelled out (for example, in dialog) is set with dashes. Leading zeros are spelled out as “oh”.

      -
      -

      He arrived at oh-nine-hundred.

      -
      -
      • -
    - - - - - - - - - - - - - -
    ResultCode
    -

    He called at 6:40  a.m., but she wasn’t up till seven a.m.

    -     		- He called at 6:40nbsp<abbr class="time">a.m.</abbr>, but she wasn’t up till seven <abbr class="time eoc">a.m.</abbr> -

    Note how the last <abbr> contains the period for the entire sentence, and consequently also has the “eoc” (end-of-clause) class.

    -
    -
    -
    -

    Ampersands in names

    -
      -
    • -

      Ampersands in names of things like firms should be separated by no-break spaces.

      -
      -

      The firm of Hawkinsnbsp&amp;nbspHarker.

      -
      -
      • -
    -
    -
    -

    Ligatures

    -

    Ligatures are symbols which combine two or more characters into one.

    -
      -
    • -

      Some older texts use ligatures like æ and œ to represent dipthongs. The modernize-spelling tool will replace many of these for you, but keep an eye out for other instances, particularly in Latin phrases and in classical names such as Œdipus. These should be either be replaced with “ae” and “oe” or with alternative modern spellings of the word they are in (check Merriam-Webster for these).

      -
      • -
    • -

      It’s very unlikely that you will encounter stylistic ligatures such as fl or ffi in the source text, but if you do they should be replaced by the individual characters they represent.

      -
      • -
    -
    -
    -

    Numbers, measurements, and math

    -
      -
    • -

      Roman numerals should not be followed by periods, unless the period is there for grammatical reasons. Some European texts include a trailing period after Roman numerals as a matter of course; remove them.

      -
      • -
    • -

      Fractions should be written using the Unicode glyphs (½, ¼, ¾, etc., or U+00BC–U+00BE and U+2150–U+2189), if a glyph exists for your fraction.

      -
      -

      I need ¼ cup of sugar.

      -
      -

      If a glyph for a fraction doesn’t exist, compose it using the fraction slash Unicode glyph (⁄ or U+2044) and superscript/subscript Unicode numbers. See this Wikipedia entry for more details.

      -
      -

      Roughly ⁶⁄₁₀ of a mile.

      -
      -
      • -
    • -

      Dimensions and equations should use the Unicode multiplication glyph (× or U+00D7) instead of the letters x or X.

      -
      -

      The board was 4 × 3 × 7 feet.

      -
      -
      • -
    • -

      Feet and inches in shorthand are set with the prime (′ or U+2032) or double prime (″ or U+2033) glyphs, not single or double quotes, and with a no-break space separating feet and inches.

      -
      -

      He was 6′nbsp1″ in height.

      -
      -
      • -
    • -

      Coordinates should be noted with the prime (′ or U+2032) or double prime (″ or U+2033) glyphs, not single or double quotes.

      -
      -

      lat. 27° 0′ N., long. 20° 1′ W.

      -
      -

      (Note that in the above example your font might render the two glyphs in the same way, but they’re different Unicode glyphs.)

      -
      • -
    • -

      Operators and operands in mathematical equations should be separated by a space.

      -

      Remember to use minus dashes (− or U+2212) instead of regular hyphens, both for negative numbers and for mathematical operations.

      -
      -

      6 − 2 + 2 = 6

      -
      -
      • -
    • -

      When forming a compound of a number + unit of measurement, and the measurement is abbreviated, separate the two with a no-break space, not a dash.

      -
      -

      A 12nbspmm pistol.

      -
      -
      • -
    -
    -
    -

    Footnotes and endnotes

    -
      -
    • -

      All footnotes should be converted to a single endnotes file. For more information on the structure of that file, see our structure and semantics manual.

      -
      • -
    • -

      “Ibid.” is a Latinism commonly used in endnotes to indicate that the source for a quotation or reference is the same as the last-mentioned source.

      -

      In the case where the last-mentioned source is in the previous endnote, we must replace Ibid. by the full reference; since ebooks use popup endnotes, “Ibid.” becomes meaningless in that context.

      -

      In the case where the last-mentioned source is in the same endnote as Ibid., we can leave Ibid. untouched.

      -
      • -
    • -

      The endnote reference number goes after ending punctuation. If the endnote references an entire sentence in quotation marks, or the last word in a sentence in quotation marks, then the endnote reference number goes outside the quotation marks.

      -
      • -
    • -

      Within an endnote, a backlink to where the endnote occurred in the text must be the last item. It is preceded by exactly one space.

      -
      • -
    -
    - - -
    -
    - diff --git a/www/css/core.css b/www/css/core.css index 3dc3f3bc..1290c2e2 100644 --- a/www/css/core.css +++ b/www/css/core.css @@ -192,7 +192,7 @@ main p, main ul, main ol, main li, main blockquote{ margin-top: 1rem; } -main p:first-child, main ul:first-child, main ol:first-child, main ul li:first-child, main ol li:first-child, main blockquote:first-child, main code:first-child{ +main p:first-child, main ul:first-child, main ol:first-child, main ul li:first-child, main ol li:first-child, main blockquote:first-child{ margin-top: 0; } @@ -204,7 +204,7 @@ ol ol, ol ul, ul ul, ul ol{ margin-left: 1.2rem; } -h1,h2,h3,h4,h5,h6,code,.ebook h1 + p{ +h1,h2,h3,h4,h5,h6,.ebook h1 + p{ -webkit-hyphens: none; hyphens: none; } @@ -1176,181 +1176,6 @@ ul.tags li + li{ margin-left: .5rem; } -code.tag, -code.path, -code.program, -code.bash, -code.regex, -code.html, -code.ietf, -code.css, -code.marc{ - border: 1px solid rgba(255,255,255,.25); - background: #333; - border-radius: .25rem; - white-space: pre-wrap; - padding: 0 .25rem; - color: #fff; -} - -figure code.html, -figure code.css{ - padding: 1rem; - background: #333; - border: none; - text-align: left; - color: #fff !important; /* in case code highlighting fails */ -} - -code.html.full, -code.css.full{ - border: none; - display: block; - padding: 1rem; - background: #333; - text-align: left; - color: #fff !important; /* in case code highlighting fails */ -} - -code.full{ - margin-top: 1rem; - color: #fff !important; /* in case code highlighting fails */ -} - -code.full::before{ - display: block; - border-bottom: 1px dashed var(--sub-text); - padding-bottom: .5rem; - margin-bottom: .5rem; - font-weight: bold; - line-height: 1; -} - -code.html.full::before{ - content: 'HTML'; -} - -code.css.full::before{ - content: 'CSS'; -} - -code{ - font-family: 'Source Code Pro', monospace; - font-size: .8rem; -} - -code.terminal{ - color: #fff; - background-color: #444; - font-family: 'Source Code Pro', monospace; - text-align: left; - padding: 1rem 1rem 1rem 3rem; - border-radius: .25rem; - position: relative; - display: block; - margin-top: 1rem; - overflow: auto; -} - -code.terminal::before{ - content: url('/images/terminal.svg'); - height: 1rem; - width: 1rem; - top: 1.15rem; - left: 1rem; - position: absolute; -} - -code.raw{ - white-space: pre; -} - -code.terminal span{ - display: block; -} - -code.terminal span::before{ - margin-right: .5rem; - color: #56DA55; - font-weight: bold; - display: inline; -} - -code.terminal > span::before{ - content:'user@localhost>'; -} - -blockquote, -figure.text{ - background: rgba(255,255,255,.25); - border: 1px solid rgba(255,255,255,.25); - padding: 1rem; - border-radius: .25rem; -} - -blockquote{ - font-style: italic; -} - -blockquote mark.error{ - background: #CF4647; - padding: .2rem; -} - -table{ - width: 100%; - text-align: left; - margin-top: 1rem; -} - -table code.full{ - display: block; - white-space: normal !important; -} - -table code.full{ - white-space: pre-wrap !important; -} - -table td{ - vertical-align: top; - padding: 1rem; -} - -table td:first-child{ - width: 25%; -} - -table td + td{ - padding-left: 10px; -} - -table p{ - margin: 0; -} - -table thead{ - border-bottom: 3px double var(--sub-text); - font-weight: bold; -} - -abbr{ - white-space: nowrap; -} - -abbr.acronym{ - font-variant: all-small-caps; -} - -abbr.temperature, -abbr.era{ - font-variant: all-small-caps; -} - -h3 abbr.initialism{ - font-variant: normal; -} - figure img{ border-radius: .25rem; border: 1px solid var(--border); @@ -1366,82 +1191,6 @@ figure p + p{ margin-top: 15px; } -figure p.wrong{ - text-decoration-line: underline; - text-decoration-style: wavy; - text-decoration-color: #CF4647; -} - -figure p.wrong:before, -figure.wrong:before{ - font-family: "FontAwesome"; - content: "\f00d"; - font-size: 1.5rem; - width: 1.5rem; - line-height: 1; - margin-right: .5rem; - color: #CF4647; - text-shadow: 1px 1px 0 rgba(0, 0, 0, .1); - display: inline-block; -} - -figure p.corrected:before, -figure.corrected:before{ - font-family: "FontAwesome"; - content: "\f00c"; - font-size: 1.5rem; - line-height: 1; - margin-right: .5rem; - width: 1.5rem; - color: #79BD9A; - text-shadow: 1px 1px 0 rgba(0, 0, 0, .1); - display: inline-block; -} - -figure.wrong:before, -figure.corrected:before{ - display: flex; - margin-right: 0; - align-self: stretch; - align-items: center; - justify-content: center; - padding: 0 .5rem; - border-top-left-radius: .25rem; - border-bottom-left-radius: .25rem; -} - -figure.wrong:before{ - background: #762729; -} - -figure.corrected:before{ - background: #406451; -} - -figure.wrong code{ - background: #550000 url('/images/stripes-dark.svg'); -} - -figure.wrong, -figure.corrected{ - display: flex; - align-items: center; -} - -figure.wrong code, -figure.corrected code{ - flex-grow: 1; - border-top-left-radius: 0; - border-bottom-left-radius: 0; -} - -.warning{ - font-size: 2rem; - font-weight: bold; - text-align: center; - font-style: normal; -} - main.ebooks nav{ display: flex; justify-content: center; @@ -1546,24 +1295,6 @@ label.search::before{ text-shadow: 1px 1px 0 rgba(255, 255, 255, .5); } -.utf{ - border: 1px solid var(--body-text); - padding: .1rem; - line-height: 1; - margin: 0 .1rem; - font-size: .5rem; - display: inline-block; - font-family: monospace; - vertical-align: middle; - margin-top: -3px; /* to match poor crimson alignment */ -} - -figure code.html .utf, -code.full .utf{ - border-color: #fff; - margin-top: 0; -} - article nav ol li:not(:first-child):not(:last-child):not(.highlighted), main.ebooks nav ol li:not(:first-child):not(:last-child):not(.highlighted){ display: none; @@ -1592,28 +1323,6 @@ main.ebooks nav ol li.highlighted:nth-last-child(2)::after{ display: none; } -#producing-an-ebook > ol { - counter-reset: item; - margin-left: 0; - padding-left: 0; - list-style: none; -} - -#producing-an-ebook > ol > li::before { - float: left; - content: counter(item) "."; - counter-increment: item; - width: 4rem; - text-align: right; - margin-left: -5.5rem; - - font-size: 1.2rem; - font-family: 'League Spartan', sans-serif; - line-height: 1.2; - letter-spacing: 1px; - text-transform: uppercase; -} - @media(max-width: 1100px){ article.ebook header{ width: calc(100% + 4rem); @@ -1876,15 +1585,6 @@ main.ebooks nav ol li.highlighted:nth-last-child(2)::after{ color: rgba(255, 255, 255, .75); } - blockquote, - figure.text{ - background: rgba(0,0,0,.25); - } - - code.terminal{ - background-color: var(--light-body-text); - } - main.ebooks > ol img:hover{ box-shadow: 3px 3px 1px rgba(0, 0, 0, .5); } diff --git a/www/css/manual.css b/www/css/manual.css index d2e8cee1..7175fd7a 100644 --- a/www/css/manual.css +++ b/www/css/manual.css @@ -1,5 +1,318 @@ @import url("monokai.css"); +main code:first-child{ + margin-top: 0; +} + +code{ + hyphens: none; +} + +blockquote, +figure.text{ + background: rgba(255,255,255,.25); + border: 1px solid rgba(255,255,255,.25); + padding: 1rem; + border-radius: .25rem; +} + +blockquote{ + font-style: italic; +} + +blockquote mark.error{ + background: #CF4647; + padding: .2rem; +} + +table{ + width: 100%; + text-align: left; + margin-top: 1rem; +} + +table code.full{ + display: block; + white-space: normal !important; +} + +table code.full{ + white-space: pre-wrap !important; +} + +table td{ + vertical-align: top; + padding: 1rem; +} + +table td:first-child{ + width: 25%; +} + +table td + td{ + padding-left: 10px; +} + +table p{ + margin: 0; +} + +table thead{ + border-bottom: 3px double var(--sub-text); + font-weight: bold; +} + +abbr{ + white-space: nowrap; +} + +abbr.acronym{ + font-variant: all-small-caps; +} + +abbr.temperature, +abbr.era{ + font-variant: all-small-caps; +} + +h3 abbr.initialism{ + font-variant: normal; +} + +code.string, +code.tag, +code.path, +code.program, +code.bash, +code.regex, +code.html, +code.xml, +code.ietf, +code.css, +code.marc{ + border: 1px solid rgba(255,255,255,.25); + background: #333; + border-radius: .25rem; + white-space: nowrap; + padding: 0 .25rem; + color: #fff; + margin: 0 .2rem; +} + +figure code.xml, +figure code.html, +figure code.css{ + padding: 1rem; + background: #333; + border: none; + text-align: left; + color: #fff !important; /* in case code highlighting fails */ +} + +code.xml.full, +code.html.full, +code.css.full{ + border: none; + display: block; + padding: 1rem; + background: #333; + text-align: left; + color: #fff !important; /* in case code highlighting fails */ +} + +code.full{ + margin-top: 1rem; + color: #fff !important; /* in case code highlighting fails */ +} + +code.full::before{ + display: block; + border-bottom: 1px dashed var(--sub-text); + padding-bottom: .5rem; + margin-bottom: .5rem; + font-weight: bold; + line-height: 1; +} + +code.xml.full::before{ + content: 'XML'; +} + +code.html.full::before{ + content: 'HTML'; +} + +code.css.full::before{ + content: 'CSS'; +} + +code{ + font-family: 'Source Code Pro', monospace; + font-size: .8rem; +} + +code.terminal{ + color: #fff; + background-color: #444; + font-family: 'Source Code Pro', monospace; + text-align: left; + padding: 1rem 1rem 1rem 3rem; + border-radius: .25rem; + position: relative; + display: block; + margin-top: 1rem; + overflow: auto; +} + +code.terminal::before{ + content: url('/images/terminal.svg'); + height: 1rem; + width: 1rem; + top: 1.15rem; + left: 1rem; + position: absolute; +} + +code.raw{ + white-space: pre; +} + +code.terminal span{ + display: block; +} + +code.terminal span::before{ + margin-right: .5rem; + color: #56DA55; + font-weight: bold; + display: inline; +} + +code.terminal > span::before{ + content:'user@localhost>'; +} + +.utf{ + border: 1px solid var(--body-text); + padding: .1rem; + line-height: 1; + margin: 0 .2rem; + display: inline-block; + font-family: monospace; + vertical-align: middle; + margin-top: -3px; /* to match poor crimson alignment */ +} + +figure code.html .utf, +code.full .utf{ + border-color: #fff; + margin-top: 0; +} + + +#producing-an-ebook > ol li::marker{ + font-weight: bold; + font-family: 'League Spartan', sans-serif; +} + +#producing-an-ebook > ol { + counter-reset: item; + margin-left: 0; + padding-left: 0; + list-style: none; +} + +#producing-an-ebook > ol > li::before { + float: left; + content: counter(item) "."; + counter-increment: item; + width: 4rem; + text-align: right; + margin-left: -5.5rem; + + font-size: 1.2rem; + font-family: 'League Spartan', sans-serif; + line-height: 1.2; + letter-spacing: 1px; + text-transform: uppercase; +} + +.warning{ + font-size: 2rem; + font-weight: bold; + text-align: center; + font-style: normal; +} + +figure p.wrong{ + text-decoration-line: underline; + text-decoration-style: wavy; + text-decoration-color: #CF4647; +} + +figure p.wrong:before, +figure.wrong:before{ + font-family: "FontAwesome"; + content: "\f00d"; + font-size: 1.5rem; + width: 1.5rem; + line-height: 1; + margin-right: .5rem; + color: #CF4647; + text-shadow: 1px 1px 0 rgba(0, 0, 0, .1); + display: inline-block; +} + +figure p.corrected:before, +figure.corrected:before{ + font-family: "FontAwesome"; + content: "\f00c"; + font-size: 1.5rem; + line-height: 1; + margin-right: .5rem; + width: 1.5rem; + color: #79BD9A; + text-shadow: 1px 1px 0 rgba(0, 0, 0, .1); + display: inline-block; +} + +figure.wrong:before, +figure.corrected:before{ + display: flex; + margin-right: 0; + align-self: stretch; + align-items: center; + justify-content: center; + padding: 0 .5rem; + border-top-left-radius: .25rem; + border-bottom-left-radius: .25rem; +} + +figure.wrong:before{ + background: #762729; +} + +figure.corrected:before{ + background: #406451; +} + +figure.wrong code{ + background: #550000 url('/images/stripes-dark.svg'); +} + +figure.wrong, +figure.corrected{ + display: flex; + align-items: center; +} + +figure.wrong code, +figure.corrected code{ + flex-grow: 1; + border-top-left-radius: 0; + border-bottom-left-radius: 0; +} + .manual p{ text-align: left; } @@ -132,8 +445,22 @@ margin-top: -3px; /* to match poor crimson alignment */ } -code.bash > span{ - color: var(--dark-button-highlight); +code.terminal b, +code.bash b{ + font-weight: normal; + color: #4a9906; +} + +code.terminal i, +code.bash i{ + font-style: normal; + color: #c4a000; +} + +code.terminal i.glob, +code.bash i.glob{ + font-style: normal; + color: #719ece; } figure code.html .ws, @@ -189,6 +516,7 @@ main.manual > nav ol{ list-style: none; } +figure code.xml, figure code.html, figure code.css{ white-space: pre; @@ -221,7 +549,7 @@ figure code.css{ } main.manual > article > section, - main.manual nav + h1{ + main.manual nav + article h1{ margin-top: 0; } @@ -235,3 +563,14 @@ figure code.css{ margin-left: 2rem; } } + +@media(prefers-color-scheme: dark){ + blockquote, + figure.text{ + background: rgba(0,0,0,.25); + } + + code.terminal{ + background-color: var(--light-body-text); + } +} diff --git a/www/index.php b/www/index.php index 0377cd3d..df4bf9cd 100644 --- a/www/index.php +++ b/www/index.php @@ -14,7 +14,7 @@ require_once('Core.php');

    Other free ebooks don’t put much effort into professional-quality typography: they use "straight" quotes instead of “curly” quotes, they ignore details like em- and en-dashes, and they look more like early-90’s web pages instead of actual books.

    -

    The Standard Ebooks project applies a rigorous and modern typography manual when developing each and every ebook to ensure they meet a professional-grade and consistent typographical standard. Our ebooks look good.

    +

    The Standard Ebooks project applies a rigorous and modern style manual when developing each and every ebook to ensure they meet a professional-grade and consistent typographical standard. Our ebooks look good.

    An example of bad typography. An example of Standard Ebooks typography. An arrow pointing from bad typography to good typography. diff --git a/www/js/core.js b/www/js/core.js deleted file mode 100644 index 83406b49..00000000 --- a/www/js/core.js +++ /dev/null @@ -1,10 +0,0 @@ -'use strict'; - -document.addEventListener('DOMContentLoaded', function(){ - if(hljs){ - let blocks = document.querySelectorAll('code.html.full, code.css.full, figure code.html'); - for(let i = 0; i < blocks.length; i++){ - hljs.highlightBlock(blocks[i]); - } - } -}); diff --git a/www/js/highlight.js/CHANGES.md b/www/js/highlight.js/CHANGES.md deleted file mode 100644 index 05473a26..00000000 --- a/www/js/highlight.js/CHANGES.md +++ /dev/null @@ -1,1646 +0,0 @@ -## Version 9.12.0 - -New language: - -- *MikroTik* RouterOS Scripting language by [Ivan Dementev][]. - -New style: - -- *VisualStudio 2015 Dark* by [Nicolas LLOBERA][] - -Improvements: - -- *Crystal* updated with new keywords and syntaxes by [Tsuyusato Kitsune][]. -- *Julia* updated to the modern definitions by [Alex Arslan][]. -- *julia-repl* added by [Morten Piibeleht][]. -- [Stanislav Belov][] wrote a new definition for *1C*, replacing the one that - has not been updated for more than 8 years. The new version supports syntax - for versions 7.7 and 8. -- [Nicolas LLOBERA][] improved C# definition fixing edge cases with function - titles detection and added highlighting of `[Attributes]`. -- [nnnik][] provided a few correctness fixes for *Autohotkey*. -- [Martin Clausen][] made annotation collections in *Clojure* to look - consistently with other kinds. -- [Alejandro Alonso][] updated *Swift* keywords. - -[Tsuyusato Kitsune]: https://github.com/MakeNowJust -[Alex Arslan]: https://github.com/ararslan -[Morten Piibeleht]: https://github.com/mortenpi -[Stanislav Belov]: https://github.com/4ppl -[Ivan Dementev]: https://github.com/DiVAN1x -[Nicolas LLOBERA]: https://github.com/Nicolas01 -[nnnik]: https://github.com/nnnik -[Martin Clausen]: https://github.com/maacl -[Alejandro Alonso]: https://github.com/Azoy - - -## Version 9.11.0 - -New languages: - -- *Shell* by [Tsuyusato Kitsune][] -- *jboss-cli* by [Raphaël Parrëe][] - -Improvements: - -- [Joël Porquet] has [greatly improved the definition of *makefile*][5b3e0e6]. -- *C++* class titles are now highlighted as in other languages with classes. -- [Jordi Petit][] added rarely used `or`, `and` and `not` keywords to *C++*. -- [Pieter Vantorre][] fixed highlighting of negative floating point values. - - -[Tsuyusato Kitsune]: https://github.com/MakeNowJust -[Jordi Petit]: https://github.com/jordi-petit -[Raphaël Parrëe]: https://github.com/rparree -[Pieter Vantorre]: https://github.com/NuclearCookie -[5b3e0e6]: https://github.com/isagalaev/highlight.js/commit/5b3e0e68bfaae282faff6697d6a490567fa9d44b - - -## Version 9.10.0 - -Apologies for missing the previous release cycle. Some thing just can't be -automated… Anyway, we're back! - -New languages: - -- *Hy* by [Sergey Sobko][] -- *Leaf* by [Hale Chan][] -- *N1QL* by [Andres Täht][] and [Rene Saarsoo][] - -Improvements: - -- *Rust* got updated with new keywords by [Kasper Andersen][] and then - significantly modernized even more by [Eduard-Mihai Burtescu][] (yes, @eddyb, - Rust core team member!) -- *Python* updated with f-literals by [Philipp A][]. -- *YAML* updated with unquoted strings support. -- *Gauss* updated with new keywords by [Matt Evans][]. -- *Lua* updated with new keywords by [Joe Blow][]. -- *Kotlin* updated with new keywords by [Philipp Hauer][]. -- *TypeScript* got highlighting of function params and updated keywords by - [Ike Ku][]. -- *Scheme* now correctly handles \`-quoted lists thanks to [Guannan Wei]. -- [Sam Wu][] fixed handling of `<<` in *C++* defines. - -[Philipp A]: https://github.com/flying-sheep -[Philipp Hauer]: https://github.com/phauer -[Sergey Sobko]: https://github.com/profitware -[Hale Chan]: https://github.com/halechan -[Matt Evans]: https://github.com/matthewevans -[Joe Blow]: https://github.com/mossarelli -[Kasper Andersen]: https://github.com/kasma1990 -[Eduard-Mihai Burtescu]: https://github.com/eddyb -[Andres Täht]: https://github.com/andrestaht -[Rene Saarsoo]: https://github.com/nene -[Philipp Hauer]: https://github.com/phauer -[Ike Ku]: https://github.com/dempfi -[Guannan Wei]: https://github.com/Kraks -[Sam Wu]: https://github.com/samsam2310 - - -## Version 9.9.0 - -New languages - -- *LLVM* by [Michael Rodler][] - -Improvements: - -- *TypeScript* updated with annotations and param lists inside constructors, by - [Raphael Parree][]. -- *CoffeeScript* updated with new keywords and fixed to recognize JavaScript - in \`\`\`, thanks to thanks to [Geoffrey Booth][]. -- Compiler directives in *Delphi* are now correctly highlighted as "meta". - -[Raphael Parree]: https://github.com/rparree -[Michael Rodler]: https://github.com/f0rki -[Geoffrey Booth]: https://github.com/GeoffreyBooth - - -## Version 9.8.0 "New York" - -This version is the second one that deserved a name. Because I'm in New York, -and the release isn't missing the deadline only because it's still Tuesday on -West Coast. - -New languages: - -- *Clean* by [Camil Staps][] -- *Flix* by [Magnus Madsen][] - -Improvements: - -- [Kenton Hamaluik][] did a comprehensive update for *Haxe*. -- New commands for *PowerShell* from [Nicolas Le Gall][]. -- [Jan T. Sott][] updated *NSIS*. -- *Java* and *Swift* support unicode characters in identifiers thanks to - [Alexander Lichter][]. - -[Camil Staps]: https://github.com/camilstaps -[Magnus Madsen]: https://github.com/magnus-madsen -[Kenton Hamaluik]: https://github.com/FuzzyWuzzie -[Nicolas Le Gall]: https://github.com/darkitty -[Jan T. Sott]: https://github.com/idleberg -[Alexander Lichter]: https://github.com/manniL - - -## Version 9.7.0 - -A comprehensive bugfix release. This is one of the best things about -highlight.js: even boring things keep getting better (even if slow). - -- VHDL updated with PSL keywords and uses more consistent styling. -- Nested C-style comments no longer break highlighting in many languages. -- JavaScript updated with `=>` functions, highlighted object attributes and - parsing within template string substitution blocks (`${...}`). -- Fixed another corner case with self-closing `` in JSX. -- Added `HEALTHCHECK` directive in Docker. -- Delphi updated with new Free Pascal keywords. -- Fixed digit separator parsing in C++. -- C# updated with new keywords and fixed to allow multiple identifiers within - generics `<...>`. -- Fixed another slow regex in Less. - - -## Version 9.6.0 - -New languages: - -- *ABNF* and *EBNF* by [Alex McKibben][] -- *Awk* by [Matthew Daly][] -- *SubUnit* by [Sergey Bronnikov][] - -New styles: - -- *Atom One* in both Dark and Light variants by [Daniel Gamage][] - -Plus, a few smaller updates for *Lasso*, *Elixir*, *C++* and *SQL*. - -[Alex McKibben]: https://github.com/mckibbenta -[Daniel Gamage]: https://github.com/danielgamage -[Matthew Daly]: https://github.com/matthewbdaly -[Sergey Bronnikov]: https://github.com/ligurio - - -## Version 9.5.0 - -New languages: - -- *Excel* by [Victor Zhou][] -- *Linden Scripting Language* by [Builder's Brewery][] -- *TAP* (Test Anything Protocol) by [Sergey Bronnikov][] -- *Pony* by [Joe Eli McIlvain][] -- *Coq* by [Stephan Boyer][] -- *dsconfig* and *LDIF* by [Jacob Childress][] - -New styles: - -- *Ocean Dark* by [Gavin Siu][] - -Notable changes: - -- [Minh Nguyễn][] added more built-ins to Objective C. -- [Jeremy Hull][] fixed corner cases in C++ preprocessor directives and Diff - comments. -- [Victor Zhou][] added support for digit separators in C++ numbers. - -[Gavin Siu]: https://github.com/gavsiu -[Builder's Brewery]: https://github.com/buildersbrewery -[Victor Zhou]: https://github.com/OiCMudkips -[Sergey Bronnikov]: https://github.com/ligurio -[Joe Eli McIlvain]: https://github.com/jemc -[Stephan Boyer]: https://github.com/boyers -[Jacob Childress]: https://github.com/braveulysses -[Minh Nguyễn]: https://github.com/1ec5 -[Jeremy Hull]: https://github.com/sourrust - - -## Version 9.4.0 - -New languages: - -- *PureBASIC* by [Tristano Ajmone][] -- *BNF* by [Oleg Efimov][] -- *Ada* by [Lars Schulna][] - -New styles: - -- *PureBASIC* by [Tristano Ajmone][] - -Improvements to existing languages and styles: - -- We now highlight function declarations in Go. -- [Taisuke Fujimoto][] contributed very convoluted rules for raw and - interpolated strings in C#. -- [Boone Severson][] updated Verilog to comply with IEEE 1800-2012 - SystemVerilog. -- [Victor Zhou][] improved rules for comments and strings in PowerShell files. -- [Janis Voigtländer][] updated the definition of Elm to version 0.17 of the - languages. Elm is now featured on the front page of . -- Special variable `$this` is highlighted as a keyword in PHP. -- `usize` and `isize` are now highlighted in Rust. -- Fixed labels and directives in x86 assembler. - -[Tristano Ajmone]: https://github.com/tajmone -[Taisuke Fujimoto]: https://github.com/temp-impl -[Oleg Efimov]: https://github.com/Sannis -[Boone Severson]: https://github.com/BooneJS -[Victor Zhou]: https://github.com/OiCMudkips -[Lars Schulna]: https://github.com/captain-hanuta -[Janis Voigtländer]: https://github.com/jvoigtlaender - - -## Version 9.3.0 - -New languages: - -- *Tagger Script* by [Philipp Wolfer][] -- *MoonScript* by [Billy Quith][] - -New styles: - -- *xt256* by [Herbert Shin][] - -Improvements to existing languages and styles: - -- More robust handling of unquoted HTML tag attributes -- Relevance tuning for QML which was unnecessary eager at seizing other - languages' code -- Improve GAMS language parsing -- Fixed a bunch of bugs around selectors in Less -- Kotlin's got a new definition for annotations, updated keywords and other - minor improvements -- Added `move` to Rust keywords -- Markdown now recognizes \`\`\`-fenced code blocks -- Improved detection of function declarations in C++ and C# - -[Philipp Wolfer]: https://github.com/phw -[Billy Quith]: https://github.com/billyquith -[Herbert Shin]: https://github.com/initbar - - -## Version 9.2.0 - -New languages: - -- *QML* by [John Foster][] -- *HTMLBars* by [Michael Johnston][] -- *CSP* by [Taras][] -- *Maxima* by [Robert Dodier][] - -New styles: - -- *Gruvbox* by [Qeole][] -- *Dracula* by [Denis Ciccale][] - -Improvements to existing languages and styles: - -- We now correctly handle JSX with arbitrary node tree depth. -- Argument list for `(lambda)` in Scheme is no longer highlighted as a function - call. -- Stylus syntax doesn't break on valid CSS. -- More correct handling of comments and strings and other improvements for - VimScript. -- More subtle work on the default style. -- We now use anonymous modules for AMD. -- `macro_rules!` is now recognized as a built-in in Rust. - -[John Foster]: https://github.com/jf990 -[Qeole]: https://github.com/Qeole -[Denis Ciccale]: https://github.com/dciccale -[Michael Johnston]: https://github.com/lastobelus -[Taras]: https://github.com/oxdef -[Robert Dodier]: https://github.com/robert-dodier - - -## Version 9.1.0 - -New languages: - -- *Stan* by [Brendan Rocks][] -- *BASIC* by [Raphaël Assénat][] -- *GAUSS* by [Matt Evans][] -- *DTS* by [Martin Braun][] -- *Arduino* by [Stefania Mellai][] - -New Styles: - -- *Arduino Light* by [Stefania Mellai][] - -Improvements to existing languages and styles: - -- Handle return type annotations in Python -- Allow shebang headers in Javascript -- Support strings in Rust meta -- Recognize `struct` as a class-level definition in Rust -- Recognize b-prefixed chars and strings in Rust -- Better numbers handling in Verilog - -[Brendan Rocks]: http://brendanrocks.com -[Raphaël Assénat]: https://github.com/raphnet -[Matt Evans]: https://github.com/matthewevans -[Martin Braun]: https://github.com/mbr0wn -[Stefania Mellai]: https://github.com/smellai - - -## Version 9.0.0 - -The new major version brings a reworked styling system. Highlight.js now defines -a limited set of highlightable classes giving a consistent result across all the -styles and languages. You can read a more detailed explanation and background in -the [tracking issue][#348] that started this long process back in May. - -This change is backwards incompatible for those who uses highlight.js with a -custom stylesheet. The [new style guide][sg] explains how to write styles -in this new world. - -Bundled themes have also suffered a significant amount of improvements and may -look different in places, but all the things now consistent and make more sense. -Among others, the Default style has got a refresh and will probably be tweaked -some more in next releases. Please do give your feedback in our -[issue tracker][issues]. - -New languages in this release: - -- *Caché Object Script* by [Nikita Savchenko][] -- *YAML* by [Stefan Wienert][] -- *MIPS Assembler* by [Nebuleon Fumika][] -- *HSP* by [prince][] - -Improvements to existing languages and styles: - -- ECMAScript 6 modules import now do not require closing semicolon. -- ECMAScript 6 classes constructors now highlighted. -- Template string support for Typescript, as for ECMAScript 6. -- Scala case classes params highlight fixed. -- Built-in names introduced in Julia v0.4 added by [Kenta Sato][]. -- Refreshed Default style. - -Other notable changes: - -- [Web workers support][webworkers] added bu [Jan Kühle][]. -- We now have tests for compressed browser builds as well. -- The building tool chain has been switched to node.js 4.x. and is now - shamelessly uses ES6 features all over the place, courtesy of [Jeremy Hull][]. -- License added to non-compressed browser build. - -[Jan Kühle]: https://github.com/frigus02 -[Stefan Wienert]: https://github.com/zealot128 -[Kenta Sato]: https://github.com/bicycle1885 -[Nikita Savchenko]: https://github.com/ZitRos -[webworkers]: https://github.com/isagalaev/highlight.js#web-workers -[Jeremy Hull]: https://github.com/sourrust -[#348]: https://github.com/isagalaev/highlight.js/issues/348 -[sg]: http://highlightjs.readthedocs.org/en/latest/style-guide.html -[issues]: https://github.com/isagalaev/highlight.js/issues -[Nebuleon Fumika]: https://github.com/Nebuleon -[prince]: https://github.com/prince-0203 - - -## Version 8.9.1 - -Some last-minute changes reverted due to strange bug with minified browser build: - -- Scala case classes params highlight fixed -- ECMAScript 6 modules import now do not require closing semicolon -- ECMAScript 6 classes constructors now highlighted -- Template string support for Typescript, as for ECMAScript 6 -- License added to not minified browser build - - -## Version 8.9.0 - -New languages: - -- *crmsh* by [Kristoffer Gronlund][] -- *SQF* by [Soren Enevoldsen][] - -[Kristoffer Gronlund]: https://github.com/krig -[Soren Enevoldsen]: https://github.com/senevoldsen90 - -Notable fixes and improvements to existing languages: - -- Added `abstract` and `namespace` keywords to TypeScript by [Daniel Rosenwasser][] -- Added `label` support to Dockerfile by [Ladislav Prskavec][] -- Crystal highlighting improved by [Tsuyusato Kitsune][] -- Missing Swift keywords added by [Nate Cook][] -- Improve detection of C block comments -- ~~Scala case classes params highlight fixed~~ -- ~~ECMAScript 6 modules import now do not require closing semicolon~~ -- ~~ECMAScript 6 classes constructors now highlighted~~ -- ~~Template string support for Typescript, as for ECMAScript 6~~ - -Other notable changes: - -- ~~License added to not minified browser build~~ - -[Kristoffer Gronlund]: https://github.com/krig -[Søren Enevoldsen]: https://github.com/senevoldsen90 -[Daniel Rosenwasser]: https://github.com/DanielRosenwasser -[Ladislav Prskavec]: https://github.com/abtris -[Tsuyusato Kitsune]: https://github.com/MakeNowJust -[Nate Cook]: https://github.com/natecook1000 - - -## Version 8.8.0 - -New languages: - -- *Golo* by [Philippe Charrière][] -- *GAMS* by [Stefan Bechert][] -- *IRPF90* by [Anthony Scemama][] -- *Access logs* by [Oleg Efimov][] -- *Crystal* by [Tsuyusato Kitsune][] - -Notable fixes and improvements to existing languages: - -- JavaScript highlighting no longer fails with ES6 default parameters -- Added keywords `async` and `await` to Python -- PHP heredoc support improved -- Allow preprocessor directives within C++ functions - -Other notable changes: - -- Change versions to X.Y.Z SemVer-compatible format -- Added ability to build all targets at once - -[Philippe Charrière]: https://github.com/k33g -[Stefan Bechert]: https://github.com/b-pos465 -[Anthony Scemama]: https://github.com/scemama -[Oleg Efimov]: https://github.com/Sannis -[Tsuyusato Kitsune]: https://github.com/MakeNowJust - - -## Version 8.7 - -New languages: - -- *Zephir* by [Oleg Efimov][] -- *Elm* by [Janis Voigtländer][] -- *XQuery* by [Dirk Kirsten][] -- *Mojolicious* by [Dotan Dimet][] -- *AutoIt* by Manh Tuan from [J2TeaM][] -- *Toml* (ini extension) by [Guillaume Gomez][] - -New styles: - -- *Hopscotch* by [Jan T. Sott][] -- *Grayscale* by [MY Sun][] - -Notable fixes and improvements to existing languages: - -- Fix encoding of images when copied over in certain builds -- Fix incorrect highlighting of the word "bug" in comments -- Treat decorators different from matrix multiplication in Python -- Fix traits inheritance highlighting in Rust -- Fix incorrect document -- Oracle keywords added to SQL language definition by [Vadimtro][] -- Postgres keywords added to SQL language definition by [Benjamin Auder][] -- Fix registers in x86asm being highlighted as a hex number -- Fix highlighting for numbers with a leading decimal point -- Correctly highlight numbers and strings inside of C/C++ macros -- C/C++ functions now support pointer, reference, and move returns - -[Oleg Efimov]: https://github.com/Sannis -[Guillaume Gomez]: https://github.com/GuillaumeGomez -[Janis Voigtländer]: https://github.com/jvoigtlaender -[Jan T. Sott]: https://github.com/idleberg -[Dirk Kirsten]: https://github.com/dirkk -[MY Sun]: https://github.com/simonmysun -[Vadimtro]: https://github.com/Vadimtro -[Benjamin Auder]: https://github.com/ghost -[Dotan Dimet]: https://github.com/dotandimet -[J2TeaM]: https://github.com/J2TeaM - - -## Version 8.6 - -New languages: - -- *C/AL* by [Kenneth Fuglsang][] -- *DNS zone file* by [Tim Schumacher][] -- *Ceylon* by [Lucas Werkmeister][] -- *OpenSCAD* by [Dan Panzarella][] -- *Inform7* by [Bruno Dias][] -- *armasm* by [Dan Panzarella][] -- *TP* by [Jay Strybis][] - -New styles: - -- *Atelier Cave*, *Atelier Estuary*, - *Atelier Plateau* and *Atelier Savanna* by [Bram de Haan][] -- *Github Gist* by [Louis Barranqueiro][] - -Notable fixes and improvements to existing languages: - -- Multi-line raw strings from C++11 are now supported -- Fix class names with dashes in HAML -- The `async` keyword from ES6/7 is now supported -- TypeScript functions handle type and parameter complexity better -- We unified phpdoc/javadoc/yardoc etc modes across all languages -- CSS .class selectors relevance was dropped to prevent wrong language detection -- Images is now included to CDN build -- Release process is now automated - -[Bram de Haan]: https://github.com/atelierbram -[Kenneth Fuglsang]: https://github.com/kfuglsang -[Louis Barranqueiro]: https://github.com/LouisBarranqueiro -[Tim Schumacher]: https://github.com/enko -[Lucas Werkmeister]: https://github.com/lucaswerkmeister -[Dan Panzarella]: https://github.com/pzl -[Bruno Dias]: https://github.com/sequitur -[Jay Strybis]: https://github.com/unreal - - -## Version 8.5 - -New languages: - -- *pf.conf* by [Peter Piwowarski][] -- *Julia* by [Kenta Sato][] -- *Prolog* by [Raivo Laanemets][] -- *Docker* by [Alexis Hénaut][] -- *Fortran* by [Anthony Scemama][] and [Thomas Applencourt][] -- *Kotlin* by [Sergey Mashkov][] - -New styles: - -- *Agate* by [Taufik Nurrohman][] -- *Darcula* by [JetBrains][] -- *Atelier Sulphurpool* by [Bram de Haan][] -- *Android Studio* by [Pedro Oliveira][] - -Notable fixes and improvements to existing languages: - -- ES6 features in JavaScript are better supported now by [Gu Yiling][]. -- Swift now recognizes body-less method definitions. -- Single expression functions `def foo, do: ... ` now work in Elixir. -- More uniform detection of built-in classes in Objective C. -- Fixes for number literals and processor directives in Rust. -- HTML ` - ``` - -- `tabReplace` and `useBR` that were used in different places are also unified - into the global options object and are to be set using `configure(options)`. - This function is documented in our [API docs][]. Also note that these - parameters are gone from `highlightBlock` and `fixMarkup` which are now also - rely on `configure`. - -- We removed public-facing (though undocumented) object `hljs.LANGUAGES` which - was used to register languages with the library in favor of two new methods: - `registerLanguage` and `getLanguage`. Both are documented in our [API docs][]. - -- Result returned from `highlight` and `highlightAuto` no longer contains two - separate attributes contributing to relevance score, `relevance` and - `keyword_count`. They are now unified in `relevance`. - -Another technically compatible change that nonetheless might need attention: - -- The structure of the NPM package was refactored, so if you had installed it - locally, you'll have to update your paths. The usual `require('highlight.js')` - works as before. This is contributed by [Dmitry Smolin][]. - -New features: - -- Languages now can be recognized by multiple names like "js" for JavaScript or - "html" for, well, HTML (which earlier insisted on calling it "xml"). These - aliases can be specified in the class attribute of the code container in your - HTML as well as in various API calls. For now there are only a few very common - aliases but we'll expand it in the future. All of them are listed in the - [class reference][cr]. - -- Language detection can now be restricted to a subset of languages relevant in - a given context — a web page or even a single highlighting call. This is - especially useful for node.js build that includes all the known languages. - Another example is a StackOverflow-style site where users specify languages - as tags rather than in the markdown-formatted code snippets. This is - documented in the [API reference][] (see methods `highlightAuto` and - `configure`). - -- Language definition syntax streamlined with [variants][] and - [beginKeywords][]. - -New languages and styles: - -- *Oxygene* by [Carlo Kok][] -- *Mathematica* by [Daniel Kvasnička][] -- *Autohotkey* by [Seongwon Lee][] -- *Atelier* family of styles in 10 variants by [Bram de Haan][] -- *Paraíso* styles by [Jan T. Sott][] - -Miscellaneous improvements: - -- Highlighting `=>` prompts in Clojure. -- [Jeremy Hull][] fixed a lot of styles for consistency. -- Finally, highlighting PHP and HTML [mixed in peculiar ways][php-html]. -- Objective C and C# now properly highlight titles in method definition. -- Big overhaul of relevance counting for a number of languages. Please do report - bugs about mis-detection of non-trivial code snippets! - -[API reference]: http://highlightjs.readthedocs.org/en/latest/api.html - -[cr]: http://highlightjs.readthedocs.org/en/latest/css-classes-reference.html -[api docs]: http://highlightjs.readthedocs.org/en/latest/api.html -[variants]: https://groups.google.com/d/topic/highlightjs/VoGC9-1p5vk/discussion -[beginKeywords]: https://github.com/isagalaev/highlight.js/commit/6c7fdea002eb3949577a85b3f7930137c7c3038d -[php-html]: https://twitter.com/highlightjs/status/408890903017689088 - -[Carlo Kok]: https://github.com/carlokok -[Bram de Haan]: https://github.com/atelierbram -[Daniel Kvasnička]: https://github.com/dkvasnicka -[Dmitry Smolin]: https://github.com/dimsmol -[Jeremy Hull]: https://github.com/sourrust -[Seongwon Lee]: https://github.com/dlimpid -[Jan T. Sott]: https://github.com/idleberg - - -## Version 7.5 - -A catch-up release dealing with some of the accumulated contributions. This one -is probably will be the last before the 8.0 which will be slightly backwards -incompatible regarding some advanced use-cases. - -One outstanding change in this version is the addition of 6 languages to the -[hosted script][d]: Markdown, ObjectiveC, CoffeeScript, Apache, Nginx and -Makefile. It now weighs about 6K more but we're going to keep it under 30K. - -New languages: - -- OCaml by [Mehdi Dogguy][mehdid] and [Nicolas Braud-Santoni][nbraud] -- [LiveCode Server][lcs] by [Ralf Bitter][revig] -- Scilab by [Sylvestre Ledru][sylvestre] -- basic support for Makefile by [Ivan Sagalaev][isagalaev] - -Improvements: - -- Ruby's got support for characters like `?A`, `?1`, `?\012` etc. and `%r{..}` - regexps. -- Clojure now allows a function call in the beginning of s-expressions - `(($filter "myCount") (arr 1 2 3 4 5))`. -- Haskell's got new keywords and now recognizes more things like pragmas, - preprocessors, modules, containers, FFIs etc. Thanks to [Zena Treep][treep] - for the implementation and to [Jeremy Hull][sourrust] for guiding it. -- Miscellaneous fixes in PHP, Brainfuck, SCSS, Asciidoc, CMake, Python and F#. - -[mehdid]: https://github.com/mehdid -[nbraud]: https://github.com/nbraud -[revig]: https://github.com/revig -[lcs]: http://livecode.com/developers/guides/server/ -[sylvestre]: https://github.com/sylvestre -[isagalaev]: https://github.com/isagalaev -[treep]: https://github.com/treep -[sourrust]: https://github.com/sourrust -[d]: http://highlightjs.org/download/ - - -## New core developers - -The latest long period of almost complete inactivity in the project coincided -with growing interest to it led to a decision that now seems completely obvious: -we need more core developers. - -So without further ado let me welcome to the core team two long-time -contributors: [Jeremy Hull][] and [Oleg -Efimov][]. - -Hope now we'll be able to work through stuff faster! - -P.S. The historical commit is [here][1] for the record. - -[Jeremy Hull]: https://github.com/sourrust -[Oleg Efimov]: https://github.com/sannis -[1]: https://github.com/isagalaev/highlight.js/commit/f3056941bda56d2b72276b97bc0dd5f230f2473f - - -## Version 7.4 - -This long overdue version is a snapshot of the current source tree with all the -changes that happened during the past year. Sorry for taking so long! - -Along with the changes in code highlight.js has finally got its new home at -, moving from its cradle on Software Maniacs which it -outgrew a long time ago. Be sure to report any bugs about the site to -. - -On to what's new… - -New languages: - -- Handlebars templates by [Robin Ward][] -- Oracle Rules Language by [Jason Jacobson][] -- F# by [Joans Follesø][] -- AsciiDoc and Haml by [Dan Allen][] -- Lasso by [Eric Knibbe][] -- SCSS by [Kurt Emch][] -- VB.NET by [Poren Chiang][] -- Mizar by [Kelley van Evert][] - -[Robin Ward]: https://github.com/eviltrout -[Jason Jacobson]: https://github.com/jayce7 -[Joans Follesø]: https://github.com/follesoe -[Dan Allen]: https://github.com/mojavelinux -[Eric Knibbe]: https://github.com/EricFromCanada -[Kurt Emch]: https://github.com/kemch -[Poren Chiang]: https://github.com/rschiang -[Kelley van Evert]: https://github.com/kelleyvanevert - -New style themes: - -- Monokai Sublime by [noformnocontent][] -- Railscasts by [Damien White][] -- Obsidian by [Alexander Marenin][] -- Docco by [Simon Madine][] -- Mono Blue by [Ivan Sagalaev][] (uses a single color hue for everything) -- Foundation by [Dan Allen][] - -[noformnocontent]: http://nn.mit-license.org/ -[Damien White]: https://github.com/visoft -[Alexander Marenin]: https://github.com/ioncreature -[Simon Madine]: https://github.com/thingsinjars -[Ivan Sagalaev]: https://github.com/isagalaev - -Other notable changes: - -- Corrected many corner cases in CSS. -- Dropped Python 2 version of the build tool. -- Implemented building for the AMD format. -- Updated Rust keywords (thanks to [Dmitry Medvinsky][]). -- Literal regexes can now be used in language definitions. -- CoffeeScript highlighting is now significantly more robust and rich due to - input from [Cédric Néhémie][]. - -[Dmitry Medvinsky]: https://github.com/dmedvinsky -[Cédric Néhémie]: https://github.com/abe33 - - -## Version 7.3 - -- Since this version highlight.js no longer works in IE version 8 and older. - It's made it possible to reduce the library size and dramatically improve code - readability and made it easier to maintain. Time to go forward! - -- New languages: AppleScript (by [Nathan Grigg][ng] and [Dr. Drang][dd]) and - Brainfuck (by [Evgeny Stepanischev][bolk]). - -- Improvements to existing languages: - - - interpreter prompt in Python (`>>>` and `...`) - - @-properties and classes in CoffeeScript - - E4X in JavaScript (by [Oleg Efimov][oe]) - - new keywords in Perl (by [Kirk Kimmel][kk]) - - big Ruby syntax update (by [Vasily Polovnyov][vast]) - - small fixes in Bash - -- Also Oleg Efimov did a great job of moving all the docs for language and style - developers and contributors from the old wiki under the source code in the - "docs" directory. Now these docs are nicely presented at - . - -[ng]: https://github.com/nathan11g -[dd]: https://github.com/drdrang -[bolk]: https://github.com/bolknote -[oe]: https://github.com/Sannis -[kk]: https://github.com/kimmel -[vast]: https://github.com/vast - - -## Version 7.2 - -A regular bug-fix release without any significant new features. Enjoy! - - -## Version 7.1 - -A Summer crop: - -- [Marc Fornos][mf] made the definition for Clojure along with the matching - style Rainbow (which, of course, works for other languages too). -- CoffeeScript support continues to improve getting support for regular - expressions. -- Yoshihide Jimbo ported to highlight.js [five Tomorrow styles][tm] from the - [project by Chris Kempson][tm0]. -- Thanks to [Casey Duncun][cd] the library can now be built in the popular - [AMD format][amd]. -- And last but not least, we've got a fair number of correctness and consistency - fixes, including a pretty significant refactoring of Ruby. - -[mf]: https://github.com/mfornos -[tm]: http://jmblog.github.com/color-themes-for-highlightjs/ -[tm0]: https://github.com/ChrisKempson/Tomorrow-Theme -[cd]: https://github.com/caseman -[amd]: http://requirejs.org/docs/whyamd.html - - -## Version 7.0 - -The reason for the new major version update is a global change of keyword syntax -which resulted in the library getting smaller once again. For example, the -hosted build is 2K less than at the previous version while supporting two new -languages. - -Notable changes: - -- The library now works not only in a browser but also with [node.js][]. It is - installable with `npm install highlight.js`. [API][] docs are available on our - wiki. - -- The new unique feature (apparently) among syntax highlighters is highlighting - *HTTP* headers and an arbitrary language in the request body. The most useful - languages here are *XML* and *JSON* both of which highlight.js does support. - Here's [the detailed post][p] about the feature. - -- Two new style themes: a dark "south" *[Pojoaque][]* by Jason Tate and an - emulation of*XCode* IDE by [Angel Olloqui][ao]. - -- Three new languages: *D* by [Aleksandar Ružičić][ar], *R* by [Joe Cheng][jc] - and *GLSL* by [Sergey Tikhomirov][st]. - -- *Nginx* syntax has become a million times smaller and more universal thanks to - remaking it in a more generic manner that doesn't require listing all the - directives in the known universe. - -- Function titles are now highlighted in *PHP*. - -- *Haskell* and *VHDL* were significantly reworked to be more rich and correct - by their respective maintainers [Jeremy Hull][sr] and [Igor Kalnitsky][ik]. - -And last but not least, many bugs have been fixed around correctness and -language detection. - -Overall highlight.js currently supports 51 languages and 20 style themes. - -[node.js]: http://nodejs.org/ -[api]: http://softwaremaniacs.org/wiki/doku.php/highlight.js:api -[p]: http://softwaremaniacs.org/blog/2012/05/10/http-and-json-in-highlight-js/en/ -[pojoaque]: http://web-cms-designs.com/ftopict-10-pojoaque-style-for-highlight-js-code-highlighter.html -[ao]: https://github.com/angelolloqui -[ar]: https://github.com/raleksandar -[jc]: https://github.com/jcheng5 -[st]: https://github.com/tikhomirov -[sr]: https://github.com/sourrust -[ik]: https://github.com/ikalnitsky - - -## Version 6.2 - -A lot of things happened in highlight.js since the last version! We've got nine -new contributors, the discussion group came alive, and the main branch on GitHub -now counts more than 350 followers. Here are most significant results coming -from all this activity: - -- 5 (five!) new languages: Rust, ActionScript, CoffeeScript, MatLab and - experimental support for markdown. Thanks go to [Andrey Vlasovskikh][av], - [Alexander Myadzel][am], [Dmytrii Nagirniak][dn], [Oleg Efimov][oe], [Denis - Bardadym][db] and [John Crepezzi][jc]. - -- 2 new style themes: Monokai by [Luigi Maselli][lm] and stylistic imitation of - another well-known highlighter Google Code Prettify by [Aahan Krish][ak]. - -- A vast number of [correctness fixes and code refactorings][log], mostly made - by [Oleg Efimov][oe] and [Evgeny Stepanischev][es]. - -[av]: https://github.com/vlasovskikh -[am]: https://github.com/myadzel -[dn]: https://github.com/dnagir -[oe]: https://github.com/Sannis -[db]: https://github.com/btd -[jc]: https://github.com/seejohnrun -[lm]: http://grigio.org/ -[ak]: https://github.com/geekpanth3r -[es]: https://github.com/bolknote -[log]: https://github.com/isagalaev/highlight.js/commits/ - - -## Version 6.1 — Solarized - -[Jeremy Hull][jh] has implemented my dream feature — a port of [Solarized][] -style theme famous for being based on the intricate color theory to achieve -correct contrast and color perception. It is now available for highlight.js in -both variants — light and dark. - -This version also adds a new original style Arta. Its author pumbur maintains a -[heavily modified fork of highlight.js][pb] on GitHub. - -[jh]: https://github.com/sourrust -[solarized]: http://ethanschoonover.com/solarized -[pb]: https://github.com/pumbur/highlight.js - - -## Version 6.0 - -New major version of the highlighter has been built on a significantly -refactored syntax. Due to this it's even smaller than the previous one while -supporting more languages! - -New languages are: - -- Haskell by [Jeremy Hull][sourrust] -- Erlang in two varieties — module and REPL — made collectively by [Nikolay - Zakharov][desh], [Dmitry Kovega][arhibot] and [Sergey Ignatov][ignatov] -- Objective C by [Valerii Hiora][vhbit] -- Vala by [Antono Vasiljev][antono] -- Go by [Stephan Kountso][steplg] - -[sourrust]: https://github.com/sourrust -[desh]: http://desh.su/ -[arhibot]: https://github.com/arhibot -[ignatov]: https://github.com/ignatov -[vhbit]: https://github.com/vhbit -[antono]: https://github.com/antono -[steplg]: https://github.com/steplg - -Also this version is marginally faster and fixes a number of small long-standing -bugs. - -Developer overview of the new language syntax is available in a [blog post about -recent beta release][beta]. - -[beta]: http://softwaremaniacs.org/blog/2011/04/25/highlight-js-60-beta/en/ - -P.S. New version is not yet available on a Yandex CDN, so for now you have to -download [your own copy][d]. - -[d]: /soft/highlight/en/download/ - - -## Version 5.14 - -Fixed bugs in HTML/XML detection and relevance introduced in previous -refactoring. - -Also test.html now shows the second best result of language detection by -relevance. - - -## Version 5.13 - -Past weekend began with a couple of simple additions for existing languages but -ended up in a big code refactoring bringing along nice improvements for language -developers. - -### For users - -- Description of C++ has got new keywords from the upcoming [C++ 0x][] standard. -- Description of HTML has got new tags from [HTML 5][]. -- CSS-styles have been unified to use consistent padding and also have lost - pop-outs with names of detected languages. -- [Igor Kalnitsky][ik] has sent two new language descriptions: CMake & VHDL. - -This makes total number of languages supported by highlight.js to reach 35. - -Bug fixes: - -- Custom classes on `
    ` tags are not being overridden anymore
-- More correct highlighting of code blocks inside non-`
    ` containers:
-  highlighter now doesn't insist on replacing them with its own container and
-  just replaces the contents.
-- Small fixes in browser compatibility and heuristics.
-
-[c++ 0x]: http://ru.wikipedia.org/wiki/C%2B%2B0x
-[html 5]: http://en.wikipedia.org/wiki/HTML5
-[ik]: http://kalnitsky.org.ua/
-
-### For developers
-
-The most significant change is the ability to include language submodes right
-under `contains` instead of defining explicit named submodes in the main array:
-
-    contains: [
-      'string',
-      'number',
-      {begin: '\\n', end: hljs.IMMEDIATE_RE}
-    ]
-
-This is useful for auxiliary modes needed only in one place to define parsing.
-Note that such modes often don't have `className` and hence won't generate a
-separate `` in the resulting markup. This is similar in effect to
-`noMarkup: true`. All existing languages have been refactored accordingly.
-
-Test file test.html has at last become a real test. Now it not only puts the
-detected language name under the code snippet but also tests if it matches the
-expected one. Test summary is displayed right above all language snippets.
-
-
-## CDN
-
-Fine people at [Yandex][] agreed to host highlight.js on their big fast servers.
-[Link up][l]!
-
-[yandex]: http://yandex.com/
-[l]: http://softwaremaniacs.org/soft/highlight/en/download/
-
-
-## Version 5.10 — "Paris".
-
-Though I'm on a vacation in Paris, I decided to release a new version with a
-couple of small fixes:
-
-- Tomas Vitvar discovered that TAB replacement doesn't always work when used
-  with custom markup in code
-- SQL parsing is even more rigid now and doesn't step over SmallTalk in tests
-
-
-## Version 5.9
-
-A long-awaited version is finally released.
-
-New languages:
-
-- Andrew Fedorov made a definition for Lua
-- a long-time highlight.js contributor [Peter Leonov][pl] made a definition for
-  Nginx config
-- [Vladimir Moskva][vm] made a definition for TeX
-
-[pl]: http://kung-fu-tzu.ru/
-[vm]: http://fulc.ru/
-
-Fixes for existing languages:
-
-- [Loren Segal][ls] reworked the Ruby definition and added highlighting for
-  [YARD][] inline documentation
-- the definition of SQL has become more solid and now it shouldn't be overly
-  greedy when it comes to language detection
-
-[ls]: http://gnuu.org/
-[yard]: http://yardoc.org/
-
-The highlighter has become more usable as a library allowing to do highlighting
-from initialization code of JS frameworks and in ajax methods (see.
-readme.eng.txt).
-
-Also this version drops support for the [WordPress][wp] plugin. Everyone is
-welcome to [pick up its maintenance][p] if needed.
-
-[wp]: http://wordpress.org/
-[p]: http://bazaar.launchpad.net/~isagalaev/+junk/highlight/annotate/342/src/wp_highlight.js.php
-
-
-## Version 5.8
-
-- Jan Berkel has contributed a definition for Scala. +1 to hotness!
-- All CSS-styles are rewritten to work only inside `
    ` tags to avoid
-  conflicts with host site styles.
-
-
-## Version 5.7.
-
-Fixed escaping of quotes in VBScript strings.
-
-
-## Version 5.5
-
-This version brings a small change: now .ini-files allow digits, underscores and
-square brackets in key names.
-
-
-## Version 5.4
-
-Fixed small but upsetting bug in the packer which caused incorrect highlighting
-of explicitly specified languages. Thanks to Andrew Fedorov for precise
-diagnostics!
-
-
-## Version 5.3
-
-The version to fulfil old promises.
-
-The most significant change is that highlight.js now preserves custom user
-markup in code along with its own highlighting markup. This means that now it's
-possible to use, say, links in code. Thanks to [Vladimir Dolzhenko][vd] for the
-[initial proposal][1] and for making a proof-of-concept patch.
-
-Also in this version:
-
-- [Vasily Polovnyov][vp] has sent a GitHub-like style and has implemented
-  support for CSS @-rules and Ruby symbols.
-- Yura Zaripov has sent two styles: Brown Paper and School Book.
-- Oleg Volchkov has sent a definition for [Parser 3][p3].
-
-[1]: http://softwaremaniacs.org/forum/highlightjs/6612/
-[p3]: http://www.parser.ru/
-[vp]: http://vasily.polovnyov.ru/
-[vd]: http://dolzhenko.blogspot.com/
-
-
-## Version 5.2
-
-- at last it's possible to replace indentation TABs with something sensible
-  (e.g. 2 or 4 spaces)
-- new keywords and built-ins for 1C by Sergey Baranov
-- a couple of small fixes to Apache highlighting
-
-
-## Version 5.1
-
-This is one of those nice version consisting entirely of new and shiny
-contributions!
-
-- [Vladimir Ermakov][vooon] created highlighting for AVR Assembler
-- [Ruslan Keba][rukeba] created highlighting for Apache config file. Also his
-  original visual style for it is now available for all highlight.js languages
-  under the name "Magula".
-- [Shuen-Huei Guan][drake] (aka Drake) sent new keywords for RenderMan
-  languages. Also thanks go to [Konstantin Evdokimenko][ke] for his advice on
-  the matter.
-
-[vooon]: http://vehq.ru/about/
-[rukeba]: http://rukeba.com/
-[drake]: http://drakeguan.org/
-[ke]: http://k-evdokimenko.moikrug.ru/
-
-
-## Version 5.0
-
-The main change in the new major version of highlight.js is a mechanism for
-packing several languages along with the library itself into a single compressed
-file. Now sites using several languages will load considerably faster because
-the library won't dynamically include additional files while loading.
-
-Also this version fixes a long-standing bug with Javascript highlighting that
-couldn't distinguish between regular expressions and division operations.
-
-And as usually there were a couple of minor correctness fixes.
-
-Great thanks to all contributors! Keep using highlight.js.
-
-
-## Version 4.3
-
-This version comes with two contributions from [Jason Diamond][jd]:
-
-- language definition for C# (yes! it was a long-missed thing!)
-- Visual Studio-like highlighting style
-
-Plus there are a couple of minor bug fixes for parsing HTML and XML attributes.
-
-[jd]: http://jason.diamond.name/weblog/
-
-
-## Version 4.2
-
-The biggest news is highlighting for Lisp, courtesy of Vasily Polovnyov. It's
-somewhat experimental meaning that for highlighting "keywords" it doesn't use
-any pre-defined set of a Lisp dialect. Instead it tries to highlight first word
-in parentheses wherever it makes sense. I'd like to ask people programming in
-Lisp to confirm if it's a good idea and send feedback to [the forum][f].
-
-Other changes:
-
-- Smalltalk was excluded from DEFAULT_LANGUAGES to save traffic
-- [Vladimir Epifanov][voldmar] has implemented javascript style switcher for
-  test.html
-- comments now allowed inside Ruby function definition
-- [MEL][] language from [Shuen-Huei Guan][drake]
-- whitespace now allowed between `
    ` and ``
-- better auto-detection of C++ and PHP
-- HTML allows embedded VBScript (`<% .. %>`)
-
-[f]: http://softwaremaniacs.org/forum/highlightjs/
-[voldmar]: http://voldmar.ya.ru/
-[mel]: http://en.wikipedia.org/wiki/Maya_Embedded_Language
-[drake]: http://drakeguan.org/
-
-
-## Version 4.1
-
-Languages:
-
-- Bash from Vah
-- DOS bat-files from Alexander Makarov (Sam)
-- Diff files from Vasily Polovnyov
-- Ini files from myself though initial idea was from Sam
-
-Styles:
-
-- Zenburn from Vladimir Epifanov, this is an imitation of a
-  [well-known theme for Vim][zenburn].
-- Ascetic from myself, as a realization of ideals of non-flashy highlighting:
-  just one color in only three gradations :-)
-
-In other news. [One small bug][bug] was fixed, built-in keywords were added for
-Python and C++ which improved auto-detection for the latter (it was shame that
-[my wife's blog][alenacpp] had issues with it from time to time). And lastly
-thanks go to Sam for getting rid of my stylistic comments in code that were
-getting in the way of [JSMin][].
-
-[zenburn]: http://en.wikipedia.org/wiki/Zenburn
-[alenacpp]: http://alenacpp.blogspot.com/
-[bug]: http://softwaremaniacs.org/forum/viewtopic.php?id=1823
-[jsmin]: http://code.google.com/p/jsmin-php/
-
-
-## Version 4.0
-
-New major version is a result of vast refactoring and of many contributions.
-
-Visible new features:
-
-- Highlighting of embedded languages. Currently is implemented highlighting of
-  Javascript and CSS inside HTML.
-- Bundled 5 ready-made style themes!
-
-Invisible new features:
-
-- Highlight.js no longer pollutes global namespace. Only one object and one
-  function for backward compatibility.
-- Performance is further increased by about 15%.
-
-Changing of a major version number caused by a new format of language definition
-files. If you use some third-party language files they should be updated.
-
-
-## Version 3.5
-
-A very nice version in my opinion fixing a number of small bugs and slightly
-increased speed in a couple of corner cases. Thanks to everybody who reports
-bugs in he [forum][f] and by email!
-
-There is also a new language — XML. A custom XML formerly was detected as HTML
-and didn't highlight custom tags. In this version I tried to make custom XML to
-be detected and highlighted by its own rules. Which by the way include such
-things as CDATA sections and processing instructions (``).
-
-[f]: http://softwaremaniacs.org/forum/viewforum.php?id=6
-
-
-## Version 3.3
-
-[Vladimir Gubarkov][xonix] has provided an interesting and useful addition.
-File export.html contains a little program that shows and allows to copy and
-paste an HTML code generated by the highlighter for any code snippet. This can
-be useful in situations when one can't use the script itself on a site.
-
-
-[xonix]: http://xonixx.blogspot.com/
-
-
-## Version 3.2 consists completely of contributions:
-
-- Vladimir Gubarkov has described SmallTalk
-- Yuri Ivanov has described 1C
-- Peter Leonov has packaged the highlighter as a Firefox extension
-- Vladimir Ermakov has compiled a mod for phpBB
-
-Many thanks to you all!
-
-
-## Version 3.1
-
-Three new languages are available: Django templates, SQL and Axapta. The latter
-two are sent by [Dmitri Roudakov][1]. However I've almost entirely rewrote an
-SQL definition but I'd never started it be it from the ground up :-)
-
-The engine itself has got a long awaited feature of grouping keywords
-("keyword", "built-in function", "literal"). No more hacks!
-
-[1]: http://roudakov.ru/
-
-
-## Version 3.0
-
-It is major mainly because now highlight.js has grown large and has become
-modular. Now when you pass it a list of languages to highlight it will
-dynamically load into a browser only those languages.
-
-Also:
-
-- Konstantin Evdokimenko of [RibKit][] project has created a highlighting for
-  RenderMan Shading Language and RenderMan Interface Bytestream. Yay for more
-  languages!
-- Heuristics for C++ and HTML got better.
-- I've implemented (at last) a correct handling of backslash escapes in C-like
-  languages.
-
-There is also a small backwards incompatible change in the new version. The
-function initHighlighting that was used to initialize highlighting instead of
-initHighlightingOnLoad a long time ago no longer works. If you by chance still
-use it — replace it with the new one.
-
-[RibKit]: http://ribkit.sourceforge.net/
-
-
-## Version 2.9
-
-Highlight.js is a parser, not just a couple of regular expressions. That said
-I'm glad to announce that in the new version 2.9 has support for:
-
-- in-string substitutions for Ruby -- `#{...}`
-- strings from from numeric symbol codes (like #XX) for Delphi
-
-
-## Version 2.8
-
-A maintenance release with more tuned heuristics. Fully backwards compatible.
-
-
-## Version 2.7
-
-- Nikita Ledyaev presents highlighting for VBScript, yay!
-- A couple of bugs with escaping in strings were fixed thanks to Mickle
-- Ongoing tuning of heuristics
-
-Fixed bugs were rather unpleasant so I encourage everyone to upgrade!
-
-
-## Version 2.4
-
-- Peter Leonov provides another improved highlighting for Perl
-- Javascript gets a new kind of keywords — "literals". These are the words
-  "true", "false" and "null"
-
-Also highlight.js homepage now lists sites that use the library. Feel free to
-add your site by [dropping me a message][mail] until I find the time to build a
-submit form.
-
-[mail]: mailto:Maniac@SoftwareManiacs.Org
-
-
-## Version 2.3
-
-This version fixes IE breakage in previous version. My apologies to all who have
-already downloaded that one!
-
-
-## Version 2.2
-
-- added highlighting for Javascript
-- at last fixed parsing of Delphi's escaped apostrophes in strings
-- in Ruby fixed highlighting of keywords 'def' and 'class', same for 'sub' in
-  Perl
-
-
-## Version 2.0
-
-- Ruby support by [Anton Kovalyov][ak]
-- speed increased by orders of magnitude due to new way of parsing
-- this same way allows now correct highlighting of keywords in some tricky
-  places (like keyword "End" at the end of Delphi classes)
-
-[ak]: http://anton.kovalyov.net/
-
-
-## Version 1.0
-
-Version 1.0 of javascript syntax highlighter is released!
-
-It's the first version available with English description. Feel free to post
-your comments and question to [highlight.js forum][forum]. And don't be afraid
-if you find there some fancy Cyrillic letters -- it's for Russian users too :-)
-
-[forum]: http://softwaremaniacs.org/forum/viewforum.php?id=6
diff --git a/www/js/highlight.js/LICENSE b/www/js/highlight.js/LICENSE
deleted file mode 100644
index 422deb73..00000000
--- a/www/js/highlight.js/LICENSE
+++ /dev/null
@@ -1,24 +0,0 @@
-Copyright (c) 2006, Ivan Sagalaev
-All rights reserved.
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-      notice, this list of conditions and the following disclaimer in the
-      documentation and/or other materials provided with the distribution.
-    * Neither the name of highlight.js nor the names of its contributors 
-      may be used to endorse or promote products derived from this software 
-      without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
-EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
-DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/www/js/highlight.js/README.md b/www/js/highlight.js/README.md
deleted file mode 100644
index 9f76e6bd..00000000
--- a/www/js/highlight.js/README.md
+++ /dev/null
@@ -1,150 +0,0 @@
-# Highlight.js
-
-[![Build Status](https://travis-ci.org/isagalaev/highlight.js.svg?branch=master)](https://travis-ci.org/isagalaev/highlight.js)
-
-Highlight.js is a syntax highlighter written in JavaScript. It works in
-the browser as well as on the server. It works with pretty much any
-markup, doesn’t depend on any framework and has automatic language
-detection.
-
-## Getting Started
-
-The bare minimum for using highlight.js on a web page is linking to the
-library along with one of the styles and calling
-[`initHighlightingOnLoad`][1]:
-
-```html
-
-
-
-```
-
-This will find and highlight code inside of `
    ` tags; it tries
-to detect the language automatically. If automatic detection doesn’t
-work for you, you can specify the language in the `class` attribute:
-
-```html
-
    ...
    
-```
-
-The list of supported language classes is available in the [class
-reference][2].  Classes can also be prefixed with either `language-` or
-`lang-`.
-
-To disable highlighting altogether use the `nohighlight` class:
-
-```html
-
    ...
    
-```
-
-## Custom Initialization
-
-When you need a bit more control over the initialization of
-highlight.js, you can use the [`highlightBlock`][3] and [`configure`][4]
-functions. This allows you to control *what* to highlight and *when*.
-
-Here’s an equivalent way to calling [`initHighlightingOnLoad`][1] using
-jQuery:
-
-```javascript
-$(document).ready(function() {
-  $('pre code').each(function(i, block) {
-    hljs.highlightBlock(block);
-  });
-});
-```
-
-You can use any tags instead of `
    ` to mark up your code. If
-you don't use a container that preserve line breaks you will need to
-configure highlight.js to use the `
    ` tag:
-
-```javascript
-hljs.configure({useBR: true});
-
-$('div.code').each(function(i, block) {
-  hljs.highlightBlock(block);
-});
-```
-
-For other options refer to the documentation for [`configure`][4].
-
-
-## Web Workers
-
-You can run highlighting inside a web worker to avoid freezing the browser
-window while dealing with very big chunks of code.
-
-In your main script:
-
-```javascript
-addEventListener('load', function() {
-  var code = document.querySelector('#code');
-  var worker = new Worker('worker.js');
-  worker.onmessage = function(event) { code.innerHTML = event.data; }
-  worker.postMessage(code.textContent);
-})
-```
-
-In worker.js:
-
-```javascript
-onmessage = function(event) {
-  importScripts('/highlight.pack.js');
-  var result = self.hljs.highlightAuto(event.data);
-  postMessage(result.value);
-}
-```
-
-
-## Getting the Library
-
-You can get highlight.js as a hosted, or custom-build, browser script or
-as a server module. Right out of the box the browser script supports
-both AMD and CommonJS, so if you wish you can use RequireJS or
-Browserify without having to build from source. The server module also
-works perfectly fine with Browserify, but there is the option to use a
-build specific to browsers rather than something meant for a server.
-Head over to the [download page][5] for all the options.
-
-**Don't link to GitHub directly.** The library is not supposed to work straight
-from the source, it requires building. If none of the pre-packaged options
-work for you refer to the [building documentation][6].
-
-**The CDN-hosted package doesn't have all the languages.** Otherwise it'd be
-too big. If you don't see the language you need in the ["Common" section][5],
-it can be added manually:
-
-```html
-
-```
-
-**On Almond.** You need to use the optimizer to give the module a name. For
-example:
-
-```
-r.js -o name=hljs paths.hljs=/path/to/highlight out=highlight.js
-```
-
-
-## License
-
-Highlight.js is released under the BSD License. See [LICENSE][7] file
-for details.
-
-## Links
-
-The official site for the library is at .
-
-Further in-depth documentation for the API and other topics is at
-.
-
-Authors and contributors are listed in the [AUTHORS.en.txt][8] file.
-
-[1]: http://highlightjs.readthedocs.io/en/latest/api.html#inithighlightingonload
-[2]: http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html
-[3]: http://highlightjs.readthedocs.io/en/latest/api.html#highlightblock-block
-[4]: http://highlightjs.readthedocs.io/en/latest/api.html#configure-options
-[5]: https://highlightjs.org/download/
-[6]: http://highlightjs.readthedocs.io/en/latest/building-testing.html
-[7]: https://github.com/isagalaev/highlight.js/blob/master/LICENSE
-[8]: https://github.com/isagalaev/highlight.js/blob/master/AUTHORS.en.txt
diff --git a/www/js/highlight.js/highlight.pack.js b/www/js/highlight.js/highlight.pack.js
deleted file mode 100644
index cc6d18ac..00000000
--- a/www/js/highlight.js/highlight.pack.js
+++ /dev/null
@@ -1,2 +0,0 @@
-/*! highlight.js v9.12.0 | BSD3 License | git.io/hljslicense */
-!function(e){var n="object"==typeof window&&window||"object"==typeof self&&self;"undefined"!=typeof exports?e(exports):n&&(n.hljs=e({}),"function"==typeof define&&define.amd&&define([],function(){return n.hljs}))}(function(e){function n(e){return e.replace(/&/g,"&").replace(//g,">")}function t(e){return e.nodeName.toLowerCase()}function r(e,n){var t=e&&e.exec(n);return t&&0===t.index}function a(e){return k.test(e)}function i(e){var n,t,r,i,o=e.className+" ";if(o+=e.parentNode?e.parentNode.className:"",t=B.exec(o))return w(t[1])?t[1]:"no-highlight";for(o=o.split(/\s+/),n=0,r=o.length;r>n;n++)if(i=o[n],a(i)||w(i))return i}function o(e){var n,t={},r=Array.prototype.slice.call(arguments,1);for(n in e)t[n]=e[n];return r.forEach(function(e){for(n in e)t[n]=e[n]}),t}function u(e){var n=[];return function r(e,a){for(var i=e.firstChild;i;i=i.nextSibling)3===i.nodeType?a+=i.nodeValue.length:1===i.nodeType&&(n.push({event:"start",offset:a,node:i}),a=r(i,a),t(i).match(/br|hr|img|input/)||n.push({event:"stop",offset:a,node:i}));return a}(e,0),n}function c(e,r,a){function i(){return e.length&&r.length?e[0].offset!==r[0].offset?e[0].offset"}function u(e){s+=""}function c(e){("start"===e.event?o:u)(e.node)}for(var l=0,s="",f=[];e.length||r.length;){var g=i();if(s+=n(a.substring(l,g[0].offset)),l=g[0].offset,g===e){f.reverse().forEach(u);do c(g.splice(0,1)[0]),g=i();while(g===e&&g.length&&g[0].offset===l);f.reverse().forEach(o)}else"start"===g[0].event?f.push(g[0].node):f.pop(),c(g.splice(0,1)[0])}return s+n(a.substr(l))}function l(e){return e.v&&!e.cached_variants&&(e.cached_variants=e.v.map(function(n){return o(e,{v:null},n)})),e.cached_variants||e.eW&&[o(e)]||[e]}function s(e){function n(e){return e&&e.source||e}function t(t,r){return new RegExp(n(t),"m"+(e.cI?"i":"")+(r?"g":""))}function r(a,i){if(!a.compiled){if(a.compiled=!0,a.k=a.k||a.bK,a.k){var o={},u=function(n,t){e.cI&&(t=t.toLowerCase()),t.split(" ").forEach(function(e){var t=e.split("|");o[t[0]]=[n,t[1]?Number(t[1]):1]})};"string"==typeof a.k?u("keyword",a.k):x(a.k).forEach(function(e){u(e,a.k[e])}),a.k=o}a.lR=t(a.l||/\w+/,!0),i&&(a.bK&&(a.b="\\b("+a.bK.split(" ").join("|")+")\\b"),a.b||(a.b=/\B|\b/),a.bR=t(a.b),a.e||a.eW||(a.e=/\B|\b/),a.e&&(a.eR=t(a.e)),a.tE=n(a.e)||"",a.eW&&i.tE&&(a.tE+=(a.e?"|":"")+i.tE)),a.i&&(a.iR=t(a.i)),null==a.r&&(a.r=1),a.c||(a.c=[]),a.c=Array.prototype.concat.apply([],a.c.map(function(e){return l("self"===e?a:e)})),a.c.forEach(function(e){r(e,a)}),a.starts&&r(a.starts,i);var c=a.c.map(function(e){return e.bK?"\\.?("+e.b+")\\.?":e.b}).concat([a.tE,a.i]).map(n).filter(Boolean);a.t=c.length?t(c.join("|"),!0):{exec:function(){return null}}}}r(e)}function f(e,t,a,i){function o(e,n){var t,a;for(t=0,a=n.c.length;a>t;t++)if(r(n.c[t].bR,e))return n.c[t]}function u(e,n){if(r(e.eR,n)){for(;e.endsParent&&e.parent;)e=e.parent;return e}return e.eW?u(e.parent,n):void 0}function c(e,n){return!a&&r(n.iR,e)}function l(e,n){var t=N.cI?n[0].toLowerCase():n[0];return e.k.hasOwnProperty(t)&&e.k[t]}function p(e,n,t,r){var a=r?"":I.classPrefix,i='',i+n+o}function h(){var e,t,r,a;if(!E.k)return n(k);for(a="",t=0,E.lR.lastIndex=0,r=E.lR.exec(k);r;)a+=n(k.substring(t,r.index)),e=l(E,r),e?(B+=e[1],a+=p(e[0],n(r[0]))):a+=n(r[0]),t=E.lR.lastIndex,r=E.lR.exec(k);return a+n(k.substr(t))}function d(){var e="string"==typeof E.sL;if(e&&!y[E.sL])return n(k);var t=e?f(E.sL,k,!0,x[E.sL]):g(k,E.sL.length?E.sL:void 0);return E.r>0&&(B+=t.r),e&&(x[E.sL]=t.top),p(t.language,t.value,!1,!0)}function b(){L+=null!=E.sL?d():h(),k=""}function v(e){L+=e.cN?p(e.cN,"",!0):"",E=Object.create(e,{parent:{value:E}})}function m(e,n){if(k+=e,null==n)return b(),0;var t=o(n,E);if(t)return t.skip?k+=n:(t.eB&&(k+=n),b(),t.rB||t.eB||(k=n)),v(t,n),t.rB?0:n.length;var r=u(E,n);if(r){var a=E;a.skip?k+=n:(a.rE||a.eE||(k+=n),b(),a.eE&&(k=n));do E.cN&&(L+=C),E.skip||(B+=E.r),E=E.parent;while(E!==r.parent);return r.starts&&v(r.starts,""),a.rE?0:n.length}if(c(n,E))throw new Error('Illegal lexeme "'+n+'" for mode "'+(E.cN||"")+'"');return k+=n,n.length||1}var N=w(e);if(!N)throw new Error('Unknown language: "'+e+'"');s(N);var R,E=i||N,x={},L="";for(R=E;R!==N;R=R.parent)R.cN&&(L=p(R.cN,"",!0)+L);var k="",B=0;try{for(var M,j,O=0;;){if(E.t.lastIndex=O,M=E.t.exec(t),!M)break;j=m(t.substring(O,M.index),M[0]),O=M.index+j}for(m(t.substr(O)),R=E;R.parent;R=R.parent)R.cN&&(L+=C);return{r:B,value:L,language:e,top:E}}catch(T){if(T.message&&-1!==T.message.indexOf("Illegal"))return{r:0,value:n(t)};throw T}}function g(e,t){t=t||I.languages||x(y);var r={r:0,value:n(e)},a=r;return t.filter(w).forEach(function(n){var t=f(n,e,!1);t.language=n,t.r>a.r&&(a=t),t.r>r.r&&(a=r,r=t)}),a.language&&(r.second_best=a),r}function p(e){return I.tabReplace||I.useBR?e.replace(M,function(e,n){return I.useBR&&"\n"===e?"
    ":I.tabReplace?n.replace(/\t/g,I.tabReplace):""}):e}function h(e,n,t){var r=n?L[n]:t,a=[e.trim()];return e.match(/\bhljs\b/)||a.push("hljs"),-1===e.indexOf(r)&&a.push(r),a.join(" ").trim()}function d(e){var n,t,r,o,l,s=i(e);a(s)||(I.useBR?(n=document.createElementNS("http://www.w3.org/1999/xhtml","div"),n.innerHTML=e.innerHTML.replace(/\n/g,"").replace(//g,"\n")):n=e,l=n.textContent,r=s?f(s,l,!0):g(l),t=u(n),t.length&&(o=document.createElementNS("http://www.w3.org/1999/xhtml","div"),o.innerHTML=r.value,r.value=c(t,u(o),l)),r.value=p(r.value),e.innerHTML=r.value,e.className=h(e.className,s,r.language),e.result={language:r.language,re:r.r},r.second_best&&(e.second_best={language:r.second_best.language,re:r.second_best.r}))}function b(e){I=o(I,e)}function v(){if(!v.called){v.called=!0;var e=document.querySelectorAll("pre code");E.forEach.call(e,d)}}function m(){addEventListener("DOMContentLoaded",v,!1),addEventListener("load",v,!1)}function N(n,t){var r=y[n]=t(e);r.aliases&&r.aliases.forEach(function(e){L[e]=n})}function R(){return x(y)}function w(e){return e=(e||"").toLowerCase(),y[e]||y[L[e]]}var E=[],x=Object.keys,y={},L={},k=/^(no-?highlight|plain|text)$/i,B=/\blang(?:uage)?-([\w-]+)\b/i,M=/((^(<[^>]+>|\t|)+|(?:\n)))/gm,C="    ",I={classPrefix:"hljs-",tabReplace:null,useBR:!1,languages:void 0};return e.highlight=f,e.highlightAuto=g,e.fixMarkup=p,e.highlightBlock=d,e.configure=b,e.initHighlighting=v,e.initHighlightingOnLoad=m,e.registerLanguage=N,e.listLanguages=R,e.getLanguage=w,e.inherit=o,e.IR="[a-zA-Z]\\w*",e.UIR="[a-zA-Z_]\\w*",e.NR="\\b\\d+(\\.\\d+)?",e.CNR="(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",e.BNR="\\b(0b[01]+)",e.RSR="!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~",e.BE={b:"\\\\[\\s\\S]",r:0},e.ASM={cN:"string",b:"'",e:"'",i:"\\n",c:[e.BE]},e.QSM={cN:"string",b:'"',e:'"',i:"\\n",c:[e.BE]},e.PWM={b:/\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/},e.C=function(n,t,r){var a=e.inherit({cN:"comment",b:n,e:t,c:[]},r||{});return a.c.push(e.PWM),a.c.push({cN:"doctag",b:"(?:TODO|FIXME|NOTE|BUG|XXX):",r:0}),a},e.CLCM=e.C("//","$"),e.CBCM=e.C("/\\*","\\*/"),e.HCM=e.C("#","$"),e.NM={cN:"number",b:e.NR,r:0},e.CNM={cN:"number",b:e.CNR,r:0},e.BNM={cN:"number",b:e.BNR,r:0},e.CSSNM={cN:"number",b:e.NR+"(%|em|ex|ch|rem|vw|vh|vmin|vmax|cm|mm|in|pt|pc|px|deg|grad|rad|turn|s|ms|Hz|kHz|dpi|dpcm|dppx)?",r:0},e.RM={cN:"regexp",b:/\//,e:/\/[gimuy]*/,i:/\n/,c:[e.BE,{b:/\[/,e:/\]/,r:0,c:[e.BE]}]},e.TM={cN:"title",b:e.IR,r:0},e.UTM={cN:"title",b:e.UIR,r:0},e.METHOD_GUARD={b:"\\.\\s*"+e.UIR,r:0},e});hljs.registerLanguage("java",function(e){var a="[À-ʸa-zA-Z_$][À-ʸa-zA-Z_$0-9]*",t=a+"(<"+a+"(\\s*,\\s*"+a+")*>)?",r="false synchronized int abstract float private char boolean static null if const for true while long strictfp finally protected import native final void enum else break transient catch instanceof byte super volatile case assert short package default double public try this switch continue throws protected public private module requires exports do",s="\\b(0[bB]([01]+[01_]+[01]+|[01]+)|0[xX]([a-fA-F0-9]+[a-fA-F0-9_]+[a-fA-F0-9]+|[a-fA-F0-9]+)|(([\\d]+[\\d_]+[\\d]+|[\\d]+)(\\.([\\d]+[\\d_]+[\\d]+|[\\d]+))?|\\.([\\d]+[\\d_]+[\\d]+|[\\d]+))([eE][-+]?\\d+)?)[lLfF]?",c={cN:"number",b:s,r:0};return{aliases:["jsp"],k:r,i:/<\/|#/,c:[e.C("/\\*\\*","\\*/",{r:0,c:[{b:/\w+@/,r:0},{cN:"doctag",b:"@[A-Za-z]+"}]}),e.CLCM,e.CBCM,e.ASM,e.QSM,{cN:"class",bK:"class interface",e:/[{;=]/,eE:!0,k:"class interface",i:/[:"\[\]]/,c:[{bK:"extends implements"},e.UTM]},{bK:"new throw return else",r:0},{cN:"function",b:"("+t+"\\s+)+"+e.UIR+"\\s*\\(",rB:!0,e:/[{;=]/,eE:!0,k:r,c:[{b:e.UIR+"\\s*\\(",rB:!0,r:0,c:[e.UTM]},{cN:"params",b:/\(/,e:/\)/,k:r,r:0,c:[e.ASM,e.QSM,e.CNM,e.CBCM]},e.CLCM,e.CBCM]},c,{cN:"meta",b:"@[A-Za-z]+"}]}});hljs.registerLanguage("python",function(e){var r={keyword:"and elif is global as in if from raise for except finally print import pass return exec else break not with class assert yield try while continue del or def lambda async await nonlocal|10 None True False",built_in:"Ellipsis NotImplemented"},b={cN:"meta",b:/^(>>>|\.\.\.) /},c={cN:"subst",b:/\{/,e:/\}/,k:r,i:/#/},a={cN:"string",c:[e.BE],v:[{b:/(u|b)?r?'''/,e:/'''/,c:[b],r:10},{b:/(u|b)?r?"""/,e:/"""/,c:[b],r:10},{b:/(fr|rf|f)'''/,e:/'''/,c:[b,c]},{b:/(fr|rf|f)"""/,e:/"""/,c:[b,c]},{b:/(u|r|ur)'/,e:/'/,r:10},{b:/(u|r|ur)"/,e:/"/,r:10},{b:/(b|br)'/,e:/'/},{b:/(b|br)"/,e:/"/},{b:/(fr|rf|f)'/,e:/'/,c:[c]},{b:/(fr|rf|f)"/,e:/"/,c:[c]},e.ASM,e.QSM]},s={cN:"number",r:0,v:[{b:e.BNR+"[lLjJ]?"},{b:"\\b(0o[0-7]+)[lLjJ]?"},{b:e.CNR+"[lLjJ]?"}]},i={cN:"params",b:/\(/,e:/\)/,c:["self",b,s,a]};return c.c=[a,s,b],{aliases:["py","gyp"],k:r,i:/(<\/|->|\?)|=>/,c:[b,s,a,e.HCM,{v:[{cN:"function",bK:"def"},{cN:"class",bK:"class"}],e:/:/,i:/[${=;\n,]/,c:[e.UTM,i,{b:/->/,eW:!0,k:"None"}]},{cN:"meta",b:/^[\t ]*@/,e:/$/},{b:/\b(print|exec)\(/}]}});hljs.registerLanguage("css",function(e){var c="[a-zA-Z-][a-zA-Z0-9_-]*",t={b:/[A-Z\_\.\-]+\s*:/,rB:!0,e:";",eW:!0,c:[{cN:"attribute",b:/\S/,e:":",eE:!0,starts:{eW:!0,eE:!0,c:[{b:/[\w-]+\(/,rB:!0,c:[{cN:"built_in",b:/[\w-]+/},{b:/\(/,e:/\)/,c:[e.ASM,e.QSM]}]},e.CSSNM,e.QSM,e.ASM,e.CBCM,{cN:"number",b:"#[0-9A-Fa-f]+"},{cN:"meta",b:"!important"}]}}]};return{cI:!0,i:/[=\/|'\$]/,c:[e.CBCM,{cN:"selector-id",b:/#[A-Za-z0-9_-]+/},{cN:"selector-class",b:/\.[A-Za-z0-9_-]+/},{cN:"selector-attr",b:/\[/,e:/\]/,i:"$"},{cN:"selector-pseudo",b:/:(:)?[a-zA-Z0-9\_\-\+\(\)"'.]+/},{b:"@(font-face|page)",l:"[a-z-]+",k:"font-face page"},{b:"@",e:"[{;]",i:/:/,c:[{cN:"keyword",b:/\w+/},{b:/\s/,eW:!0,eE:!0,r:0,c:[e.ASM,e.QSM,e.CSSNM]}]},{cN:"selector-tag",b:c,r:0},{b:"{",e:"}",i:/\S/,c:[e.CBCM,t]}]}});hljs.registerLanguage("bash",function(e){var t={cN:"variable",v:[{b:/\$[\w\d#@][\w\d_]*/},{b:/\$\{(.*?)}/}]},s={cN:"string",b:/"/,e:/"/,c:[e.BE,t,{cN:"variable",b:/\$\(/,e:/\)/,c:[e.BE]}]},a={cN:"string",b:/'/,e:/'/};return{aliases:["sh","zsh"],l:/\b-?[a-z\._]+\b/,k:{keyword:"if then else elif fi for while in do done case esac function",literal:"true false",built_in:"break cd continue eval exec exit export getopts hash pwd readonly return shift test times trap umask unset alias bind builtin caller command declare echo enable help let local logout mapfile printf read readarray source type typeset ulimit unalias set shopt autoload bg bindkey bye cap chdir clone comparguments compcall compctl compdescribe compfiles compgroups compquote comptags comptry compvalues dirs disable disown echotc echoti emulate fc fg float functions getcap getln history integer jobs kill limit log noglob popd print pushd pushln rehash sched setcap setopt stat suspend ttyctl unfunction unhash unlimit unsetopt vared wait whence where which zcompile zformat zftp zle zmodload zparseopts zprof zpty zregexparse zsocket zstyle ztcp",_:"-ne -eq -lt -gt -f -d -e -s -l -a"},c:[{cN:"meta",b:/^#![^\n]+sh\s*$/,r:10},{cN:"function",b:/\w[\w\d_]*\s*\(\s*\)\s*\{/,rB:!0,c:[e.inherit(e.TM,{b:/\w[\w\d_]*/})],r:0},e.HCM,s,a,t]}});hljs.registerLanguage("shell",function(s){return{aliases:["console"],c:[{cN:"meta",b:"^\\s{0,3}[\\w\\d\\[\\]()@-]*[>%$#]",starts:{e:"$",sL:"bash"}}]}});hljs.registerLanguage("xml",function(s){var e="[A-Za-z0-9\\._:-]+",t={eW:!0,i:/`]+/}]}]}]};return{aliases:["html","xhtml","rss","atom","xjb","xsd","xsl","plist"],cI:!0,c:[{cN:"meta",b:"",r:10,c:[{b:"\\[",e:"\\]"}]},s.C("",{r:10}),{b:"<\\!\\[CDATA\\[",e:"\\]\\]>",r:10},{b:/<\?(php)?/,e:/\?>/,sL:"php",c:[{b:"/\\*",e:"\\*/",skip:!0}]},{cN:"tag",b:"|$)",e:">",k:{name:"style"},c:[t],starts:{e:"",rE:!0,sL:["css","xml"]}},{cN:"tag",b:"|$)",e:">",k:{name:"script"},c:[t],starts:{e:"",rE:!0,sL:["actionscript","javascript","handlebars","xml"]}},{cN:"meta",v:[{b:/<\?xml/,e:/\?>/,r:10},{b:/<\?\w+/,e:/\?>/}]},{cN:"tag",b:"",c:[{cN:"name",b:/[^\/><\s]+/,r:0},t]}]}});
\ No newline at end of file
diff --git a/www/js/highlight.js/styles/paraiso-dark.css b/www/js/highlight.js/styles/paraiso-dark.css
deleted file mode 100644
index e7292401..00000000
--- a/www/js/highlight.js/styles/paraiso-dark.css
+++ /dev/null
@@ -1,72 +0,0 @@
-/*
-    Paraíso (dark)
-    Created by Jan T. Sott (http://github.com/idleberg)
-    Inspired by the art of Rubens LP (http://www.rubenslp.com.br)
-*/
-
-/* Paraíso Comment */
-.hljs-comment,
-.hljs-quote {
-  color: #8d8687;
-}
-
-/* Paraíso Red */
-.hljs-variable,
-.hljs-template-variable,
-.hljs-tag,
-.hljs-name,
-.hljs-selector-id,
-.hljs-selector-class,
-.hljs-regexp,
-.hljs-link,
-.hljs-meta {
-  color: #ef6155;
-}
-
-/* Paraíso Orange */
-.hljs-number,
-.hljs-built_in,
-.hljs-builtin-name,
-.hljs-literal,
-.hljs-type,
-.hljs-params,
-.hljs-deletion {
-  color: #f99b15;
-}
-
-/* Paraíso Yellow */
-.hljs-title,
-.hljs-section,
-.hljs-attribute {
-  color: #fec418;
-}
-
-/* Paraíso Green */
-.hljs-string,
-.hljs-symbol,
-.hljs-bullet,
-.hljs-addition {
-  color: #48b685;
-}
-
-/* Paraíso Purple */
-.hljs-keyword,
-.hljs-selector-tag {
-  color: #815ba4;
-}
-
-.hljs {
-  display: block;
-  overflow-x: auto;
-  background: #2f1e2e;
-  color: #a39e9b;
-  padding: 0.5em;
-}
-
-.hljs-emphasis {
-  font-style: italic;
-}
-
-.hljs-strong {
-  font-weight: bold;
-}
diff --git a/www/manual/1.0.0/1-code-style.php b/www/manual/1.0.0/1-code-style.php
index 9151e550..44a5ca8f 100644
--- a/www/manual/1.0.0/1-code-style.php
+++ b/www/manual/1.0.0/1-code-style.php
@@ -1,12 +1,12 @@
  '1. XHTML, CSS, and SVG Code Style - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?>
-	
    
+	
    
 		
    
 
 
    
 
    XHTML, CSS, and SVG Code Style
    
-
    The se clean tool in the Standard Ebooks toolset formats XHTML, CSS, and SVG code according to our style guidelines. The vast majority of the time its output is correct and no further modifications to code style are necessary.
    
+
    The se clean tool in the Standard Ebooks toolset formats XHTML, CSS, and SVG code according to our style guidelines. The vast majority of the time its output is correct and no further modifications to code style are necessary.
    
 
    
 
    XHTML formatting
    
 
      
@@ -18,7 +18,7 @@ require_once('Core.php');
 
 
    1. Tabs are used for indentation.
      2. 
 
    2. Tag names are lowercase.
      3. 
-
    3. Tags whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content.
+
    4. Elements whose content is phrasing content are on a single line, with no whitespace between the opening and closing tags and the content.
 					
      <p>
 	It was a dark and stormy night...
 </p>
      
@@ -72,7 +72,7 @@ Demoiselle Jeanne D’Ys</p
      <section EPUB:TYPE="CHAPTER" XML:LANG="EN-US">...</section>
      
 
      <section epub:type="chapter" xml:lang="en-US">...</section>
      
 
      5. 
-
    5. The string utf-8 is lowercase.
      6. 
+
    6. The string utf-8 is lowercase.
      7. 
 
    
 
    
 
    Classes
    
@@ -181,7 +181,7 @@ Demoiselle Jeanne D’Ys</pCommits and Commit Messages
 
      
 
    1. Commits are broken into single units of work. A single unit of work may be, for example, "fixing typos across 10 files", or "adding cover art", or "working on metadata".
      2. 
-
    2. Commits that introduce material changes to the ebook text (for example modernizing spelling or fixing a probable printer’s typo; but not fixing a transcriber’s typo) are prefaced with the string [Editorial], followed by a space, then the commit message. This makes it easy to search the repo history for commits that make editorial changes to the work.
      3. 
+
    3. Commits that introduce material changes to the ebook text (for example modernizing spelling or fixing a probable printer’s typo; but not fixing a transcriber’s typo) are prefaced with the string [Editorial], followed by a space, then the commit message. This makes it easy to search the repo history for commits that make editorial changes to the work.
      4. 
 
    
 
    
 
    
diff --git a/www/manual/1.0.0/10-art-and-images.php b/www/manual/1.0.0/10-art-and-images.php
index 65ea6add..6aa6c067 100644
--- a/www/manual/1.0.0/10-art-and-images.php
+++ b/www/manual/1.0.0/10-art-and-images.php
@@ -1,13 +1,13 @@
  '10. Art and Images - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?>
-	
    
+	
    
 		
    
 
 
    
 
    Art and Images
    
-
    When you create a new Standard Ebooks draft using the se create-draft tool, you’ll already have templates for the cover and titlepage images present in ./images/.
    
-
    Text in these SVG files is represented as text, not paths, so you can edit them using a text editor and not an SVG editor. Then, the se build-images tool converts these text-based source images into path-based compiled images, for distribution in the final epub file. We do this so to avoid having to distribute the font files along with the epub.
    
+
    When you create a new Standard Ebooks draft using the se create-draft tool, you’ll already have templates for the cover and titlepage images present in ./images/.
    
+
    Text in these SVG files is represented as text, not paths, so you can edit them using a text editor and not an SVG editor. Then, the se build-images tool converts these text-based source images into path-based compiled images, for distribution in the final epub file. We do this so to avoid having to distribute the font files along with the epub.
    
 
    To develop cover and titlepage images, you must have the free League Spartan and Sorts Mill Goudy fonts installed on your system.
    
 
    
 
    Complete list of files
    
@@ -17,27 +17,28 @@ require_once('Core.php');
 
  • ./images/cover.jpg: A cropped part of the source image that will serve as the actual image file we use in the cover. Must be exactly 1400w × 2100h.
    • 
 
  • ./images/cover.svg: The SVG source file for the cover, with any text represented as actual, editable text. Must be exactly 1400w × 2100h pixels. Since the final cover image SVG has the text converted to paths, we keep this file around to make it easier to make changes to the cover in the future.
    • 
 
  • ./src/epub/images/cover.svg: The final SVG cover image. This image should be exactly like ./images/cover.svg, but with the text converted to paths.
-					
    This image is generated by the se build-images tool.
    
+					
    This image is generated by the se build-images tool.
    
 
    • 
 
  • ./images/titlepage.svg: The SVG source file for the titlepage, with any text represented as actual, editable text. Must be exactly 1400 pixels wide, but the height must exactly match the text height plus some padding (described below).
    • 
 
  • ./src/epub/images/titlepage.svg: The final SVG titlepage image, with text converted to paths just like the cover page.
-					
    This image is generated by the se build-images tool.
    
+					
    This image is generated by the se build-images tool.
    
 
    • 
 
 
    
 
    
 
    SVG patterns
    
 
      
-
    1. SVGs are only sized with viewBox, not height or width.
+
    2. SVGs are only sized with viewBox, not height or width.
 					
        
-
      1. The viewBox attribute consists of whole numbers, without fractions.
        2. 
+
      2. The viewBox attribute consists of whole numbers, without fractions.
        3. 
 
      
+
 
      3. 
-
    3. The only attributes on the <svg> root element are: xmlns, version, and viewBox.
      4. 
-
    4. The contents of the SVG’s <title> element matches the alt attribute of its <img> element in the text.
      5. 
+
    5. The only attributes on the <svg> root element are: xmlns, version, and viewBox.
      6. 
+
    6. The contents of the SVG’s <title> element matches the alt attribute of its <img> element in the text.
      7. 
 
    7. Grouping with <g> is avoided, unless it makes semantic sense. Groups whose sole purpose is to apply transforms should have those transforms applied to the children, and the group removed.
      8. 
 
    8. The use of fill color is avoided unless strictly necessary. Not defining a fill color allows for night mode compatibility.
      9. 
-
    9. The transform attribute is illegal; transforms are applied to their elements directly.
      10. 
+
    10. The transform attribute is illegal; transforms are applied to their elements directly.
      11. 
 
    
 
    
 
    
@@ -46,14 +47,14 @@ require_once('Core.php');
 
    The SE Editor-in-Chief must review and approve of the cover art you select before you can commit it to your repository.
    
 
    Do not commit cover art without contacting the mailing list first!
    
 
-
    The cover image is auto-generated by the se create-draft tool. The arrangement of the text is a suggestion, and may be changed by the producer in case a more visually-pleasing arrangment is desired.
    
-
    After completing ./images/cover.svg, use the se build-images tool to build the rasterized distribution SVG in ./src/epub/images/cover.svg.
    
+
    The cover image is auto-generated by the se create-draft tool. The arrangement of the text is a suggestion, and may be changed by the producer in case a more visually-pleasing arrangment is desired.
    
+
    After completing ./images/cover.svg, use the se build-images tool to build the rasterized distribution SVG in ./src/epub/images/cover.svg.
    
 
      
-
    1. The <title> element has a value of The cover for the Standard Ebooks edition of followed by the title string.
      2. 
+
    2. The <title> element has a value of The cover for the Standard Ebooks edition of followed by the title string.
      3. 
 
    
 
    
 
    Cover image layout
    
-
    se create-draft generates ./images/cover.svg for you with correct dimensions and layout. It’s rarely necessary to edit the cover.
    
+
    se create-draft generates ./images/cover.svg for you with correct dimensions and layout. It’s rarely necessary to edit the cover.
    
 
      
 
    1. Both the title and author are in League Spartan font with 5px letter spacing in ALL CAPS.
      2. 
 
    2. The left and right sides of the black title box have at least 40px padding. More padding is preferrable over cramming the title in.
      3. 
@@ -185,19 +186,19 @@ require_once('Core.php');
 
    
 
    
 
    The titlepage image
    
-
    The titlepage image is auto-generated by the se create-draft tool. The arrangement of the text is a suggestion, and may be changed by the producer in case a more visually-pleasing arrangment is desired.
    
-
    After completing ./images/titlepage.svg, use the se build-images tool to build the rasterized distribution SVG in ./src/epub/images/titlepage.svg.
    
+
    The titlepage image is auto-generated by the se create-draft tool. The arrangement of the text is a suggestion, and may be changed by the producer in case a more visually-pleasing arrangment is desired.
    
+
    After completing ./images/titlepage.svg, use the se build-images tool to build the rasterized distribution SVG in ./src/epub/images/titlepage.svg.
    
 
      
-
    1. The <title> element has a value of The titlepage for the Standard Ebooks edition of followed by the title string.
      2. 
+
    2. The <title> element has a value of The titlepage for the Standard Ebooks edition of followed by the title string.
      3. 
 
    
 
    
 
    Titlepage image layout
    
 
      
 
    1. The title, author, other contributors are in League Spartan font with 5px letter spacing in ALL CAPS.
      2. 
 
    2. The titlepage does not include subtitles.
-						
      For example, the titlepage would contain THE MAN WHO WAS THURSDAY, but not THE MAN WHO WAS THURSDAY: A NIGHTMARE.
      
+						
      For example, the titlepage would contain THE MAN WHO WAS THURSDAY, but not THE MAN WHO WAS THURSDAY: A NIGHTMARE.
      
 
      3. 
-
    3. Names of contributors besides the author are preceded by translated by or illustrated by. translated by and illustrated by are set in lowercase Sorts Mill Goudy Italic font.
      4. 
+
    4. Names of contributors besides the author are preceded by translated by or illustrated by. translated by and illustrated by are set in lowercase Sorts Mill Goudy Italic font.
      5. 
 
    5. Only the author, translator, and illustrator are on the titlepage. Other contributors like writers of introductions or annotators are not included.
      6. 
 
    6. The canvas has a padding area of 50px vertically and 100px horizontally in which text must not enter.
      7. 
 
    7. The viewbox width is exactly 1400px wide.
      8. 
@@ -223,12 +224,12 @@ require_once('Core.php');
 
      
 
      Contributor lines dimensions
      
 
        
-
      1. “Contributors” are a “contributor descriptor,” like translated by, followed by the contributor name on a new line.
        2. 
+
      2. “Contributors” are a “contributor descriptor,” like translated by, followed by the contributor name on a new line.
        3. 
 
      3. The first contributor descriptor line begins 150px below the last author line.
        4. 
 
      4. Contributor descriptor lines are 40px tall, all lowercase, in the Sorts Mill Goudy Italic font.
        5. 
 
      5. The contributor name begins 20px below the contributor descriptor line.
        6. 
 
      6. The contributor name is 40px tall, ALL CAPS, in the League Spartan font.
        7. 
-
      7. If there is more than one contributor of the same type (like multiple translators), they are listed on one line. If there are two, separate them with AND. If there are more than two, separate them with commas, and AND after the final comma. Example: Siddhartha, by Hermann Hesse.
        8. 
+
      8. If there is more than one contributor of the same type (like multiple translators), they are listed on one line. If there are two, separate them with AND. If there are more than two, separate them with commas, and AND after the final comma. Example: Siddhartha, by Hermann Hesse.
        9. 
 
      9. If there is more than one contributor type (like both a translator and an illustrator), the next contributor descriptor begins 80px after the last contributor name.
        10. 
 
      
 
      
diff --git a/www/manual/1.0.0/2-filesystem.php b/www/manual/1.0.0/2-filesystem.php
index db151a48..0b3d3cbd 100644
--- a/www/manual/1.0.0/2-filesystem.php
+++ b/www/manual/1.0.0/2-filesystem.php
@@ -1,7 +1,7 @@
  '2. Filesystem Layout and File Naming Conventions - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?>
-	
      
+	
      
 		
      
 
 
      
@@ -229,7 +229,7 @@ require_once('Core.php');
 
      
 
      
 
      The se-lint-ignore.xml file
      
-
      The se lint tool makes best guesses to alert the user to potential issues in an ebook production, and it may sometimes guess wrong. An se-lint-ignore.xml file can be placed in the ebook root to make se lint ignore specific error numbers in an ebook.
      
+
      The se lint tool makes best guesses to alert the user to potential issues in an ebook production, and it may sometimes guess wrong. An se-lint-ignore.xml file can be placed in the ebook root to make se lint ignore specific error numbers in an ebook.
      
 
        
 
      1. se-lint-ignore.xml is optional. If it exists, it is in the ebook root.
        2. 
 
      2. An empty se-lint-ignore.xml file looks like this:
@@ -239,17 +239,17 @@ require_once('Core.php');
 
        3. 
 
      3. The <se-lint-ignore> root element contains one or more <file> elements.
 					
          
-
        1. <file> elements have a path attribute containing a filename to match in ./src/epub/text/.
+
        2. <file> elements have a path attribute containing a filename to match in ./src/epub/text/.
 							
          <file path="chapter-3-1-11.xhtml">
 </file>
          
 
          3. 
-
        3. path attributes accept shell-style globbing to match files.
+
        4. path attributes accept shell-style globbing to match files.
 							
          <file path="chapter-*.xhtml">
 </file>
          
 
          5. 
 
        5. Each <file> element contains one or more <ignore> elements. Each <ignore> element contains one <code> element and one <reason> element.
 							
            
-
          1. The value of <code> is the error/warning code provided by se lint. This code will be ignored for its parent file(s) when se lint is next run.
            2. 
+
          2. The value of <code> is the error/warning code provided by se lint. This code will be ignored for its parent file(s) when se lint is next run.
            3. 
 
          3. The value of <reason> is a prose explanation about why the code was ignored. This is to aid future producers or reviewers in understanding the reasoning behind why a code was ignored.
 									
              
 
            1. <reason> is required to have a non-whitespace value.
              2. 
@@ -263,25 +263,25 @@ require_once('Core.php');
 
              
 
              Example
              
 
              The following is an example of a complete se-lint-ignore.xml file from Tractatus Logico-Philosophicus.
              
-
              <?xml version="1.0" encoding="utf-8"?>
-<se-lint-ignore>
-	<file path="introduction.xhtml">
-		<ignore>
-			<code>t-002</code>
-			<reason>Punctuation is deliberately placed outside of quotes in this ebook to prevent confusion with mathematical symbols and formulas.</reason>
-		</ignore>
-	</file>
-	<file path="tractatus-logico-philosophicus.xhtml">
-		<ignore>
-			<code>s-021</code>
-			<reason>The &lt;title&gt; tag is accurate; the work title appears in the half title.</reason>
-		</ignore>
-		<ignore>
-			<code>t-002</code>
-			<reason>Punctuation is deliberately placed outside of quotes in this ebook to prevent confusion with mathematical symbols and formulas.</reason>
-		</ignore>
-	</file>
-</se-lint-ignore>
              
+
              <?xml version="1.0" encoding="utf-8"?>
+<se-lint-ignore>
+	<file path="introduction.xhtml">
+		<ignore>
+			<code>t-002</code>
+			<reason>Punctuation is deliberately placed outside of quotes in this ebook to prevent confusion with mathematical symbols and formulas.</reason>
+		</ignore>
+	</file>
+	<file path="tractatus-logico-philosophicus.xhtml">
+		<ignore>
+			<code>s-021</code>
+			<reason>The &lt;title&gt; tag is accurate; the work title appears in the half title.</reason>
+		</ignore>
+		<ignore>
+			<code>t-002</code>
+			<reason>Punctuation is deliberately placed outside of quotes in this ebook to prevent confusion with mathematical symbols and formulas.</reason>
+		</ignore>
+	</file>
+</se-lint-ignore>
              
 
              
 
      
 
    
diff --git a/www/manual/1.0.0/3-the-structure-of-an-ebook.php b/www/manual/1.0.0/3-the-structure-of-an-ebook.php
index b9d39022..3ff2c5c7 100644
--- a/www/manual/1.0.0/3-the-structure-of-an-ebook.php
+++ b/www/manual/1.0.0/3-the-structure-of-an-ebook.php
@@ -1,7 +1,7 @@
  '3. The Structure of an Ebook - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?>
-	
    
+	
    
 		
    
 
 
    
@@ -14,11 +14,11 @@ require_once('Core.php');
 
    Front matter is material that appears before the main content of the work. It includes such items as a dedication, an epigraph, an introduction, and so on.
    
 
    
 
    Cover
    
-
    An image presenting the outer appearance of the book, usually consisting of an image, the title of the book and the author’s name. For Standard Ebooks productions, the cover is an SVG image generated from template that combines the book title and author, and a background image. The se build-images tool generates the cover image used for distribution.
    
+
    An image presenting the outer appearance of the book, usually consisting of an image, the title of the book and the author’s name. For Standard Ebooks productions, the cover is an SVG image generated from template that combines the book title and author, and a background image. The se build-images tool generates the cover image used for distribution.
    
 
    
 
    
 
    Title page
    
-
    A page listing the title of the book and the author’s name. For Standard Ebooks productions, the title page contains an SVG image generated by the se create-draft tool, which is then compiled for distribution using the se build-images tool.
    
+
    A page listing the title of the book and the author’s name. For Standard Ebooks productions, the title page contains an SVG image generated by the se create-draft tool, which is then compiled for distribution using the se build-images tool.
    
 
    
 
    
 
    Imprint
    
@@ -71,7 +71,7 @@ require_once('Core.php');
 
    
 
    Prologue
    
 
    A prologue is generally found only in works of fiction. It may introduce characters, set up background information, or bring forward a critical part of the action to which the story leads.
    
-
    A prologue is generally part of the body matter, unless the prologue is a fictional element of a frame narrative. In that case, it may be appropriate to place it in front of the half title and give it a different title, while keeping the prologue semantic inflection.
    
+
    A prologue is generally part of the body matter, unless the prologue is a fictional element of a frame narrative. In that case, it may be appropriate to place it in front of the half title and give it a different title, while keeping the prologue semantic inflection.
    
 
    
 
    
 
    Epilogue
    
diff --git a/www/manual/1.0.0/4-semantics.php b/www/manual/1.0.0/4-semantics.php
index f9a6261d..142b2ba1 100644
--- a/www/manual/1.0.0/4-semantics.php
+++ b/www/manual/1.0.0/4-semantics.php
@@ -1,7 +1,7 @@
  '4. Semantics - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?>
-	
    
+	
    
 		
    
 
 
    
@@ -15,8 +15,8 @@ require_once('Core.php');
 	Is he in heaven?⁠—Is he in hell,<br/>
 	That demmed, elusive Pimpernel?”</div>
 </div>
    -

    While that snipped might visually present the text as a paragraph followed by a quotation of verse, the actual HTML tells us nothing about what these lines of text actually are.

    -

    Compare the above snippet to this next snippet, which renders almost identically but uses semantically-correct tags and epub’s semantic inflection to tell us what the text is:

    +

    While that snippet might visually present the text as a paragraph followed by a quotation of verse, the actual HTML tells us nothing about what these lines of text actually are.

    +

    Compare the above snippet to this next snippet, which renders almost identically but uses semantically-correct elements and epub’s semantic inflection to tell us what the text is:

    <p>“All done in the tying of a cravat,” Sir Percy had declared to his clique of admirers.</p> <blockquote epub:type="z3998:poem"> <p> @@ -29,29 +29,29 @@ require_once('Core.php'); <span>That demmed, elusive Pimpernel?”</span> </p> </blockquote>
    -

    By inspecting the tags above, we can see that the first line is a semantic paragraph (<p> stands for paragraph, of course); the paragraph is followed by a semantic block quotation, which browsers automatically render with a margin; the quotation is a poem; the poem has one stanza; and there are four lines in the poem. (By SE convention, <p> elements in verse are stanzas and <span> elements are lines.)

    +

    By inspecting the elements above, we can see that the first line is a semantic paragraph (<p> stands for paragraph, of course); the paragraph is followed by a semantic block quotation, which browsers automatically render with a margin; the quotation is a poem; the poem has one stanza; and there are four lines in the poem. (By SE convention, <p> elements in verse are stanzas and <span> elements are lines.)

    -

    Semantic Tags

    -

    Epub allows for the use of the full range of tags in the HTML5 spec. Each tag has a semantic meaning, and each tag in a Standard Ebook is carefully considered before use.

    +

    Semantic Elements

    +

    Epub allows for the use of the full range of elements in the HTML5 spec. Each element has a semantic meaning, and each element in a Standard Ebook is carefully considered before use.

    Below is an incomplete list of HTML5 elements and their semantic meanings. These are some of the most common elements encountered in an ebook.

    -

    Block-level tags

    -

    Block-level tags are by default rendered with { display: block; }. See the complete list of block-level tags.

    +

    Block-level elements

    +

    Block-level elements are by default rendered with { display: block; }. See the complete list of block-level elements.

      -

    1. Sectioning block-level tags denote major structural divisions in a work. +

    2. Sectioning block-level elements denote major structural divisions in a work.

        -

      1. <body>: The top-level tag in any XHTML file. Must contain a direct child that is either a <section> or <article>.

        2. +

      2. <body>: The top-level element in any XHTML file. Must contain a direct child that is either a <section> or <article>.

      3. <section>: A major structural division in a work. Typically a part, volume, chapter, or subchapter. Semantically a <section> cannot stand alone, but is part of a larger work.

      4. <article>: An item in a larger work that could be pulled out of the work and serialized or syndicated separately. For example, a single poem in a poetry collection, or a single short story in a short story collection; but not a single poem in a larger novel.

      3. -

    3. Other block-level tags have well-defined semantic meanings. +

    4. Other block-level elements have well-defined semantic meanings.

      1. <p>: A paragraph of text.

      2. <blockquote>: A quotation displayed on the block level. This may include non-speech “quotations” like business cards, headstones, telegrams, letters, and so on.

      3. <figure>: Encloses a photograph, chart, or illustration, represented with an <img> element. Optionally includes a <figcaption> element for a context-appropriate caption.

        4. -

      4. <figcaption>: Only appears as a child of <figure>. Represents a context-appropriate caption for the sibling <img>. A caption is not the same as an <img> element’s alt text. alt text is strictly a textual description of the image used for screen readers, whereas <figcaption> has more freedom in its contents, depending on its context.

        5. -

      5. <header>: Denotes a header section applying to its direct parent. <header> is typically found in sections where there is additional header content besides the section title, but can also be used in <blockquote>s or other block-level tags that require header styling.

        6. +

      6. <figcaption>: Only appears as a child of <figure>. Represents a context-appropriate caption for the sibling <img>. A caption is not the same as an <img> element’s alt text. alt text is strictly a textual description of the image used for screen readers, whereas <figcaption> has more freedom in its contents, depending on its context.

        7. +

      7. <header>: Denotes a header section applying to its direct parent. <header> is typically found in sections where there is additional header content besides the section title, but can also be used in <blockquote>s or other block-level elements that require header styling.

      8. <footer>: Denotes a footer section applying to its direct parent. Typically used to denote signatures in sections like prefaces, forewords, letters, telegrams, and so on.

      9. <hr>: Denotes a thematic break. <hr> is not used any place a black border is desired; it strictly denotes a thematic break.

      10. <ol>: Denotes an ordered list. Ordered lists are automatically numbered by the renderer.

        11. @@ -60,39 +60,39 @@ require_once('Core.php');

      11. <table>: Denotes a tabular section, for example when displaying tabular data, or reports or charts where a tabular appearance is desired.

      5. -

    5. <div> elements are almost never appropriate, as they have no semantic meaning. However, they may in rare occasions be used to group related elements in a situation where no other semantic tag is appropriate.

      6. +

    6. <div> elements are almost never appropriate, as they have no semantic meaning. However, they may in rare occasions be used to group related elements in a situation where no other semantic element is appropriate.

    -

    Inline tags

    -

    Inline tags are by default rendered with { display: inline; }. See the complete list of inline tags.

    +

    Inline elements

    +

    Inline elements are by default rendered with { display: inline; }. See the complete list of inline elements.

    1. <em>: Text rendered in italics, with the semantic meaning of emphasized speech, or speech spoken in a different tone of voice; for example, a person shouting, or putting stress on a particular word.

      2. -

    2. <i>: Text rendered in italics, without any explicit semantic meaning. Because <i> lacks semantic meaning, the epub:type attribute is added with appropriate semantic inflection to describe the contents of the tag. +

    3. <i>: Text rendered in italics, without any explicit semantic meaning. Because <i> lacks semantic meaning, the epub:type attribute is added with appropriate semantic inflection to describe the contents of the element.

      <p>The <abbr class="initialism">HMS</abbr> <i epub:type="se:name.vessel.ship">Bounty</i>.</p>
      4. -

    4. <b>: Text rendered in small caps, without any explicit semantic meaning. Because <b> lacks semantic meaning, the epub:type attribute can be added with appropriate semantic inflection to describe the contents of the tag; however, unlike <i>, it’s rare for <b> to require semantic meaning, as it is generally used only for visual styling.

      5. -

    5. <span>: Plain inline text that requires specific styling or semantic meaning that cannot be achieved with any other semantically meaningful inline tag. Typically used in conjunction with a class or epub:type attribute.

      6. +

    6. <b>: Text rendered in small caps, without any explicit semantic meaning. Because <b> lacks semantic meaning, the epub:type attribute can be added with appropriate semantic inflection to describe the contents of the element; however, unlike <i>, it’s rare for <b> to require semantic meaning, as it is generally used only for visual styling.

      7. +

    7. <span>: Plain inline text that requires specific styling or semantic meaning that cannot be achieved with any other semantically meaningful inline element. Typically used in conjunction with a class or epub:type attribute.

    Semantic Inflection

    The epub spec allows for semantic inflection, which is a way of adding semantic metadata to elements in the ebook document.

    -

    For example, an ebook producer may want to convey that the contents of a certain <section> are part of a chapter. They would do that by using the epub:type attribute:

    +

    For example, an ebook producer may want to convey that the contents of a certain <section> are part of a chapter. They would do that by using the epub:type attribute:

    <section epub:type="chapter">...</section>
      -

    1. The epub spec includes a vocabulary that can be used in the epub:type attribute. This vocabulary has priority when selecting a semantic keyword, even if other vocabularies contain the same one.

      2. +

    2. The epub spec includes a vocabulary that can be used in the epub:type attribute. This vocabulary has priority when selecting a semantic keyword, even if other vocabularies contain the same one.

    3. The epub spec might not contain a keyword necessary to describe the semantics of a particular element. In that case, the z3998 vocabulary is consulted next. -

      Keywords using this vocabulary are preceded by the z3998 namespace.

      +

      Keywords using this vocabulary are preceded by the z3998 namespace.

      <blockquote epub:type="z3998:letter">...</blockquote>

    4. If the z3998 vocabulary doesn’t have an appropriate keyword, the Standard Ebooks vocabulary is consulted next. -

      Keywords using this vocabulary are preceded by the se namespace.

      -

      Unlike other vocabularies, the Standard Ebooks vocabulary is organized hierarchically. A complete vocabulary entry begins with the root vocabulary entry, with subsequent children separated by ..

      +

      Keywords using this vocabulary are preceded by the se namespace.

      +

      Unlike other vocabularies, the Standard Ebooks vocabulary is organized hierarchically. A complete vocabulary entry begins with the root vocabulary entry, with subsequent children separated by ..

      The <abbr class="initialism">HMS</abbr> <i epub:type="se:name.vessel.ship">Bounty</i>.
      5. -

    5. The epub:type attribute can have multiple keywords separated by spaces, even if the vocabularies are different. +

    6. The epub:type attribute can have multiple keywords separated by spaces, even if the vocabularies are different.

      <section epub:type="chapter z3998:letter">...</section>

    7. Child elements inherit the semantics of their parent element. diff --git a/www/manual/1.0.0/5-general-xhtml-patterns.php b/www/manual/1.0.0/5-general-xhtml-patterns.php index 6ed46267..7b6fe3ab 100644 --- a/www/manual/1.0.0/5-general-xhtml-patterns.php +++ b/www/manual/1.0.0/5-general-xhtml-patterns.php @@ -1,20 +1,20 @@ '5. General XHTML Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -

      +

      General XHTML Patterns

      This section covers general patterns used when producing XHTML that are not specific to ebooks.

      -

      id attributes

      +

      id attributes

      -

      id attributes of <section> and <article> elements

      +

      id attributes of <section> and <article> elements

        -

      1. Each <section> has an id attribute.

        2. -

      2. <section> or <article> elements that are direct children of the <body> element have an id attribute identical to the filename containing that <section> or <article>, without the trailing extension.

        3. -

      3. In files containing multiple <section> or <article> elements, each of those elements has an id attribute identical to what the filename would be if the section was in an individual file, without the trailing extension. +

      4. Each <section> has an id attribute.

        5. +

      5. <section> or <article> elements that are direct children of the <body> element have an id attribute identical to the filename containing that <section> or <article>, without the trailing extension.

        6. +

      6. In files containing multiple <section> or <article> elements, each of those elements has an id attribute identical to what the filename would be if the section was in an individual file, without the trailing extension.

        <body epub:type="bodymatter z3998:fiction"> <article id="the-fox-and-the-grapes" epub:type="se:short-story"> <h2 epub:type="title">The Fox and the Grapes</h2> @@ -29,11 +29,11 @@ require_once('Core.php');
      -

      id attributes of other elements

      +

      id attributes of other elements

        -

      1. id attributes are generally used to identify parts of the document that a reader may wish to navigate to using a hash in the URL. That generally means major structural divisions. Therefore, elements that are not <section> or <article> elements do not have an id attribute, unless a part of the ebook, like an endnote, refers to a specific point in the book, and a direct link is desirable.

        2. -

      2. id attributes are not used as hooks for CSS styling.

        3. -

      3. If an element that is not a <section> or <article> requires an id attribute, the attribute’s value is the name of the tag followed by -N, where N is the sequence number of the tag start at 1. +

      4. id attributes are generally used to identify parts of the document that a reader may wish to navigate to using a hash in the URL. That generally means major structural divisions. Therefore, elements that are not <section> or <article> elements do not have an id attribute, unless a part of the ebook, like an endnote, refers to a specific point in the book, and a direct link is desirable.

        5. +

      5. id attributes are not used as hooks for CSS styling.

        6. +

      6. If an element that is not a <section> or <article> requires an id attribute, the attribute’s value is the name of the element followed by -N, where N is the sequence number of the element start at 1.

        <p>See <a href="#p-4">this paragraph</a> for more details.</p> <p>...</p> <p>...</p> @@ -44,7 +44,7 @@ require_once('Core.php');
      -

      class attributes

      +

      class attributes

      Classes denote a group of elements sharing a similar style.

      1. Classes are not used as single-use style hooks. There is almost always a way to compose a CSS selector to select a single element without the use of a one-off class. @@ -112,16 +112,16 @@ require_once('Core.php');

      -

      xml:lang attributes

      +

      xml:lang attributes

        -

      1. When words are required to be pronounced in a language other than English, the xml:lang attribute is used to indicate the IETF language tag in use. +

      2. When words are required to be pronounced in a language other than English, the xml:lang attribute is used to indicate the IETF language tag in use.

          -

        1. The xml:lang attribute is used even if a word is not required to be italicized. This allows screen readers to understand that a particular word or phrase should be pronounced in a certain way. A <span xml:lang="TAG"> element is used to wrap text that has non-English pronunciation but that does not need further visual styling.

          2. -

        2. The xml:lang attribute is included in any word that requires special pronunciation, including names of places and titles of books.

          3. +

        3. The xml:lang attribute is used even if a word is not required to be italicized. This allows screen readers to understand that a particular word or phrase should be pronounced in a certain way. A <span xml:lang="TAG"> element is used to wrap text that has non-English pronunciation but that does not need further visual styling.

          4. +

        4. The xml:lang attribute is included in any word that requires special pronunciation, including names of places and titles of books.

        She opened the book titled <i epub:type="se:name.publication.book" xml:lang="la">Mortis Imago</i>.
          -

        1. The xml:lang attribute is applied to the highest-level tag possible. If italics are required and moving the xml:lang attribute would also remove an <i> element, the parent element can be styled with body [xml|lang]{ font-style: italic; }.

          2. +

        2. The xml:lang attribute is applied to the highest-level element possible. If italics are required and moving the xml:lang attribute would also remove an <i> element, the parent element can be styled with body [xml|lang]{ font-style: italic; }.

        <blockquote> <p><i xml:lang="es">“Como estas?” el preguntó.</i></p> @@ -145,14 +145,14 @@ require_once('Core.php');

      3. Convert chapter or part numbers that are in Roman numerals to decimal numbers. Do not convert other Roman numerals that may be in the chapter title.

        <title>Chapter 10</title>
        4. -

      4. If a chapter or part is only an ordinal and has no title or subtitle, the <title> element is Chapter followed by the chapter number. +

      5. If a chapter or part is only an ordinal and has no title or subtitle, the <title> element is Chapter followed by the chapter number.

        <title>Chapter 4</title> ... <h2 epub:type="title z3998:roman">IV</h2> ... <p>The chapter body...</p>
        6. -

      6. If a chapter or part has a title or subtitle, the <title> element is Chapter, followed by the chapter number in decimal, followed by a colon and a single space, followed by the title or subtitle. +

      7. If a chapter or part has a title or subtitle, the <title> element is Chapter, followed by the chapter number in decimal, followed by a colon and a single space, followed by the title or subtitle.

        <title>Chapter 6: The Reign of Louis XVI</title> ... <h2 epub:type="title"> @@ -178,7 +178,7 @@ require_once('Core.php');

        Ordered/numbered and unordered lists

          -

        1. All <li> children of <ol> and <ul> elements have at least one direct child block-level tag. This is usually a <p> element, but not necessarily; for example, a <blockquote> element might also be appropriate. +

        2. All <li> children of <ol> and <ul> elements have at least one direct child block-level element. This is usually a <p> element, but not necessarily; for example, a <blockquote> element might also be appropriate.

          <ul> <li>Don’t forget to feed the pigs.</li> </ul>
          diff --git a/www/manual/1.0.0/6-high-level-structural-patterns.php b/www/manual/1.0.0/6-high-level-structural-patterns.php deleted file mode 100644 index 2ee0e21b..00000000 --- a/www/manual/1.0.0/6-high-level-structural-patterns.php +++ /dev/null @@ -1,928 +0,0 @@ - '6. High Level Structural Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          -
          - -
          -

          High Level Structural Patterns

          -

          Section should contain high-level structural patterns for common formatting situations.

          -
          -

          Sectioning

          -
            -

          1. Major structural divisions of a larger work, like parts, volumes, books, chapters, or subchapters, are contained in a <section> element.

            2. -

          2. Individual items in a larger collection (like a poem in a poetry collection) are contained in a <article> element.

            3. -

          3. In <section> or <articles> elements that have titles, the first child element is an <h1>–<h6> element, or a <header> element containing the section’s title.

            4. -
          -
          -

          Recomposability

          -

          “Recomposability” is the concept of generating a single structurally-correct HTML5 file out of an epub file. All Standard Ebooks are recomposable.

          -
            -

          1. XHTML files that contain <section> or <articles> elements that are semantic children of <section> or <articles> elements in other files, are wrapped in stubs of all parent <section> or <articles> elements, up to the root.

            2. -

          2. Each such included parent element has the identical id and epub:type attributes of its real counterpart.

            3. -
          -
          -

          Examples

          -

          Consider a book that contains several top-level subdivisions: Books 1–4, with each book having 3 parts, and each part having 10 chapters. Below is an example of three files demonstrating the structure necessary to achieve recomposability:

          -

          Book 1 (book-1.xhtml):

          -
          <section id="book-1" epub:type="division"> - <h2 epub:type="title">Book <span epub:type="z3998:roman">I</span></h2> -</section>
          -

          Book 1, Part 2 (part-1-2.xhtml):

          -
          <section id="book-1" epub:type="division"> - <section id="part-1-2" epub:type="part"> - <h2 epub:type="title">Part <span epub:type="z3998:roman">II</span></h2> - </section> -</section>
          -

          Book 1, Part 2, Chapter 3 (chapter-1-2-3.xhtml):

          -
          <section id="book-1" epub:type="division"> - <section id="part-1-2" epub:type="part"> - <section id="chapter-3" epub:type="chapter"> - <h2 epub:type="title">Chapter <span epub:type="z3998:roman">III</span></h2> - <p>...</p> - <p>...</p> - </section> - </section> -</section>
          -
          -
          -
          -
          -

          Headers

          -
            -

          1. <h1>–<h6> elements are used for headers of sections that are structural divisions of a document, i.e., divisions that appear in the table of contents. <h1>–<h6> elements are not used for headers of components that are not in the table of contents. For example, they are not used to mark up the title of a short poem in a chapter, where the poem itself is not a structural component of the larger ebook.

            2. -

          2. A section containing an <h1>–<h6> appears in the table of contents.

            3. -

          3. The book’s title is implicitly at the <h1> level, even if <h1> is not present in the ebook. Because of the implicit <h1>, all other sections begin at <h2>.

            4. -

          4. Each <h1>–<h6> element uses the correct number for the section’s heading level in the overall book, not the section’s heading level in the individual file. For example, given an ebook with a file named part-2.xhtml containing: -

            <section id="part-2" epub:type="part"> - <h2 epub:type="title">Part <span epub:type="z3998:roman">II</span></h2> -</section>
            -

            Consider this example for the file chapter-2-3.xhtml:

            -
            <section id="part-2" epub:type="part"> - <section id="chapter-2-3" epub:type="chapter"> - <h2 epub:type="title z3998:roman">III</h2> - ... - </section> -</section>
            -
            <section id="part-2" epub:type="part"> - <section id="chapter-2-3" epub:type="chapter"> - <h3 epub:type="title z3998:roman">III</h3> - ... - </section> -</section>
            -
            5. -

          5. Each <h1>–<h6> element has a direct parent <section> or <article> element.

            6. -
          -
          -

          Header patterns

          -
            -

          1. Sections without titles: -

            <h2 epub:type="title z3998:roman">XI</h2>
            -
            2. -

          2. Sections with titles but no ordinal (i.e. chapter) numbers: -

            <h2 epub:type="title">A Daughter of Albion</h2>
            -
            3. -

          3. Sections with titles and ordinal (i.e. chapter) numbers: -

            span[epub|type~="subtitle"]{ - display: block; - font-weight: normal; -}
            -
            <h2 epub:type="title"> - <span epub:type="z3998:roman">XI</span> - <span epub:type="subtitle">Who Stole the Tarts?</span> -</h2>
            -
            4. -

          4. Sections titles and subtitles but no ordinal (i.e. chapter) numbers: -

            span[epub|type~="subtitle"]{ - display: block; - font-weight: normal; -}
            -
            <h2 epub:type="title"> - <span>An Adventure</span> - <span epub:type="subtitle">(A Driver’s Story)</span> -</h2>
            -
            5. -

          5. Sections that require titles, but that are not in the table of contents: -

            header{ - font-variant: small-caps; - margin: 1em; - text-align: center; -}
            -
            <header> - <p>The Title of a Short Poem</p> -</header>
            -
            6. -
          -
          -
          -

          Bridgeheads

          -

          Bridgeheads are sections in a chapter header that give an abstract or summary of the following chapter. They may be in prose or in a short list with clauses separated by em dashes.

          -
            -

          1. The last clause in a bridgehead ends in appropriate punctuation, like a period.

            2. -

          2. Bridgeheads have the following CSS and HTML structure: -

            [epub|type~="bridgehead"]{ - display: inline-block; - font-style: italic; - max-width: 60%; - text-align: justify; - text-indent: 0; -} - -[epub|type~="bridgehead"] i{ - font-style: normal; -}
            -
            <header> - <h2 epub:type="title z3998:roman">I</h2> - <p epub:type="bridgehead">Which treats of the character and pursuits of the famous gentleman Don Quixote of La Mancha.</p> -</header>
            -
            <header> - <h2 epub:type="title z3998:roman">X</h2> - <p epub:type="bridgehead">Our first night⁠wj—Under canvas⁠wj—An appeal for help⁠wj—Contrariness of teakettles, how to overcome⁠wj—Supper⁠wj—How to feel virtuous⁠wj—Wanted! a comfortably-appointed, well-drained desert island, neighbourhood of South Pacific Ocean preferred⁠wj—Funny thing that happened to George’s father⁠wj—A restless night.</p> -</header>
            -
            3. -
          -
          -
          -
          -

          Epigraphs

          -
            -

          1. All epigraphs include this CSS: -

            /* All epigraphs */ -[epub|type~="epigraph"]{ - font-style: italic; - hyphens: none; -} - -[epub|type~="epigraph"] em, -[epub|type~="epigraph"] i{ - font-style: normal; -} - -[epub|type~="epigraph"] cite{ - margin-top: 1em; - font-style: normal; - font-variant: small-caps; -} - -[epub|type~="epigraph"] cite i{ - font-style: italic; -} -/* End all epigraphs */
            -
            2. -
          -
          -

          Epigraphs in section headers

          -
            -

          1. Epigraphs in section headers have the quote source in a <cite> element set in small caps, without a leading em-dash and without a trailing period. -

            <header> - <h2 epub:type="title z3998:roman">II</h2> - <blockquote epub:type="epigraph"> - <p>“Desire no more than to thy lot may fall. …”</p> - <cite>—Chaucer.</cite> - </blockquote> -</header>
            -
            header [epub|type~="epigraph"] cite{ - font-variant: small-caps; -}
            -
            <header> - <h2 epub:type="title z3998:roman">II</h2> - <blockquote epub:type="epigraph"> - <p>“Desire no more than to thy lot may fall. …”</p> - <cite>Chaucer</cite> - </blockquote> -</header>
            -
            2. -

          2. In addition to the CSS used for all epigraphs, this additional CSS is included for epigraphs in section headers: -

            /* Epigraphs in section headers */ -section > header [epub|type~="epigraph"]{ - display: inline-block; - margin: auto; - max-width: 80%; - text-align: left; -} - -section > header [epub|type~="epigraph"] + *{ - margin-top: 3em; -} - -@supports(display: table){ - section > header [epub|type~="epigraph"]{ - display: table; - } -} -/* End epigraphs in section headers */
            -
            3. -
          -
          -
          -

          Full-page epigraphs

          -
            -

          1. In full-page epigraphs, the epigraph is centered on the page for ereaders that support advanced CSS. For all other ereaders, the epigraph is horizontally centered with a small margin above it.

            2. -

          2. Full-page epigraphs that contain multiple quotations are represented by multiple <blockquote> elements.

            3. -

          3. In addition to the CSS used for all epigraphs, this additional CSS is included for full-page epigraphs: -

            /* Full-page epigraphs */ -section[epub|type~="epigraph"]{ - text-align: center; -} - -section[epub|type~="epigraph"] > *{ - display: inline-block; - margin: auto; - margin-top: 3em; - max-width: 80%; - text-align: left; -} - -@supports(display: flex){ - section[epub|type~="epigraph"]{ - align-items: center; - box-sizing: border-box; - display: flex; - flex-direction: column; - justify-content: center; - min-height: calc(98vh - 3em); - padding-top: 3em; - } - - section[epub|type~="epigraph"] > *{ - margin: 0; - } - - section[epub|type~="epigraph"] > * + *{ - margin-top: 3em; - } -} -/* End full-page epigraphs */
            -
            4. -

          4. Example HTML: -

            <body epub:type="frontmatter"> - <section id="epigraph" epub:type="epigraph"> - <blockquote> - <p>Reorganisation, irrespectively of God or king, by the worship of Humanity, systematically adopted.</p> - <p>Man’s only right is to do his duty.</p> - <p>The Intellect should always be the servant of the Heart, and should never be its slave.</p> - </blockquote> - <blockquote> - <p>“We tire of thinking and even of acting; we never tire of loving.”</p> - </blockquote> - </section> -</body>
            -
            5. -
          -
          -
          -
          -

          Poetry, verse, and songs

          -

          Unfortunately there’s no great way to semantically format poetry in HTML. As such, unrelated elements are conscripted for use in poetry.

          -
            -

          1. A stanza is represented by a <p> element styled with this CSS: -

            [epub|type~="z3998:poem"] p{ - text-align: left; - text-indent: 0; -} - -[epub|type~="z3998:poem"] p + p{ - margin-top: 1em; -} - -[epub|type~="z3998:poem"] + p{ - text-indent: 0; -}
            -
            2. -

          2. Each stanza contains <span> elements, each one representing a line in the stanza, styled with this CSS: -

            [epub|type~="z3998:poem"] p > span{ - display: block; - text-indent: -1em; - padding-left: 1em; -}
            -
            3. -

          3. Each <span> line is followed by a <br/> element, except for the last line in a stanza, styled with this CSS: -

            [epub|type~="z3998:poem"] p > span + br{ - display: none; -}
            -
            4. -

          4. Indented <span> lines have the i1 class. Do not use nbsp for indentation. Indenting to different levels is done by incrementing the class to i2, i3, and so on, and including the appropriate CSS. -

            p span.i1{ - text-indent: -1em; - padding-left: 2em; -} - -p span.i2{ - text-indent: -1em; - padding-left: 3em; -}
            -
            5. -

          5. Poems, songs, and verse that are shorter part of a longer work, like a novel, are wrapped in a <blockquote> element. -

            <blockquote epub:type="z3998:poem"> - <p> - <span>...</span></br> - <span>...</span> - </p> -</blockquote>
            -
            6. -

          6. The parent element of poetry, verse, or song, has the semantic inflection of z3998:poem, z3998:verse, z3998:song, or z3998:hymn.

            7. -

          7. If a poem is quoted and has one or more lines removed, the removed lines are represented with a vertical ellipses (⋮ or U+22EE) in a <span class="elision"> element styled with this CSS: -

            span.elision{ - margin: .5em; - margin-left: 3em; -} - -/* If eliding within an epigraph, include this additional style: */ -[epub|type~="epigraph"] span.elision{ - font-style: normal; -}
            -
            <blockquote epub:type="z3998:verse"> - <p> - <span>O Lady! we receive but what we give,</span> - <br/> - <span>And in our life alone does nature live:</span> - <br/> - <span>Ours is her wedding garments, ours her shroud!</span> - <br/> - <span class="elision">⋮</span> - <br/> - <span class="i1">Ah! from the soul itself must issue forth</span> - <br/> - <span>A light, a glory, a fair luminous cloud,</span> - </p> -</blockquote>
            -
            8. -
          -
          -

          Examples

          -

          Note that below we include CSS for the i2 class, even though it’s not used in the example. It’s included to demonstrate how to adjust the CSS for indentation levels after the first.

          -
          [epub|type~="z3998:poem"] p{ - text-align: left; - text-indent: 0; -} - -[epub|type~="z3998:poem"] p > span{ - display: block; - text-indent: -1em; - padding-left: 1em; -} - -[epub|type~="z3998:poem"] p > span + br{ - display: none; -} - -[epub|type~="z3998:poem"] p + p{ - margin-top: 1em; -} - -[epub|type~="z3998:poem"] + p{ - text-indent: 0; -} - -p span.i1{ - text-indent: -1em; - padding-left: 2em; -} - -p span.i2{ - text-indent: -1em; - padding-left: 3em; -}
          -
          <blockquote epub:type="z3998:poem"> - <p> - <span>“How doth the little crocodile</span> - <br/> - <span class="i1">Improve his shining tail,</span> - <br/> - <span>And pour the waters of the Nile</span> - <br/> - <span class="i1">On every golden scale!</span> - </p> - <p> - <span>“How cheerfully he seems to grin,</span> - <br/> - <span class="i1">How neatly spread his claws,</span> - <br/> - <span>And welcome little fishes in</span> - <br/> - <span class="i1"><em>With gently smiling jaws!</em>”</span> - </p> -</blockquote>
          -
          -
          -
          -

          Plays & Drama

          -
            -

          1. Dialog in plays is structured using <table> elements.

            2. -

          2. Each <tr> is either a block of dialog or a standalone stage direction.

            3. -

          3. Works that are plays or that contain sections of dramatic dialog have this core CSS: -

            [epub|type~="z3998:drama"]{ - border-collapse: collapse; -} - -[epub|type~="z3998:drama"] tr:first-child td{ - padding-top: 0; -} - -[epub|type~="z3998:drama"] tr:last-child td{ - padding-bottom: 0; -} - -[epub|type~="z3998:drama"] td{ - vertical-align: top; - padding: .5em; -} - -[epub|type~="z3998:drama"] td:last-child{ - padding-right: 0; -} - -[epub|type~="z3998:drama"] td:first-child{ - padding-left: 0; -} - -[epub|type~="z3998:drama"] td[epub|type~="z3998:persona"]{ - hyphens: none; - text-align: right; - width: 20%; -} - -[epub|type~="z3998:drama"] td p{ - text-indent: 0; -} - -table[epub|type~="z3998:drama"], -[epub|type~="z3998:drama"] table{ - margin: 1em auto; -} - -[epub|type~="z3998:stage-direction"]{ - font-style: italic; -} - -[epub|type~="z3998:stage-direction"]::before{ - content: "("; - font-style: normal; -} - -[epub|type~="z3998:stage-direction"]::after{ - content: ")"; - font-style: normal; -} - -[epub|type~="z3998:persona"]{ - font-variant: all-small-caps; -}
            -
            4. -
          -
          -

          Dialog rows

          -
            -

          1. The first child of a row of dialog is a <td> element with the semantic inflection of z3998:persona.

            2. -

          2. The second child of a row of dialog is a <td> element containing the actual dialog. Elements that contain only one line of dialog do not have a block-level child (like <p>). -

            <tr> - <td epub:type="z3998:persona">Algernon</td> - <td>Did you hear what I was playing, Lane?</td> -</tr> -<tr> - <td epub:type="z3998:persona">Lane</td> - <td>I didn’t think it polite to listen, sir.</td> -</tr>
            -
            3. -

          3. When several personas speak at once, or a group of personas ("The Actors") speaks at once, the containing <tr> element has the together class, and the first <td> child has a rowspan attribute corresponding to the number of lines spoken together. -

            tr.together td{ - padding: 0 .5em 0 0; - vertical-align: middle; -} - -tr.together td:only-child, -tr.together td + td{ - border-left: 1px solid; -} - -.together + .together td[rowspan], -.together + .together td[rowspan] + td{ - padding-top: .5em; -} - -[epub|type~="z3998:drama"] .together td:last-child{ - padding-left: .5em; -}
            -
            <tr class="together"> - <td rowspan="3" epub:type="z3998:persona">The Actors</td> - <td>Oh, what d’you think of that?</td> -</tr> -<tr class="together"> - <td>Only the mantle?</td> -</tr> -<tr class="together"> - <td>He must be mad.</td> -</tr> -<tr class="together"> - <td rowspan="2" epub:type="z3998:persona">Some Actresses</td> - <td>But why?</td> -</tr> -<tr class="together"> - <td>Mantles as well?</td> -</tr>
            -
            4. -
          -
          -
          -

          Stage direction rows

          -
            -

          1. The first child of a row of stage direction is an empty <td> element.

            2. -

          2. The second child of a row of dialog is a <td> element containing the stage direction

            3. -

          3. Stage direction is wrapped in an <i epub:type="z3998:stage-direction"> element.

            4. -

          4. Personas mentioned in stage direction are wrapped in a <b epub:type="z3998:persona"> element.

            5. -
          -
          -

          Examples

          -
          <tr> - <td/> - <td> - <i epub:type="z3998:stage-direction"><b epub:type="z3998:persona">Lane</b> is arranging afternoon tea on the table, and after the music has ceased, <b epub:type="z3998:persona">Algernon</b> enters.</i> - </td> -</tr>
          -
          -
          -
          -

          Works that are complete plays

          -
            -

          1. The top-level element (usually <body>) has the z3998:drama semantic inflection.

            2. -

          2. Acts are <section> elements containing at least one <table> for dialog, and optionally containing an act title and other top-level stage direction.

            3. -

          3. Introductory or high-level stage direction is presented using <p> elements outside of the dialog table. -

            <body epub:type="bodymatter z3998:fiction z3998:drama"> - <section id="act-1" epub:type="chapter z3998:scene"> - <h2 epub:type="title">Act <span epub:type="z3998:roman">I</span></h2> - <p>Scene: Morning-room in Algernon’s flat in Half-Moon Street. The room is luxuriously and artistically furnished. The sound of a piano is heard in the adjoining room.</p> - <table> - ... - </table> - <p epub:type="z3998:stage-direction">Act Drop</p> - </section> -</body>
            -
            4. -

          4. Dramatis personae are presented as a <ul> element listing the characters. -

            [epub|type~="z3998:dramatis-personae"]{ - text-align: center; -} - -[epub|type~="z3998:dramatis-personae"] ul{ - list-style: none; - margin: 0; - padding: 0; -} - -[epub|type~="z3998:dramatis-personae"] ul li{ - margin: 1em; - font-style: italic; -}
            -
            <section id="dramatis-personae" epub:type="z3998:dramatis-personae"> - <h2 epub:type="title">Dramatis Personae</h2> - <ul> - <li> - <p>King Henry <span epub:type="z3998:roman">V</span></p> - </li> - <li> - <p>Duke of Clarence, brother to the King</p> - </li> - ... - </ul> -</section>
            -
            5. -
          -
          -
          -
          -

          Letters

          -

          Letters require particular attention to styling and semantic tagging. Letters may not exactly match the formatting in the source scans, but they are in visual sympathy with the source.

          -
            -

          1. Letters are wrapped in a <blockquote> element with the appropriate semantic inflection, usually z3998:letter.

            2. -
          -
          -

          Letter headers

          -
            -

          1. Parts of a letter prior to the body of the letter, for example the location where it is written, the date, and the salutation, are wrapped in a <header> element.

            2. -

          2. If there is only a salutation and no other header content, the <header> element is omitted.

            3. -

          3. The location and date of a letter have the semantic inflection of se:letter.dateline. Dates are in a <time> element with a computer-readable date. -

            <header> - <p epub:type="se:letter.dateline">Blarney Castle, <time datetime="1863-10-11">11th of October, 1863</time></p> -</header>
            -
            4. -

          4. The salutation (for example, “Dear Sir” or “My dearest Jane”) has the semantic inflection of z3998:salutation.

            5. -

          5. The first line of a letter after the salutation is not indented.

            6. -

          6. Salutations that are within the first line of the letter are wrapped in a <span epub:type="z3998:salutation> element (or a <b epub:type="z3998:salutation> element if small-caps are desired). -

            <p><b epub:type="z3998:salutation">Dear Mother</b>, I was so happy to hear from you.</p>
            -
            7. -

          7. The name of the recipient of the letter, when set out other than within a saluation (for example a letter headed “To: John Smith Esquire”), is given the semantic inflection of z3998:recipient. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it is placed within a <footer> element.

            8. -
          -
          -
          -

          Letter footers

          -
            -

          1. Parts of a letter after the body of the letter, for example the signature or postscript, are wrapped in a <footer> element.

            2. -

          2. The footer element has the following CSS: -

            footer{ - margin-top: 1em; - text-align: right; -}
            -
            3. -

          3. The valediction (for example, “Yours Truly” or “With best regards”) has the semantic inflection of z3998:valediction.

            4. -

          4. The sender’s name has semantic inflection of z3998:sender. If the name appears to be a signature to the letter, it has the signature class and the corresponding .signature CSS. -

            .signature{ - font-variant: small-caps; -}
            -
            <footer> - <p class="signature z3998:sender"><abbr class="name">R. A.</abbr> Johnson</p> -</footer>
            -
            <footer> - <p class="z3998:sender"><span class="signature">John Doe</span>, President</p> -</footer>
            -
            5. -

          5. Postscripts have the semantic inflection of z3998:postscript and the following CSS: -

            [epub|type=~"z3998:postscript"]{ - margin-top: 1em; - text-align: left; -}
            -
            6. -
          -
          -
          -

          Examples

          -
          [epub|type~="z3998:letter"] header{ - text-align: right; -} - -footer{ - margin-top: 1em; - text-align: right; -} - -[epub|type~="z3998:salutation"] + p, -[epub|type~="z3998:letter"] header + p{ - text-indent: 0; -} - -[epub|type~="z3998:sender"], -[epub|type~="z3998:recipient"], -[epub|type~="z3998:salutation"]{ - font-variant: small-caps; -} - -[epub|type~="z3998:postscript"]{ - margin-top: 1em; - text-indent: 0; - text-align: left; -} - -.signature{ - font-variant: small-caps; -}
          -
          <blockquote epub:type="z3998:letter"> - <p epub:type="z3998:salutation">Dearest Auntie,</p> - <p>Please may we have some things for a picnic? Gerald will bring them. I would come myself, but I am a little tired. I think I have been growing rather fast.</p> - <footer> - <p epub:type="z3998:valediction">Your loving niece,</p> - <p class="signature" epub:type="z3998:sender">Mabel</p> - <p epub:type="z3998:postscript"><abbr>P.S.</abbr>wj—Lots, please, because some of us are very hungry.</p> - </footer> -</blockquote>
          -
          <blockquote epub:type="z3998:letter"> - <header> - <p epub:type="se:letter.dateline">Gracechurch-street, <time datetime="08-02">August 2</time>.</p> - </header> - <p><span epub:type="z3998:salutation">My dear Brother</span>, At last I am able to send you some tidings of my niece, and such as, upon the whole, I hope will give you satisfaction. Soon after you left me on Saturday, I was fortunate enough to find out in what part of London they were. The particulars, I reserve till we meet. It is enough to know they are discovered, I have seen them both⁠wj—</p> - <p>I shall write again as soon as anything more is determined on.</p> - <footer> - <p epub:type="z3998:valediction">Yours, etc.</p> - <p class="signature" epub:type="z3998:sender">Edward Gardner</p> - </footer> -</blockquote>
          -
          -
          -
          -

          Images

          -
            -

          1. <img> elements have an alt attribute that uses prose to describe the image in detail; this is what screen reading software will read aloud. -

              -

            1. The alt attribute describes the visual image itself in words, which is not the same as writing a caption or describing its place in the book. -

              <img alt="The illustration for chapter 10" src="..." />
              -
              <img alt="Pierre’s fruit-filled dinner" src="..." />
              -
              <img alt="An apple and a pear inside a bowl, resting on a table." src="..." />
              -
              2. -

            2. The alt attribute is one or more complete sentences ended with periods or other appropriate punctuation. It is not composed of sentence fragments or complete sentences without ending punctuation.

              3. -

            3. The alt attribute is not necessarily the same as text in the image’s sibling <figcaption> element, if one is present.

              4. -
            -
            2. -

          2. <img> elements have semantic inflection denoting the type of image. Common values are z3998:illustration or z3998:photograph.

            3. -

          3. <img> element whose image is black-on-white line art (i.e. exactly two colors, not grayscale!) are PNG files with a transparent background. They have the se:image.color-depth.black-on-transparent semantic inflection.

            4. -

          4. <img> elements that are meant to be aligned on the block level or displayed as full-page images are contained in a parent <figure> element, with an optional <figcaption> sibling. -

              -

            1. When contained in a <figure> element, the <img> element does not have an id attribute; instead the <figure> element has the id attribute.

              2. -

            2. An optional <figcaption> element containing a concise context-dependent caption may follow the <img> element within a <figure> element. This caption depends on the surrounding context, and is not necessarily (or even ideally) identical to the <img> element’s alt attribute.

              3. -

            3. All figure elements, regardless of positioning, have this CSS: -

              figure img{ - display: block; - margin: auto; - max-width: 100%; -} - -figure + p{ - text-indent: 0; -} - -figcaption{ - font-size: .75em; - font-style: italic; - margin: 1em; -}
              -
              4. -

            4. <figure> elements that are meant to be displayed as full-page images have the full-page class and this additional CSS: -

              figure.full-page{ - margin: 0; - max-height: 100%; - page-break-before: always; - page-break-after: always; - page-break-inside: avoid; - text-align: center; -}
              -
              5. -

            5. <figure> elements that meant to be aligned block-level with the text have this additional CSS: -

              figure{ - margin: 1em auto; - text-align: center; -}
              -
              6. -
            -
            5. -
          -
          -

          Examples

          -
          /* If the image is meant to be on its own page, use this selector... */ -figure.full-page{ - margin: 0; - max-height: 100%; - page-break-before: always; - page-break-after: always; - page-break-inside: avoid; - text-align: center; -} - -/* If the image is meant to be inline with the text, use this selector... */ -figure{ - margin: 1em auto; - text-align: center; -} - -/* In all cases, also include the below styles */ -figure img{ - display: block; - margin: auto; - max-width: 100%; -} - -figure + p{ - text-indent: 0; -} - -figcaption{ - font-size: .75em; - font-style: italic; - margin: 1em; -}
          -
          <p>...</p> -<figure id="illustration-10"> - <img alt="An apple and a pear inside a bowl, resting on a table." src="../images/illustration-10.jpg" epub:type="z3998:photograph"/> - <figcaption>The Monk’s Repast</figcaption> -</figure>
          -
          <p>...</p> -<figure class="full-page" id="image-11"> - <img alt="A massive whale breaching the water, with a sailor floating in the water directly within the whale’s mouth." src="../images/illustration-11.jpg" epub:type="z3998:illustration"/> - <figcaption>The Whale eats Sailor Jim.</figcaption> -</figure>
          -
          <p>He saw strange alien text that looked like this: <img alt="A line of alien heiroglyphs." src="../images/alien-text.svg" epub:type="z3998:illustration se:color-depth.black-on-transparent" />. There was nothing else amongst the ruins.</p>
          -
          -
          -
          -

          List of Illustrations (the LoI)

          -

          If an ebook has any illustrations that are major structural components of the work (even just one!), then the ebook includes an loi.xhtml file at the end of the ebook. This file lists the illustrations in the ebook, along with a short caption or description.

          -
            -

          1. The LoI is an XHTML file located in ./src/epub/text/loi.xhtml.

            2. -

          2. The LoI file has the backmatter semantic inflection.

            3. -

          3. The LoI only contains links to images that are major structural components of the work. -

              -

            1. An illustration is a major structural component if, for example: it is an illustration of events in the book, like a full-page drawing or end-of-chapter decoration; it is essential to the plot, like a diagram of a murder scene or a map; or it is a component of the text, like photographs in a documentary narrative.

              2. -

            2. An illustration is not a major structural components if, for example: it is a drawing used to represent a person’s signature, like an X mark; it is an inline drawing representing text in alien languages; it is a drawing used as a layout element to illustrate forms, tables, or diagrams.

              3. -
            -
            4. -

          4. The LoI file contains a single <section id="loi" epub:type="loi"> element, which in turn contains an <h2 epub:type="title">List of Illustrations</h2> element, followed by a <nav epub:type="loi"> element containing an <ol> element, which in turn contains list items representing the images.

            5. -

          5. If an image listed in the LoI has a <figcaption> element, then that caption is used in the anchor text for that LoI entry. If not, the image’s alt attribute is used. If the <figcaption> element is too long for a concise LoI entry, the alt attribute is used instead.

            6. -

          6. Links to the images go directly to the image’s corresponding id hashes, not just the top of the containing file.

            7. -
          -
          -

          Examples

          -
          <?xml version="1.0" encoding="UTF-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: http://standardebooks.org/vocab/1.0" xml:lang="en-GB"> - <head> - <title>List of Illustrations</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> - </head> - <body epub:type="backmatter"> - <section id="loi" epub:type="loi"> - <nav epub:type="loi"> - <h2 epub:type="title">List of Illustrations</h2> - <ol> - <li> - <a href="../text/preface.xhtml#the-edge-of-the-world">The Edge of the World</a> - </li> - ... - </ol> - </nav> - </section> - </body> -</html>
          -
          -
          -
          -

          Endnotes

          -
            -

          1. Ebooks do not have footnotes, only endnotes. Footnotes are instead converted to endnotes.

            2. -

          2. “Ibid.” is a Latinism commonly used in endnotes to indicate that the source for a quotation or reference is the same as the last-mentioned source. -

            When the last-mentioned source is in the previous endnote, Ibid. is replaced by the full reference; otherwise Ibid. is left as-is. Since ebooks use popup endnotes, “Ibid.” becomes meaningless without context.

            -
            3. -
          -
          -

          Noterefs

          -

          The noteref is the superscripted number in the body text that links to the endnote at the end of the book.

          -
            -

          1. Endnotes are referenced in the text by an <a> tag with the semantic inflection noteref. -

              -

            1. Noterefs point directly to the corresponding endnote <li> element in the endnotes file.

              2. -

            2. Noterefs have an id attribute like noteref-n, where n is identical to the endnote number.

              3. -

            3. The text of the noteref is the endnote number.

              4. -
            -
            2. -

          2. If located at the end of a sentence, noterefs are placed after ending punctuation.

            3. -

          3. If the endnote references an entire sentence in quotation marks, or the last word in a sentence in quotation marks, then the noteref is placed outside the quotation marks.

            4. -
          -
          -
          -

          The endnotes file

          -
            -

          1. Endnotes are in an XHTML file located in ./src/epub/text/endnotes.xhtml.

            2. -

          2. The endnotes file has the backmatter semantic inflection.

            3. -

          3. The endnotes file contains a single <section id="endnotes" epub:type="endnotes"> element, which in turn contains an <h2 epub:type="title">Endnotes</h2> element, followed by an <ol> element containing list items representing the endnotes.

            4. -

          4. Each endnote’s id attribute is in sequential ascending order.

            5. -
          -
          -
          -

          Individual endnotes

          -
            -

          1. An endnote is an <li id="note-n" epub:type="endnote"> element containing one or more block-level text elements and one backlink element.

            2. -

          2. Each endnote’s contains a backlink, which has the semantic inflection backlink, contains the text ↩, and has the href attribute pointing to the corresponding noteref hash. -

              -

            1. In endnotes where the last block-level element is a <p> element, the backlink goes at the end of the <p> element, preceded by exactly one space.

              2. -

            2. In endnotes where the last block-level element is verse, quotation, or otherwise not plain prose text, the backlink goes in its own <p> element following the last block-level element in the endnote.

              3. -
            -
            3. -

          3. Endnotes with ending citations have those citations are wrapped in a <cite> element, including any em-dashes. A space follows the <cite> element, before the backlink.

            4. -
          -
          -
          -

          Examples

          -
          <p>... a continent that was not rent asunder by volcanic forces as was that legendary one of Atlantis in the Eastern Ocean.<a href="endnotes.xhtml#note-1" id="noteref-1" epub:type="noteref">1</a> My work in Java, in Papua, ...</p>
          -
          <?xml version="1.0" encoding="UTF-8"?> -<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: http://standardebooks.org/vocab/1.0" xml:lang="en-GB"> - <head> - <title>Endnotes</title> - <link href="../css/core.css" rel="stylesheet" type="text/css"/> - <link href="../css/local.css" rel="stylesheet" type="text/css"/> - </head> - <body epub:type="backmatter"> - <section id="endnotes" epub:type="endnotes"> - <h2 epub:type="title">Endnotes</h2> - <ol> - <li id="note-1" epub:type="endnote"> - <p>For more detailed observations on these points refer to <abbr class="name">G.</abbr> Volkens, “Uber die Karolinen Insel Yap.” <cite>—<abbr class="name eoc">W. T. G.</abbr></cite> <a href="chapter-2.xhtml#noteref-1" epub:type="backlink">↩</a></p> - </li> - </ol> - <ol> - <li id="note-2" epub:type="endnote"> - <blockquote epub:type="z3998:verse"> - <p> - <span>“Who never ceases still to strive,</span> - <br/> - <span>’Tis him we can deliver.”</span> - </p> - </blockquote> - <p> - <a href="chapter-4.xhtml#noteref-2" epub:type="backlink">↩</a> - </p> - </li> - </ol> - </section> - </body> -</html>
          -
          -
          -
          -
          -
          - diff --git a/www/manual/1.0.0/6-standard-ebooks-section-patterns.php b/www/manual/1.0.0/6-standard-ebooks-section-patterns.php index 300b0663..229fc5de 100644 --- a/www/manual/1.0.0/6-standard-ebooks-section-patterns.php +++ b/www/manual/1.0.0/6-standard-ebooks-section-patterns.php @@ -1,7 +1,7 @@ '6. Standard Ebooks Section Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          +
          @@ -15,9 +15,9 @@ require_once('Core.php');

          • Start with an empty string.

          • Append the title of the work, without any subtitles.

            • -

          • Append , by, then the author. If there are two authors, separate them with :html:` and`. If there are three or more authors, each one is separated by ,, and the final one is preceded by , and.

            • -

          • If there is a translator, append . Translated by, then the translator name. Multiple translators are handled in the same manner as multiple authors.

            • -

          • If there is an illustrator, append . Illustrated by, then the illustrator name. Multiple illustrators are handled in the same manner as mutliple authors.

            • +

          • Append , by, then the author. If there are two authors, separate them with and. If there are three or more authors, each one is separated by ,, and the final one is preceded by , and.

            • +

          • If there is a translator, append . Translated by, then the translator name. Multiple translators are handled in the same manner as multiple authors.

            • +

          • If there is an illustrator, append . Illustrated by, then the illustrator name. Multiple illustrators are handled in the same manner as mutliple authors.

        3. While the title string may contain periods, it never ends in a period.

          4. @@ -26,11 +26,11 @@ require_once('Core.php');

          The table of contents

          The table of contents (the ToC) is not viewable as a page in the ebook’s reading order. Instead, the reader’s ereading system displays the ToC as part of its reading interface.

          -

          These rules outline how to structure the ToC. Typically, the se print-toc tool constructs the ToC according to these rules, without further changes being necessary.

          +

          These rules outline how to structure the ToC. Typically, the se print-toc tool constructs the ToC according to these rules, without further changes being necessary.

          The <nav> element

            -

          1. The first child of the Toc’s <body> tag is a <nav> element with the semantic inflection toc.

            2. +

          2. The first child of the ToC’s <body> element is a <nav> element with the semantic inflection toc.

          3. The first child of the <nav> element is a <h2 epub:type="title">Table of Contents</h2> element.

          4. The second child of the <nav> element is an <ol> element representing the items in the Table of Contents.

          @@ -74,7 +74,7 @@ require_once('Core.php');

          <li> descendents

            -

          1. Each <li> contains an <a> tag pointing to a file or hash, and optionally also contains an <ol> element representing a nested series of ToC items.

            2. +

          2. Each <li> contains an <a> element pointing to a file or hash, and optionally also contains an <ol> element representing a nested series of ToC items.

          3. If an <li> element contains a nested <ol> element, that <li>’s first child is an <a> element that points to the beginning of that section.

            <li> <a href="text/halftitle.xhtml">Sybil</a> @@ -86,7 +86,7 @@ require_once('Core.php'); <a href="text/chapter-1-1.xhtml" epub:type="z3998:roman">I</a> </li>
            4. -

          4. Roman numerals in the ToC have the semantic inflection of z3998:roman. A <span> element is included if the entire contents of the <a> element are not a Roman numeral. +

          5. Roman numerals in the ToC have the semantic inflection of z3998:roman. A <span> element is included if the entire contents of the <a> element are not a Roman numeral.

            <li> <a href="text/chapter-1.xhtml">I</a> </li>
            @@ -108,16 +108,16 @@ require_once('Core.php');

            <a> descendents

              -

            1. Chapters without titles are represented by their Roman ordinal, without the word Chapter. +

            2. Chapters without titles are represented by their Roman ordinal, without the word Chapter.

              <a epub:type="title z3998:roman">XI</a>

            3. Chapters with titles are represented by their Roman ordinal, followed by a colon and a space, followed by the chapter title.

              <a href="text/chapter-3.xhtml"><span epub:type="z3998:roman">III</span>: The Moon Rock</a>
              4. -

            4. Chapters with unique identifiers (i.e. not Chapter, but something unique to the style of the book, like Book or Stave), include that unique identifier in the <a> element. +

            5. Chapters with unique identifiers (i.e. not Chapter, but something unique to the style of the book, like Book or Stave), include that unique identifier in the <a> element.

              <a href="text/chapter-1.xhtml">Stave <span epub:type="z3998:roman">I</span>: Marley’s Ghost</a>
              6. -

            6. High-level sections (like parts or divisions) without titles are represented by their identifier (like Book or Part), followed by their Roman ordinal. +

            7. High-level sections (like parts or divisions) without titles are represented by their identifier (like Book or Part), followed by their Roman ordinal.

              <a href="text/book-1.xhtml">Book <span epub:type="z3998:roman">I</span></a>

            8. High-level sections (like parts or divisions) with titles include the title. @@ -143,7 +143,7 @@ require_once('Core.php');

            The landmarks <nav> element

            -

            After the first <nav> element, there is a second <nav> element with the semantic inflection of landmarks.

            +

            After the first <nav> element, there is a second <nav> element with the semantic inflection of landmarks.

            1. The first child is an <h2 epub:type="title">Landmarks</h2> element.

            2. The second child is an <ol> element listing the major structural divisions of the book.

              3. @@ -152,7 +152,7 @@ require_once('Core.php');

              <li> descendents

              Each <li> element contains a link to one of the major structural divisions of the book. In general, a structural division is any section of the book that is not part of the body text, plus one element representing the beginning of the body text.

                -

              1. Each <li> element has the computed semantic inflection of top-level <section> element in the file. The computed semantic inflection includes inherited semantic inflection from the <body> tag. +

              2. Each <li> element has the computed semantic inflection of top-level <section> element in the file. The computed semantic inflection includes inherited semantic inflection from the <body> element.

                <li> <a href="text/preface.xhtml" epub:type="frontmatter preface">Preface</a> </li>
                @@ -176,9 +176,9 @@ require_once('Core.php');

                The titlepage

                1. The Standard Ebooks titlepage is the first item in the ebook’s content flow. Standard Ebooks do not have a separate cover page file within the content flow.

                  2. -

                2. The title page has a <title> element with the value Titlepage.

                  3. +

                3. The title page has a <title> element with the value Titlepage.

                4. The titlepage contains one <section id="titlepage" epub:type="titlepage"> element which in turn contains one <img src="../images/titlepage.svg"> element.

                  5. -

                5. The <img> element has its alt attribute set to The titlepage for the Standard Ebooks edition of 6. Standard Ebooks Section Patterns - The Standard Ebooks Manual_STRING, where 6. Standard Ebooks Section Patterns - The Standard Ebooks Manual_STRING is the Standard Ebooks title string for the ebook.

                  6. +

                6. The <img> element has its alt attribute set to The titlepage for the Standard Ebooks edition of TITLE_STRING, where TITLE_STRING is the Standard Ebooks title string for the ebook.

                7. A complete titlepage looks like the following template:

                  <?xml version="1.0" encoding="utf-8"?> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" epub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-US"> @@ -189,7 +189,7 @@ require_once('Core.php'); </head> <body epub:type="frontmatter"> <section id="titlepage" epub:type="titlepage"> - <img alt="The titlepage for the Standard Ebooks edition of 6. Standard Ebooks Section Patterns - The Standard Ebooks Manual_STRING" src="../images/titlepage.svg"/> + <img alt="The titlepage for the Standard Ebooks edition of TITLE_STRING" src="../images/titlepage.svg"/> </section> </body> </html>
                  @@ -200,7 +200,7 @@ require_once('Core.php');

                  The imprint

                  1. The Standard Ebooks imprint is the second item in the ebook’s content flow.

                    2. -

                  2. The imprint has a <title> element with the value Imprint.

                    3. +

                  3. The imprint has a <title> element with the value Imprint.

                  4. The imprint contains one <section id="imprint" epub:type="imprint"> element, which in turn contains one <header> element with the Standard Ebooks logo, followed by a series of <p> elements containing the imprint’s content.

                  5. The second <p> element contains links to the online transcription that the ebook is based off of, followed by a link to the online page scans used to proof against.

                      @@ -240,7 +240,7 @@ require_once('Core.php');

                      1. A half title page is included when there is front matter of any type in an ebook besides the titlepage and imprint.

                      2. The half title page located after the last item of front matter, before the body matter.

                        3. -

                      3. The half title page has a <title> element with the value Half Title.

                        4. +

                      4. The half title page has a <title> element with the value Half Title.

                      5. The half title page contains one <section id="halftitlepage" epub:type="halftitlepage"> element, which in turn contains one <h1 epub:type="fulltitle"> element containing the full title of the ebook, including subtitles. The half title page is the only place where an <h1> element may appear in a Standard Ebook.

                      6. Formatting for the <h1> element follows patterns in 7.2.6.6 and 7.2.6.7.

                      7. A complete half title page looks like the following template: @@ -267,7 +267,7 @@ require_once('Core.php');

                        The colophon

                        1. The colophon is the second-to-last item in the ebook’s content flow.

                          2. -

                        2. The colophon has a <title> element with the value Colophon.

                          3. +

                        3. The colophon has a <title> element with the value Colophon.

                        4. The half title page contains one <section id="colophon" epub:type="colophon"> element, which in turn contains one <header> element with the Standard Ebooks logo, followed by a series of <p> elements containing the colophon’s content.

                        @@ -275,11 +275,11 @@ require_once('Core.php');

                        1. Within <p> elements, proper names except for the book title and cover art title are wrapped in an <a> element pointing to the name’s Wikipedia page, or to a link representing the name, like a personal homepage.

                        2. If a name does not have a Wikipedia entry, the name is wrapped in <b class="name">.

                          3. -

                        3. Two names are separated by and. Three or more names are separated by commas, with the final name separated by , and. (I.e., with an Oxford comma.) +

                        4. Two names are separated by and. Three or more names are separated by commas, with the final name separated by , and. (I.e., with an Oxford comma.)

                          <b class="name">Fritz Ohrenschall</b>, <b class="name">Sania Ali Mirza</b> and <a href="https://www.pgdp.net">The Online Distributed Proofreading Team</a>
                          <b class="name">Fritz Ohrenschall</b>, <b class="name">Sania Ali Mirza</b>, and <a href="https://www.pgdp.net">The Online Distributed Proofreading Team</a>
                          5. -

                        5. Any anonymous contributor is listed as An Anonymous Volunteer.

                          6. +

                        6. Any anonymous contributor is listed as An Anonymous Volunteer.

                        @@ -297,7 +297,7 @@ was published in 1919 by<br<br/> <a href="https://en.wikipedia.org/wiki/Abraham_Merritt">Abraham Merritt</a>.</p>
          -

        1. If the book has a translator, a translator block follows the author name in the same <p> tag. The translator block follows this formula: It was translated from LANGUAGE in YEAR by <a href="TRANSLATOR_WIKI_URL">TRANSLATOR</a>.. +

        2. If the book has a translator, a translator block follows the author name in the same <p> element. The translator block follows this formula: It was translated from LANGUAGE in YEAR by <a href="TRANSLATOR_WIKI_URL">TRANSLATOR</a>..

          <p><i epub:type="se:name.publication.book">Eugene Onegin</i><br/> was published in 1837 by<br/> <a href="https://en.wikipedia.org/wiki/Alexander_Pushkin">Alexander Pushkin</a>.<br/> @@ -394,7 +394,7 @@ You can check for updates to this ebook, view its revision history, or download

          Where traditionally published ebooks may contain a copyright page at the front of the ebook, Standard Ebooks contain an Uncopyright page at the end of the ebook.

          1. The Uncopyright page is the last item in the ebook’s content flow.

            2. -

          2. The Uncopyright page follows the template created by se create-draft exactly.

            3. +

          3. The Uncopyright page follows the template created by se create-draft exactly.

      diff --git a/www/manual/1.0.0/7-high-level-structural-patterns.php b/www/manual/1.0.0/7-high-level-structural-patterns.php index 9c7d1d3e..721e4d01 100644 --- a/www/manual/1.0.0/7-high-level-structural-patterns.php +++ b/www/manual/1.0.0/7-high-level-structural-patterns.php @@ -1,7 +1,7 @@ '7. High Level Structural Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
      +
      @@ -19,7 +19,7 @@ require_once('Core.php');

      “Recomposability” is the concept of generating a single structurally-correct HTML5 file out of an epub file. All Standard Ebooks are recomposable.

      1. XHTML files that contain <section> or <articles> elements that are semantic children of <section> or <articles> elements in other files, are wrapped in stubs of all parent <section> or <articles> elements, up to the root.

        2. -

      2. Each such included parent element has the identical id and epub:type attributes of its real counterpart.

        3. +

      3. Each such included parent element has the identical id and epub:type attributes of its real counterpart.

      Examples

      @@ -353,7 +353,7 @@ require_once('Core.php'); display: none; }
      8. -

    8. Indented <span> lines have the i1 class. Do not use nbsp for indentation. Indenting to different levels is done by incrementing the class to i2, i3, and so on, and including the appropriate CSS. +

    9. Indented <span> lines have the i1 class. Do not use nbsp for indentation. Indenting to different levels is done by incrementing the class to i2, i3, and so on, and including the appropriate CSS.

      p span.i1{ text-indent: -1em; padding-left: 2em; @@ -372,7 +372,7 @@ require_once('Core.php'); </p> </blockquote>
      10. -

    10. The parent element of poetry, verse, or song, has the semantic inflection of z3998:poem, z3998:verse, z3998:song, or z3998:hymn.

      11. +

    11. The parent element of poetry, verse, or song, has the semantic inflection of z3998:poem, z3998:verse, z3998:song, or z3998:hymn.

    12. If a poem is quoted and has one or more lines removed, the removed lines are represented with a vertical ellipses (⋮ or U+22EE) in a <span class="elision"> element styled with this CSS:

      span.elision{ margin: .5em; @@ -402,7 +402,7 @@ require_once('Core.php');

    Examples

    -

    Note that below we include CSS for the i2 class, even though it’s not used in the example. It’s included to demonstrate how to adjust the CSS for indentation levels after the first.

    +

    Note that below we include CSS for the .i2 class, even though it’s not used in the example. It’s included to demonstrate how to adjust the CSS for indentation levels after the first.

    [epub|type~="z3998:poem"] p{ text-align: left; text-indent: 0; @@ -525,7 +525,7 @@ require_once('Core.php');

    Dialog rows

      -

    1. The first child of a row of dialog is a <td> element with the semantic inflection of z3998:persona.

      2. +

    2. The first child of a row of dialog is a <td> element with the semantic inflection of z3998:persona.

    3. The second child of a row of dialog is a <td> element containing the actual dialog. Elements that contain only one line of dialog do not have a block-level child (like <p>).

      <tr> <td epub:type="z3998:persona">Algernon</td> @@ -536,7 +536,7 @@ require_once('Core.php'); <td>I didn’t think it polite to listen, sir.</td> </tr>
      4. -

    4. When several personas speak at once, or a group of personas ("The Actors") speaks at once, the containing <tr> element has the together class, and the first <td> child has a rowspan attribute corresponding to the number of lines spoken together. +

    5. When several personas speak at once, or a group of personas ("The Actors") speaks at once, the containing <tr> element has the together class, and the first <td> child has a rowspan attribute corresponding to the number of lines spoken together.

      tr.together td{ padding: 0 .5em 0 0; vertical-align: middle; @@ -596,7 +596,7 @@ require_once('Core.php');

      Works that are complete plays

        -

      1. The top-level element (usually <body>) has the z3998:drama semantic inflection.

        2. +

      2. The top-level element (usually <body>) has the z3998:drama semantic inflection.

      3. Acts are <section> elements containing at least one <table> for dialog, and optionally containing an act title and other top-level stage direction.

      4. Introductory or high-level stage direction is presented using <p> elements outside of the dialog table.

        <body epub:type="bodymatter z3998:fiction z3998:drama"> @@ -643,26 +643,26 @@ require_once('Core.php');

      Letters

      -

      Letters require particular attention to styling and semantic tagging. Letters may not exactly match the formatting in the source scans, but they are in visual sympathy with the source.

      +

      Letters require particular attention to styling and semantic inflection. Letters may not exactly match the formatting in the source scans, but they are in visual sympathy with the source.

        -

      1. Letters are wrapped in a <blockquote> element with the appropriate semantic inflection, usually z3998:letter.

        2. +

      2. Letters are wrapped in a <blockquote> element with the appropriate semantic inflection, usually z3998:letter.

      Letter headers

      1. Parts of a letter prior to the body of the letter, for example the location where it is written, the date, and the salutation, are wrapped in a <header> element.

      2. If there is only a salutation and no other header content, the <header> element is omitted.

        3. -

      3. The location and date of a letter have the semantic inflection of se:letter.dateline. Dates are in a <time> element with a computer-readable date. +

      4. The location and date of a letter have the semantic inflection of se:letter.dateline. Dates are in a <time> element with a computer-readable date.

        <header> <p epub:type="se:letter.dateline">Blarney Castle, <time datetime="1863-10-11">11th of October, 1863</time></p> </header>
        5. -

      5. The salutation (for example, “Dear Sir” or “My dearest Jane”) has the semantic inflection of z3998:salutation.

        6. +

      6. The salutation (for example, “Dear Sir” or “My dearest Jane”) has the semantic inflection of z3998:salutation.

      7. The first line of a letter after the salutation is not indented.

      8. Salutations that are within the first line of the letter are wrapped in a <span epub:type="z3998:salutation> element (or a <b epub:type="z3998:salutation> element if small-caps are desired).

        <p><b epub:type="z3998:salutation">Dear Mother</b>, I was so happy to hear from you.</p>
        9. -

      9. The name of the recipient of the letter, when set out other than within a saluation (for example a letter headed “To: John Smith Esquire”), is given the semantic inflection of z3998:recipient. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it is placed within a <footer> element.

        10. +

      10. The name of the recipient of the letter, when set out other than within a saluation (for example a letter headed “To: John Smith Esquire”), is given the semantic inflection of z3998:recipient. Sometimes this may occur at the end of a letter, particularly for more formal communications, in which case it is placed within a <footer> element.

      @@ -675,8 +675,8 @@ require_once('Core.php'); text-align: right; }
      6. -

    6. The valediction (for example, “Yours Truly” or “With best regards”) has the semantic inflection of z3998:valediction.

      7. -

    7. The sender’s name has semantic inflection of z3998:sender. If the name appears to be a signature to the letter, it has the signature class and the corresponding .signature CSS. +

    8. The valediction (for example, “Yours Truly” or “With best regards”) has the semantic inflection of z3998:valediction.

      9. +

    9. The sender’s name has semantic inflection of z3998:sender. If the name appears to be a signature to the letter, it has the signature class and the corresponding .signature CSS.

      .signature{ font-variant: small-caps; }
      @@ -687,8 +687,8 @@ require_once('Core.php'); <p class="z3998:sender"><span class="signature">John Doe</span>, President</p> </footer>
    -

  • Postscripts have the semantic inflection of z3998:postscript and the following CSS: -

    [epub|type=~"z3998:postscript"]{ +

  • Postscripts have the semantic inflection of z3998:postscript and the following CSS: +

    [epub|type~="z3998:postscript"]{ margin-top: 1em; text-align: left; }
    @@ -751,23 +751,23 @@ require_once('Core.php');

    Images

      -

    1. <img> elements have an alt attribute that uses prose to describe the image in detail; this is what screen reading software will read aloud. +

    2. <img> elements have an alt attribute that uses prose to describe the image in detail; this is what screen reading software will read aloud.

        -

      1. The alt attribute describes the visual image itself in words, which is not the same as writing a caption or describing its place in the book. +

      2. The alt attribute describes the visual image itself in words, which is not the same as writing a caption or describing its place in the book.

        <img alt="The illustration for chapter 10" src="..." />
        <img alt="Pierre’s fruit-filled dinner" src="..." />
        <img alt="An apple and a pear inside a bowl, resting on a table." src="..." />
        3. -

      3. The alt attribute is one or more complete sentences ended with periods or other appropriate punctuation. It is not composed of sentence fragments or complete sentences without ending punctuation.

        4. -

      4. The alt attribute is not necessarily the same as text in the image’s sibling <figcaption> element, if one is present.

        5. +

      5. The alt attribute is one or more complete sentences ended with periods or other appropriate punctuation. It is not composed of sentence fragments or complete sentences without ending punctuation.

        6. +

      6. The alt attribute is not necessarily the same as text in the image’s sibling <figcaption> element, if one is present.

      3. -

    3. <img> elements have semantic inflection denoting the type of image. Common values are z3998:illustration or z3998:photograph.

      4. -

    4. <img> element whose image is black-on-white line art (i.e. exactly two colors, not grayscale!) are PNG files with a transparent background. They have the se:image.color-depth.black-on-transparent semantic inflection.

      5. +

    5. <img> elements have semantic inflection denoting the type of image. Common values are z3998:illustration or z3998:photograph.

      6. +

    6. <img> element whose image is black-on-white line art (i.e. exactly two colors, not grayscale!) are PNG files with a transparent background. They have the se:image.color-depth.black-on-transparent semantic inflection.

    7. <img> elements that are meant to be aligned on the block level or displayed as full-page images are contained in a parent <figure> element, with an optional <figcaption> sibling.

        -

      1. When contained in a <figure> element, the <img> element does not have an id attribute; instead the <figure> element has the id attribute.

        2. -

      2. An optional <figcaption> element containing a concise context-dependent caption may follow the <img> element within a <figure> element. This caption depends on the surrounding context, and is not necessarily (or even ideally) identical to the <img> element’s alt attribute.

        3. +

      3. When contained in a <figure> element, the <img> element does not have an id attribute; instead the <figure> element has the id attribute.

        4. +

      4. An optional <figcaption> element containing a concise context-dependent caption may follow the <img> element within a <figure> element. This caption depends on the surrounding context, and is not necessarily (or even ideally) identical to the <img> element’s alt attribute.

      5. All figure elements, regardless of positioning, have this CSS:

        figure img{ display: block; @@ -785,7 +785,7 @@ require_once('Core.php'); margin: 1em; }
        6. -

      6. <figure> elements that are meant to be displayed as full-page images have the full-page class and this additional CSS: +

      7. <figure> elements that are meant to be displayed as full-page images have the full-page class and this additional CSS:

        figure.full-page{ margin: 0; max-height: 100%; @@ -856,7 +856,7 @@ require_once('Core.php');

        If an ebook has any illustrations that are major structural components of the work (even just one!), then the ebook includes an loi.xhtml file at the end of the ebook. This file lists the illustrations in the ebook, along with a short caption or description.

        1. The LoI is an XHTML file located in ./src/epub/text/loi.xhtml.

          2. -

        2. The LoI file has the backmatter semantic inflection.

          3. +

        3. The LoI file has the backmatter semantic inflection.

        4. The LoI only contains links to images that are major structural components of the work.

          1. An illustration is a major structural component if, for example: it is an illustration of events in the book, like a full-page drawing or end-of-chapter decoration; it is essential to the plot, like a diagram of a murder scene or a map; or it is a component of the text, like photographs in a documentary narrative.

            2. @@ -864,8 +864,8 @@ require_once('Core.php');

        5. The LoI file contains a single <section id="loi" epub:type="loi"> element, which in turn contains an <h2 epub:type="title">List of Illustrations</h2> element, followed by a <nav epub:type="loi"> element containing an <ol> element, which in turn contains list items representing the images.

          6. -

        6. If an image listed in the LoI has a <figcaption> element, then that caption is used in the anchor text for that LoI entry. If not, the image’s alt attribute is used. If the <figcaption> element is too long for a concise LoI entry, the alt attribute is used instead.

          7. -

        7. Links to the images go directly to the image’s corresponding id hashes, not just the top of the containing file.

          8. +

        8. If an image listed in the LoI has a <figcaption> element, then that caption is used in the anchor text for that LoI entry. If not, the image’s alt attribute is used. If the <figcaption> element is too long for a concise LoI entry, the alt attribute is used instead.

          9. +

        9. Links to the images go directly to the image’s corresponding id hashes, not just the top of the containing file.

        Examples

        @@ -904,10 +904,10 @@ require_once('Core.php');

        Noterefs

        The noteref is the superscripted number in the body text that links to the endnote at the end of the book.

          -

        1. Endnotes are referenced in the text by an <a> tag with the semantic inflection noteref. +

        2. Endnotes are referenced in the text by an <a> element with the semantic inflection noteref.

          1. Noterefs point directly to the corresponding endnote <li> element in the endnotes file.

            2. -

          2. Noterefs have an id attribute like noteref-n, where n is identical to the endnote number.

            3. +

          3. Noterefs have an id attribute like noteref-n, where n is identical to the endnote number.

          4. The text of the noteref is the endnote number.

          3. @@ -919,16 +919,16 @@ require_once('Core.php');

          The endnotes file

          1. Endnotes are in an XHTML file located in ./src/epub/text/endnotes.xhtml.

            2. -

          2. The endnotes file has the backmatter semantic inflection.

            3. +

          3. The endnotes file has the backmatter semantic inflection.

          4. The endnotes file contains a single <section id="endnotes" epub:type="endnotes"> element, which in turn contains an <h2 epub:type="title">Endnotes</h2> element, followed by an <ol> element containing list items representing the endnotes.

            5. -

          5. Each endnote’s id attribute is in sequential ascending order.

            6. +

          6. Each endnote’s id attribute is in sequential ascending order.

        Individual endnotes

        1. An endnote is an <li id="note-n" epub:type="endnote"> element containing one or more block-level text elements and one backlink element.

          2. -

        2. Each endnote’s contains a backlink, which has the semantic inflection backlink, contains the text ↩, and has the href attribute pointing to the corresponding noteref hash. +

        3. Each endnote’s contains a backlink, which has the semantic inflection backlink, contains the text ↩, and has the href attribute pointing to the corresponding noteref hash.

          1. In endnotes where the last block-level element is a <p> element, the backlink goes at the end of the <p> element, preceded by exactly one space.

          2. In endnotes where the last block-level element is verse, quotation, or otherwise not plain prose text, the backlink goes in its own <p> element following the last block-level element in the endnote.

            3. diff --git a/www/manual/1.0.0/7-table-of-contents-patterns.php b/www/manual/1.0.0/7-table-of-contents-patterns.php deleted file mode 100644 index 8ae9bd49..00000000 --- a/www/manual/1.0.0/7-table-of-contents-patterns.php +++ /dev/null @@ -1,158 +0,0 @@ - '7. Table of Contents Patterns - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
            -
            - -
            -

            Table of Contents Patterns

            -

            The table of contents (the ToC) is not viewable as a page in the ebook’s reading order. Instead, the reader’s ereading system displays the ToC as part of its reading interface.

            -

            These rules outline how to structure the ToC. Typically, the output of se print-toc constructs ToCs according to these rules, without further changes being necessary.

            -
            -

            The ToC <nav> element

            -
              -

            1. The first child of the Toc’s <body> tag is a <nav> element with the semantic inflection toc.

              2. -

            2. The first child of the <nav> element is a <h2 epub:type="title">Table of Contents</h2> element.

              3. -

            3. The second child of the <nav> element is an <ol> element representing the items in the Table of Contents.

              4. -
            -
            -

            The top-level <ol> element

            -

            The <nav> element’s top-level <ol> element contains a list of items in the Table of Contents.

            -
              -

            1. The first child is a link to the titlepage. -

              <li> - <a href="text/titlepage.xhtml">Titlepage</a> -</li>
              -
              2. -

            2. The second child is a link to the imprint. -

              <li> - <a href="text/imprint.xhtml">Imprint</a> -</li>
              -
              3. -

            3. The second-to-last child is a link to the colophon. -

              <li> - <a href="text/colophon.xhtml">Colophon</a> -</li>
              -
              4. -

            4. The second-to-last child is a link to the Uncopyright. -

              <li> - <a href="text/uncopyright.xhtml">Uncopyright</a> -</li>
              -
              5. -

            5. In books with half title pages, the half title page is listed in the ToC and the next sibling is an <ol> element containing the book’s contents. -

              <li> - <a href="text/halftitle.xhtml">The Moon Pool</a> - <ol> - <li> - <a href="text/chapter-1.xhtml"><span epub:type="z3998:roman">I</span>: The Thing on the Moon Path</a> - </li> - <li> - <a href="text/chapter-2.xhtml"><span epub:type="z3998:roman">II</span>: “Dead! All Dead!”</a> - </li>
              -
              6. -
            -
            -
            -

            <li> descendents

            -
              -

            1. Each <li> contains an <a> tag pointing to a file or hash, and optionally also contains an <ol> element representing a nested series of ToC items.

              2. -

            2. If an <li> element contains a nested <ol> element, that <li>’s first child is an <a> element that points to the beginning of that section. -

              <li> - <a href="text/halftitle.xhtml">Sybil</a> - <ol> - <li> - <a href="text/book-1.xhtml">Book <span epub:type="z3998:roman">I</span></a> - <ol> - <li> - <a href="text/chapter-1-1.xhtml" epub:type="z3998:roman">I</a> - </li>
              -
              3. -

            3. Roman numerals in the ToC have the semantic inflection of z3998:roman. A <span> element is included if the entire contents of the <a> element are not a Roman numeral. -

              <li> - <a href="text/chapter-1.xhtml">I</a> -</li>
              -
              <li> - <a href="text/chapter-1.xhtml"><span epub:type="z3998:roman">I</span></a> -</li>
              -
              <li> - <a href="text/chapter-1.xhtml" epub:type="z3998:roman">I</a> -</li>
              -
              <li> - <a href="text/book-1.xhtml">Book <span epub:type="z3998:roman">I</span></a> - <ol> - ... - </ol> -</li>
              -
              4. -
            -
            -
            -

            <a> descendents

            -
              -

            1. Chapters without titles are represented by their Roman ordinal, without the word Chapter. -

              <a epub:type="title z3998:roman">XI</a>
              -
              2. -

            2. Chapters with titles are represented by their Roman ordinal, followed by a colon and a space, followed by the chapter title. -

              <a href="text/chapter-3.xhtml"><span epub:type="z3998:roman">III</span>: The Moon Rock</a>
              -
              3. -

            3. Chapters with unique identifiers (i.e. not Chapter, but something unique to the style of the book, like Book or Stave), include that unique identifier in the <a> element. -

              <a href="text/chapter-1.xhtml">Stave <span epub:type="z3998:roman">I</span>: Marley’s Ghost</a>
              -
              4. -

            4. High-level sections (like parts or divisions) without titles are represented by their identifier (like Book or Part), followed by their Roman ordinal. -

              <a href="text/book-1.xhtml">Book <span epub:type="z3998:roman">I</span></a>
              -
              5. -

            5. High-level sections (like parts or divisions) with titles include the title. -

              <a href="text/book-10.xhtml">Book <span epub:type="z3998:roman">X</span>: The Boys</a>
              -
              6. -

            6. Sections that are not chapters do not include their subtitles in the ToC. -

              <a href="text/epilogue.xhtml">Epilogue: A Morning Call</a>
              -
              <a href="text/epilogue.xhtml">Epilogue</a>
              -
              7. -

            7. High-level sections (like parts or divisions) with titles include the title. -

              <a href="text/book-10.xhtml">Book <span epub:type="z3998:roman">X</span>: The Boys</a>
              -
              8. -

            8. Entries for half title pages do not include the subtitle. -

              <li> - <a href="text/halftitle.xhtml">His Last Bow</a> - <ol> - ... - </ol> -</li>
              -
              9. -
            -
            -
            -
            -

            The landmarks <nav> element

            -

            After the first <nav> element, there is a second <nav> element with the semantic inflection of landmarks.

            -
              -

            1. The first child is an <h2 epub:type="title">Landmarks</h2> element.

              2. -

            2. The second child is an <ol> element listing the major structural divisions of the book.

              3. -
            -
            -

            <li> descendents

            -

            Each <li> element contains a link to one of the major structural divisions of the book. In general, a structural division is any section of the book that is not part of the body text, plus one element representing the beginning of the body text.

            -
              -

            1. Each <li> element has the computed semantic inflection of top-level <section> element in the file. The computed semantic inflection includes inherited semantic inflection from the <body> tag. -

              <li> - <a href="text/preface.xhtml" epub:type="frontmatter preface">Preface</a> -</li>
              -
              2. -

            2. The body text, as a single unit regardless of internal divisions, is represented by a link to the first file of the body text. In a prose novel, this is usually Chapter 1 or Part 1. In a collection this is usually the first item, like the first short story in a short story collection. The text is the title of the work as represented in the metadata <dc:title> element. -

              <li> - <a href="text/book-1.xhtml" epub:type="bodymatter z3998:fiction">Sybil</a> -</li>
              -
              <li> - <a href="text/chapter-1.xhtml" epub:type="bodymatter z3998:fiction">The Moon Pool</a> -</li>
              -
              <li> - <a href="text/the-adventure-of-wisteria-lodge.xhtml" epub:type="bodymatter z3998:fiction">His Last Bow</a> -</li>
              -
              3. -
            -
            -
            -
            -
            -
            - diff --git a/www/manual/1.0.0/8-typography.php b/www/manual/1.0.0/8-typography.php index bfdc6390..c35faebc 100644 --- a/www/manual/1.0.0/8-typography.php +++ b/www/manual/1.0.0/8-typography.php @@ -1,7 +1,7 @@ '8. Typography - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
            +
            @@ -14,13 +14,13 @@ require_once('Core.php');

            <title>Chapter VII</title>
            <title>Chapter 7</title>
            -

          3. Section titles are titlecased according to the output of se titlecase. Section titles are not all-caps or small-caps.

            4. +

          4. Section titles are titlecased according to the output of se titlecase. Section titles are not all-caps or small-caps.

          5. Section titles do not have trailing periods.

            6. -

          6. Chapter titles omit the word Chapter, unless the word used is a stylistic choice for prose style purposes. Chapters with unique identifiers (i.e. not Chapter, but something unique to the style of the book, like Book or Stave) do include that unique identifier in the title. +

          7. Chapter titles omit the word Chapter, unless the word used is a stylistic choice for prose style purposes. Chapters with unique identifiers (i.e. not Chapter, but something unique to the style of the book, like Book or Stave) do include that unique identifier in the title.

            <h2 epub:type="title">Chapter <span epub:type="z3998:roman">II</span></h2>
            <h2 epub:type="title z3998:roman">II</h2>
            <h2 epub:type="title">Stave <span epub:type="z3998:roman">III</span></h2>
            -

            In special cases it may be desirable to retain Chapter for clarity. For example, Frankenstein has “Chapter” in titles to differentiate between the “Letter” sections.

            +

            In special cases it may be desirable to retain Chapter for clarity. For example, Frankenstein has “Chapter” in titles to differentiate between the “Letter” sections.

        @@ -60,7 +60,7 @@ require_once('Core.php');
        <p>She was learning her A B Cs.</p>
        <p>His trident had the shape of an E.</p>
        8. -

      8. The ordinal nth is set with an italicized n, and without a hyphen. +

      9. The ordinal nth is set with an italicized n, and without a hyphen.

        <p>The <i>n</i>th degree.</p>
      @@ -79,8 +79,8 @@ require_once('Core.php');

    8. Words and phrases that are originally non-English in origin, but that can now be found in Merriam-Webster, are not italicized.

      <p>Sir Percy’s bon mot had gone the round of the brilliant reception-rooms.</p>
      9. -

    9. Inline-level italics are set using the <i> element with an xml:lang attribute corresponding to the correct IETF language tag.

      10. -

    10. Block-level italics are set using an xml:lang attribute on the closest encompassing block element, with the style of font-style: italic. +

    11. Inline-level italics are set using the <i> element with an xml:lang attribute corresponding to the correct IETF language tag.

      12. +

    12. Block-level italics are set using an xml:lang attribute on the closest encompassing block element, with the style of font-style: italic.

      In this example, note the additional namespace declaration, and that we target descendants of the <body> element; otherwise, the entire <body> element would receive italics!

      @namespace xml "http://www.w3.org/XML/1998/namespace"; @@ -97,7 +97,7 @@ require_once('Core.php'); </p> </blockquote>
      13. -

    13. Words that are in a non-English “alien” language (i.e. one that is made up, like in a science fiction or fantasy work) are italicized and given an IETF languate tag in a custom namespace. Custom namespaces begin consist of x-TAG, where TAG is a custom descriptor of 8 characters or less.

      14. +

    14. Words that are in a non-English “alien” language (i.e. one that is made up, like in a science fiction or fantasy work) are italicized and given an IETF languate tag in a custom namespace. Custom namespaces begin consist of x-TAG, where TAG is a custom descriptor of 8 characters or less.

    <p>“<i xml:lang="x-arcturan">Dolm</i>,” said Haunte.</p>
    @@ -146,7 +146,7 @@ require_once('Core.php');

    Taxonomy

      -

    1. Binomial names (generic, specific, and subspecific) are italicized with a <i> element having the z3998:taxonomy semantic inflection. +

    2. Binomial names (generic, specific, and subspecific) are italicized with a <i> element having the z3998:taxonomy semantic inflection.

      <p>A bonobo monkey is <i epub:type="z3998:taxonomy">Pan paniscus</i>.</p>

    3. Family, order, class, phylum or division, and kingdom names are capitalized but not italicized. @@ -161,14 +161,14 @@ require_once('Core.php');

      Capitalization

      1. In general, capitalization follows modern English style. Some very old works frequently capitalize nouns that today are no longer capitalized. These archaic capitalizations are removed, unless doing so would change the meaning of the work.

        2. -

      2. Titlecasing, or the capitalization of titles, follows the formula used in the se titlecase tool.

        3. +

      3. Titlecasing, or the capitalization of titles, follows the formula used in the se titlecase tool.

      4. Text in all caps is almost never correct typography. Instead, such text is changed to the correct case and surround with a semantically-meaningful element like <em> (for emphasis), <strong> (for strong emphasis, like shouting) or <b> (for unsemantic formatting required by the text). <strong> and <b> are styled in small-caps by default in Standard Ebooks.

        <p>The sign read BOB’S RESTAURANT.</p>
        <p>“CHARGE!” he cried.</p>
        <p>The sign read <b>Bob’s Restaurant</b>.</p>
        <p>“<strong>Charge!</strong>” he cried.</p>
        5. -

      5. When something is addressed as an apostrophe, O is capitalized. +

      6. When something is addressed as an apostrophe, O is capitalized.

        <p>I carried the bodies into the sea, O walker in the sea!</p>
      @@ -322,7 +322,7 @@ require_once('Core.php'); <p><abbr>Lat.</abbr> 27° 0’ <abbr class="compass">N.</abbr>, <abbr>long.</abbr> 20° 1’ <abbr class="compass eoc">W.</abbr></p>
    • <p><abbr>Lat.</abbr> 27° 0′ <abbr class="compass">N.</abbr>, <abbr>long.</abbr> 20° 1′ <abbr class="compass eoc">W.</abbr></p>
    • -

  • Ordinals for Arabic numbers are as follows: st, nd, rd, th. +

  • Ordinals for Arabic numbers are as follows: st, nd, rd, th.

    <p>The 1st, 2d, 3d, 4th.</p>
    <p>The 1st, 2nd, 3rd, 4th.</p>
    • @@ -387,7 +387,7 @@ require_once('Core.php');

  • In works that are math-oriented or that have a significant amount of math, all variables, equations, and other mathematical objects are set using MathML.

      -

    1. When MathML is used in a file, the m namespace is declared at the top of the file and used for all subsequent MathML code, as follows: +

    2. When MathML is used in a file, the m namespace is declared at the top of the file and used for all subsequent MathML code, as follows:

      xmlns:m="http://www.w3.org/1998/Math/MathML"

      This namespace is declared and used even if there is just a single MathML equation in a file.

      <html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" ub:prefix="z3998: http://www.daisy.org/z3998/2012/vocab/structure/, se: https://standardebooks.org/vocab/1.0" xml:lang="en-GB"> @@ -420,10 +420,10 @@ require_once('Core.php'); </m:math> </p>
      3. -

    3. Each <m:math> element has an alttext attribute. +

    4. Each <m:math> element has an alttext attribute.

        -

      1. The alttext attribute describes the contents in the element in plain-text Unicode according to the rules in this specification.

        2. -

      2. Operators in the alttext attribute are surrounded by a single space. +

      3. The alttext attribute describes the contents in the element in plain-text Unicode according to the rules in this specification.

        4. +

      4. Operators in the alttext attribute are surrounded by a single space.

        <p> <m:math alttext="x+1=y"> <m:apply> @@ -467,7 +467,7 @@ require_once('Core.php'); </m:math> </p>
        5. -

      5. If a Presentational MathML expression contains a function, the invisible Unicode function application glyph (U+2061) is used as an operator between the function name and its operand. This element looks exactly like the following, including the comment for readability: <m:mo>⁡<!--hidden U+2061 function application--></m:mo>. (Note that the preceding element contains an invisible Unicode character! It can be revealed with the se unicode-names tool.) +

      6. If a Presentational MathML expression contains a function, the invisible Unicode function application glyph (U+2061) is used as an operator between the function name and its operand. This element looks exactly like the following, including the comment for readability: <m:mo>⁡<!--hidden U+2061 function application--></m:mo>. (Note that the preceding element contains an invisible Unicode character! It can be revealed with the se unicode-names tool.)

        <p> <m:math alttext="f(x)"> <m:mi>f</m:mi> @@ -515,7 +515,7 @@ require_once('Core.php'); </m:math> </p>
        7. -

      7. If a MathML variable includes an overline, it is set by combining the variable’s normal Unicode glyph and the Unicode overline glyph (‾ or U+203E) in a <m:mover> element. However in the alttext attribute, the Unicode overline combining mark (U+0305) is used to represent the overline in Unicode. +

      8. If a MathML variable includes an overline, it is set by combining the variable’s normal Unicode glyph and the Unicode overline glyph (‾ or U+203E) in a <m:mover> element. However in the alttext attribute, the Unicode overline combining mark (U+0305) is used to represent the overline in Unicode.

        <p> <m:math alttext="x̅"> <m:mover> @@ -557,7 +557,7 @@ require_once('Core.php');

        1. “OK” is set without periods or spaces. It is not an abbreviation.

          2. -

        2. When an abbreviation contains a terminal period, its <abbr> tag has the additional eoc class (End of Clause) if the terminal period is also the last period in clause. Such sentences do not have two consecutive periods. +

        3. When an abbreviation contains a terminal period, its <abbr> element has the additional eoc class (End of Clause) if the terminal period is also the last period in clause. Such sentences do not have two consecutive periods.

          <p>She loved Italian food like pizza, pasta, <abbr class="eoc">etc.</abbr></p>
          <p>He lists his name alphabetically as Johnson, <abbr class="name eoc">R. A.</abbr></p>
          <p>His favorite hobby was <abbr class="acronym">SCUBA</abbr>.</p>
          @@ -599,13 +599,13 @@ require_once('Core.php');

          Times

          1. Times in a.m. and p.m. format are set in lowercase, with periods, and without spaces.

            2. -

          2. “a.m.” and “p.m.” are wrapped in an <abbr class="time"> element.

            3. +

          3. a.m. and p.m. are wrapped in an <abbr class="time"> element.

          Times as digits

          1. Digits in times are separated by a colon, not a period or comma.

            2. -

          2. Times written in digits followed by “a.m.” or “p.m.” are set with a no-break space ( or U+00A0) between the digit and “a.m.” or “p.m.”. +

          3. Times written in digits followed by a.m. or p.m. are set with a no-break space ( or U+00A0) between the digit and a.m. or p.m..

            <p>He called at 6:40nbsp<abbr class="time eoc">a.m.</abbr></p>
          @@ -646,12 +646,12 @@ require_once('Core.php');

        Abbreviated units of temperature

        -

        Units of temperature measurement, like Farenheit or Celcius, may be abbreviated to “F” or “C”.

          -

        1. Units of temperature measurement do not have trailing periods.

          2. -

        2. If an abbreviated unit of temperature measurement is preceded by a number, the unit of measurement is first preceded by a hair space ( or U+200A).

          3. -

        3. Abbreviated units of measurement are set in small caps.

          4. -

        4. Abbreviated units of measurement are wrapped in an <abbr class="temperature"> element. +

        5. Units of temperature measurement, like Farenheit or Celcius, may be abbreviated to “F” or “C”.

          6. +

        6. Units of temperature measurement do not have trailing periods.

          7. +

        7. If an abbreviated unit of temperature measurement is preceded by a number, the unit of measurement is first preceded by a hair space ( or U+200A).

          8. +

        8. Abbreviated units of measurement are set in small caps.

          9. +

        9. Abbreviated units of measurement are wrapped in an <abbr class="temperature"> element.

          abbr.temperature{ font-variant: all-small-caps; }
          diff --git a/www/manual/1.0.0/9-metadata.php b/www/manual/1.0.0/9-metadata.php index 6bb17497..49eeaa22 100644 --- a/www/manual/1.0.0/9-metadata.php +++ b/www/manual/1.0.0/9-metadata.php @@ -1,13 +1,13 @@ '9. Metadata - The Standard Ebooks Manual', 'highlight' => 'contribute', 'manual' => true]) ?> -
          +

          Metadata

          Metadata in a Standard Ebook is stored in the ./src/epub/content.opf file. The file contains some boilerplate that an ebook producer won’t have to touch, and a lot of information that they will have to touch as an ebook is produced.

          -

          Follow the general structure of the content.opf file generated by se create-draft. Don’t rearrange the order of anything in there.

          +

          Follow the general structure of the content.opf file generated by se create-draft. Don’t rearrange the order of anything in there.

          General URL rules

            @@ -22,14 +22,14 @@ require_once('Core.php');

            The ebook identifier

              -

            1. The <dc:identifier> element contains the unique identifier for the ebook. The identifier is the Standard Ebooks URL for the ebook, prefaced by url:. +

            2. The <dc:identifier> element contains the unique identifier for the ebook. The identifier is the Standard Ebooks URL for the ebook, prefaced by url:.

              <dc:identifier id="uid">url:https://standardebooks.org/ebooks/anton-chekhov/short-fiction/constance-garnett</dc:identifier>

            Forming the SE URL

            The SE URL is formed by the following algorithm.

            -

            (Note: Strings can be made URL-safe using the se make-url-safe tool.)

            +

            (Note: Strings can be made URL-safe using the se make-url-safe tool.)

            • Start with the URL-safe author of the work, as it appears on the titlepage. If there is more than one author, continue appending subsequent URL-safe authors, separated by an underscore. Do not alpha-sort the author name.

            • Append a forward slash, then the URL-safe title of the work. Do not alpha-sort the title.

              • @@ -41,7 +41,7 @@ require_once('Core.php');

            Publication date and release identifiers

            -

            There are several elements in the metadata describing the publication date, updated date, and revision number of the ebook. Generally these are not updated by hand; instead, the se prepare-release tool updates them automatically.

            +

            There are several elements in the metadata describing the publication date, updated date, and revision number of the ebook. Generally these are not updated by hand; instead, the se prepare-release tool updates them automatically.

            1. <dc:date> is a timestamp representing the first publication date of this ebook file. Once the ebook is released to the public, this value doesn’t change.

            2. <meta property="dcterms:modified"> is a timestamp representing the last time this ebook file was modified. This changes often.

              3. @@ -67,7 +67,7 @@ require_once('Core.php');

            3. The <meta property="title-type" refines="#title">main</meta> element identifies the main part of the title.

            4. A second <dc:title id="subtitle"> element contain the subtitle, and is refined with <meta property="title-type" refines="#subtitle">subtitle</meta>.

            5. A third <dc:title id="fulltitle"> element contains the complete title on one line, with the main title and subtitle separated by a colon and space, and is refined with <meta property="title-type" refines="#fulltitle">extended</meta>.

              6. -

            6. All three <dc:title> elements have an accompanying <meta property="file-as"> element, even if the file-as value is the same as the title.

              7. +

            7. All three <dc:title> elements have an accompanying <meta property="file-as"> element, even if the file-as value is the same as the title.

            <dc:title id="title">The Moon Pool</dc:title> <meta property="file-as" refines="#title">Moon Pool, The</meta>
            @@ -110,13 +110,13 @@ require_once('Core.php');

            The <dc:subject> element

            <dc:subject> elements describe the categories the ebook belongs to.

              -

            1. Each <dc:subject> has the id attribute set to subject-#, where # is a number starting at 1, without leading zeros, that increments with each subject.

              2. +

            2. Each <dc:subject> has the id attribute set to subject-#, where # is a number starting at 1, without leading zeros, that increments with each subject.

            3. The <dc:subject> elements are arranged sequentially in a single block.

            4. <dc:subject> values are sourced from Library of Congress Subject Headings.

            5. If the transcription for the ebook comes from Project Gutenberg, the values of the <dc:subject> elements come from the Project Gutenberg “bibrec” page for the ebook. Otherwise, the values come from the Library of Congress catalog listing for the book.

            6. After the block of <dc:subject> elements there is a block of <meta property="authority" refines="#subject-N"> and <meta property="term" refines="#subject-N"> element pairs.

                -

              1. <meta property="authority" refines="#subject-N"> contains the source for the category. For Library of Congress categories, the value is LCSH.

                2. +

              2. <meta property="authority" refines="#subject-N"> contains the source for the category. For Library of Congress categories, the value is LCSH.

              3. <meta property="term" refines="#subject-N"> contains term ID for that subject heading.

              7. @@ -175,8 +175,8 @@ require_once('Core.php');

              Required SE subjects for specific types of books

                -

              1. Ebooks that are collections of short stories have the SE subject Shorts as one of the SE subjects.

                2. -

              2. Ebooks that are young adult or children’s books have the SE subject Childrens as one of the SE subjects.

                3. +

              3. Ebooks that are collections of short stories have the SE subject Shorts as one of the SE subjects.

                4. +

              4. Ebooks that are young adult or children’s books have the SE subject Childrens as one of the SE subjects.

            @@ -199,7 +199,7 @@ require_once('Core.php');

          1. The long description is a non-biased, encyclopedia-like description of the book, including any relevant publication history, backstory, or historical notes. It is as detailed as possible without giving away plot spoilers. It does not impart the producer’s opinions of the book, or include content warnings. Think along the lines of a Wikipedia-like summary of the book and its history, but under no circumstances can a producer copy and paste from Wikipedia! (Wikipedia licenses articles under a CC license which is incompatible with Standard Ebooks’ CC0 public domain dedication.)

          2. The long descriptions is typogrified, i.e. it contains Unicode curly quotes, em-dashes, and the like.

          3. The long description is in escaped HTML, with the HTML beginning on its own line after the <meta property="se:long-description"> element. -

            +

          4. Long description HTML follows the general code style conventions.

          5. The long description element is directly followed by: <meta property="meta-auth" refines="#long-description">https://standardebooks.org</meta>

            6. @@ -209,7 +209,7 @@ require_once('Core.php');

            Book language

              -

            1. The <dc:language> element follows the long description block. It contains the IETF language tag for the language that the work is in. Usually this is either en-US or en-GB.

              2. +

            2. The <dc:language> element follows the long description block. It contains the IETF language tag for the language that the work is in. Usually this is either en-US or en-GB.

            @@ -235,7 +235,7 @@ require_once('Core.php');

            Readability metadata

            -

            These two elements are automatically computed by the se prepare-release tool.

            +

            These two elements are automatically computed by the se prepare-release tool.

            1. The <meta property="se:word-count"> element contains an integer representing the ebooks total word count, excluding some SE files like the colophon and Uncopyright.

            2. The <meta property="se:reading-ease.flesch"> element contains a decimal representing the computed Flesch reading ease for the book.

              3. @@ -248,7 +248,7 @@ require_once('Core.php');

              1. If there is exactly one contributor in a set (for example, only one author, or only one translator) then the <meta property="display-seq"> element is omitted for that contributor.

              2. If there is more than one contributor in a set (for example, multiple authors, or translators) then the <meta property="display-seq"> element is specified for each contributor, with a value equal to their position in the SE identifier.

                3. -

              3. The epub standard specifies that in a set of contributors, if at least one has the display-seq attribute, then other contributors in the set without the display-seq attribute are ignored. For SE purposes, this also means they will be excluded from the SE identifier.

                4. +

              4. The epub standard specifies that in a set of contributors, if at least one has the display-seq property, then other contributors in the set without the display-seq value are ignored. For SE purposes, this also means they will be excluded from the SE identifier.

              5. By SE convention, contributors with <meta property="display-seq">0</meta> are excluded from the SE identifier.

            @@ -256,7 +256,7 @@ require_once('Core.php');

            The author metadata block

            1. <dc:creator id="author"> contains the author’s name as it appears on the cover.

              2. -

            2. If there is more than one author, the first author’s id is author-1, the second author-2, and so on.

              3. +

            3. If there is more than one author, the first author’s id is author-1, the second author-2, and so on.

            4. <meta property="file-as" refines="#author"> contains the author’s name as filed alphabetically. This element is included even if it’s identical to <dc:creator>.

            5. <meta property="se:name.person.full-name" refines="#author"> contains the author’s full name, with any initials or middle names expanded, and including any titles. This element is not included if the value is identical to <dc:creator>.

            6. <meta property="alternate-script" refines="#author"> contains the author’s name as it appears on the cover, but transliterated into their native alphabet if applicable. For example, Anton Chekhov’s name would be contained here in the Cyrillic alphabet. This element is not included if not applicable.

              7. @@ -268,7 +268,7 @@ require_once('Core.php');

            7. <meta property="role" refines="#author" scheme="marc:relators"> contains the MARC relator tag for the roles the author played in creating this book. -

              There is always one element with the value of aut. There may be additional elements for additional values, if applicable. For example, if the author also illustrated the book, there would be an additional <meta property="role" refines="#author" scheme="marc:relators">ill</meta> element.

              +

              There is always one element with the value of aut. There may be additional elements for additional values, if applicable. For example, if the author also illustrated the book, there would be an additional <meta property="role" refines="#author" scheme="marc:relators">ill</meta> element.

            This example shows a complete author metadata block for Short Fiction, by Anton Chekhov:

            @@ -284,19 +284,19 @@ require_once('Core.php');

            The translator metadata block

            1. If the work is translated, the <dc:contributor id="translator"> metadata block follows the author metadata block.

              2. -

            2. If there is more than one translator, then the first translator’s id is translator-1, the second translator-2, and so on.

              3. +

            3. If there is more than one translator, then the first translator’s id is translator-1, the second translator-2, and so on.

            4. Each block is identical to the author metadata block, but with <dc:contributor id="translator"> instead of <dc:creator id="author">.

              5. -

            5. The MARC relator tag is trl: <meta property="role" refines="#translator" scheme="marc:relators">trl</meta>.

              6. -

            6. Translators often annotate the work; if this is the case, the additional MARC relator tag ann is included in a separate <meta property="role" refines="#translator" scheme="marc:relators"> element.

              7. +

            7. The MARC relator tag is trl: <meta property="role" refines="#translator" scheme="marc:relators">trl</meta>.

              8. +

            8. Translators often annotate the work; if this is the case, the additional MARC relator tag ann is included in a separate <meta property="role" refines="#translator" scheme="marc:relators"> element.

            The illustrator metadata block

            1. If the work is illustrated by a person who is not the author, the illustrator metadata block follows.

              2. -

            2. If there is more than one illustrator, the first illustrator’s id is illustrator-1, the second illustrator-2, and so on.

              3. +

            3. If there is more than one illustrator, the first illustrator’s id is illustrator-1, the second illustrator-2, and so on.

            4. Each block is identical to the author metadata block, but with <dc:contributor id="illustrator"> instead of <dc:creator id="author">.

              5. -

            5. The MARC relator tag is ill: <meta property="role" refines="#illustrator" scheme="marc:relators">ill</meta>.

              6. +

            6. The MARC relator tag is ill: <meta property="role" refines="#illustrator" scheme="marc:relators">ill</meta>.

            @@ -304,7 +304,7 @@ require_once('Core.php');

            The “cover artist” is the artist who painted the art the producer selected for the Standard Ebook cover.

            1. The cover artist metadata block is identical to the author metadata block, but with <dc:contributor id="artist"> instead of <dc:creator id="author">.

              2. -

            2. The MARC relator tag is art: <meta property="role" refines="#artist" scheme="marc:relators">art</meta>.

              3. +

            3. The MARC relator tag is art: <meta property="role" refines="#artist" scheme="marc:relators">art</meta>.

            @@ -312,18 +312,18 @@ require_once('Core.php');

            Occasionally a book may have other contributors besides the author, translator, and illustrator; for example, a person who wrote a preface, an introduction, or who edited the work or added endnotes.

            1. Additional contributor blocks are identical to the author metadata block, but with <dc:contributor> instead of <dc:creator>.

              2. -

            2. The id attribute of the <dc:contributor> is the lowercase, URL-safe, fully-spelled out version of the MARC relator tag. For example, if the MARC relator tag is wpr, the id attribute would be writer-of-preface.

              3. -

            3. The MARC relator tag is one that is appropriate for the role of the additional contributor. Common roles for ebooks are: wpr, ann, and aui.

              4. +

            4. The id attribute of the <dc:contributor> is the lowercase, URL-safe, fully-spelled out version of the MARC relator tag. For example, if the MARC relator tag is wpr, the id attribute would be writer-of-preface.

              5. +

            5. The MARC relator tag is one that is appropriate for the role of the additional contributor. Common roles for ebooks are: wpr, ann, and aui.

            Transcriber metadata

            1. If the ebook is based on a transcription by someone else, like Project Gutenberg, then transcriber blocks follow the general contributor metadata blocks.

              2. -

            2. If the transcriber is anonymous, the value for the producer’s <dc:contributor> element is An Anonymous Volunteer.

              3. -

            3. If there is more than one transcriber, the first transcriber is transcriber-1, the second transcriber-2, and so on.

              4. +

            4. If the transcriber is anonymous, the value for the producer’s <dc:contributor> element is An Anonymous Volunteer.

              5. +

            5. If there is more than one transcriber, the first transcriber is transcriber-1, the second transcriber-2, and so on.

            6. The <meta property="file-as" refines="#transcriber-1"> element contains an alpha-sorted representation of the transcriber’s name.

              7. -

            7. The MARC relator tag is trc: <meta property="role" refines="#transcriber-1" scheme="marc:relators">trc</meta>.

              8. +

            8. The MARC relator tag is trc: <meta property="role" refines="#transcriber-1" scheme="marc:relators">trc</meta>.

            9. If the transcriber’s personal homepage is known, the element <meta property="se:url.homepage" refines="#transcriber-1"> is included, whose value is the URL of the transcriber’s homepage. The URL must link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.

            @@ -331,18 +331,18 @@ require_once('Core.php');

            Producer metadata

            These elements describe the SE producer who produced the ebook for the Standard Ebooks project.

              -

            1. If there is more than one producer, the first producer is producer-1, the second producere-2, and so on.

              2. +

            2. If there is more than one producer, the first producer is producer-1, the second producere-2, and so on.

            3. The producer metadata block is identical to the author metadata block, but with <dc:contributor id="producer-1"> instead of <dc:creator id="author">.

              4. -

            4. If a producer is anonymous, the value for the producer’s <dc:contributor> element is Anonymous.

              5. +

            5. If a producer is anonymous, the value for the producer’s <dc:contributor> element is Anonymous.

            6. If the producer’s personal homepage is known, the element <meta property="se:url.homepage" refines="#producer-1"> is included, whose value is the URL of the transcriber’s homepage. The URL must link to a personal homepage only; no products, services, or other endorsements, commercial or otherwise.

            7. The MARC relator tags for the SE producer usually include all of the following:

                -

              • bkp: The producer produced the ebook.

                • -

              • blw: The producer wrote the blurb (the long description).

                • -

              • cov: The producer selected the cover art.

                • -

              • mrk: The producer wrote the HTML markup for the ebook.

                • -

              • pfr: The producer proofread the ebook.

                • -

              • tyg: The producer reviewed the typography of the ebook.

                • +

              • bkp: The producer produced the ebook.

                • +

              • blw: The producer wrote the blurb (the long description).

                • +

              • cov: The producer selected the cover art.

                • +

              • mrk: The producer wrote the HTML markup for the ebook.

                • +

              • pfr: The producer proofread the ebook.

                • +

              • tyg: The producer reviewed the typography of the ebook.

            @@ -350,19 +350,19 @@ require_once('Core.php');

            The ebook manifest

            The <manifest> element is a required part of the epub spec that defines a list of files within the ebook.

            - +

            1. The manifest is in alphabetical order.

              2. -

            2. The id attribute is the basename of the href attribute.

              3. -

            3. Files which contain SVG images have the additional properties="svg" property in their manifest item.

              4. -

            4. The manifest item for the table of contents file has the additional properties="nav" property.

              5. -

            5. The manifest item for the cover image has the additional properties="cover-image" property.

              6. +

            6. The id attribute is the basename of the href attribute.

              7. +

            7. Files which contain SVG images have the additional properties attribute with the value svg in their manifest item.

              8. +

            8. The manifest item for the table of contents file has the additional properties attribute with the value nav.

              9. +

            9. The manifest item for the cover image has the additional properties attribute with the value cover-image.

            The ebook spine

            The <spine> element is a required part of the epub spec that defines the reading order of the files in the ebook.

            - +
          diff --git a/www/manual/1.0.0/index.php b/www/manual/1.0.0/index.php index 5c655f70..3c75d3fa 100644 --- a/www/manual/1.0.0/index.php +++ b/www/manual/1.0.0/index.php @@ -10,8 +10,9 @@ require_once('Core.php');

          If a rule is not covered in this manual, the directive is to follow the rules in the Chicago Manual of Style, 16th edition.

          These rules align closely with the style rules used in modern publishing. However, books from the turn of the 20th century and older may appear to follow a different set of rules. Producers are expected to adjust those older conventions to match this manual.

          Having said that, literature is a complex and multifaceted art, and in the process of converting older books some may call for a bending of a rule, or for an outright exception. Producers should not feel bound to slavishly follow these directives if a book seems to cry out for an exception. As Ralph Waldo Emerson once wrote, “a foolish consistency is the hobgoblin of little minds.” If unsure, producers are urged and welcomed to contact the Standard Ebooks Editor in Chief for final-word guidance.

          +

          To contribute, please visit the GitHub repository or contact the mailing list.

          Editor-in-chief: Alex Cabal

          -

          Contributors (in alpha order): David Grigg, B. Timothy Keith, Vince Rice, Emma Sweeney, Robin Whittleton, Kenny Williams.

          +

          Contributors (in alpha order): David Grigg, B. Timothy Keith, Vince Rice, Emma Sweeney, Robin Whittleton.

          Table of Contents

            diff --git a/www/manual/index.php b/www/manual/index.php index 1cd14cab..8371363f 100644 --- a/www/manual/index.php +++ b/www/manual/index.php @@ -8,5 +8,14 @@ sort($dirs); $currentManual = str_replace(WEB_ROOT, '', $dirs[sizeof($dirs) - 1]); +$url = HttpInput::GetString('url', true, ''); +$url = preg_replace('|^/|ius', '', $url); +$url = preg_replace('|\.php$|ius', '', $url); +$url = preg_replace('|/$|ius', '', $url); + +if($url != ''){ + $url = '/' . $url; +} + http_response_code(302); -header('Location: ' . $currentManual); +header('Location: ' . $currentManual . $url);