WebVTT - general restructure to match normal API docs #34034

hamishwillee · 2024-06-10T07:59:10Z

The current WebVTT docs include all information in a single doc which mixes the Web API, guide, WebVTT file format, tutorials, etc and has quite a bit of duplication.

This attempts to push the document into a more standard pattern

Separate WebVTT API as "standard doc"
Separate WebVTT file format doc
Delete tutorials
Delete compat doc out to BCD, and remove stuff that isn't in BCD
Fix Fix WebVTT description indicating that text payload lines need to start with a hyphen #19997
Update the Interface docs to have standard form
Add STYLE blocks
Rebase against Remove mention of "kind=descriptions" for track HTML element #34713 and check

Note, I did not do this - cannot get Regions to work in FF in any form:

Add REGION blocks - Choose not to do as untestable (see https://bugzilla.mozilla.org/show_bug.cgi?id=1906787 )

This is part of minimum work to meet minimum docs criteria for #33589

github-actions · 2024-06-10T08:00:43Z

Preview URLs (17 pages)

Flaws (21)

Note! 11 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/API/WebVTT_API/Web_Video_Text_Tracks_Format
Title: Web Video Text Tracks Format (WebVTT)
Flaw count: 1

broken_links:
- No need for the pathname in anchor links if it's the same page

URL: /en-US/docs/Web/API/HTMLVideoElement
Title: HTMLVideoElement
Flaw count: 6

macros:
- /en-US/docs/Web/API/HTMLVideoElement/mozParsedFrames does not exist
- /en-US/docs/Web/API/HTMLVideoElement/mozDecodedFrames does not exist
- /en-US/docs/Web/API/HTMLVideoElement/mozPresentedFrames does not exist
- /en-US/docs/Web/API/HTMLVideoElement/mozPaintedFrames does not exist
- /en-US/docs/Web/API/HTMLVideoElement/mozFrameDelay does not exist
- and 1 more flaws omitted

URL: /en-US/docs/Web/API/TextTrack
Title: TextTrack
Flaw count: 1

macros:
- /en-US/docs/Web/API/HTMLMediaElement/addTrack does not exist

URL: /en-US/docs/Web/API/TextTrackList
Title: TextTrackList
Flaw count: 1

macros:
- /en-US/docs/Web/API/HTMLMediaElement/addTextTrack does not exist

URL: /en-US/docs/Web/API/VTTRegion
Title: VTTRegion
Flaw count: 9

macros:
- /en-US/docs/Web/API/VTTRegion/VTTRegion does not exist
- /en-US/docs/Web/API/VTTRegion/id does not exist
- /en-US/docs/Web/API/VTTRegion/width does not exist
- /en-US/docs/Web/API/VTTRegion/lines does not exist
- /en-US/docs/Web/API/VTTRegion/regionAnchorX does not exist
- and 4 more flaws omitted

URL: /en-US/docs/Web/HTML/Element/track
Title: <track>: The Embed Text Track element
Flaw count: 3

macros:
- /en-US/docs/Web/API/HTMLTrackElement/track does not exist
- /en-US/docs/Web/API/HTMLTrackElement/track does not exist
- /en-US/docs/Web/API/HTMLMediaElement/addTrack does not exist

External URLs (2)

URL: /en-US/docs/Web/API/WebVTT_API/Web_Video_Text_Tracks_Format
Title: Web Video Text Tracks Format (WebVTT)

https://en.wikipedia.org/wiki/Ruby_character (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/HTML/Element/track
Title: <track>: The Embed Text Track element

https://www.w3.org/TR/html-aria/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-07-12 06:39:16)

files/en-us/web/css/_doublecolon_cue-region/index.md

files/en-us/web/css/_doublecolon_cue/index.md

github-actions · 2024-06-14T19:02:48Z

This pull request has merge conflicts that must be resolved before it can be merged.

files/en-us/web/html/element/video/index.md

chrisdavidmills

@hamishwillee quite a few comments here, but mainly grammatical quibbles. Nothing particularly major. I know this is a restructure, but I couldn't help myself ;-)

I'm approving it so as not to hold you up.

chrisdavidmills · 2024-07-09T06:23:16Z

files/en-us/_redirects.txt

@@ -11358,6 +11358,7 @@
 /en-US/docs/Web/CSS/::-webkit-scrollbar-thumb	/en-US/docs/Web/CSS/::-webkit-scrollbar
 /en-US/docs/Web/CSS/::-webkit-scrollbar-track	/en-US/docs/Web/CSS/::-webkit-scrollbar
 /en-US/docs/Web/CSS/::-webkit-scrollbar-track-piece	/en-US/docs/Web/CSS/::-webkit-scrollbar
+/en-US/docs/Web/CSS/::cue-region	/en-US/docs/Web/API/WebVTT_API


I understand why you'd want to delete this, as it has no support anywhere. Estelle and I have started adding notes to spec landing pages to mention items that are specified but not supported anywhere, just in case people go "x is in the spec; why is it not documented?"

So for example:

Note: The specification defines another pseudo-element, ::cue-region, but this is not supported by any browsers.

@chrisdavidmills Is there a discussion on this? The reason I ask is that I love the idea of making it clear that things are deliberately not documented, but we should harmonize the team approach.

If it were me, we would list them (as though they were defined) in the overview page but be tagged with a macro that applies styling {{no_browser_implementation("::cue-region")}} to indicate that they aren't supported (linked to info text). This could then be added/removed by BCD possibly.

But there are many options, and maybe a note is the right one.

PS For now I have done as you suggested!

I don't know if there is a discussion anywhere about it. I guess you could ask Estelle. I think it is a reasonable approach for now, and there aren't so many of them that we couldn't change if something else is eventually decided.

chrisdavidmills · 2024-07-09T06:43:15Z

files/en-us/web/api/texttrack/index.md

-The `TextTrack` interface—part of the API for handling WebVTT (text tracks on media presentations)—describes and controls the text track associated with a particular {{HTMLElement("track")}} element.
+The `TextTrack` interface of the [WebVTT API](/en-US/docs/Web/API/WebVTT_API) represents a text track associated with a media element.
+
+The object owns the list of {{domxref("VTTCue")}} objects that will be displayed over the video at various points.


Seems a bit odd that this page doesn't indicate the relationship between TextTrack, <track>/HTMLTrackElement, and media elements like <video>/HTMLVideoElement; it is just implied by an example later on. Maybe add just a sentence to talk about this, e.g.

"A TextTrack can be added to a media element using the addTrack() method. This has the same effect as declaratively adding a text track via a <track> element".

Just give people an idea of how they relate, as it is confusing.

Similar comment applies to the <track>/HTMLTrackElement pages and <video>/HTMLVideoElement pages.

Very point. I have fixed this up a bit TextTrack, TextTrackList and <track> now properly cross link.

I added an example of using track in the video element too. It's not something that integrates well, and that video element page needs more love and testing than I am willing to give it.

That set of changes in 6952a0a

files/en-us/web/api/texttrackcue/index.md

files/en-us/web/api/texttracklist/index.md

files/en-us/web/api/webvtt_api/web_video_text_tracks_format/index.md

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

<track> element creation info Track/Video element cross linking

files/en-us/web/api/webvtt_api/web_video_text_tracks_format/index.md

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

hamishwillee · 2024-07-12T06:44:11Z

files/en-us/web/html/element/video/index.md

 ### Detecting track addition and removal

-You can detect when tracks are added to and removed from a `<video>` element using the {{domxref("VideoTrackList/addtrack_event", "addtrack")}} and {{domxref("VideoTrackList/removetrack_event", "removetrack")}} events. However, these events aren't sent directly to the `<video>` element itself. Instead, they're sent to the track list object within the `<video>` element's {{domxref("HTMLMediaElement")}} that corresponds to the type of track that was added to the element:
+You can detect when tracks are added to and removed from a `<video>` element using the {{domxref("VideoTrackList/addtrack_event", "addtrack")}} and {{domxref("VideoTrackList/removetrack_event", "removetrack")}} events. However, these events aren't sent directly to the `<video>` element itself.


FYI, I found this whole thing a bit confusing because the track elements dont allow you to add anything other than text tracks to the video/audio. So it's a bit unclear how you'd add new audio tracks (for example).

hamishwillee · 2024-07-12T06:45:35Z

Thanks for that mammoth review @chrisdavidmills - I have taken almost all of it on board. This is much better than it was.

chrisdavidmills · 2024-07-14T05:27:32Z

files/en-us/web/html/element/video/index.md

 - {{domxref("HTMLMediaElement.videoTracks")}}
-  - : Add an `addtrack` listener to this {{domxref("VideoTrackList")}} object to be informed when video tracks are added to the element.
+  - : A {{domxref("VideoTrackList")}} containing all of the media element's audio tracks.


@hamishwillee I did find one small thing here — this line should say "video tracks".

Thanks! Fixed by #34832

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Jun 10, 2024

hamishwillee mentioned this pull request Jun 10, 2024

[Web API] HTML character entities are supported in WebVTT #33589

Closed

8 tasks

github-actions bot added Content:CSS Cascading Style Sheets docs Content:HTML Hypertext Markup Language docs labels Jun 11, 2024

hamishwillee commented Jun 11, 2024

View reviewed changes

files/en-us/web/css/_doublecolon_cue-region/index.md Outdated Show resolved Hide resolved

github-actions bot added size/xl [PR only] >1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Jun 11, 2024

hamishwillee commented Jun 11, 2024

View reviewed changes

files/en-us/web/css/_doublecolon_cue/index.md Outdated Show resolved Hide resolved

github-actions bot added the merge conflicts 🚧 [PR only] label Jun 14, 2024

hamishwillee force-pushed the webvtt_edits branch from 448af34 to e23b0cb Compare July 2, 2024 05:28

github-actions bot removed the merge conflicts 🚧 [PR only] label Jul 2, 2024

github-actions bot reviewed Jul 2, 2024

View reviewed changes

files/en-us/web/html/element/video/index.md Outdated Show resolved Hide resolved

hamishwillee force-pushed the webvtt_edits branch 2 times, most recently from 1f4466d to 205ae20 Compare July 9, 2024 06:03

hamishwillee marked this pull request as ready for review July 9, 2024 06:05

hamishwillee requested review from a team as code owners July 9, 2024 06:05

hamishwillee requested review from sideshowbarker, chrisdavidmills and pepelsbey and removed request for a team July 9, 2024 06:05

chrisdavidmills approved these changes Jul 9, 2024

View reviewed changes

sideshowbarker removed their request for review July 9, 2024 10:14

hamishwillee and others added 13 commits July 12, 2024 15:04

Any character references supported + del old relnotes

806e337

Fix payload lines don't have to start with a hyphen mdn#19997

3a4954e

API ref for interfaces - update to current standard

f534a3c

WebVTT file format split out

a683cd7

Delete ::cue-region CSS pseudo class (no implementations)

ded9885

Web API - Styling example

e464e3b

Start updating WebVTT text format doc

876a688

Prettier the video element

1419714

Add STYLE block. Add Style examples

b317e71

Tidy up after removing description kind

5a5a523

Apply suggestions from code review

9b78124

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

add note about :cue-region support (or lack of

5bd64be

TextTrack - explain how created

6952a0a

<track> element creation info Track/Video element cross linking

hamishwillee force-pushed the webvtt_edits branch from 5a42143 to 6952a0a Compare July 12, 2024 06:06

hamishwillee commented Jul 12, 2024

View reviewed changes

files/en-us/web/api/webvtt_api/web_video_text_tracks_format/index.md Outdated Show resolved Hide resolved

Apply suggestions from code review

f322968

Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>

hamishwillee commented Jul 12, 2024

View reviewed changes

hamishwillee merged commit 3975bcf into mdn:main Jul 12, 2024
9 checks passed

hamishwillee deleted the webvtt_edits branch July 12, 2024 06:45

chrisdavidmills reviewed Jul 14, 2024

View reviewed changes

hamishwillee mentioned this pull request Jul 14, 2024

video element typo #34832

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WebVTT - general restructure to match normal API docs #34034

WebVTT - general restructure to match normal API docs #34034

hamishwillee commented Jun 10, 2024 •

edited

Loading

github-actions bot commented Jun 10, 2024 •

edited

Loading

github-actions bot commented Jun 14, 2024

chrisdavidmills left a comment

chrisdavidmills Jul 9, 2024

hamishwillee Jul 12, 2024

hamishwillee Jul 12, 2024

chrisdavidmills Jul 14, 2024

chrisdavidmills Jul 9, 2024

hamishwillee Jul 12, 2024

hamishwillee Jul 12, 2024

hamishwillee commented Jul 12, 2024

chrisdavidmills Jul 14, 2024

hamishwillee Jul 14, 2024

WebVTT - general restructure to match normal API docs #34034

WebVTT - general restructure to match normal API docs #34034

Conversation

hamishwillee commented Jun 10, 2024 • edited Loading

github-actions bot commented Jun 10, 2024 • edited Loading

github-actions bot commented Jun 14, 2024

chrisdavidmills left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee commented Jul 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee commented Jun 10, 2024 •

edited

Loading

github-actions bot commented Jun 10, 2024 •

edited

Loading