From d2279a614b8741200199984845eedfaa024bfac6 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Fri, 22 Nov 2024 16:17:57 -0800 Subject: [PATCH] Editorial: more changes to conform with ECMA format * Use consistent casing throughout (e.g., sections, titles) * Must -> shall * Move some references to bibliography section, adjust references section to match PDF * Adjust boilerplate to ensure section ordering at end (index, bibliography, license) matches PDF * Add JSON normative ref --- source-map.bs | 123 +++++++++++++++++++++++++++----------------------- 1 file changed, 66 insertions(+), 57 deletions(-) diff --git a/source-map.bs b/source-map.bs index 3b2b780..2f5796f 100644 --- a/source-map.bs +++ b/source-map.bs @@ -1,6 +1,6 @@ 
-Title: Source Map Format Specification
-H1: Source Map
+Title: Source map format specification
+H1: Source map
 Shortname: source-map
 Level: none
 Status: STAGE0
@@ -15,7 +15,7 @@ Former Editor: John Lenz, Google
 Former Editor: Nick Fitzgerald, Mozilla
 Previous Version: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit?pli=1#
 Repository: source-map/source-map-spec
-Abstract: This Ecma standard defines the Source Map format, used for mapping transpiled source code back to the original sources.
+Abstract: This Ecma standard defines the Source map format, used for mapping transpiled source code back to the original sources.
 No Abstract: true
 Markup Shorthands: markdown yes
 Group: tc39
@@ -110,7 +110,7 @@ urlPrefix:https://webassembly.github.io/spec/core/; type:dfn; spec:wasm
     "id": "rfc4648",
     "publisher": "IETF",
     "status": "Standards Track",
-    "title": "The Base16, Base32, and Base64 Data Encodings"
+    "title": "IETF RFC 4648, The Base16, Base32, and Base64 Data Encodings"
   },
   "URL": {
     "href": "https://url.spec.whatwg.org/",
@@ -151,7 +151,7 @@ urlPrefix:https://webassembly.github.io/spec/core/; type:dfn; spec:wasm
 
 
Introduction

 
-This Ecma Standard defines the Source Map Format, used for mapping transpiled source code back to the original sources.
+This Ecma Standard defines the Source map format, used for mapping transpiled source code back to the original sources.
 
 The source map format has the following goals:
 * Support source-level debugging allowing bidirectional mapping
@@ -249,47 +249,30 @@ References {#references}
 ========================
 
 
 
-
Normative References

+The following documents are referred to in the text in such a way that some or all of their content constitutes
+requirements of this document. For dated references, only the edition cited applies. For undated references, the
+latest edition of the referenced document (including any amendments) applies.
+
+
Normative references

 

 

  
\[ECMA-262]
  
ECMAScript® Language Specification. Standards Track. URL: https://tc39.es/ecma262/
- 
\[ENCODING]
- 
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
- 
\[FETCH]
- 
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
- 
\[INFRA]
- 
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
- 
\[URL]
- 
URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
- 
\[WEBIDL]
- 
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/
+ 
\[JSON]
+ 
The JSON data interchange syntax. Standards Track. URL: https://tc39.es/ecma404/
 

-
Informative References

+
+
Informative references

 

  
\[BASE64]
- 
The Base16, Base32, and Base64 Data Encodings. Standards Track. URL: https://www.ietf.org/rfc/rfc4648.txt
- 
\[EvalSourceURL]
- 
Give your eval a name with //@ sourceURL. archive. URL: https://web.archive.org/web/20120814122523/http://blog.getfirebug.com/2009/08/11/give-your-eval-a-name-with-sourceurl/
- 
\[V2Format]
- 
Source Map Revision 2 Proposal. URL: https://docs.google.com/document/d/1xi12LrcqjqIHTtZzrzZKmQ3lbTv9mKrN076UB-j3UZQ/edit?hl=en_US
- 
\[VLQ]
- 
Variable-length quantity. reference article. URL: https://en.wikipedia.org/wiki/Variable-length_quantity
+ 
IETF RFC 4648, The Base16, Base32, and Base64 Data Encodings. Standards Track. URL: https://www.ietf.org/rfc/rfc4648.txt
  
\[WasmNamesBinaryFormat]
  
WebAssembly Names binary format. Living Standard. URL: https://www.w3.org/TR/wasm-core-2/#names%E2%91%A2
-

-

+
 
 Terms and definitions {#terminology}
 ====================================
@@ -336,7 +319,7 @@ For the purposes of this document, the following terms and definitions apply.
       content (and there is only one group representing a line). Source maps for other content types
       may diverge from this.
 
-Source Map Format {#source-map-format}
+Source map format {#source-map-format}
 ======================================
 
 A source map is a JSON document containing a top-level JSON object with the
@@ -355,7 +338,7 @@ following structure:
 }
 ```
 
-* version is the version field which must always be the number
+* version is the version field which shall always be the number
     `3` as an integer. The source map may be rejected if the field has any other value.
 * file is an optional name of the generated code
     that this source map is associated with. It's not specified if this can
@@ -492,7 +475,7 @@ To optionally report an error, implementations can choose to:
 - Report an error to the user, and continue processing.
 - Throw an error to abort the running algorithm. ([[Infra#algorithm-control-flow]])
 
-Mappings Structure {#mappings-structure}
+Mappings structure {#mappings-structure}
 ----------------------------------------
 
 The [=json/mappings=] data is broken down as follows:
@@ -515,12 +498,12 @@ The fields in each segment are:
 
 3. If present, the zero-based starting line in the original source.  This field contains a
     [=Base64 VLQ=] relative to the previous occurrence of this field, unless it is the first
-    occurrence of this field, in which case the whole value is represented.  Must be present if there
+    occurrence of this field, in which case the whole value is represented.  Shall be present if there
     is a source field.
 
 4. If present, the zero-based starting [=column=] of the line in the original source.  This
     field contains a [=Base64 VLQ=] relative to the previous occurrence of this field, unless it
-    is the first occurrence of this field, in which case the whole value is represented.  Must
+    is the first occurrence of this field, in which case the whole value is represented. Shall
     be present if there is a source field.
 
 5. If present, the zero-based index into the [=json/names=] list associated with this segment.  This
@@ -672,7 +655,7 @@ in the calling algorithm.
 ### [=decoded mapping|Mappings=] for generated JavaScript code ### {#mappings-javascript}
 
 Generated code positions that may have [=decoded mapping|mapping=] entries are defined in terms of *input elements*
-as per [=ECMAScript Lexical Grammar=]. [=decoded mapping|Mapping=] entries must point to either:
+as per [=ECMAScript Lexical Grammar=]. [=decoded mapping|Mapping=] entries shall point to either:
 
 1. the first code point of the source text matched by
     [=IdentifierName=], [=PrivateIdentifier=], [=Punctuator=], [=DivPunctuator=], [=RightBracePunctuator=],
@@ -702,7 +685,7 @@ from immediately invoked function expressions.
 The following enumeration lists productions of the ECMAScript [=Syntactic Grammar=]
 and the respective token or non-terminal (on the right-hand side of the production)
 for which source map generators should emit a [=named mapping=].
-The [=decoded mapping|mapping=] entry created for such tokens must follow [[#mappings-javascript]].
+The [=decoded mapping|mapping=] entry created for such tokens shall follow [[#mappings-javascript]].
 
 The enumeration should be understood as the "minimum". In general,
 source map generators are free to emit any additional [=named mappings=].
@@ -746,7 +729,7 @@ encoded as 0 (`A`).
 
 1. Source map generators may emit named [=decoded mapping|mappings=] for [=IdentifierReference=] in [=Expression=].
 
-Resolving Sources {#resolving-sources}
+Resolving sources {#resolving-sources}
 --------------------------------------
 
 If the sources are not absolute URLs after prepending the [=json/sourceRoot=], the sources are
@@ -787,11 +770,11 @@ corresponding to the given URL.
 Extensions {#extensions}
 ------------------------
 
-Source map consumers must ignore any additional unrecognized properties, rather than causing the
+Source map consumers shall ignore any additional unrecognized properties, rather than causing the
 source map to be rejected, so that additional features can be added to this format without
 breaking existing users.
 
-Index Map {#index-map}
+Index map {#index-map}
 ======================
 
 To support concatenating generated code and other common post-processing,
@@ -843,10 +826,10 @@ Section objects have the following fields:
 * map is an embedded complete source map object.
     An embedded map does not inherit any values from the containing index map.
 
-The sections must be sorted by starting position and the represented sections
-must not overlap.
+The sections shall be sorted by starting position and the represented sections
+shall not overlap.
 
-Retrieving Source Maps {#linking-and-fetching}
+Retrieving source maps {#linking-and-fetching}
 ========================================================
 
 Linking generated code to source maps {#linking-generated-code}
@@ -859,7 +842,7 @@ There are two possible ways to link source maps to the output.  The first requir
 support in order to add an HTTP header and the second requires an annotation in the source.
 
 Source maps are linked through URLs as defined in [[URL]]; in particular,
-characters outside the set permitted to appear in URIs must be percent-encoded
+characters outside the set permitted to appear in URIs shall be percent-encoded
 and it may be a data URI.  Using a data URI along with [=json/sourcesContent=] allows
 for a completely self-contained source map.
 
@@ -914,7 +897,7 @@ code unambiguously links to a source map if the result of all the ext
 is the same.
 
 If a tool consumes one or more source files that [=unambiguously links to a source map=] and it
-produces an output file that links to a source map, it must do so [=unambiguously links to a
+produces an output file that links to a source map, it shall do so [=unambiguously links to a
 source map|unambiguously=].
 
 

@@ -1055,7 +1038,7 @@ To match a Source Map URL in a comment |comment| (a [=string=]), run
 Note: The prefix for this annotation was initially `//@` however this conflicts with Internet
 Explorer's Conditional Compilation and was changed to `//#`.
 
-Source map generators must only emit `//#` while source map consumers must accept both `//@` and `//#`.
+Source map generators shall only emit `//#` while source map consumers shall accept both `//@` and `//#`.
 
 #### Extraction methods for CSS sources #### {#extraction-css}
 
@@ -1081,7 +1064,7 @@ Since WebAssembly is not a textual format and it does not support comments, it s
 The URL is encoded using [[WasmNamesBinaryFormat]], and it's placed as the content of the [=custom section=]. It is invalid for
 tools that generate WebAssembly code to generate two or more [=custom section|custom sections=] with the "sourceMappingURL" name.
 
-Fetching Source Maps {#fetching-source-maps}
+Fetching source maps {#fetching-source-maps}
 --------------------------------------------
 
 To fetch a source map given a [=/URL=] |url|, run the following steps:
@@ -1120,7 +1103,7 @@ Conventions {#conventions}
 The following conventions should be followed when working with source maps or
 when generating them.
 
-Source Map Naming {#source-map-naming}
+Source map naming {#source-map-naming}
 --------------------------------------
 
 Commonly, a source map will have the same name as the generated file but with a `.map`
@@ -1138,12 +1121,12 @@ eval'd code, it has the following form:
 
 It is described in [[EvalSourceURL]].
 
-Language Neutral Stack Mapping Notes {#language-neutral-mapping}
+Language neutral stack mapping notes {#language-neutral-mapping}
 ================================================================
 
 Stack tracing mapping without knowledge of the source language is not covered by this document.
 
-Multi-level Mapping Notes {#multi-level-mapping}
+Multi-level mapping notes {#multi-level-mapping}
 ================================================
 
 It is getting more common to have tools generate sources from some DSL (templates) or compile
@@ -1160,7 +1143,33 @@ However, It is unclear what a "source map reference" looks like in anything othe
 More specifically, what a source map reference looks like in a language that doesn't support
 JavaScript-style single-line comments.
 
-License {#license}
-==================
+
+

+

+
+
Bibliography

+
+

+ 
\[ENCODING]
+ 
Anne van Kesteren. Encoding Standard. Living Standard. URL: https://encoding.spec.whatwg.org/
+ 
\[FETCH]
+ 
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
+ 
\[INFRA]
+ 
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
+ 
\[URL]
+ 
URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
+ 
\[WEBIDL]
+ 
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/
+ 
\[EvalSourceURL]
+ 
Give your eval a name with //@ sourceURL. archive. URL: https://web.archive.org/web/20120814122523/http://blog.getfirebug.com/2009/08/11/give-your-eval-a-name-with-sourceurl/
+ 
\[V2Format]
+ 
Source Map Revision 2 Proposal. URL: https://docs.google.com/document/d/1xi12LrcqjqIHTtZzrzZKmQ3lbTv9mKrN076UB-j3UZQ/edit?hl=en_US
+ 
\[VLQ]
+ 
Variable-length quantity. reference article. URL: https://en.wikipedia.org/wiki/Variable-length_quantity
+

+

+
+
License

 
 This work is licensed under a [Creative Commons Attribution-ShareAlike 3.0 Unported License](http://creativecommons.org/licenses/by-sa/3.0/).