From 6fa548f57fee85d888c9ec6c5146c199793be675 Mon Sep 17 00:00:00 2001 From: Alex Cabal Date: Tue, 31 Mar 2020 13:29:40 -0500 Subject: [PATCH] Add links to section identifiers --- www/css/manual.css | 5 + www/manual/1.0.0/1-code-style.php | 72 ++-- www/manual/1.0.0/10-art-and-images.php | 132 +++---- www/manual/1.0.0/2-filesystem.php | 78 ++--- .../1.0.0/3-the-structure-of-an-ebook.php | 48 +-- www/manual/1.0.0/4-semantics.php | 60 ++-- www/manual/1.0.0/5-general-xhtml-patterns.php | 66 ++-- .../6-standard-ebooks-section-patterns.php | 150 ++++---- .../7-high-level-structural-patterns.php | 248 ++++++------- www/manual/1.0.0/8-typography.php | 330 +++++++++--------- www/manual/1.0.0/9-metadata.php | 242 ++++++------- 11 files changed, 718 insertions(+), 713 deletions(-) diff --git a/www/css/manual.css b/www/css/manual.css index 7175fd7a..155e5027 100644 --- a/www/css/manual.css +++ b/www/css/manual.css @@ -348,6 +348,11 @@ figure.corrected code{ font-size: 2rem; } +.manual section[id] > aside.number a, +.manual section[id] ol > li > aside.number a{ + text-decoration: none; +} + .manual h1 + section > h2:first-child{ margin-top: 0; } diff --git a/www/manual/1.0.0/1-code-style.php b/www/manual/1.0.0/1-code-style.php index 44a5ca8f..7c882402 100644 --- a/www/manual/1.0.0/1-code-style.php +++ b/www/manual/1.0.0/1-code-style.php @@ -7,28 +7,28 @@ require_once('Core.php');

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.

-
+

XHTML formatting

    -

  1. The first line of all XHTML files is: +

  2. The first line of all XHTML files is:

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

  3. The second line of all XHTML files is (replace xml:lang="en-US" with the appropriate language tag for the file): +

  4. The second line of all XHTML files is (replace xml:lang="en-US" 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="en-US">
    5. -

  5. Tabs are used for indentation.

    6. -

  6. Tag names are lowercase.

    7. -

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

  8. Tabs are used for indentation.

    9. +

  9. Tag names are lowercase.

    10. +

  10. 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>
    <p>It was a dark and stormy night...</p>
-
+

<br/> elements

    -

  1. <br/> elements within phrasing content are on the same line as the preceding phrasing content, and are followed by a newline. +

  2. <br/> elements within phrasing content are on the same line as the preceding phrasing content, and are followed by a newline.

    <p>“Pray for the soul of the <br/> Demoiselle Jeanne D’Ys.</p>
    @@ -37,7 +37,7 @@ Demoiselle Jeanne D’Ys.</p<p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys.</p>
    3. -

  3. The next indentation level after a <br/> element is the same as the previous indentation level. +

  4. The next indentation level after a <br/> element is the same as the previous indentation level.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys,<br/> who died<br/> @@ -49,14 +49,14 @@ who died<br/&g in her youth for love of<br/> Philip, a Stranger.</p>
    5. -

  5. The closing tag of the phrasing content broken by a <br/> element is on the same line as the last line of the phrasing content. +

  6. The closing tag of the phrasing content broken by a <br/> element is on the same line as the last line of the phrasing content.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys. </p>
    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys.</p>
    7. -

  7. <br/> elements have phrasing content both before and after; they don’t appear with phrasing content only before, or only after. +

  8. <br/> elements have phrasing content both before and after; they don’t appear with phrasing content only before, or only after.

    <p>“Pray for the soul of the<br/> Demoiselle Jeanne D’Ys<br/></p>
    <p>“Pray for the soul of the<br/> @@ -64,21 +64,21 @@ Demoiselle Jeanne D’Ys</p
-
+

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. In IETF language tags, the language subtag is capitalized. +

  3. Attributes are in alphabetical order.

    4. +

  4. Attributes, their namespaces, and their values are lowercase, except for values which are IETF language tags. In IETF language tags, the language subtag is capitalized.

    <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.

-
+

Classes

    -

  1. Classes are not used as one-time style hooks. There is almost always a clever selector that can be constructed instead of taking the shortcut of adding a class to an element.

    2. -

  2. Classes are named semantically, describing what they are styling instead of the resulting visual style. +

  3. Classes are not used as one-time style hooks. There is almost always a clever selector that can be constructed instead of taking the shortcut of adding a class to an element.

    4. +

  4. Classes are named semantically, describing what they are styling instead of the resulting visual style.

    <p>There was one great tomb more lordly than all the rest; huge it was, and nobly proportioned. On it was but one word</p> <blockquote class="small-caps"> <p>Dracula.</p> @@ -92,20 +92,20 @@ Demoiselle Jeanne D’Ys</p
-
+

CSS formatting

    -

  1. The first two lines of all CSS files are: +

  2. The first two lines of all CSS files are:

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

  3. Tabs are used for indentation.

    4. -

  4. Selectors, properties, and values are lowercase.

    5. +

  5. Tabs are used for indentation.

    6. +

  6. Selectors, properties, and values are lowercase.

-
+

Selectors

    -

  1. Selectors are each on their own line, directly followed by a comma or a brace with no whitespace in between. +

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

    abbr.era, .signature{ font-variant: all-small-caps; }
    @@ -114,7 +114,7 @@ Demoiselle Jeanne D’Ys</pfont-variant: all-small-caps; }
    3. -

  3. Complete selectors are separated by exactly one blank line. +

  4. Complete selectors are separated by exactly one blank line.

    abbr.era{ font-variant: all-small-caps; } @@ -133,22 +133,22 @@ Demoiselle Jeanne D’Ys</pfont-variant: small-caps; }
    5. -

  5. Closing braces are on their own line.

    6. +

  6. Closing braces are on their own line.

-
+

Properties

    -

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

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

    abbr.era{ font-variant: all-small-caps; }
    abbr.era{ font-variant: all-small-caps; }
    3. -

  3. Where possible, properties are in alphabetical order. +

  4. Where possible, properties are in alphabetical order.

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

    5. -

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

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

    blockquote{ margin-left: 1em; margin-right: 1em; @@ -160,7 +160,7 @@ Demoiselle Jeanne D’Ys</pborder: none; }
    7. -

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

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

    abbr.era{ font-variant: all-small-caps }
    @@ -171,17 +171,17 @@ Demoiselle Jeanne D’Ys</p
-
+

SVG Formatting

    -

  1. SVG formatting follows the same directives as XHTML formatting.

    2. +

  2. SVG formatting follows the same directives as XHTML formatting.

-
+

Commits 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 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".

    4. +

  4. 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.

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 6aa6c067..1f5b4be3 100644 --- a/www/manual/1.0.0/10-art-and-images.php +++ b/www/manual/1.0.0/10-art-and-images.php @@ -4,12 +4,12 @@ require_once('Core.php');
-
+

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.

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:

    @@ -25,23 +25,23 @@ require_once('Core.php');
-
+

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. 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. 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.

    6. -

  6. The use of fill color is avoided unless strictly necessary. Not defining a fill color allows for night mode compatibility.

    7. -

  7. The transform attribute is illegal; transforms are applied to their elements directly.

    8. +

  8. The only attributes on the <svg> root element are: xmlns, version, and viewBox.

    9. +

  9. The contents of the SVG’s <title> element matches the alt attribute of its <img> element in the text.

    10. +

  10. 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.

    11. +

  11. The use of fill color is avoided unless strictly necessary. Not defining a fill color allows for night mode compatibility.

    12. +

  12. The transform attribute is illegal; transforms are applied to their elements directly.

-
+

The cover image