A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).

Talk:Reviewing

From WHATWG Wiki
Revision as of 08:08, 26 January 2011 by Annevk (talk | contribs) (moved Talk:Reviewing HTML5 to Talk:Reviewing: these reviewing tips apply to all specs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Suggest a new tag:

 <do_not_reformat_source>
 </do_not_reformat_source>

To provide a standardize way to tell tools like html tidy that the code in that section should not be reformatted without an explicit override. It would do nothing in the browser. Some markup is best left as is. For example, tables, embedded structured data, etc.

Whitis 21:51, 6 May 2009 (UTC)

I would recommend asking the developers of the tools you use (e.g. tidy) to support a "class" value that would do this, that way it can work even with HTML4 documents, no need to add an element or anything. Hixie 21:55, 6 May 2009 (UTC)

  No good. That would be specific to individual tools.    There needs to be a standard used by all tools.   If you want to
  include a standard class instead of a tag, that is fine.   But it should be mentioned in the markup spec as that is one 
  document that all the the tool developers will read.  This does fall within the domain of the spec, just as providing
  print media support, handicapped support, etc.    View source (or edit) is another presentation.
...
  Consider this a source code accessibility issue.     Whitis 07:25, 7 May 2009 (UTC)


4.11.2 datagrid element/folds/tabs Note: this comment and the ones which follow evolved as they were written. Some evolved with parts moving from tags to attributes or to CSS. Some evolved with new names based on finding existing precedent. Some of the changes were backpatched into the text, but not all.

There should also be a <fold> tag (or equivalent functionality) that is very similar but less table/list oriented. <fold status="open">

Section one

...

...

</fold> <fold>

Section two

 ...

</fold>

Attributes might be another way to do this which avoids inserting a tag between body and h2.

 <section fold="open">

Section one

  ...
 </section>
  • <fold_title>blah blah</fold_title>
    blah blah
    • <fold_title>Blah blah </fold_title>
      blah blah

      Absence of fold attribute makes it unfoldable unless the user allows it.

      This is similar to the hidden attribute but with some key differences. A fold Icon would still be present, along with descriptive text. Folding and unfolding would be accomplished by the user agent without any scripts to set the disabled attribute. In the case of sections, there would be special handling in that the text of any H1...H6 tag would not go away when folded. For other contexts, there may need to be a <fold_title>...</fold_title> or similar tag or a fold_title="tagname" attribute that lists what tag contents will be displayed when folded.

      This can be done in CSS as well. However folds and tabs are a basic logical construct and could exist in both domains. If the basic construct isn't defined at the HTML level, documents will be missing fold/tab titles that can be used by user stylesheets or user controls to override document behavior. Even if new tags/attributes are not defined, the basic markup using
      or
      (or other elements which can also be tabbed or folded) should be mentioned in the HTML5 spec.

      I.E. This is how you define where the folds/tabs would occur and this is what to use for a title and CSS is used to make it actually happen. You can not leave this to be fragmented by different folks using different classes. Since class allows multiple classes to be specifified, standard classes could be used while still retaining the ability to style each object individually (or as a subgroup) by specifying multiple classes. HTML5 at least needs to specify the classes to be used and make sure that the classes alone are adequate.

      Now technically, datagrid allows flow context. It is not at all clear how it handles flow content. The spaces for examples desparately need to be filled in and more examples given (flow content, sections, lists). If you are going to use it like the fold tag/attribute, <section> should be explictly mentioned and an example given, as that is an important case, though not the only one. As should numbered/unnumbered lists and definition lists.
       blocks are another important case where folding is reasonably expected.  
      User agents may provide an ability to, at the users request, fold all sections, whether or not they have a fold attribute (it basically sets fold to yes if it exists and creates it if it doesn't.    The user agent can also provide an unfold all.  This would work for <section> tags but wouldn't work as well for (un)numbered lists as existing content doesn't identify a title to be retained when folded (unless it has a 
      tag). "The data being presented is provided by script using the methods described in the following sections." No. That probably isn't what you meant to say. It can be provided by a script but it must be possible to provide it without one. The section on datagrids should spell out how you define the nesting levels and initial fold state on grid rows, even if that is described elsewhere. I don't see support for tabs. Maybe I didn't missed it, or maybe it is done using CSS. Tabs in the modern GUI sense. Not to be confused with the obsolete HTML3 tab tag (typewriter tabs) that were replaced with tables. <section tabs="true">

      Title

      <section>

      Tab title

      .... </section> <section>

      Tab Title

      ... </section> </section> If the browser doesn't support tabs, it can display the sections in a normal vertical orientation. section should take a title attribute, to be used when there isn't an h1...h6 section title. Another place where tabs are needed is in tables. Consider the tables here which are really subsets of a larger table. http://en.wikipedia.org/wiki/Comparison_of_media_players#Subtitle_support <colgroup tabs="true"> <colgroup title="Tab 1"> ... </colgroup> <colgroup title="Tab 2"> ... </colgroup> </colgroup> Browsers should be encouraged to provide a control that would convert sections or table column groups to tabs. Also to freeze or repeat row/column headings when a table wider/higher than the window scrolls, under user control. And they should provide an untabify control. Tabs may, and often will, occur inside forms. This could be provided via CSS, provided the base HTML contains provisions for a tab title. The same mechanism for titles can be used for both folding and tabbing. Note: looks like <legend> tag could be used for folding/tab titles, with H1...H6 used if not present. Needs to be allowed in <section> and
    • . <section><legend>...</legend> ... </section> would be a suitable docbook style replacement for the broken H1...H6 tags. This would make more sense than the <section>

      ...

      ... </section> kludge. I really don't like the idea of using H1 for lower level sections. Either use the right numbered level or use the unnumbered <legend>. ~~~ VIDEO Go visit hulu.com and youtube and imagine doing what they are doing with the video tag. We really need to make it possible to use standards to do what they are doing and not require Flash or Silverlight so the stuff will play across multiple operating systems, multiple browsers, on portable devices, and on set top boxes. It should not be necessary to use flash, silverlight, or scripts. Do it right and users have a case for insisting on standard compliant video players. The functionality I describe here is easy enough to implement and provides for the functionality offered by those services. Examples have been updated to be more consistent with SMIL, but not entirely. SMIL uses CamelCase, doesn't let you specify codecs (the SMIL type attribute is inadquate as it is only sufficient to identify the container format. The container format doesn't tell you if you can play what is inside. There are also some cases where it may make more sense to reuse existing HTML semantics. SMIL seemed a little week in some areas when it came to defining the global timeline without first reading the files, which might not be downloaded yet, but that may have just been due to some bad examples. SMIL doesn't seem to clearly define the difference between a playlist and a single playlist item composed of multiple clips (such as commercials). We aren't implementing SMIL just trying to be similar where we do the same thing unless there is a reason to do otherwise. <seq single_program="true"> <base href="http:/www.example.com/media/webchurns/" /> <segments total_time="17:37" title="As the Web Churns: Episode 13" > <video src="commercial1.ogg" noskip="true" vcodec="codec/FourCC" acodec="codec/FourCC" /> <par> <video src="chapter1.ogg" vcodec="codec/FourCC" acodec="codec/FourCC" /> <textstream src="subtitles1_en.xxx" type="subtitle/subrip" captions="on" > initial_time="0:30" title="Chapter 1"> <chapter_mark timestamp="5:00" /> <chapter_mark timestamp="10:00" /> <overlay start_time="0:00" end_time="0:05> <img src="logo.png" /> </overlay> </segment> <video src="commercial2.ogg" initial_time="12:00" noskip="true" vcodec="codec/FourCC" acodec="codec/FourCC" > <video src="chapter2.ogg" subtitle_src="subtitles2_en.xxx" initial_time="12:30" title="Chapter title 2" vcodec="codec/FourCC" acodec="codec/FourCC" /> <segment src="chapter3.ogg" subtitle_src="subtitles3_en.xxx" initial_time="15:00" clip_begin="0:10" clip_end="0.20" vcodec="codec/FourCC" acodec="codec/FourCC" /> <overlay start_time="end"> <img src="final_overlay.jpg" use_map="#shapes" /> <map name="shapes"> ... </map> </overlay> </segments> <alt> Alternate content </alt> </seq> Chapter marks can be displayed as a mark on the timeline (see hulu, where they coincide with commercial breaks) and the next/prev chapter buttons can be used to skip between chapters as when watching a DVD. total_time and initial_time attributes allow the player to construct a timeline without loading all the video files to know their length. This next one allows a video to be played that is contained in a single file with the commericals inserted. An alternate syntax using sublips follows, which might be simpler. <seq> <inserts> <par> <video src="episode15.mpg" title="Episode 15" /> <textstream src="subtitles15.xxx" type="subtitles/subrip/" offset="-0.05" /> </par> <insert src="commercial1.mpg" timestamp="0:00" duration="0:30" vcodec="codec/FourCC" acodec="codec/FourCC" > <insert src="commercial2.mpg" timestamp="0.15" duration=0:30> <overlay start_time="0:00" end_time="0.10"> <img src="..." use_map=""> </vid_overlay> <overlay start_time="0:15" end_time="0:20"> <text> Join the Mobile Infantry and save the Galaxy. Service guarantees citizenship. <a href="http://www.imdb.com/title/tt0120201/quotes"> Would you like to know more?</a> </text> </overlay> <inserts> </seq> Or instead of inserts, you can list the main video multiple times with clip_begin, clip_end tags. <seq total_time=> <video src=commercial1.mpg" initial_time="0:00" duration="0:30"/> <video src="episode15.mpg" initial_time="0:30" clip_begin="0:00" clip_end="15:00/> <video src="commercial2.mpg" initial_time="15:30" duration="0:30"/> <video src="episode15.mpg" initial_time="16:00" clipBegin="15:00" clipEnd="15:30" > <overlay> ... </overlay> </video> </seq> However, browsers may have trouble playing subclips, other than those which resume where the previous one left off (like after a commercial break). Randomly jumping 20 minutes into a video file requires the browser to download the 20 minutes that were not played and, if there is no index, scan through it to find the approriate time point. This can require too much bandwidth and prefetching. So, authors should be discouraged from jumping deep into the middle of clips which haven't already been played up to that point. If an overlay occurs at the end of a sequence, the overlay will overlay the last frame. However, it may be a non-transparent image or specify a background, in which case it doesn't. This next one is similar to the first except instead of the segments being presented as a single video, it allows multiple separate videos to be presented (similar feature for audio tag, also). The next/previous playlist item buttons on the viewer can be used. <seq single_program="false" > <video src="episode1.ogg" title="Episode 1" vcodec="codec/FourCC" acodec="codec/FourCC"/> <video src="episode2.ogg" title="Episode 2" vcodec="codec/FourCC" acodec="codec/FourCC" /> </video> <seq single_program="false" > <audio src="song1.ogg" title="Song 1" acodec="FourCC"/> <audio src="song2.ogg" title="Song 2" acodec="FourCC"/> </audio> Instead of "title=", we can include a <legend>. This allows formatting, though player may not support complex formating and may be separate from browser, so needs to be simple. When considering alternate video formats needed to support content and alternate languages, we are likely to end up with video/audio/text inside <switch> inside <par> inside <seq> as the general structure (though not all levels are always required). We could also have <seq> inside <par> for cases like full length subtitles overlaid on top of a video divided into shorter clips (possibly with commercial breaks). <seq> <par> <switch> <video ... /> <video ... /> <video ... /> </switch> <switch> <textstream ...> </switch> <switch> <audio ... /> </switch> <overlay> ... </overlay> </par> <par> </par> </seq> Still need to markup: - Whether the timestamps in subtitle files refer to the global timeline (appropriate for multimedia presentations) or within a particular clip (more appropriate for commercials inserted into a program) - Whether particular clips occupy space on the global timeline or not. For commercials, it may be better for them to appear as a singularity in the timeline so the timeline of the original material is maintained. If a browser uses an external player, it can stream the tags, preceeded by a basename tag, to stdin on the player. For a primitive player that doesn't support the xml tags, it can generate a simple playlist (with the inserts first?) or invoke the player with all the segments on the command line. mplayer, for example supports AX, Winamp, SMIL, or a simple one per line format). Xine supports asx, toxine m3u, pls, sfv, and raw text. Both support external subtitle files. External players may not understand complex html text overlays, image overlays (easily added), or image maps. It is possible some might support smilText. On the other hand, for built in players, these come naturally for the browser. Some systems, such as the X Video Extension, may have trouble with full overlays. They can do chroma keying to give full or no transparency but not partial transparency. However, OpenGL allows full compositing. Overlays at the end, when the video is paused, aren't a problem. Note that you can also do things like play a video and pause it and insert other video clips or audio + text/image as commentary with the above markup. You can also do a Mystery Science Theater 3000 audio+image overlay or audio+video overlay if the player supports it using the same markup format (requires a player that can mix audio and/or video and transparency in video stream). A DVD style commentary is somewhat problematic because we haven't included a volume control for the main video audio. SMIL tiny profile could be used. It doesn't support appear to support all the stuff above, but it can be added, possibly from the full profile. Or by trying to reuse existing HTML elements as I have done above. I changed my <video> and <audio> to <seq> and my segments to <video> and <audio>, above to resemble SMIL. http://www.w3.org/TR/SMIL/smil-tiny-profile.html Subtitles/captions are an important accessibility feature that SMIL tiny profile doesn't appear to adequately address. They may be included in the video stream or in a separate file. A separate file may not even be on the same server. the <par>,<smilText>, and <textStream> tags appear to be usable for subtitles: <par> <video src="movie-vid.rm"/> <textstream src="movie-sub-en.rt" systemLanguage="en" systemOverdubOrSubtitle="subtitle"/> </par> And the <switch> can be used to select a language. SubRip seems to be the most widely supported subtitle format at the moment. http://en.wikipedia.org/wiki/Comparison_of_media_players#Subtitle_support Thus adding <seq>, <par>, <textstream>, and <switch> to the <audio> and <video> tags and adding smil time options to the <video> and <audio> tags would do much of what I described (except the overlays at the end which I think there are other smil tags to accomplish though reusing built in img/imgmap/canvas might be easier to implement). If these tags are contained in a <smil> tag then they are SMIL (XHTML+SMIL) and if they are not, then HTML semantics would apply. <par> also allows you to merge separate audio and video files. <seq> (SMIL) Play items in sequence <par> (SMIL) Play items simultaneously <switch> (SMIL) Play one of the alternate items listed <video> (SMIL) video stream <audio> (SMIL) audio stream <textstream> (SMIL) text stream (subtitles) <img> (HTML) still image to overlay, or part of a slideshow. Needs additional timing tags. <map> (HTML) image map <a> (HTML) Hypertext link if use clicks on non transparent portion of image overlay and there is no imagemap. attributes Distinquish between a sequence of clips that make up one logical video (or audio) and a sequence that makes up multiple videos (playlist vs. fragments). <chapter> chapter marks <smil> NOT USED. If present, then you have XHTML+SMIL and a bunch of other options are available. <ref> (SMIL) other content types: SVG, flash (best avoided), etc. <alt> Alternate content when not using <object> semantics. <loop> Replay content ad-infitium (used for overlays at end of video). Streams need attributes that define the start and end positions within the stream to play and where the clip starts in the timeline. Same syntax will work for video, audio, and slideshows. Also allows subtitling audio (lyrics for song, transcript for radio broadcast). <Object> semantics could be used to specify multiple alternative formats since browsers may support only some audio, video, and subtitle formats. However, additional attributes may be needed to advise the browser in advance which formats are used in the referenced files so it can decide which to load without having to try to load and parse each one in turn. This example lets the browser choose a video source file based on whether or not it supports the Dirac video codec: <seq> <switch> <video src="episode15_dirac.ogg" acodec="codec/vrbs" vcodec="codec/dirac" type="applicaton/ogg"/> <video src="episode15_theora.ogg" acodec="codec/vrbs" vcodec="codec/ther" type="application/ogg"/> </switch> </seq> Dirac doesn't seem to have a FourCC yet, so I used the long ID. Here switch is used assuming we can't use the <object> semantics of including alternates in the tag body. If we use <par>, we can put overlays there, and could also put chapter marks there. We then need a general container that can be put inside <par> to contain html text, images, imagemaps, etc. There is a use for a special hypertext link tag (or attributes on the standard tag) that specifies: - The URL of a web page to load - An xpath that identifies a video object on that page - The URL of a subtitle file to insert when playing. This allows a website to provide links to another site where a video is viewed with the normal content of that site but subtitles are added by the first site providing the link. Since this alters the content at that site, the browser should popup a message that indicates this is being done so it doesn't appear the target site has been hacked if the user thinks they have followed a normal hypertext link. ~~~~ CANVAS I object to canvas only being scriptable. For each of the DOM drawing function calls, there should be an element. <canvas> <canvas_scale x="1.2" y="1.2" /> <canvas_rotate angle="90 /> <canvas_translate x="1.2" y="2.3 /> <canvas_transform ... /> <canvas_set_transform ... /> <canvas_path> <canvas_move_to x="1.23" y="2.35" /> <canvas_line_to(x="1.23 y="4.56 >/ <canvas_quadratic_curve_to cpx="1.23" cpy="4.56" x="7.89" y="0.12" /> <canvas_bezier_curve_to cp1x="1.2" cp1y="3.4" cp2x="4.5" cp2y="6.7" x="8.9" y="0.1" /> <canvas_arc_to x="1.2" y="3.4" radius="5.5" direction="ccw" /> <closepath /> <stroke /> <fill /> </canvas_path> <canvas_rect x="1.2" y="3.4" w="5.6" h="6.7" /> <canvas_arc x="1.2" y="2.3" radius="5.6", start_angle="7.8" send_angle="9.0", direction="cw"); </canvas> SaveState()/RestoreState(): <canvas_save_state /> </canvas_restore_state /> <canvas_push> </canvas_push> It costs almost nothing to add these tags compared to the work of implementing the canvas. It provides a simple alternative to SVG that uses built in functionality, is less complex, and is XML friendly (no storing paths inside attribute strings), and allows drawing simple graphs without scripts, or when scripts are disabled for security reasons or not implemented. The javascript functions already defined could populate the display list, stored as XML tags in the DOM hierarchy. arcTo(), should only take one coordinate; it is inconsistent with other path operators. If you want the current functionality, call moveTo() first. It should use the current position as the starting point to be consistent with the others. It is also missing a direction which makes it ambiguous as there are always two arcs that satisfy the endpoints and radius. I also have doubts about using width and height rather than two coordinates for rect. ~~~~ Smarter subscripts/superscripts: superscripts and subscripts do not behave properly when both are used, nor do the accomodate all the positions needed. There is a center, plus 8/16 compass rose positions, plus two extra far left and far right positions. Started with 9, then was improved. <compass style="{child-font-size: -2}"> <C></C> <E></E> <ENE></ENE> <NE></NE> <N></N> <NW></NW> <WNW></WNW> <W></W> <WSW><WSW> <SW></SW> <SE></SE> <! -- southeast --> <ESE><ESE> <EE></EE> <WW></WW> </compass> Useful for Periodic table elements, simple, simultaneous super and subscripts, various linguistic stuff, etc. Without halfway positions and the far east and west positions, it acts like a 3x3 table with a concise notation and the appropriate cells populated. The four alternate corner cells positions are shifted half a cell towards the midline (to super/subscript positions) and the alternate far east and far west cells are shifted outward to new columns centered on the midline providing a way to guarantee that text which preceeds or follows is aligned with the midline. would look if super and sub scripts were placed over/above each other. <ninebox><WW>x=</WW><C>&integral_sign;</C><SE>&negative_infity;</SE><NE>&positive_infinity;</NE><WW>sin(x)/x</WW><ninebox> http://preparatorychemistry.com/Bishop_Isotope_Notation.htm Sodium with isotope, weight, and charge. <ninebox><WNW>23</NW><ESE>11</ESE><C>Na</C><ENE>+</ENE></ninebox> Instead of squash, you can have ENE, ENW, ESW, ESE for the four alternate corner locations. Of course, ninebox can be added to CSS, instead. display=ninebox, display=NW, display=NE, etc. This is good if you style: <element><name>NA</name><mass>23</mass><number>11</number><charge>+<charge></element> But it does get verbose if you have to use , etc. Styles might apply to change the size or shift position, but the fundamental structural orientation is more basic. This is finishing the job that subscript and superscript started and is arguably not just a style. It may not be that abstract but it is fundamentally structural and not just a superficial styling detail. And it eliminates some incredibly contorted use of tables for non-tabular data. You need a 11x9 table with lots of rowspans and colspans, to define the overlapping cell locations occupied by these locations. The basic tags could be defined and CSS used to fine tune the position or to apply equivalent behavior to abstract div/span markup or other xml namespaces. Note that even unicode deviates from its left-to-right/right-to-left model to provide an over and under code, but doesn't finish the job. This is more basic than MathML which also fails to be a suitably abstract math notation - you can't actually evaluate MathML expressions (hence the creation of OpenMath). This also applies to various areas outside the math domain. Started out as 9 boxes, hence the name, but a more suitable one should be used. Maybe compass? ~~~~ Nine slice images (Note: this one is in CSS3, so it only needs mention in HTML5 spec) Various systems use an image divided into 9 parts (like a tic-tac-toe board). Some names include scale-9 and 9-scale This defines two X and two Y image slice locations. When the image is scaled, the four corners are not scaled and the four edge squares and the center square are expanded. Very handy for buttons, tabs, window borders, etc. An example would be a rectangle with rounded edges. To implement this, you need a slice_x1, slice_x2, slice_y1, and slice_y2 attribute to be added wherever a tag has an attribute that can point to an image. (Note that this could also include pointing to an SVG file, though SVG tools probably haven't added this functionality. In the simplest cases, this would be replaced with desparately needed corner rounding on CSS. But it may contain much more detail. http://rwillustrator.blogspot.com/2007/04/understanding-9-slice-scaling.html This, with width="640" height="480" slice_x1="8" slice_y1="8" slice_x2="24" slice_y2="24" or more succinctly width=640 height=480 img_slice="8,8,24,24" or even more succinctly: width=640 height=480 img_slice="8" replaces an entire screenfull of HTML and reduces 9 image WGETS to one. It also eliminates additional structural damage because you can simply say background="foo.png" img_slice="8,8,24,24" And not put have your content in the middle of this 9x9 table monstrosity. Or better yet, style="{background-image=foo.png; background_img_slice=8,8,24,24;}" (actually, the slices have been added to border-image as: border-image: url("border.png") 8 8 8 8; http://www.neverpanic.de/blog/single/9-slice-scaling-in-html/ http://blog.hempton.com/2008/11/9-grid-scaling-support-in-javascriptcss/ http://www.bytearray.org/?p=118 http://grub.enbug.org/ThemeFormat These are supported in flash, adobe illustrator, fireworks, a jQuery plugin, an actionscript module, and a number of user interface toolkits. Even the grub bootloader supports it, after a fashion, automatically loading 9 images using a wildcard. Apparently, some even scale SWF animated backgrounds this way as if they were images. This should be pushed to CSS3 with the appropriate CSS3 module being released before HTML5 with the HTML5 specification specifically calling for HTML5 compliant tools to implement it and advising users to avoid the 9 separate images plus hideous markup. It would be a good addition to PNG, as well. CSS3 appears to accomodate 8 of the 9 slices, as 8 seperate images in the border module. But it also allows border-image to use a 9-slice. This will apparently be in firefox 3.1. I do think this merits some mention in the HTML5 spec. http://www.lrbabe.com/sdoms/borderImage/index.html ~~~
      blocks could have a numbering option 
       sets the initial line number to 100 and activates line numbering.  This allows the text which accompanies a 
       block to reference individual lines.   The initial number needs to be settable because in an online source code browser, numbers should line up with original file.    This can, however, be done by including
      the text of the numbers for autogenerated content.  <textareas> could also have numbering; this is very useful for matching up error messages with lines of markedup text when a wysiwyg editor is not used (for example, in a wiki); also, this is compatible with javascript wysiwig editors that take over a text area.  Low priority, but worth mentioning.
      ~~~~