tt elements not allowed in html5 - replace with var ?

[DanRathbun]

Re, the html default templates (and their css.)

<tt> elements are not allowed in html5.

Q? Should they be replaced with <var> elements ?

(1) Basically it will be a search and replace on the erb files. But should these new files be put in a new format folder "html5" ?

(2) And then a check through the default stylesheet(s) to add selector chains with var wherever tt is currently used. (It is probably a good idea to leave the selector chains with tt in the stylesheet for now, as custom templates may rely upon them for some time to come.)

"default/fulldoc/html/css/full_list.css" No occurances of tt

"default/fulldoc/html/css/styles.css" Occurances of tt: L96 L241 L256 L257 L270

[DanRathbun]

I am wondering if perhaps ERB can replace html elements when it parses ".erb" files ?

[lsegal]

Is there a reason to change this? Can you list any browsers that reproduce rendering problems?

[DanRathbun]

Just asking a question.

Can you list any browsers that reproduce rendering problems?

I would not call following the specification a problem. Unknown or not allowed elements are supposed to be ignored. As at some time in the future, pages rendered with strict will likely not display those elements that are no longer allowed. (If things follow the same behavior as they did in the past.)

NO, I have not yet done any testing.

And well I thought perhaps maybe you may wish to do some planning ahead for default html5 template(s). There may be other elements that are no longer "allowed". (I have only noticed <tt> so far.)

I thought I'd ask your opinion, about how best to handle something like this. (Just humor me.) If you had to,.. would you change the default "html" template, or create a new one beside it named "html5" ?

If you don't know (or care,) then maybe tag this issue with "Question" and "Investigate" and perhaps someone else will weight in.

Or perhaps there is a YARD forum somewhere I do not know of, that is better for these type of questions ?

Is there a reason to change this ?

I my mind yes,... since I'm editing basically all of the erb files, (for my custom template,) I thought I might as well change them now. (Three years from now, I won't want to spend two weeks relearning the guts of YARD all over again.)

[0x1eef]

@lsegal well, it is not valid HTML5 markup.. but i doubt it's gonna break in any browsers anytime soon. still, the w3c validator test for the base64 module docs (generated by yard of course) notes "tt" is obsolete and recommends using CSS instead. it's not the only warning/error though.

[lsegal]

@DanRathbun sorry, I may have been misunderstanding your question:

Q? Should they be replaced with elements ?

I was understanding this to mean should they be replaced in YARD's codebase. If you are customizing your templates, you can feel free to customize anything you like in order to comply with whatever requirements you have. You don't need to move them to a custom folder.

To answer your second question, yes, YARD does have a mailing list for dicsussions:

https://groups.google.com/forum/#!forum/yardoc

The GitHub issues list is more for problems / features meant to be added to YARD itself. This is why I thought we were talking about making changes to YARD.

[DanRathbun]

If you are customizing your templates, you can feel free to customize anything you like in order to comply with whatever requirements you have.

Of, course this is obvious. What I do in my template will not effect anyone else unless they adopt my template. And of course, I can decide to use <pre> elements (or just a <div> or <span> with monospace css font-family,) ... as <var> elements are said to be rendered in italic style by most browsers.

I thought we were talking about making changes to YARD.

Well, ... I was bringing up the issue, that I have found obsolete elements in the default template. I suspected that there are more issues related to html5, and @r-obert has confirmed this.

I am the kind of person who likes to plan ahead and fix things when they are right in front of me. I do not like to put things off if I suspect they'll pop up to bite me later.

So, yes I posted it here to make you and YARD contributors generally aware of html5 issues. But wrote it aimed towards a known specific issue (as I thought it might be rejected out of hand if it were a general issue / question.)

@r-obert, thank you for the validation report! It shows there are also some other issues with the default templates. (Stylesheets could use a first line of: @charset "UTF-8" and templates remove charset attribute from <link> elements loading stylesheets.)

I see the <div> not allowed beneath <span> elements as the most problematic.

So, Loren, seeing as how there are a great many users affected using the current default "html" template, ... I wondered if it was smarter to create a side-by-side clone named "html5", that could be used via command line parameter: "yardoc -f html5"

Or perhaps you have a better idea ? A plugin that automatically on-demand "html5-ifies" the current default "html" template ??

[0x1eef]

@DanRathbun the html template uses the HTML5 doctype, so it is HTML5 with a few markup errors. fixing them in one template sounds better than creating two templates, one broken and one fixed, then defaulting to the broken one.

[DanRathbun]

@r-obert I agree, but was reluctant to break current sites. Having a temporary format template specifically for "html5" could serve as a test in the interim. (I am wary of using Git branches as I've already sync'd to the wrong branch before and lost edits. Not an expert at all the ins and outs of Git.) Then again, the current template isn't exactly broken yet.

[lsegal]

Sorry, this thread is hard to follow.

You're both right-- yes, there are theoretical future problems with the markup being used, but also, yes, changing this in the library would probably break a couple of users relying on <tt> styling. Breaking users is a much more immediate issue, and so changing this is a non-starter right now, unless you can provide a case where real-world users are already being affected.

Creating a new html5 template is also not a valid solution since it's unlikely to ever be used by users (we found that nobody opted into alternative templates when we had them). That codebase is likely to languish since it won't be in the direct usage path and nobody will be maintaining or reporting issues on it.

Unless someone can provide a concrete case where users are affected by this or will be at some known time ("in the future" is not an argument here since there is no actual timeline for deprecation and realistically <tt> is unlikely to ever be ignored outright by user-agents any time soon), I'm inclined to close this as WontFix.

Or perhaps you have a better idea ? A plugin that automatically on-demand "html5-ifies" the current default "html" template ??

You're also free to write this. If a large number of users are using this over YARD's default template, we can re-have the discussion, but not breaking existing users will always be a priority over these kinds of refactors.

[DanRathbun]

Everything you say is understandable. But a few notes:

... yes, changing this in the library would probably break a couple of users relying on <tt> styling.

I did note above, (and even searched using my code editor,) every occurrence of tt in the stylesheets, and said that any current rules (for tt) should not be removed, but rather have whatever element would replace <tt> in the templates, be added into the selector sets for the same rules.

Creating a new html5 template is also not a valid solution since it's unlikely to ever be used by users (we found that nobody opted into alternative templates when we had them).

I meant this only as a temporary "test bed" template. But I suppose it could be added into a YARD install via a gem or plugin ? (Then, testers would be installing purposefully in order to test, via -f html5 CLI parameter.)

So then it wouldn't need be in the default YARD gem at all. (Until some time in the future when it is needed.) Strike that. If I have to do this on my own, it will not be a drop in replacement for the default template.

... (we found that nobody opted into alternative templates when we had them).

I cannot see why. Everyone I know who has to use the output from the default html template does not care for how the results work. The 4 guys guys I know who have their own projects and know how YARD works, are planning on doing their own templates from scratch.

Anything more than tweaking a few styles with an addendum stylesheet, quickly becomes a convoluted timesink. (It seems no management anywhere wants to spend any more time or money on documentation than the basics.)

You're both right-- yes, there are theoretical future problems with the markup being used, but ...

The <tt> elements are not the only issue that is found by the validator. In addition, because of misuse of <div>, (a block element,) as inline,... the validator has not fully checked the output.

You're also free to write this.

Ok. Will do. I'll put a html5 template in my own repo, as a plugin or a gem addon.

This will also allow me to do some hierarchical structure changes to the output, and add navigation features.

[DanRathbun]

Unless someone can provide a concrete case where users are affected by this or will be at some known time ("in the future" is not an argument here since there is no actual timeline for deprecation and realistically <tt> is unlikely to ever be ignored outright by user-agents any time soon), I'm inclined to close this as WontFix.

I'll save you the trouble, since I opened it.

Recently many people were the victims of this same thinking, twice over. Once because suddenly Google Maps API no longer wanted to support MSIE below version 10, and began displaying a warning to users that they needed to update their browsers, or use another one. Problem is it wasn't a browser. It was a browser frame inside an application process.

The other issue occurred when browser emulation version was increased, it broke javascript code (running in these embedded browser frames,) that still used old deprecated Microsoft IE only event names,... which was no longer allowed in MSIE v11.

The point I'm making is that both of these situations (one causing the other,) were foreseeable and preventable because features were deprecated and ample time was given to adjust products. But preventative maintenance was not done, and the failures occurred right in the face of the users, preventing the customers from doing the work they do with the software product. They then freak out, post in the forums, they need to install fixes, etc. The customer is not happy having wasted half a day.

Ok. So I had my say. I've given you a "heads up".