Bug 13226 - Rename "Interfaces" index section to more precise "Element interfaces"
Summary: Rename "Interfaces" index section to more precise "Element interfaces"
Status: RESOLVED FIXED
Alias: None
Product: HTML WG
Classification: Unclassified
Component: LC1 HTML5 spec (show other bugs)
Version: unspecified
Hardware: All All
: P2 normal
Target Milestone: ---
Assignee: Silvia Pfeiffer
QA Contact: HTML WG Bugzilla archive list
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2011-07-12 20:05 UTC by Glenn Adams
Modified: 2012-10-06 14:31 UTC (History)
7 users (show)

See Also:


Attachments
Patch - Interfaces Index (2.14 KB, patch)
2011-11-21 16:55 UTC, Glenn Adams
Details | Diff
script to generate interface index (1.21 KB, text/x-perl-script)
2012-02-12 08:53 UTC, Cameron McCormack
Details
Python port of Cameron's script (1.33 KB, text/x-python)
2012-10-05 18:17 UTC, Sam Ruby
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Glenn Adams 2011-07-12 20:05:49 UTC
At present, Index (Interfaces) only includes a "list of interfaces for elements" table. However, a number of interfaces are defined that do not correspond to elements and that are not listed in this index.

Suggest that a separate, full (lexicographically) ordered table be provided in addition to the current list of all defined interfaces. This table should include (1) entries (links) to the following (defined) interfaces that are presently not in this index, and (2) entries (links) to those interfaces currently listed in the index (within list of interfaces for elements table):

ApplicationCache
AudioTrack
AudioTrackList
BarProp
BeforeUploadEvent
HashChangeEvent
History
HTMLAllCollection
HTMLAnchorElement (supplemental)
HTMLAppletElement
HTMLAreaElement (supplemental)
HTMLBaseFontElement
HTMLBodyElement (supplemental)
HTMLBRElement (supplemental)
HTMLCollection
HTMLDirectoryElement
HTMLDivElement  (supplemental)
HTMLDListElement (supplemental)
HTMLDocument
HTMLDocument (supplemental)
HTMLEmbedElement (supplemental)
HTMLFontElement
HTMLFormControlsCollection
HTMLFrameElement
HTMLFrameSetElement
HTMLHeadingElement (supplemental)
HTMLHRElement (supplemental)
HTMLHtmlElement (supplemental)
HTMLIFrameElement (supplemental)
HTMLImageElement (supplemental)
HTMLInputElement (supplemental)
HTMLLegendElement (supplemental)
HTMLLIElement (supplemental)
HTMLLinkElement (supplemental)
HTMLMarqueeElement
HTMLMediaElement
HTMLMenuElement (supplemental)
HTMLMetaElement (supplemental)
HTMLObjectElement (supplemental)
HTMLOListElement (supplemental)
HTMLOptionsCollection
HTMLParagraphElement (supplemental)
HTMLParamElement (supplemental)
HTMLPreElement (supplemental)
HTMLScriptElement (supplemental)
HTMLTableCaptionElement (supplemental)
HTMLTableCellElement
HTMLTableCellElement (supplemental)
HTMLTableColElement (supplemental)
HTMLTableElement (supplemental)
HTMLTableRowElement (supplemental)
HTMLTableSectionElement (supplemental)
HTMLUListElement (supplemental)
HTMLUnknownElement
DataTransfer
DataTransferItem
DataTransferItemList
DOMHTMLImplementation
DOMTokenList
DOMSettableTokenList
DOMStringMap
External
Function
FunctionStringCallback
Location
MediaController
MediaError
MutableTextTrack
Navigator
NavigatorContentUtils
NavigatorID
NavigatorOnLine
NavigatorStorageUtils
PageTransitionEvent
PopStateEvent
RadioNodeList
TextTrack
TextTrackCue
TextTrackCueList
TimeRanges
Transferable
ValidityState
VideoTrack
VideoTrackList
Window
WindowBase64
WindowModel
WindowTimers
XMLDocumentLoader

This comment is in reference to Editor's Draft of 11 July 2011.
Comment 1 Ms2ger 2011-07-15 13:34:27 UTC
I think the easiest way forward would be to attach such a table to this bug, ready to be inserted into the source of the spec.
Comment 2 Michael[tm] Smith 2011-08-04 05:35:27 UTC
mass-move component to LC1
Comment 3 Ian 'Hixie' Hickson 2011-08-17 23:51:14 UTC
EDITOR'S RESPONSE: This is an Editor's Response to your comment. If you are satisfied with this response, please change the state of this bug to CLOSED. If you have additional information and would like the editor to reconsider, please reopen this bug. If you would like to escalate the issue to the full HTML Working Group, please add the TrackerRequest keyword to this bug, and suggest title and text for the tracker issue; or you may create a tracker issue yourself, if you are able to do so. For more details, see this document:
   http://dev.w3.org/html5/decision-policy/decision-policy.html

Status: Did Not Understand Request
Change Description: no spec change
Rationale: If you really want this, please do as suggested in comment 1. However, this kind of thing is a maintenance nightmare and I'm not very enthusiastic about it.
Comment 4 Glenn Adams 2011-11-20 18:16:36 UTC
Please provide a reference (URL) to the source material for generating the Interface appendix, and I will prepare additional material to insert in that appendix in order to complete the index of defined Interfaces.
Comment 5 Ms2ger 2011-11-20 20:22:28 UTC
http://svn.whatwg.org/webapps/
Comment 6 Glenn Adams 2011-11-21 16:55:27 UTC
Created attachment 1045 [details]
Patch - Interfaces Index

This patch, applied to revision 6831 of [1], does the following:

* change heading of Interfaces index to read Interfaces of Elements
* adds new Interfaces and Types index, which lists *all* defined interfaces and *all* normatively referenced external interfaces and types

[1] http://svn.whatwg.org/webapps/source
Comment 7 Ian 'Hixie' Hickson 2011-12-03 00:12:18 UTC
That patch is incomplete (e.g. it doesn't include WebSockets, which would have to be included and marked as not applying to the W3C copy of the spec).

However, I'm really not at all convinced this index would be in any way useful. What purpose does it serve? It's a maintenance nightmare (has to be updated every time we change the interfaces), and doesn't seem to summarise any information that anyone would ever need to quickly look up.
Comment 8 Ian 'Hixie' Hickson 2011-12-07 20:04:18 UTC
EDITOR'S RESPONSE: This is an Editor's Response to your comment. If you are satisfied with this response, please change the state of this bug to CLOSED. If you have additional information and would like the editor to reconsider, please reopen this bug. If you would like to escalate the issue to the full HTML Working Group, please add the TrackerRequest keyword to this bug, and suggest title and text for the tracker issue; or you may create a tracker issue yourself, if you are able to do so. For more details, see this document:
   http://dev.w3.org/html5/decision-policy/decision-policy.html

Status: Rejected
Change Description: no spec change
Rationale: see comment 7
Comment 9 Glenn Adams 2011-12-07 20:13:32 UTC
(In reply to comment #8)
> EDITOR'S RESPONSE: This is an Editor's Response to your comment. If you are
> satisfied with this response, please change the state of this bug to CLOSED. If
> you have additional information and would like the editor to reconsider, please
> reopen this bug. If you would like to escalate the issue to the full HTML
> Working Group, please add the TrackerRequest keyword to this bug, and suggest
> title and text for the tracker issue; or you may create a tracker issue
> yourself, if you are able to do so. For more details, see this document:
>    http://dev.w3.org/html5/decision-policy/decision-policy.html
> 
> Status: Rejected
> Change Description: no spec change
> Rationale: see comment 7

If you choose to ignore this bug, and not add the additional full table of interfaces, then please change the title of the heading to "Interfaces (Partial)" and add a descriptive note to the following effect:

"This index does not enumerate all interfaces defined by this specification."
Comment 10 Ian 'Hixie' Hickson 2011-12-07 20:23:59 UTC
I'm happy to change the title of the section to "Element Interfaces", which is what it lists.
Comment 11 Glenn Adams 2011-12-07 20:29:49 UTC
(In reply to comment #10)
> I'm happy to change the title of the section to "Element Interfaces", which is
> what it lists.

ok, i can accept that, but it still begs the question of the completeness of the index; the reason for having an index is so that the reader has a convenient place to find an enumeration of whatever; it would certainly be a service to the reader to have a full list of interfaces, and I spent some effort to create that list;

i understand that, like any manually created index, it is challenging to update frequently; if you had a tool to automate that indexing, then it would reduce or remove that problem; e.g., would it be possible to use micro-syntax to label interface defs to easily extract an index that you could integrate into your production chain?
Comment 12 Cameron McCormack 2011-12-07 23:04:16 UTC
Why not merge the current Element Interfaces table into the Elements table?  It seems the Elements table already has everything in the Element Interfaces table except for the list of inherited interfaces.

I think having the Interfaces section list all interfaces in the spec would be useful.  Whenever I need to look up an interface in the spec, I have to remember what section of the spec it is in (since I prefer to use the multipage version of the spec rather than the single page, where I would otherwise be able to just press Cmd+F). I don't think it should be that hard -- can I write you a Perl script to add this?
Comment 13 Ian 'Hixie' Hickson 2012-01-31 22:36:55 UTC
If you can write a script to automatically generate such an interface table, I would be more than happy to use it. Ping me on IRC if you're still interested in doing this.
Comment 14 Ian 'Hixie' Hickson 2012-02-01 03:41:07 UTC
(Reassigning to heycam for now; please reassign to me if you change your mind or do it.)
Comment 15 Cameron McCormack 2012-02-12 08:53:16 UTC
Created attachment 1078 [details]
script to generate interface index

I don't know what format you want the index in.  This script takes the "index" file (the post-processed file) as input.  It generates output like:

<ul>
 <li><code><a href=#htmlanchorelement>HTMLAnchorElement</a></code>, <a href=#xxx1>partial</a>
 <li><code><a href=#htmlelement>HTMLElement</a></code>
 <li><code>XMLDocument</code>, <a href=#xmldocument>partial</a>
</ul>

where xxx1 is the id="" on the <a>HTMLAnchorElement</a> in the <pre> for its obsolete attributes, if you added one.

Feel free to adapt as desired.  It's probably quite sensitive to the exact formatting of the markup you seem to use.
Comment 16 contributor 2012-07-18 04:16:50 UTC
This bug was cloned to create bug 17796 as part of operation convergence.
Comment 17 Ms2ger 2012-08-15 17:13:40 UTC
Filter on [Idon'tcareaboutHTMLWGbugspam].
Comment 18 Sam Ruby 2012-10-05 18:17:41 UTC
Created attachment 1201 [details]
Python port of Cameron's script
Comment 19 Sam Ruby 2012-10-06 14:31:38 UTC
EDITOR'S RESPONSE: This is an Editor's Response to your comment. If
you are satisfied with this response, please change the state of
this bug to CLOSED. If you have additional information and would
like the Editor to reconsider, please reopen this bug. If you would
like to escalate the issue to the full HTML Working Group, please
add the TrackerRequest keyword to this bug, and suggest title and
text for the Tracker Issue; or you may create a Tracker Issue
yourself, if you are able to do so. For more details, see this
document:   http://dev.w3.org/html5/decision-policy/decision-policy-v2.html

Status: Accepted
Change Description:
https://github.com/w3c/html/commit/74021b3b94cf515490cdfaba98bd770127b22de2
http://dev.w3.org/html5/spec/single-page.html#all-interfaces
Rationale: accepted WHATWG change