Re: Formatting of html tags

I am against the third usage suggestion - I think we should always mark an
element name with <code>, whether or not there are angle brackets.

(I also think we should be consistent, but I understand it makes it harder
to edit and inconsistencies will surely slip through)


☆*PhistucK*


On Fri, Jul 18, 2014 at 8:05 PM, Amelia Bellamy-Royds <
amelia.bellamy.royds@gmail.com> wrote:

> 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/#renoirb  ✪  https://renoirboulanger.com/  ✪
>>>>>  @renoirb
>>>>> ~
>>>>>
>>>>>
>>>>>
>>>>
>>>
>>
>