cuts

from section id=abstract
      <!--
      <p>Map Markup Language is a text format for encoding map information for the World Wide Web.</p>
      <p>The objective of MapML is to allow Web-based user agent software (browsers and others) to display and edit maps and map data without necessary customization.</p>

      <p>The <a href="https://html.spec.whatwg.org/multipage/image-maps.html#the-map-element">standard HTML <code>map</code></a> element allows the HTML author to designate sub-areas of an image to be used as hyperlinks, creating a two-dimensional "image map".  
        This functionality, while useful, is limited to the simplest of mapping applications.  A more generally useful <a href="#the-map-element"><code>map</code></a> element would enable (functions like) zooming and panning of the map 
          in a traditional Web mapping way, while simultaneously being simple and declarative for an HTML author to include on their Web page.  This specification proposes the syntax and semantics of an extended <code>map</code> element.</p>
      <p>The applications of Web maps are diverse.  The wide scope of use of Web maps appears similarly broad to that of other Web media types, such as video or audio.  In other words, there are a multitude of reasons for wanting to include
      a map on your Web page.  The HTML <a href="#the-map-element"><code>map</code></a> element proposed by this document should be provider-agnostic, 
      and should only depend on Web standards, including Uniform Resource Identifiers, Document Object Model, Cascading Style Sheets and media types.</p>
      -->

from section id=sotd

        <!-- (!) The intent should be clear from the "abstract" and "introduction" sections, as well as the linked explainer.
        <section>
        <h3>Intent of this Specification</h3>
        
        <p>This specification describes Map Markup Language (MapML), which is a hypertext document format for maps. This specification is also intended as a proposal to the HTML Working Group to extend the semantics of the <a href="https://html.spec.whatwg.org/multipage/image-maps.html#the-map-element">standard HTML <code>map</code></a> element.</p>

        <p>
          MapML is needed because while Web browsers implement HTML and SVG, including the <code>&lt;map&gt;</code> element, those implementations do not meet the requirements of the broader Web mapping community. On the one hand, the
          semantics of maps are quite different from those of Scalable Vector Graphics, while on the other hand, the semantics of the HTML <code>map</code> element are incomplete or insufficient relative to modern Web maps and mapping in
          general. Robust web maps are implemented by a variety of non-standard technologies. Web maps do not work without script support, making their creation a job beyond the realm of beginners' skill sets, while making them potentially
          inaccessible due to developer inattention. In order to improve collaboration and integration of the mapping and Web communities, it is desirable to enhance or augment the functionality of the &lt;map&gt; (or a similar &lt;new&gt;)
          element in HTML to include the accessible user interface functions of modern web maps (e.g. panning, zooming, searching for, and zooming to, styling, identifying feature properties, etc.), while maintaining a simple, declarative,
          accessible interface for HTML authors. At the same time, the DOM interface to the new or improved elements should provide low-level programmable mapping hooks in the style of the Web.
        </p>
        <p>To achieve this it is necessary to define a new hypertext format (MapML) and media type which encodes map semantics.</p>
        <p>
          This document is an evolving proposal to the Web and Mapping communities. Collaborators and implementation experience is requested. The intention is to define a new hypertext format (MapML) which encodes map layer semantics
          directly, but which leverages existing standards where possible and desirable, such as Cascading Style Sheets and OGC Simple Features, for example. MapML will provide an essential part of the contract between Web user agents and
          Web servers when map features are exchanged, in a manner based on the architectural style of the Web, in a similar way to how HTML provides (part of) the contract for documents.
        </p>
        </section>
        -->

from section id=use cases and requirements

        <!-- Move this section into a separate document (https://github.com/Maps4HTML/MapML/issues/3)
        <section>
        <h3 id="use-cases">Use Cases</h3>
        <p>The following usage scenarios illustrate some of the ways in which <strong>Map Markup Language</strong> might be used for various applications:</p>

        <ul>
          <li>
            <strong>Tiled maps</strong> <p>Modern map services are dominantly created by composing adjacent map 'tiles' (often bitmapped images) into a coherent and unified image of a map.</p>
          </li>
          <li>
            <strong>Image-based maps</strong> <p>Web services typically produce a single geo-referenced image which constitutes a map. MapML encodes URL references to such images, together with appropriate georeferencing metadata.</p>
          </li>
          <li>
            <strong>Vector-based maps</strong> <p>Geospatial databases, for example PostGIS, are able to serve and manipulate vector representations of features which can be symbolized according to their properties.</p>
          </li>
          <li>
            <strong>Multi-layer maps</strong> <p>Maps are often required to overlay information in such a way as to enable both visual and automatated spatial relationship processing. MapML will support the layering of information using the
          <a href="https://www.w3.org/TR/SVG/render.html#PaintersModel">painters model</a>, wherein elements are drawn in document order overtop of earlier elements, together with CSS styling (transparency) techniques.</p>
          </li>
          <li>
            <strong>Use CSS for map styles</strong> <p>MapML elements should be style-able with CSS rules supplied by the MapML author. For example, the MapML author should be able to link to a stylesheet from a MapML document.</p>
          </li>
          <li>
            <strong>Location search</strong> <p>A MapML service might want to allow service consumers to search within the contents of a service for a place name or an address, over which the map is repositioned when a selection is made. MapML
          should provide (markup) facilities to enable such searches without forcing the client download large amounts of geospatial data.</p>
          </li>
          <li>
            <strong>Hyperlinks between and within services</strong> <p>MapML should allow service-level links such that service providers can link together / federate to provide apparently seamless spatial coverage.</p>
          </li>
          <li>
            <strong>Feature identification</strong> <p>If a MapML document includes features, the MapML author should be able to markup any or all of those features in a way which lends itself to feature identification and property display.</p>
          </li>
          <li>
            <strong>Attribution</strong> <p>MapML documents encode citation information on a per-request basis, making it available as markup in the response.</p>
          </li>
        </ul>      

        <p>The following use cases illustrate some of the ways in which <strong>the <a href="#the-map-element"><code>map</code></a> element</strong> might be used in Web mapping applications:</p>
      
        <ul>
          <li id="uc-multiple-layers"><strong>Multiple, user-controllable map layers</strong>
            <p>The <a href="#the-map-element"><code>map</code></a> element allows HTML authors to add zero or more map layers to the map, with optional controls enabled declaratively.</p>
          </li>
          
          <li id="uc-feature-identification"><strong>Selection / identification / description of map features</strong>
            <p>
              The user should be able to interact with individual map features as individual elements, with or without hyperlinks.
            </p>
          </li>
          <li id="uc-zooming"><strong>Rescaling to expose greater detail (zooming)</strong>
            <p>The user should be able to zoom in or out on the map to expose more or less detail as desired / possible.</p>
             
          </li>
          <li id="uc-panning"><strong>Repositioning to examine relationships between places (panning)</strong>
            <p>The user should be able to pan the map so as to examine locations other than the default or initial location displayed, as desired / possible.</p>
          </li>
          <li id="uc-css"><strong>Using Cascading Style Sheets to enable HTML authors to control the style of their own map content.</strong>
            <p>The HTML author should be able to use Cascading Style Sheets on the <code>map</code> element and its children so as to create the user experience desired, 
              with the caveat that the style of features in map sources / services should be under the control of the exclusive control of the map content author, per MapML requirements. In brief, the HTML author 
            should not be able to style content that does not belong to them, but should be able to create and style features displayed on the map from their own domain.</p>
          </li>
          <li id="uc-features"><strong>Map links of various shapes, including points, lines, polygons, circles and rectangles</strong>
            <p>HTML authors should be able to place and style links on a web map, allowing navigation of the browser through user selection.  </p>
          </li>
          <li id="uc-map-links"><strong>Links within and between services to enable a "Web of maps"</strong>
            <p>A map layer could be "distributed" over many URLs, and the user agent would seamlessly present the contents of those URLs to the user, possibly although not necessarily as though
            they were a single end point.  For example, a response document should be able to communicate a link to an adjacent zoom level or geographic area in the response entity and the user agent 
            could conditionally follow that link depending on the gestures of the user. </p>
          </li>
          <li id="uc-api"><strong>API-level access to the map, its layers, features and events</strong>
            <p>Scripting has an important place in the presentation of map information.  Declarative web maps should be able to be progressively enhanced through the use of script.
            Furthermore, web maps should emit map- and control-specific events which support progressive enhancement.</p>
          </li>
          <li id="uc-crawlable"><strong>Crawler-generated location-enabled, searchable indexes of Web content</strong>
            <p>Web maps should serve to geocode content in a Web page, such that crawlers may be able to augment their indexes with location information, leading to enhanced discovery possibilities for
            Web search users.</p>
          </li>
        </ul>
        </section>
        <section>
        <h3 id="requirements">Requirements</h3>
        <ul>
          <li id="req-uniform-interface">
          <strong>Uniform interface</strong><p>No URL recipes should be required to be supported by clients - support for simple opaque URLs and standardized media types should be all that is required clients. Application state / state
          transitions should be conveyed in markup.</p>
          </li>
          <li id="req-implementation-commitments">
            <strong>Implementation commitments</strong><p>Simple, lightweight server software should be available to allow authors to serve spatial resources as MapML.</p>
          </li>
          <li id="req-accessible-custom-element">
            <strong>Accessible custom element</strong><p>One or more accessible Custom Element clients should be available to demonstrate client functionality.</p>
          </li>
          <li id="req-ease-of-authoring">
            <strong>Ease of authoring</strong><p>A range of authoring situations should be supported, from simple single file services to robust MapML services over large volumes of framework data.</p>
          </li>
        </ul>
        </section>
        -->