Make the table of contents more useful/less dense #885
Labels
editorial
Changes that do not affect how the standard is understood.
good first issue
Ideal for someone new to a WHATWG standard or software project
Comments
domenic
added
editorial
|
What about a show/hide feature that meets 2 goals: de-clutter TOC; make info quickly available if needed? Similar to examples below (but finalized by proper designer). Expanded states would stay persistent with Default
Open
|
|
That would be a pretty nice bonus! Probably a decent bit of work though, as our TOC is generated by our spec tooling, and this would need to hook into that. (Or fix it up afterward using JS, I guess?) |
|
True, I noticed Bikeshed is building. Python's not my forte, but I hacked a "toc-collapsible" detection to add the scaffolding needed by implementing spec pages. The implementing spec page could add CSS for all layout and a small JS click handler. This allows per-page customization and decouples presentation/functionality from Bikeshed. https://dev.anthum.com/pub/whatwg-streams-toc-expand.html https://github.com/AnthumChris/bikeshed/commit/d04732bae6b3e861d2de50b7d548f7cc72fb19c1 |
|
That looks like a pretty nice UX and design! The JS doesn't work in Firefox (due to using |
|
/cc @tabatkins so he knows we're plotting to add this collapsible-sections-in-the-TOC support to Bikeshed. |
|
I can create an issue in Bikeshed that I originate changes from to ensure this is described and documented in the BS docs. I added a second design prototype with arrows on left. Both use the same Bikeshed codebase while providing unique CSS for design variants: https://dev.anthum.com/pub/whatwg-streams-toc-expand-right-text.html |
|
Ooh, I'm down for this. I've been wanting to do some improvements to ToC anyway - I very much like Tobie's "indicate what section of the spec you're currently looking at" stuff too. |
|
Might we just want to use |
|
Hmm yeah I was thinking that would have some issues mixing into the ul/li structure, but on second thought it seems like it'd work great. |
domenic
added a commit
that referenced
this issue
Apr 13, 2020
Normative changes, all stemming from the Web IDL adaptation: * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. (At least, pending whatwg/webidl#357 resolution.) Closes #952. * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. Note that the size function is not settable anymore, but highWaterMark has a setter. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
domenic
added a commit
that referenced
this issue
Apr 13, 2020
Normative changes, all stemming from the Web IDL adaptation: * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. (At least, pending whatwg/webidl#357 resolution.) Closes #952. * All methods and accesors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. Note that the size function is not settable anymore, but highWaterMark has a setter. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
11 tasks
domenic
added a commit
that referenced
this issue
Apr 13, 2020
Normative changes, all stemming from the Web IDL adaptation: * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. (At least, pending whatwg/webidl#357 resolution.) Closes #952. * All methods and accesors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. Note that the size function is not settable anymore, but highWaterMark has a setter. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
domenic
added a commit
that referenced
this issue
Jun 11, 2020
Closes #963. Normative changes to widely-implemented features, roughly in order of most disruptive to least-disruptive: * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes #1005. In particular this means that attempts to set either of them post-creation will throw a TypeError. Chromium already ships these semantics. * Functions which take a dictionary no longer accept non-objects. * For the queuing strategy classes, their highWaterMark property will no longer return a non-number from their highWaterMark properties, if one was passed to the constructor. Instead, NaN will be returned. * All methods and accessors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes #586. * All classes now have [Symbol.toStringTag] properties. Closes #952. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. * Property lookup in options arguments now happens earlier, at argument-conversion time, and in alphabetical order, per dictionary rules. Normative changes to unimplemented features: * ReadableStream's getIterator() method has been renamed to values() as part of adopting Web IDL's infrastructure for async iterators. * The byobRequest property on ReadableByteStreamController now returns null when there is no BYOB request, instead of returning undefined. * The view property on ReadableStreamBYOBRequest now returns null when the view cannot be written into, instead of returning undefined. * Various byte-stream-related APIs that used to specifically prohibit detached buffers now check for zero-length views or buffers, which is a more general category. * The async iterator's next() and return() methods now behave more like async generators, e.g. returning promises fulfilled with { value: undefined, done: true } after return()ing the iterator, instead of returning a rejected promise. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. Closes #963. Closes #1017. See #1036 for further followup on the iteration result objects. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes #885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes #907. * Abstract operations are now consistently alphabetized within their section. Closes #684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes #687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes #965.
yutakahirano
pushed a commit
to yutakahirano/streams
that referenced
this issue
Jun 3, 2021
Closes whatwg#963. Normative changes to widely-implemented features, roughly in order of most disruptive to least-disruptive: * For the queuing strategy classes, their size and highWaterMark properties are now getters on the prototype, instead of data properties on the prototype and instance (respectively). Closes whatwg#1005. In particular this means that attempts to set either of them post-creation will throw a TypeError. Chromium already ships these semantics. * Functions which take a dictionary no longer accept non-objects. * For the queuing strategy classes, their highWaterMark property will no longer return a non-number from their highWaterMark properties, if one was passed to the constructor. Instead, NaN will be returned. * All methods and accessors are now enumerable, per Web IDL defaults, instead of non-enumerable, per ECMAScript defaults. * All classes are now exposed globally. Formerly, ReadableStreamDefaultReader, ReadableStreamBYOBReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStreamDefaultWriter, WritableStreamDefaultController, and TransformStreamDefaultController were not exposed. Closes whatwg#586. * All classes now have [Symbol.toStringTag] properties. Closes whatwg#952. * Some functions have changed their length property value. * Some exceptions are thrown earlier, at argument-conversion time. * Property lookup in options arguments now happens earlier, at argument-conversion time, and in alphabetical order, per dictionary rules. Normative changes to unimplemented features: * ReadableStream's getIterator() method has been renamed to values() as part of adopting Web IDL's infrastructure for async iterators. * The byobRequest property on ReadableByteStreamController now returns null when there is no BYOB request, instead of returning undefined. * The view property on ReadableStreamBYOBRequest now returns null when the view cannot be written into, instead of returning undefined. * Various byte-stream-related APIs that used to specifically prohibit detached buffers now check for zero-length views or buffers, which is a more general category. * The async iterator's next() and return() methods now behave more like async generators, e.g. returning promises fulfilled with { value: undefined, done: true } after return()ing the iterator, instead of returning a rejected promise. Editorial changes: * All APIs are specified to using Web IDL now, instead of using a modified version of the ECMAScript specification conventions. We continue using abstract operations and completion records for now, and we have to drop down to the ECMAScript level in a couple places (notably for dealing with %ObjectPrototype% vs. null-prototype iteration result objects, and transferring array buffers). But overall this removes a lot of type-checking and conversion boilerplate from the specification. Closes whatwg#963. Closes whatwg#1017. See whatwg#1036 for further followup on the iteration result objects. * Individual abstract operations, constructors, methods, and properties no longer have their own heading. They are instead lumped together in sections. Closes whatwg#885. * The constructors, methods, and properties are now documented in a per-class block, using the usual WHATWG "domintro" style. Closes whatwg#907. * Abstract operations are now consistently alphabetized within their section. Closes whatwg#684. * By using Bikeshed's <div algorithm> feature, we now get automatic identifier highlighting. Closes whatwg#687. * Switched to 100-character line limits, 1-space indents, and omitting end tags, per WHATWG conventions. * Removed usage of emu-algify in favor of using some more of Bikeshed's built-in features, plus manually annotating a few things. * Switched to concise Bikeshed linking syntax, e.g. [=term=] and [$AbstractOp$]. * Eliminated a number of utility abstract operations, especially around calling functions, by better using Web IDL. Other bug fixes: * Web IDL makes constructor behavior clear, so this closes whatwg#965.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Streams is a bit different in structure from other specifications in that it uses a heading for every API surface and abstract operation. This leads to a much larger table of contents than other specifications, and as such, I think the TOC is not very useful in its current form.
I think we should omit:
X"This can be done by adding
class="no-toc"to the appropriate headings in theindex.bsdocument.Marking this as a "good first issue" in case anyone wants to help out.
The text was updated successfully, but these errors were encountered: