Improve all examples #1199

edent · 2018-02-09T09:45:48Z

Fixes #1182

Please feedback any mistakes.

Ridiculously large, sorry!

Fixes #1182

* Indentation * Unicode Fixes #1182

Fixes #1182

* Better layout * Alt Text * Fixes #1176 ? Possibly Fixes #1182

* Fixes #1176 * Remove unnecessary bitly link * More cleanup Fixes #1182

* Fix alt text * Remove bitly * Fix broken links * Update examples to match the example given Fixes #1182

* Simplify Examples * Fill spelling and grammar * Beautify Fixes #1182

* Simplify examples Fixes #1182

Re #1182

* Invisible Times (!) made visible. * MathML example to be displayed Re #1182

Re #1182

* Clarify spellcheck Re #1182

Re #1182

* Needs answer from #1191 * Re #1182

Re #1182

* Simplified several examples * Added highlights where possible Re #1182

* Simplified examples * Reduced verbiage * Corrected errors Re #1182

* Simplified examples Re #1182

* Simplified examples (dramatically in some cases) * Fixed errors * Updated to modern style Re #1182

* Simplified * Fixed broken markup Re #1182

* Better example text (out of copyright) * Improved formatting * `sh` isn't a language code(!) Re #1182

* Improved abbr * Better quotes re #1182

chaals · 2018-02-09T12:16:37Z

Wondering if we should merge this and then continue review filing issues for particular things, or get the whole review done first. I don't mind either way...

agcolom · 2018-02-09T11:50:57Z

sections/semantics.include

-          &lt;p&gt; &lt;label for=c&gt; &lt;input id=a&gt; &lt;/label&gt; &lt;span id=b&gt; &lt;input id=c&gt; &lt;/span&gt; &lt;/p&gt;
-        </pre>
+        <xmp highlight="html">
+          <p> <label for=c> <input id=a> </label> <span id=b> <input id=c> </span> </p>


Should we add quotes around attribute values?

agcolom · 2018-02-09T11:53:32Z

sections/semantics-embedded-content.include

-      :: <pre highlight="html">
-  &lt;source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'&gt;
-      </pre>
+      :: <xmp highlight="html"><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></xmp>


Should we inverse single and double quotes in the source tag? (I'm good either way...). This goes for this line as well as the next 12 examples.

Actually, whatever we do we need to do for all examples with the codecs attribute

agcolom · 2018-02-09T11:56:41Z

sections/semantics-embedded-content.include

-    </pre>
+    <xmp highlight="html">
+      <ul>
+        <li><button><img src="b.png" alt="Bold"></button></li>


no closing tag for img. We either add it or modify the style guide. (My preference was no closing tag to img but I think I was the only one...).

I'd prefer it to be <img .... /> - I've not made the changes yet.

I prefer ... /> too

agcolom · 2018-02-09T11:57:06Z

sections/semantics-embedded-content.include

-    </pre>
+    <xmp highlight="html">
+      <a href="https://w3.org">
+        <img src="images/w3c_home.png" width="72" height="48" alt="W3C web site">


same as above (closing tag to img) (there is a number of examples on this page where this comment would apply. Some already have a closing tag.

agcolom · 2018-02-09T12:02:30Z

sections/semantics-embedded-content.include

-    </pre>
+    <xmp highlight="html">
+      <h2>From today's featured article</h2>
+      <img src="/uploads/100-marie-lloyd.jpg" alt="A singer on the stage" width="100" height="150">


same as previously... question about img closing tag

agcolom · 2018-02-09T12:31:51Z

sections/semantics-tabular-data.include

+      <caption>Specification values: <b>Steel</b>, <b>Castings</b>, Ann. A.S.T.M. A27-16, Class B;* P max. 0.06; S max. 0.05.</caption>
+      <thead>
+        <tr>
+          <th rowspan=2>Grade.</th>


not sure, but wondering whether 2 should be in quotes or is it as is intentionally? (also next example)

I missed it. My grep was looking for words after =. Didn't think about numbers! D'oh!

agcolom · 2018-02-09T12:36:38Z

sections/semantics-grouping-content.include

+      <xmp highlight="html">
+        <p>For instance, this fantastic sentence has bullets relating to</p>
+        <ul>
+          <li>wizards,<li>


should <li> at end of lines be </li>?

agcolom · 2018-02-09T12:37:24Z

sections/semantics-grouping-content.include

+      <xmp highlight="html">
+        <div>For instance, this fantastic sentence has bullets relating to
+          <ul>
+            <li>wizards,<li>


See above (eol <li> -> </li>)

agcolom · 2018-02-09T12:37:41Z

sections/semantics-grouping-content.include

+        <div>
+          <p>For instance, this fantastic sentence has bullets relating to</p>
+          <ul>
+            <li>wizards,<li>


See above (eol <li> -> </li>)

agcolom · 2018-02-09T12:43:36Z

sections/browsers.include

@@ -5103,7 +5103,7 @@
        </head>

        <body onload="updateIndicator()" ononline="updateIndicator()" onoffline="updateIndicator()">
-          <p>The network is: <span>(state unknown)</span>
+          <p>The network is: <span>(state unknown)</p>


Should there still be a  before ?

@agcolom

Thanks @agcolom & @chaals

chaals

couple more things...

chaals · 2018-02-09T18:01:13Z

sections/semantics-sections.include

-      &lt;/style&gt;
+    <xmp highlight="html">
+      <style>
+        section { border: "double medium"; margin: "2em"; }


some quotes that should not be in CSS

chaals · 2018-02-09T18:03:02Z

sections/semantics-sections.include

+    <xmp highlight="html">
+      <nav>
+        <h2>Navigation</h2>
+        <p>You are on my home page. To the north lies <a href="/blog">my blog</a>, from whence the sounds of battle can be heard. To the east you can see a large mountain, upon which many <a href="/school">school papers</a> are littered. Far up this mountain you can spy a little figure who appears to be me, desperately scribblinga <a href="/school/thesis">thesis</a>.</p>


"from whence" is tautological, redundantly repeating the same concept twice.

And should "scribblinga" be "scribbling on a"?

If it's good enough for Shakespeare, it's good enough for the spec :-) https://english.stackexchange.com/questions/10906/is-from-whence-correct-or-should-it-be-whence
I'll fix the scribbling.

jonathantneal · 2018-02-10T15:46:17Z

sections/infrastructure.include


-    You can also mix styles; the following is still equivalent:
+    You can also mix styles; the following is also equivalent:


I’m not sure this is better. This now says “also” twice.

jonathantneal · 2018-02-10T15:49:32Z

sections/introduction.include


-          <pre class="bad" highlight="html">&lt;a href="?art&amp;copy">Art and Copy&lt;/a></pre>


Does <xmp> know to escape &?

jonathantneal · 2018-02-10T15:52:49Z

sections/semantics-interactive-elements.include

+
+    CSS:
+    <xmp highlight="css">
+      details>summary {


May the selector spacing be preserved here? e.g. details > summary. That would be more readable and consistent with the choice to preserve spacing between properties and values.

Agreed. Note to self - https://www.w3.org/TR/CSS2/selector.html#child-selectors

jonathantneal · 2018-02-10T16:08:53Z

sections/browsers.include

-  &lt;/p>
-  </pre>
+    <xmp highlight="html">
+      <!DOCTYPE html>


The HTML5 Boilerplate project already went through the hot drama of this and ended up going with lowercase conformity (<!doctype html>), which has then trickled down into other projects. However, if we’re going to kick the dust back up and uppercase part or all of this, I’d hope everyone plays nice and aligns on one defacto.

h5bp/html5-boilerplate#1522

My first pass was to make it consistent throughout the examples. Discussion on what it should be is taking place in #1193
I'm happy either way.

LC43

started bottom up, pointed out some unescaped strings and suggested rephrasing.

LC43 · 2018-02-10T15:25:23Z

sections/syntax.include

@@ -6647,7 +6667,7 @@
  following markup:

  <pre highlight="html">
-    &lt;table>&lt;b>&lt;tr>&lt;td>aaa&lt;/td>&lt;/tr>bbb&lt;/table>ccc
+    &lt;table><mark>&lt;b></mark>&lt;tr>&lt;td>aaa&lt;/td>&lt;/tr>bbb&lt;/table>ccc


missing unescape.

I'm not sure what you mean. The  element has to be unescaped in order to highlight the text.

i meant the rest of the tags. so, if i got this right, if a block of code has a , none of it is transformed into <xmp highlight="html"> and unescaped ?

presumably your comment was "has a  element ...

In which case the answer is yes. We keep using <pre> if we want to use actual markup on the example code...

LC43 · 2018-02-10T15:29:38Z

sections/syntax.include

+          <xmp highlight="html" class="bad"><a href="a">a<table><a href="b">b</table>x</xmp>
+          The first <{a}> element would be closed upon seeing the second one, and the "x" character
+          would be inside a link to  "b", not to "a". This is despite the fact that the outer
+          <{a}> element is not in table scope (meaning that a regular &lt;/a&gt; end tag at the


missing unescape.

LC43 · 2018-02-10T15:34:59Z

sections/syntax.include

@@ -362,74 +362,74 @@
  <div class="example">
    For example, in the following case it's ok to remove the "<code>&lt;html></code>" tag:


missing unescape in line 363 and in line 356.

LC43 · 2018-02-10T15:40:13Z

sections/syntax.include


    With the tag removed, the document actually turns into the same as this:

    <pre highlight="html">
-      &lt;!DOCTYPE HTML>
+      &lt;!DOCTYPE html>


these next lines are missing unescape.

This is intentional. There is no way to add a  into an <xmp> element and have it show up as highlighted text.

this is answers my question above :)

LC43 · 2018-02-10T15:50:51Z

sections/syntax.include

+          <p>Welcome to this example.</p>
+        </body>
+      </html>
+    </xmp>

    (The <{body}> and <{html}> element end tags could be omitted without trouble; any spaces after
    those get parsed into the <{body}> element anyway.)

    Usually, however, white space isn't an issue. If we first remove the white space we don't care


how about rephrasing this as:
"If the white space is not important, it can be removed:"

If so, the next lines could also be changed.

LC43 · 2018-02-10T15:52:13Z

sections/syntax.include

-    </pre>
+    <xmp highlight="html">
+      <!DOCTYPE html><title>Hello</title><p>Welcome to this example.</p>
+    </xmp>

    At that point, we can also add some white space back:


"At that point, some white space can be added back:"

LC43 · 2018-02-10T15:54:34Z

sections/syntax.include

@@ -528,7 +528,7 @@
    We can thus simplify the earlier example further:


"Thus, the earlier example can be simplified further:"

LC43 · 2018-02-10T16:04:04Z

sections/syntax.include

@@ -912,13 +918,13 @@
    In the following example, the tree construction stage will be called upon to handle a "`p`"


some references to tags use <{p}>, and in this case to

"`p`"

LC43 · 2018-02-10T16:06:57Z

sections/syntax.include

      ...
-    </pre>
+    </xmp>
  </div>

  To handle these cases, parsers have a <dfn>script nesting level</dfn>, which must be initially set


``` The DOM will not let {{Document}} nodes contain {{Text}} nodes, so they are ignored. ```

LC43 · 2018-02-10T16:09:02Z

sections/syntax.include

+      <td>
+        <xmp highlight="html">
+          A<script>
+            var  text  =  document.createTextNode('B');


extra whitespace.

* Re #1199 (comment) * Re #1182

* re #1199 (comment) * Re #1182

* re https://github.com/w3c/html/pull/1199/files/4ef35b7e3aed78cdec6414ca60ec77e36dbf76c4#r167402154 * re #1182

* Re #1199 (comment) * Re #1182

* Fix #1199 (comment) * Re #1182

scottaohara · 2018-02-11T18:14:58Z

sections/browsers.include

-  </pre>
+    <xmp highlight="html">
+      <!DOCTYPE html>
+      <title>Line</title>


should we wrap this in a head? Other examples in this file do so, and there's a body in this example.

Yup. Fixing it now.

* Re #1199 (review) * Re #1182

jonathantneal · 2018-02-13T14:34:55Z

🎉 Thanks for getting this in!

Is it live? I’m seeing odd indentation in the Drag and Drop Introduction Example.

scottaohara · 2018-02-13T15:36:05Z

@jonathantneal there may be some instances where we need to do some additional clean up.

I just did some other minor edits to that file & example, so once that is published, we'll see if the indenting is still an issue.

judeGibbons · 2018-02-14T22:16:55Z

sections/semantics-document-metadata.include

@@ -832,12 +832,11 @@
  <div class="example">
  The following examples illustrate code that should be avoided:
  <pre highlight="html">
+    &lt;!-- DO NOT DO THIS -->


3 stray < s - lines 835, 837, 839

No, these are in a pre element, with live  elements so specific bits get highlighted. So the code for display needs to be escaped as it is.

Chaals is right. They need to stay escaped.

judeGibbons · 2018-02-14T22:20:06Z

sections/semantics-document-metadata.include

+      <!DOCTYPE html>
+      <html lang="en">
+        <head>
+          <title>This is an example for the &lt;base&gt; element</title>


stray < and >

These aren't stray. They're needed to display the <base> as is.

Actually you don't within a title element. It uses the RCDATA parsing path so the text goes into the DOM

I am not sure if I would recommend writing HTML this way, though. Question for the Style guide #1193 I suspect

chaals · 2018-02-15T09:37:09Z

Please note

This Pull Request has been merged. Changes should be suggested as new issues, and made as new Pull Requests.

edent added 30 commits February 3, 2018 22:40

Update examples - semantics-root

08b06ee

Fixes #1182

Update examples - rendering

3239e6f

* Indentation * Unicode Fixes #1182

Update Examples - webappapis

bff7293

* Indentation * Unicode Fixes #1182

Update Examples - semantics

d1ed57e

Fixes #1182

Update Examples - obsolete

eda8fee

Fixes #1182

Updated Examples - semantics-embedded-content

b76dfa6

* Better layout * Alt Text * Fixes #1176 ? Possibly Fixes #1182

Update Examples - semantics-embedded-content

b46891d

* Fixes #1176 * Remove unnecessary bitly link * More cleanup Fixes #1182

Update Examples - semantics-embedded-content

bf6cee6

* Fix alt text * Remove bitly * Fix broken links * Update examples to match the example given Fixes #1182

Update Example - semantics-embedded-content

7cc9f6b

* Simplify Examples * Fill spelling and grammar * Beautify Fixes #1182

Update examples - semantics-embedded-content

464c84e

* Simplify examples Fixes #1182

Major fix to image map example

eb050ed

Re #1182

MathML example corrected - semantics-embedded-content

93ca24a

* Invisible Times (!) made visible. * MathML example to be displayed Re #1182

Update Example - infrastructure

7577d1b

Re #1182

Update Examples - semantics-interactive-elements

626413f

Re #1182

Updated examples - Browsers

14d069d

Re #1182

Updated Exampls - editing

960e249

* Clarify spellcheck Re #1182

Update highlighting - editing

1c72d4c

Re #1182

Updated Examples - introduction

a765769

Re #1182

Update examples - semantics-edits

b27608f

* Needs answer from #1191 * Re #1182

Update Examples - semantics-edits

6bf284a

Re #1182

Update Examples - semantics-document-metadata

9842a50

Re #1182

Updated Examples - semantics-common-idioms

f3b2bd8

Re #1182

Update Examples - semantics-scriptings

b29585f

Re #1182

Updated Examples - semantics-links

6392d31

* Simplified several examples * Added highlights where possible Re #1182

Update examples - semantics-tabular-data

72f47f6

* Simplified examples * Reduced verbiage * Corrected errors Re #1182

Updated examples - dom

dd98e68

* Simplified examples Re #1182

Update examples - semantics-sections

50101e6

* Simplified examples (dramatically in some cases) * Fixed errors * Updated to modern style Re #1182

Update Examples - syntax

adf11b0

* Simplified * Fixed broken markup Re #1182

Updated examples - semantics-grouping-content

51cc5ff

* Better example text (out of copyright) * Improved formatting * `sh` isn't a language code(!) Re #1182

Updated examples - semantics-textlevel (1)

44f0e3e

* Improved abbr * Better quotes re #1182

agcolom reviewed Feb 9, 2018

View reviewed changes

edent added 2 commits February 9, 2018 15:08

Updated Examples - fix errors

6cb9c04

Thanks @agcolom & @chaals

Merge branch '1182-edent-xmp' of github.com:w3c/html into 1182-edent-xmp

4ef35b7

chaals reviewed Feb 10, 2018

View reviewed changes

jonathantneal reviewed Feb 10, 2018

View reviewed changes

LC43 reviewed Feb 10, 2018

View reviewed changes

chaals and others added 7 commits February 11, 2018 00:08

Thank you...

2120127

Fix CSS

6a62750

* Re #1199 (comment) * Re #1182

Fix examples

b019803

* Re #1199 (comment) * Re #1182

Update Examples

122ca28

* re #1199 (comment) * Re #1182

Update examples

4da3c99

* re https://github.com/w3c/html/pull/1199/files/4ef35b7e3aed78cdec6414ca60ec77e36dbf76c4#r167402154 * re #1182

Update examples

170682f

* Re #1199 (comment) * Re #1182

Update Examples

a4088b1

* Fix #1199 (comment) * Re #1182

scottaohara reviewed Feb 11, 2018

View reviewed changes

scottaohara mentioned this pull request Feb 11, 2018

Create Style Guide for our examples #1193

Closed

Update Examples

1867fcf

* Re #1199 (review) * Re #1182

chaals removed the help wanted label Feb 13, 2018

chaals merged commit 44d4428 into master Feb 13, 2018

chaals mentioned this pull request Feb 13, 2018

Cleanup Embedded content section #1176

Closed

judeGibbons reviewed Feb 14, 2018

View reviewed changes

w3c locked as resolved and limited conversation to collaborators Feb 15, 2018

edent deleted the 1182-edent-xmp branch October 17, 2018 15:14


		You can also mix styles; the following is still equivalent:
		You can also mix styles; the following is also equivalent:


		<pre class="bad" highlight="html"><a href="?art&copy">Art and Copy</a></pre>

		@@ -362,74 +362,74 @@
		<div class="example">
		For example, in the following case it's ok to remove the "<code><html></code>" tag:

		@@ -528,7 +528,7 @@
		We can thus simplify the earlier example further:

		@@ -912,13 +918,13 @@
		In the following example, the tree construction stage will be called upon to handle a "`p`"

Improve all examples #1199

Improve all examples #1199

Conversation

edent commented Feb 9, 2018

chaals commented Feb 9, 2018

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

chaals Feb 9, 2018 • edited Loading

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

agcolom Feb 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chaals 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathantneal Feb 10, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LC43 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LC43 Feb 11, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LC43 Feb 10, 2018 • edited Loading

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

LC43 Feb 10, 2018 • edited Loading

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

jonathantneal commented Feb 13, 2018

scottaohara commented Feb 13, 2018

judeGibbons Feb 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

judeGibbons Feb 14, 2018 • edited Loading

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

chaals commented Feb 15, 2018

chaals Feb 9, 2018 •

edited

Loading

agcolom Feb 9, 2018 •

edited

Loading

jonathantneal Feb 10, 2018 •

edited

Loading

LC43 Feb 11, 2018 •

edited

Loading

LC43 Feb 10, 2018 •

edited

Loading

LC43 Feb 10, 2018 •

edited

Loading

judeGibbons Feb 14, 2018 •

edited

Loading

judeGibbons Feb 14, 2018 •

edited

Loading