<commit_before><!DOCTYPE html>
<html lang="en-GB">
  <head>
    <meta charset="utf-8">
    <title>Scholarly HTML — Markedly Smart</title>
    <link rel="stylesheet" href="scholarly.css">
    <link rel="stylesheet" href="node_modules/prismjs/themes/prism-coy.css">
    <script src="node_modules/prismjs/prism.js" defer></script>
  </head>
  <body prefix="schema: http://schema.org/ xsd: http://www.w3.org/2001/XMLSchema# sa: https://ns.science.ai/">
    <header>
      <p class="title">Scholarly HTML</p>
      <p class="subtitle">Markedly Smart</p>
    </header>
    <article id="what" typeof="schema:ScholarlyArticle">
      <h1>What is Scholarly HTML?</h1>
      <!--
        XXX
          - favicon
          - script that adds sectionals
          - highlight on targets for citations
      -->
      <section typeof="sa:Abstract" id="abstract">
        <h2>Abstract</h2>
        <p>
          Scholarly HTML is a domain-specific data format built entirely on open standards that
          enables the interoperable exchange of scholarly articles in a manner that is compatible
          with off-the-shelf browsers. This document describes how Scholarly HTML works and how it
          is encoded as a document. It is, itself, written in Scholarly HTML.
        </p>
      </section>
      <section typeof="sa:MaterialsAndMethods" id="motivation">
        <h2>Motivation</h2>
        <p>
          Scholarly articles are still primarily encoded as unstructured graphics formats in which
          most of the information initially created by research, or even just in the text, is lost.
          This was an acceptable, if deplorable, condition when viable alternatives did not seem
          possible, but document technology has today reached a level of maturity and universality
          that makes this situation no longer tenable. Information cannot be disseminated if it is
          destroyed before even having left its creator’s laptop.
        </p>
        <p>
          According to the New York Times, adding structured information to their recipes (instead
          of exposing simply as plain text) improved their discoverability to the point of producing
          an immediate rise of 52 percent in traffic (<a href="#ref-nyt"
          property="schema:citation">NYT, 2014</a>). At this point in time, cupcake recipes are
          reaping greater benefits from modern data format practices than the whole scientific
          endeavour.
        </p>
        <p>
          This is not solely a loss for the high principles of knowledge sharing in science, it also
          has very immediate pragmatic consequences. Any tool, any service that tries to integrate
          with scholarly publishing has to spend the brunt of its complexity (or budget) extracting
          data the author would have willingly shared out of antiquated formats. This places
          stringent limits on the improvement of the scholarly toolbox, on the discoverability of
          scientific knowledge, and particularly on processes of meta-analysis.
        </p>
        <p>
          To address these issues, we have followed an approach rooted in established best practices
          for the reuse of open, standard formats. The «HTML Vernacular» body of practice provides
          guidelines for the creation of domain-specific data formats that make use of HTML’s
          inherent extensibility (<a href="#ref-vernacular" property="schema:citation">Science.AI,
          2015b</a>). Using the vernacular foundation overlaid with «schema.org» metadata we have
          produced a format for the interchange of scholarly articles built on open standards, ready
          for all to use.
        </p>
        <p>
          Our high-level goals were:
        </p>
        <ul>
          <li>
            Uncompromisingly enabling structured metadata, accessibility, and internationalisation.
          </li>
          <li>
            Pragmatically working in Web browsers, even if it occasionally incurs some markup
            overhead.
          </li>
          <li>
            Powerfully customisable for inclusion in arbitrary Web sites, while remaining easy to
            process and interoperable.
          </li>
          <li>
            Entirely built on top of open, royalty-free standards.
          </li>
          <li>
            Long-term viability as a data format.
          </li>
        </ul>
        <p>
          Additionally, in view of the specific problem we addressed, in the creation of this
          vernacular we have favoured the reliability of interchange over ease of authoring; but
          have nevertheless attempted to cater to the later as much as possible.
        </p>
      </section>
      <section typeof="sa:Results" id="definition">
        <h2>Definition</h2>
        <p>
          A <dfn id="scholarly-html">Scholarly HTML document</dfn> is a valid HTML document that
          follows some additional rules to specialised its meaning and make it predictable to
          processors wishing to produce or consume scholarly articles. These rules are outlined in
          the following sections.
        </p>
        <section id="file-headers">
          <h3>File &amp; Supporting Structure</h3>
          <p>
            The document must be encoded in UTF-8, and transmitted with a media type of
            <code>text/html</code>. It must feature a <code>DOCTYPE</code> as its preamble.
          </p>
          <p>
            The <code>html</code> root element must feature a valid <code>lang</code> attribute.
          </p>
          <p>
            The <code>head</code> element of the document must contain a
            <code class="language-html">&lt;meta charset="utf-8"></code> element (preferable as its
            first child) and a <code>title</code> element. All the other content of the
            <code>head</code> is ignored.
          </p>
          <p>
            The <code>body</code> element must have a <code>prefix</code> attribute, which must
            declare the following mapping:
          </p>
          <table typeof="schema:Table">
            <thead>
              <tr>
                <th>Prefix</th>
                <th>URL</th>
              </tr>
            </thead>
            <tr>
              <td>schema</td>
              <td>http://schema.org/</td>
            </tr>
            <tr>
              <td>xsd</td>
              <td>http://www.w3.org/2001/XMLSchema#</td>
            </tr>
            <tr>
              <td>sa</td>
              <td>https://ns.science.ai/</td>
            </tr>
            <caption>
              The list of mappings that must be declared by the <code>body</code> element.
            </caption>
          </table>
          <p>
            Having to declare prefixes is undoubtably an annoyance and it does hurt the human
            authorability of the format (since hand-creating a document essentially requires a
            boilerplate prefix declaration). This trade-off is made for several reasons. The most
            important motivation is that having predictable prefixes means that the content can be
            styled with CSS using reliable attribute selectors on the semantic information that
            describes the document’s structure. The alternative would be to use URLs everywhere,
            such that instead of <code>sa:Abstract</code> we would have
            <code>https://ns.science.ai/Abstract</code>; but in practice that approach is more
            painful since the content then becomes bloated with URLs that are longer than is
            comfortable.
          </p>
          <p>
            The RDFa content of the article must systematically make use of these prefixes when the
            values match their URLs as prefixes. Authors may declare other prefix-URL mappings in
            the <code>prefix</code> attribute of the <code>body</code> element (or
            <code>prefix</code> attributes elsewhere), including other prefixes mapping to the same
            URLs if needed, but inside of the article’s content these prefixes must be used for
            these URLs.
          </p>
        </section>
        <section id="article">
          <h3>Article Structure</h3>
          <p>
            The article content is everything that is contained inside the first
            <code>article</code> element in document order that has a
            <code>typeof="schema:ScholarlyArticle"</code>. Everything part of the <code>body</code>
            outside of that subtree is ignored. This enables publishers to surround the article
            content with any amount of supporting markup, for instance for headers, footers,
            or navigation, as well as to wrap the article inside arbitrary markup that may be
            needed for stylistic reasons.
          </p>
          <p>
            The first element child of the <code>article</code> element must be an <code>h1</code>
            heading that serves as the primary title for the document. It may itself contain markup.
            The white-space-normalised text value of the <code>h1</code> must appear as a substring
            of the white-space-normalised text value of the <code>title</code> element. This ensures
            semantic alignment between the two, while enabling publishers to add their name to the
            <code>title</code> so as to identify themselves there alongside the content.
          </p>
          <p>
            The containers for authors, affiliations, and funding are not specified yet. There is
            an <a href="https://github.com/scienceai/scholarly.vernacular.io/issues">open issue</a>
            on this topic.
          </p>
          <p>
            Any children of <code>article</code> that are not <code>section</code> elements are
            ignored.
          </p>
          <p>
            The <code>section</code> elements can be nested arbitrarily deep. Each
            <code>section</code> element must have as its first element child an <code>hX</code>
            heading element the numeric part of which must be the number of <code>section</code>
            ancestor elements that heading elements has up to the <code>article</code> element, plus
            one. If the numeric part is greater than 6, then <code>h6</code> must be used but an
            <code>aria-level</code> attribute must be added that reflects the accurate depth.
            (The <code>aria-level</code> attribute can be used at lower depths but is not required
            there.)
          </p>
          <p>
            Each <code>section</code> element may contain an arbitrary number of
            <a href="#hunk-elements">hunk elements</a>, followed by an arbitrary number of
            <code>section</code> elements being subsections. Note that
            <a href="#hunk-elements">hunk elements</a> must imperatively appear <em>before</em> the
            subsections.
          </p>
          <p>
            Sections are expected to be typed using the <code>typeof</code> attribute. The following
            <code>typeof</code> values are currently understood:
          </p>
          <ul>
            <li><code>sa:Abstract</code></li>
            <li><code>sa:MaterialsAndMethods</code></li>
            <li><code>sa:Results</code></li>
            <li><code>sa:Conclusion</code></li>
            <li><code>sa:Acknowledgements</code></li>
            <li><code>sa:ReferenceList</code></li>
          </ul>
          <p>
            Hopefully these types are largely self-documenting, they are described further in the
            Scholarly Article ontology
            (<a href="#ref-sa-ontology" property="schema:citation">Science.AI, 2015a</a>).
          </p>
          <p>
            The section typed <code>sa:ReferenceList</code> has special processing rules described
            in the <a href="#references-section">References section</a>.
          </p>
        </section>
        <section id="hunk-elements">
          <h3>Hunk Elements</h3>
          <p>
            <dfn>Hunk elements</dfn> are the meaningful blocks from which sections are built. They
            contain text and <a href="#inline-element">inline elements</a>. There are several
            types of hunk elements.
          </p>
          <p>
            The most common hunk element is <code>p</code>, which is used to capture paragraphs. It
            requires no special processing.
          </p>
          <p>
            The <code>aside</code> hunk element is used to capture text boxes. If it contains an
            <code>hX</code> heading element, that element must be its first element child and its
            numeric part must reflect its depth, making use of <code>aria-level</code> according to
            the same rules as apply for <code>section</code>. The other childre of
            <code>aside</code> must all be hunk elements.
          </p>
          <p>
            The <code>figure</code> element is a general container for content units that are
            embedded inside the main body of the text. It can come in several flavours that are
            dictated by its <code>typeof</code> attribute.
          </p>
          <p>
            If <code>figure</code> has <code>typeof="sa:Image"</code> then it is an image container.
            It must contain an <code>img</code> child element and should contain a
            <code>figcaption</code> labelling that image. An example of an image figure would be:
          </p>
          <figure typeof="sa:Image">
            <img src="hop-less.png" width="880" height="655">
            <figcaption>
              Reconstruction of Sthenurus stirlingi, by <NAME>; in
              «<cite><a
              href="http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0109888">Locomotion
              in Extinct Giant Kangaroos: Were Sthenurines Hop-Less Monsters?</a></cite>», by
              <NAME>, <NAME>, <NAME>.
            </figcaption>
          </figure>
          <p>
            If <code>figure</code> has <code>typeof="sa:Table"</code> then it is a table container.
            It must contain nothing other than a <code>table</code> element. If a caption is
            available, it should be included using the <code>caption</code> child element of the
            <code>table</code>, and not the <code>figcaption</code> child of the
            <code>figure</code>.
          </p>
          <p>
            If <code>figure</code> has <code>typeof="sa:Formula"</code> then it is a formula
            container. It must contain a <code>math</code> element and optionally a
            <code>figcaption</code> describing the formula. The <code>math</code> element must be
            valid MathML 3. Additionally, given the dismal state of support for MathML in Web
            browser the <code>math</code> element must contain an <code>annotation</code>
            descendant with the TeX equivalent of the formula.
          </p>
          <p>
            If <code>figure</code> has <code>typeof="sa:XXXX"</code> (see the
            <a href="https://github.com/scienceai/scholarly.vernacular.io/issues/3">relevant
            issue</a>) then it is a code container. It must contain a <code>pre</code> element
            and optionally a <code>figcaption</code>. The <code>pre</code> element must contain as
            its only child a <code>code</code> element. The <code>code</code> element should
            contain a description of the type of code that it contains (see the previously mentioned
            issue for discussion of how).
          </p>
        </section>
        <section id="inline-elements">
          <h3>Inline Elements</h3>
          <p>
            <dfn>Inline elements</dfn> essentially decorate, describe, and enrich text. Inside of
            <a href="#hunk-elements">hunk elements</a>, of heading elements, and of captioning
            elements (<code>caption</code> and <code>figcaption</code>) the following inline
            elements can be used (and where applicable they can nest within one another):
          </p>
          <ul>
            <li><code>a</code></li>
            <li><code>abbr</code></li>
            <li><code>bdi</code></li>
            <li><code>bdo</code></li>
            <li><code>cite</code></li>
            <li><code>code</code></li>
            <li><code>data</code></li>
            <li><code>del</code></li>
            <li><code>dfn</code></li>
            <li><code>em</code></li>
            <li><code>img</code> (for small, contextual images that should not be figures)</li>
            <li><code>ins</code></li>
            <li><code>kbd</code></li>
            <li><code>mark</code></li>
            <li><code>math</code> (for inline equations that should not be figures; they must also contain a TeX annotation)</li>
            <li><code>meter</code></li>
            <li><code>q</code></li>
            <li><code>ruby</code> (with embedded <code>rb</code>, <code>rt</code>, <code>rtc</code>, and <code>rp</code>)</li>
            <li><code>samp</code></li>
            <li><code>span</code></li>
            <li><code>strong</code></li>
            <li><code>sub</code></li>
            <li><code>sup</code></li>
            <li><code>svg</code> (for small, contextual images that should not be figures)</li>
            <li><code>time</code></li>
            <li><code>var</code></li>
            <li><code>wbr</code></li>
          </ul>
          <p>
            If an <code>a</code> element is linking to a citation, then it must have
            <code>property="schema:citation"</code>; if it is linking to a figure it must have
            <code>property="schema:hasPart"</code>. These are known as <dfn>flavoured links</dfn>,
            they can be used to enhance the user experience by treating their behaviour differently
            from regular links.
          </p>
        </section>
        <section id="references-section">
          <h3>The References Section</h3>
          <p>
            The references section is a special type of <code>section</code> element with
            <code>typeof="sa:ReferenceList"</code>.
          </p>
          <p>
            Apart from its heading element, it must contain nothing other than an <code>ol</code>
            or a <code>dl</code> element.
          </p>
          <p>
            If using a <code>dl</code> element, its content must be exclusively a strictly
            alternating sequence of <code>dt</code> then <code>dd</code> elements, with the latter
            being the citation-bearing element. The <code>dt</code> is used as a label in some
            citation formats.
          </p>
          <p>
            If using an <code>ol</code>, then its content is only <code>li</code> elements that are
            the citation-bearing elements.
          </p>
          <p>
            The citation-bearing element will have an <code>id</code> and be
            <code>typeof="sa:ScholarlyArticle"</code> (see
            <a href="https://github.com/scienceai/scholarly.vernacular.io/issues/2">#2</a>). Its
            content follows the «flexcite» format (being defined as part of this document, see
            <a href="https://github.com/scienceai/scholarly.vernacular.io/issues/4">#4</a>). The
            references section of this document is an example.
          </p>
        </section>
      </section>
      <section typeof="sa:Conclusion" id="conclusion">
        <h2>Conclusion</h2>
        <p>
          Scholarly HTML is currently a work in progress and is open to change. If you have
          feedback, simply
          <a href="https://github.com/scienceai/scholarly.vernacular.io/issues">open an issue</a> on
          GitHub, or <a href="https://github.com/scienceai/scholarly.vernacular.io">make a pull
          request</a>.
        </p>
        <p>
          We believe that this vernacular establishes that it is possible to capture scholarly
          information accurately, while retaining a clean HTML structure that does minimum violence
          to the language’s spirit.
        </p>
        <p>
          The science.ai platform currently supports (most of) Scholarly HTML, but our goal is not
          to make this a proprietary standard — quite the opposite. We would like the scholarly
          publishing as much as possible to align on common practices so that we can all focus on
          problems more interesting than content conversion.
        </p>
      </section>
      <section typeof="sa:ReferenceList" id="references">
        <h2>References</h2>
        <dl>
          <dt>NYT, 2014</dt>
          <dd id="ref-nyt" typeof="schema:ScholarlyArticle"
              resource="http://www.scribd.com/doc/224608514/The-Full-New-York-Times-Innovation-Report">
            <cite property="schema:name"><a
              href="http://www.scribd.com/doc/224608514/The-Full-New-York-Times-Innovation-Report">The
              Full New York Times Innovation Report</a></cite>,
            by
            <span property="schema:author" typeof="schema:Person">
              <span property="schema:name">New York Times</span>
            </span>;
            <time property="schema:datePublished" datetime="2014-03" datatype="xsd:gYearMonth">2014 Mar</time>.
          </dd>
          <dt>Science.AI, 2015a</dt>
          <dd id="ref-sa-ontology" typeof="schema:ScholarlyArticle"
              resource="https://github.com/scienceai/scholarly-article/blob/master/scholarly-article.json">
            <cite property="schema:name"><a
              href="https://github.com/scienceai/scholarly-article/blob/master/scholarly-article.json">The
              Scholarly Article ontology</a></cite>,
            by
            <span property="schema:author" typeof="schema:Person">
              <span property="schema:name">Science.AI</span>
            </span>;
            <time property="schema:datePublished" datetime="2015-09" datatype="xsd:gYearMonth">2015 Sep</time>.
          </dd>
          <dt>Science.AI, 2015b</dt>
          <dd id="ref-vernacular" typeof="schema:ScholarlyArticle" resource="http://vernacular.io/">
            <cite property="schema:name"><a href="http://vernacular.io/">Vernacular — HTML Made Special</a></cite>,
            by
            <span property="schema:author" typeof="schema:Person">
              <span property="schema:name">Science.AI</span>
            </span>;
            <time property="schema:datePublished" datetime="2015-10" datatype="xsd:gYearMonth">2015 Oct</time>.
          </dd>
        </dl>
      </section>
    </article>
    <footer>
      <p>
        <a href="http://creativecommons.org/licenses/by/4.0/">CC-BY</a>
        <a href="https://twitter.com/sciencedotai">@sciencedotai</a>
        •
        Contributors:
        <a href="https://twitter.com/robinberjon">@robinberjon</a>
        •
        Brought to you by the
        <a href="http://science.ai/"><img src="sciencedotai.svg" alt="science.ai logo" height="20px"></a>
        League of JStice
      </p>
    </footer>
  </body>
</html>
<commit_msg>add meta viewport, fixes #6<commit_after><!DOCTYPE html>
<html lang="en-GB">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width">
    <title>Scholarly HTML — Markedly Smart</title>
    <link rel="stylesheet" href="scholarly.css">
    <link rel="stylesheet" href="node_modules/prismjs/themes/prism-coy.css">
    <script src="node_modules/prismjs/prism.js" defer></script>
  </head>
  <body prefix="schema: http://schema.org/ xsd: http://www.w3.org/2001/XMLSchema# sa: https://ns.science.ai/">
    <header>
      <p class="title">Scholarly HTML</p>
      <p class="subtitle">Markedly Smart</p>
    </header>
    <article id="what" typeof="schema:ScholarlyArticle">
      <h1>What is Scholarly HTML?</h1>
      <!--
        XXX
          - favicon
          - script that adds sectionals
          - highlight on targets for citations
      -->
      <section typeof="sa:Abstract" id="abstract">
        <h2>Abstract</h2>
        <p>
          Scholarly HTML is a domain-specific data format built entirely on open standards that
          enables the interoperable exchange of scholarly articles in a manner that is compatible
          with off-the-shelf browsers. This document describes how Scholarly HTML works and how it
          is encoded as a document. It is, itself, written in Scholarly HTML.
        </p>
      </section>
      <section typeof="sa:MaterialsAndMethods" id="motivation">
        <h2>Motivation</h2>
        <p>
          Scholarly articles are still primarily encoded as unstructured graphics formats in which
          most of the information initially created by research, or even just in the text, is lost.
          This was an acceptable, if deplorable, condition when viable alternatives did not seem
          possible, but document technology has today reached a level of maturity and universality
          that makes this situation no longer tenable. Information cannot be disseminated if it is
          destroyed before even having left its creator’s laptop.
        </p>
        <p>
          According to the New York Times, adding structured information to their recipes (instead
          of exposing simply as plain text) improved their discoverability to the point of producing
          an immediate rise of 52 percent in traffic (<a href="#ref-nyt"
          property="schema:citation">NYT, 2014</a>). At this point in time, cupcake recipes are
          reaping greater benefits from modern data format practices than the whole scientific
          endeavour.
        </p>
        <p>
          This is not solely a loss for the high principles of knowledge sharing in science, it also
          has very immediate pragmatic consequences. Any tool, any service that tries to integrate
          with scholarly publishing has to spend the brunt of its complexity (or budget) extracting
          data the author would have willingly shared out of antiquated formats. This places
          stringent limits on the improvement of the scholarly toolbox, on the discoverability of
          scientific knowledge, and particularly on processes of meta-analysis.
        </p>
        <p>
          To address these issues, we have followed an approach rooted in established best practices
          for the reuse of open, standard formats. The «HTML Vernacular» body of practice provides
          guidelines for the creation of domain-specific data formats that make use of HTML’s
          inherent extensibility (<a href="#ref-vernacular" property="schema:citation">Science.AI,
          2015b</a>). Using the vernacular foundation overlaid with «schema.org» metadata we have
          produced a format for the interchange of scholarly articles built on open standards, ready
          for all to use.
        </p>
        <p>
          Our high-level goals were:
        </p>
        <ul>
          <li>
            Uncompromisingly enabling structured metadata, accessibility, and internationalisation.
          </li>
          <li>
            Pragmatically working in Web browsers, even if it occasionally incurs some markup
            overhead.
          </li>
          <li>
            Powerfully customisable for inclusion in arbitrary Web sites, while remaining easy to
            process and interoperable.
          </li>
          <li>
            Entirely built on top of open, royalty-free standards.
          </li>
          <li>
            Long-term viability as a data format.
          </li>
        </ul>
        <p>
          Additionally, in view of the specific problem we addressed, in the creation of this
          vernacular we have favoured the reliability of interchange over ease of authoring; but
          have nevertheless attempted to cater to the later as much as possible.
        </p>
      </section>
      <section typeof="sa:Results" id="definition">
        <h2>Definition</h2>
        <p>
          A <dfn id="scholarly-html">Scholarly HTML document</dfn> is a valid HTML document that
          follows some additional rules to specialised its meaning and make it predictable to
          processors wishing to produce or consume scholarly articles. These rules are outlined in
          the following sections.
        </p>
        <section id="file-headers">
          <h3>File &amp; Supporting Structure</h3>
          <p>
            The document must be encoded in UTF-8, and transmitted with a media type of
            <code>text/html</code>. It must feature a <code>DOCTYPE</code> as its preamble.
          </p>
          <p>
            The <code>html</code> root element must feature a valid <code>lang</code> attribute.
          </p>
          <p>
            The <code>head</code> element of the document must contain a
            <code class="language-html">&lt;meta charset="utf-8"></code> element (preferable as its
            first child), a
            <code class="language-html">&lt;meta name="viewport" content="width=device-width"></code>
            element (and no other viewport <code>meta</code>), and a <code>title</code> element. All
            the other content of the <code>head</code> is ignored.
          </p>
          <p>
            The <code>body</code> element must have a <code>prefix</code> attribute, which must
            declare the following mapping:
          </p>
          <table typeof="schema:Table">
            <thead>
              <tr>
                <th>Prefix</th>
                <th>URL</th>
              </tr>
            </thead>
            <tr>
              <td>schema</td>
              <td>http://schema.org/</td>
            </tr>
            <tr>
              <td>xsd</td>
              <td>http://www.w3.org/2001/XMLSchema#</td>
            </tr>
            <tr>
              <td>sa</td>
              <td>https://ns.science.ai/</td>
            </tr>
            <caption>
              The list of mappings that must be declared by the <code>body</code> element.
            </caption>
          </table>
          <p>
            Having to declare prefixes is undoubtably an annoyance and it does hurt the human
            authorability of the format (since hand-creating a document essentially requires a
            boilerplate prefix declaration). This trade-off is made for several reasons. The most
            important motivation is that having predictable prefixes means that the content can be
            styled with CSS using reliable attribute selectors on the semantic information that
            describes the document’s structure. The alternative would be to use URLs everywhere,
            such that instead of <code>sa:Abstract</code> we would have
            <code>https://ns.science.ai/Abstract</code>; but in practice that approach is more
            painful since the content then becomes bloated with URLs that are longer than is
            comfortable.
          </p>
          <p>
            The RDFa content of the article must systematically make use of these prefixes when the
            values match their URLs as prefixes. Authors may declare other prefix-URL mappings in
            the <code>prefix</code> attribute of the <code>body</code> element (or
            <code>prefix</code> attributes elsewhere), including other prefixes mapping to the same
            URLs if needed, but inside of the article’s content these prefixes must be used for
            these URLs.
          </p>
        </section>
        <section id="article">
          <h3>Article Structure</h3>
          <p>
            The article content is everything that is contained inside the first
            <code>article</code> element in document order that has a
            <code>typeof="schema:ScholarlyArticle"</code>. Everything part of the <code>body</code>
            outside of that subtree is ignored. This enables publishers to surround the article
            content with any amount of supporting markup, for instance for headers, footers,
            or navigation, as well as to wrap the article inside arbitrary markup that may be
            needed for stylistic reasons.
          </p>
          <p>
            The first element child of the <code>article</code> element must be an <code>h1</code>
            heading that serves as the primary title for the document. It may itself contain markup.
            The white-space-normalised text value of the <code>h1</code> must appear as a substring
            of the white-space-normalised text value of the <code>title</code> element. This ensures
            semantic alignment between the two, while enabling publishers to add their name to the
            <code>title</code> so as to identify themselves there alongside the content.
          </p>
          <p>
            The containers for authors, affiliations, and funding are not specified yet. There is
            an <a href="https://github.com/scienceai/scholarly.vernacular.io/issues">open issue</a>
            on this topic.
          </p>
          <p>
            Any children of <code>article</code> that are not <code>section</code> elements are
            ignored.
          </p>
          <p>
            The <code>section</code> elements can be nested arbitrarily deep. Each
            <code>section</code> element must have as its first element child an <code>hX</code>
            heading element the numeric part of which must be the number of <code>section</code>
            ancestor elements that heading elements has up to the <code>article</code> element, plus
            one. If the numeric part is greater than 6, then <code>h6</code> must be used but an
            <code>aria-level</code> attribute must be added that reflects the accurate depth.
            (The <code>aria-level</code> attribute can be used at lower depths but is not required
            there.)
          </p>
          <p>
            Each <code>section</code> element may contain an arbitrary number of
            <a href="#hunk-elements">hunk elements</a>, followed by an arbitrary number of
            <code>section</code> elements being subsections. Note that
            <a href="#hunk-elements">hunk elements</a> must imperatively appear <em>before</em> the
            subsections.
          </p>
          <p>
            Sections are expected to be typed using the <code>typeof</code> attribute. The following
            <code>typeof</code> values are currently understood:
          </p>
          <ul>
            <li><code>sa:Abstract</code></li>
            <li><code>sa:MaterialsAndMethods</code></li>
            <li><code>sa:Results</code></li>
            <li><code>sa:Conclusion</code></li>
            <li><code>sa:Acknowledgements</code></li>
            <li><code>sa:ReferenceList</code></li>
          </ul>
          <p>
            Hopefully these types are largely self-documenting, they are described further in the
            Scholarly Article ontology
            (<a href="#ref-sa-ontology" property="schema:citation">Science.AI, 2015a</a>).
          </p>
          <p>
            The section typed <code>sa:ReferenceList</code> has special processing rules described
            in the <a href="#references-section">References section</a>.
          </p>
        </section>
        <section id="hunk-elements">
          <h3>Hunk Elements</h3>
          <p>
            <dfn>Hunk elements</dfn> are the meaningful blocks from which sections are built. They
            contain text and <a href="#inline-element">inline elements</a>. There are several
            types of hunk elements.
          </p>
          <p>
            The most common hunk element is <code>p</code>, which is used to capture paragraphs. It
            requires no special processing.
          </p>
          <p>
            The <code>aside</code> hunk element is used to capture text boxes. If it contains an
            <code>hX</code> heading element, that element must be its first element child and its
            numeric part must reflect its depth, making use of <code>aria-level</code> according to
            the same rules as apply for <code>section</code>. The other childre of
            <code>aside</code> must all be hunk elements.
          </p>
          <p>
            The <code>figure</code> element is a general container for content units that are
            embedded inside the main body of the text. It can come in several flavours that are
            dictated by its <code>typeof</code> attribute.
          </p>
          <p>
            If <code>figure</code> has <code>typeof="sa:Image"</code> then it is an image container.
            It must contain an <code>img</code> child element and should contain a
            <code>figcaption</code> labelling that image. An example of an image figure would be:
          </p>
          <figure typeof="sa:Image">
            <img src="hop-less.png" width="880" height="655">
            <figcaption>
              Reconstruction of Sthenurus stirlingi, by <NAME>; in
              «<cite><a
              href="http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0109888">Locomotion
              in Extinct Giant Kangaroos: Were Sthenurines Hop-Less Monsters?</a></cite>», by
              <NAME>, <NAME>, <NAME>.
            </figcaption>
          </figure>
          <p>
            If <code>figure</code> has <code>typeof="sa:Table"</code> then it is a table container.
            It must contain nothing other than a <code>table</code> element. If a caption is
            available, it should be included using the <code>caption</code> child element of the
            <code>table</code>, and not the <code>figcaption</code> child of the
            <code>figure</code>.
          </p>
          <p>
            If <code>figure</code> has <code>typeof="sa:Formula"</code> then it is a formula
            container. It must contain a <code>math</code> element and optionally a
            <code>figcaption</code> describing the formula. The <code>math</code> element must be
            valid MathML 3. Additionally, given the dismal state of support for MathML in Web
            browser the <code>math</code> element must contain an <code>annotation</code>
            descendant with the TeX equivalent of the formula.
          </p>
          <p>
            If <code>figure</code> has <code>typeof="sa:XXXX"</code> (see the
            <a href="https://github.com/scienceai/scholarly.vernacular.io/issues/3">relevant
            issue</a>) then it is a code container. It must contain a <code>pre</code> element
            and optionally a <code>figcaption</code>. The <code>pre</code> element must contain as
            its only child a <code>code</code> element. The <code>code</code> element should
            contain a description of the type of code that it contains (see the previously mentioned
            issue for discussion of how).
          </p>
        </section>
        <section id="inline-elements">
          <h3>Inline Elements</h3>
          <p>
            <dfn>Inline elements</dfn> essentially decorate, describe, and enrich text. Inside of
            <a href="#hunk-elements">hunk elements</a>, of heading elements, and of captioning
            elements (<code>caption</code> and <code>figcaption</code>) the following inline
            elements can be used (and where applicable they can nest within one another):
          </p>
          <ul>
            <li><code>a</code></li>
            <li><code>abbr</code></li>
            <li><code>bdi</code></li>
            <li><code>bdo</code></li>
            <li><code>cite</code></li>
            <li><code>code</code></li>
            <li><code>data</code></li>
            <li><code>del</code></li>
            <li><code>dfn</code></li>
            <li><code>em</code></li>
            <li><code>img</code> (for small, contextual images that should not be figures)</li>
            <li><code>ins</code></li>
            <li><code>kbd</code></li>
            <li><code>mark</code></li>
            <li><code>math</code> (for inline equations that should not be figures; they must also contain a TeX annotation)</li>
            <li><code>meter</code></li>
            <li><code>q</code></li>
            <li><code>ruby</code> (with embedded <code>rb</code>, <code>rt</code>, <code>rtc</code>, and <code>rp</code>)</li>
            <li><code>samp</code></li>
            <li><code>span</code></li>
            <li><code>strong</code></li>
            <li><code>sub</code></li>
            <li><code>sup</code></li>
            <li><code>svg</code> (for small, contextual images that should not be figures)</li>
            <li><code>time</code></li>
            <li><code>var</code></li>
            <li><code>wbr</code></li>
          </ul>
          <p>
            If an <code>a</code> element is linking to a citation, then it must have
            <code>property="schema:citation"</code>; if it is linking to a figure it must have
            <code>property="schema:hasPart"</code>. These are known as <dfn>flavoured links</dfn>,
            they can be used to enhance the user experience by treating their behaviour differently
            from regular links.
          </p>
        </section>
        <section id="references-section">
          <h3>The References Section</h3>
          <p>
            The references section is a special type of <code>section</code> element with
            <code>typeof="sa:ReferenceList"</code>.
          </p>
          <p>
            Apart from its heading element, it must contain nothing other than an <code>ol</code>
            or a <code>dl</code> element.
          </p>
          <p>
            If using a <code>dl</code> element, its content must be exclusively a strictly
            alternating sequence of <code>dt</code> then <code>dd</code> elements, with the latter
            being the citation-bearing element. The <code>dt</code> is used as a label in some
            citation formats.
          </p>
          <p>
            If using an <code>ol</code>, then its content is only <code>li</code> elements that are
            the citation-bearing elements.
          </p>
          <p>
            The citation-bearing element will have an <code>id</code> and be
            <code>typeof="sa:ScholarlyArticle"</code> (see
            <a href="https://github.com/scienceai/scholarly.vernacular.io/issues/2">#2</a>). Its
            content follows the «flexcite» format (being defined as part of this document, see
            <a href="https://github.com/scienceai/scholarly.vernacular.io/issues/4">#4</a>). The
            references section of this document is an example.
          </p>
        </section>
      </section>
      <section typeof="sa:Conclusion" id="conclusion">
        <h2>Conclusion</h2>
        <p>
          Scholarly HTML is currently a work in progress and is open to change. If you have
          feedback, simply
          <a href="https://github.com/scienceai/scholarly.vernacular.io/issues">open an issue</a> on
          GitHub, or <a href="https://github.com/scienceai/scholarly.vernacular.io">make a pull
          request</a>.
        </p>
        <p>
          We believe that this vernacular establishes that it is possible to capture scholarly
          information accurately, while retaining a clean HTML structure that does minimum violence
          to the language’s spirit.
        </p>
        <p>
          The science.ai platform currently supports (most of) Scholarly HTML, but our goal is not
          to make this a proprietary standard — quite the opposite. We would like the scholarly
          publishing as much as possible to align on common practices so that we can all focus on
          problems more interesting than content conversion.
        </p>
      </section>
      <section typeof="sa:ReferenceList" id="references">
        <h2>References</h2>
        <dl>
          <dt>NYT, 2014</dt>
          <dd id="ref-nyt" typeof="schema:ScholarlyArticle"
              resource="http://www.scribd.com/doc/224608514/The-Full-New-York-Times-Innovation-Report">
            <cite property="schema:name"><a
              href="http://www.scribd.com/doc/224608514/The-Full-New-York-Times-Innovation-Report">The
              Full New York Times Innovation Report</a></cite>,
            by
            <span property="schema:author" typeof="schema:Person">
              <span property="schema:name">New York Times</span>
            </span>;
            <time property="schema:datePublished" datetime="2014-03" datatype="xsd:gYearMonth">2014 Mar</time>.
          </dd>
          <dt>Science.AI, 2015a</dt>
          <dd id="ref-sa-ontology" typeof="schema:ScholarlyArticle"
              resource="https://github.com/scienceai/scholarly-article/blob/master/scholarly-article.json">
            <cite property="schema:name"><a
              href="https://github.com/scienceai/scholarly-article/blob/master/scholarly-article.json">The
              Scholarly Article ontology</a></cite>,
            by
            <span property="schema:author" typeof="schema:Person">
              <span property="schema:name">Science.AI</span>
            </span>;
            <time property="schema:datePublished" datetime="2015-09" datatype="xsd:gYearMonth">2015 Sep</time>.
          </dd>
          <dt>Science.AI, 2015b</dt>
          <dd id="ref-vernacular" typeof="schema:ScholarlyArticle" resource="http://vernacular.io/">
            <cite property="schema:name"><a href="http://vernacular.io/">Vernacular — HTML Made Special</a></cite>,
            by
            <span property="schema:author" typeof="schema:Person">
              <span property="schema:name">Science.AI</span>
            </span>;
            <time property="schema:datePublished" datetime="2015-10" datatype="xsd:gYearMonth">2015 Oct</time>.
          </dd>
        </dl>
      </section>
    </article>
    <footer>
      <p>
        <a href="http://creativecommons.org/licenses/by/4.0/">CC-BY</a>
        <a href="https://twitter.com/sciencedotai">@sciencedotai</a>
        •
        Contributors:
        <a href="https://twitter.com/robinberjon">@robinberjon</a>
        •
        Brought to you by the
        <a href="http://science.ai/"><img src="sciencedotai.svg" alt="science.ai logo" height="20px"></a>
        League of JStice
      </p>
    </footer>
  </body>
</html>

{'fraction_non_alphanumeric': 0.10598712446351931, 'fraction_numerical': 0.0061158798283261805, 'mean_word_length': 2.115040106951872, 'pattern_counts': {'":': 0, '<': 1246, '<?xml version=': 0, '>': 1249, 'https://': 26, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '41231', 'n_tokens_mistral': 12584, 'n_tokens_neox': 12082, 'n_words': 4362}