W3C home > Mailing lists > Public > public-webplatform@w3.org > July 2014

Re: Formatting of html tags

From: Amelia Bellamy-Royds <amelia.bellamy.royds@gmail.com>
Date: Fri, 18 Jul 2014 11:05:57 -0600
Message-ID: <CAFDDJ7yw87zjYso1gkp59dF7a3neOztHRq=bqEgAAT=hh8qsdg@mail.gmail.com>
To: PhistucK <phistuck@gmail.com>
Cc: Pearl Chen <pearlchen@google.com>, Renoir Boulanger <renoir@w3.org>, "public-webplatform@w3.org" <public-webplatform@w3.org>
There is one other issue to think of -- accessibility.

If the HTML is "How to use the <code>&lt;style&gt;</code> element", most
screen readers will read that as "How to use the less-than style
greater-than element".  While it is important that screen readers
communicate punctuation markup for inline code, I'm sure it's rather
annoying if every sentence in a page has those extra less-than/greater-than
marks read out.

However, I am still uncomfortable about having marks that appear in the
page and look like normal text, but which are not copied when someone
selects the text.

I think a sensible approach is:

   - If you use the word "element", this conveys the same meaning as the
   angle brackets, so they are not required and neither is the code markup.
      - "The style element is widely supported in browsers".
   - If you are using the tag name on its own to represent the element, use
   angle brackets and code mark-up.
      - "There is wide browser support for* <style>*."
   - If the context of the sentence makes it completely clear that you're
   talking about an element tag, you can just use the tag name.
      - "The span element can be used to apply custom styles with CSS.  The
      use of a span should be limited to situations where there is no valid
      semantic tag."
   - However, if there is ambiguity (e.g. style element versus style
   attribute), use one of the other formats.
   - In a page about an element tag, be sure to show the tag format, with
   angle brackets, at least once -- preferably in the summary.

Example:
 "The teletype element (<code>&lt;tt&gt;</code>) creates monospaced text.
 It's use is deprecated in favour of semantic elements like
<code>&lt;code&gt;<code>.  However, the tt element is still widely
supported in browsers."

Which would render like:
 "The teletype element (*<tt>*) creates monospaced text.  It's use is
deprecated in favour of semantic elements like *<code>*, along with CSS
stylesheets.  However, the tt element is still widely supported in
browsers."

(And yes, Renoirb, please try to break old habits and use <code> instead of
the non-semantic <tt>.  WPD should be an example of best practices!)

This seems to be the style used by MSDN imported pages, except for
code-formatting markup, which makes things easier, too.  E.g, see:
http://docs.webplatform.org/wiki/html/elements/input

One thing's certain.  Once a consensus is reached in this discussion, we
should update the style guide!

Amelia BR



On 18 July 2014 10:23, PhistucK <phistuck@gmail.com> wrote:

> Your example is unrelated...
> My suggestion was only referring to the element name mention situation.
> Inline code is unrelated here and of course should have actual angle
> brackets.
>
>
> ☆*PhistucK*
>
>
> On Fri, Jul 18, 2014 at 7:18 PM, Pearl Chen <pearlchen@google.com> wrote:
>
>> Regarding copy and paste of the angled brackets, I would want the
>> brackets copied too, especially if the inline code represented something
>> more than just the tag name. Example:
>>
>> Display: "An element can be styled using using the *style* attribute
>> (e.g. *<div style="padding: 1em;"></div>*) or via CSS selectors."
>>
>> Wiki input:  "An element can be styled using using the
>> <code>style</code> attribute (e.g. <code>&lt;div style="padding:
>> 1em;"&gt;&lt;/div&lt;</code>) or via CSS selectors."
>>
>> A blanket statement saying that all inline code should be wrapped in
>> <code></code> seems sufficient to me.
>>
>> A contributor really shouldn't have to think so hard, or know so many
>> rules about their writing situation, in order to contribute.
>>
>>
>>
>>
>>
>> On Fri, Jul 18, 2014 at 12:00 PM, Pearl Chen <pearlchen@google.com>
>> wrote:
>>
>>> I've never used <tt> before and when I looked it up, MDN says
>>> <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tt> <tt> is
>>> obsolete and shouldn't be used anymore.
>>>
>>> For most developers and content writers, <code> would be more apparent,
>>> imo.
>>>
>>>
>>>
>>>
>>>
>>>
>>> On Fri, Jul 18, 2014 at 11:51 AM, Renoir Boulanger <renoir@w3.org>
>>> wrote:
>>>
>>>> hi all,
>>>>
>>>> Personally, what I do is one of three things:
>>>>
>>>>
>>>> 1. Inline mention
>>>>
>>>> When I have to use a tag name in full, I use <tt>&lt;tag-name&gt;</tt>.
>>>> Not pretty, but not too long to write.
>>>>
>>>>
>>>> 2. In page code sample
>>>>
>>>> I use the <syntaxHighlight> extension which takes care of hilighting [0]
>>>>
>>>> <syntaxHighlight lang="html5">
>>>>   <!DOCTYPE html>
>>>>   ...
>>>> <syntaxHighlight>
>>>>
>>>> The syntaxHighlight escapes for us the tags, supports html and all that
>>>> jazz.
>>>>
>>>> And, it works pretty well [1]
>>>>
>>>>
>>>> 3. Create a code sample in Dabblet
>>>>
>>>> see code.webplatform.org
>>>>
>>>>
>>>>   [0]:
>>>>
>>>> http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages
>>>>   [1]:
>>>>
>>>> http://docs.webplatform.org/w/index.php?title=Beginners/html&action=formedit
>>>>
>>>> --
>>>> Regards,
>>>>
>>>> Renoir Boulanger  |  Developer operations engineer
>>>> W3C  |  Web Platform Project
>>>>
>>>> http://w3.org/people/#renoirbhttps://renoirboulanger.com/  ✪
>>>>  @renoirb
>>>> ~
>>>>
>>>>
>>>>
>>>
>>
>
Received on Friday, 18 July 2014 17:06:33 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:21:02 UTC