RFR: 8294158: HTML formatting for PassFailJFrame instructions

Wed Sep 20 18:09:40 UTC 2023

On Tue, 12 Sep 2023 14:11:15 GMT, Alexey Ivanov <aivanov at openjdk.org> wrote:

>>> Could be… On the other hand, in post XHTML era, the elements are usually in lower-case. Thus we should stick with it and use lowercase HTML elements anyway.
>> 
>> https://www.w3schools.com/html/html_elements.asp
>> 
>>> HTML is Not Case Sensitive
>>> 
>>> HTML tags are not case sensitive: `<P>` means the same as `<p>`.
>>> 
>>> The HTML standard does not require lowercase tags, but W3C recommends lowercase in HTML, and demands lowercase for stricter document types like XHTML.
>>> 
>>> At W3Schools we always use lowercase tag names.
>> 
>> So this is still a recommendation, not a requirement (we don't use XHTML).
>> But I agree that this can be helpful for a certain amount of consistency across tests(they can still use other tags in uppercase).
>> 
>> 
>>> Although neither <html> nor <body> are required, I prefer to always add them. These two elements don't add much overhead, do they?
>> 
>> It is a matter of personal taste. 
>> Normally, I prefer to indent a content of such tags by extra spaces, andThis can create additional formatting difficulties under the 80(120) character limit per line.
>> In those cases, I would prefer to omit those tags.
>
> I know HTML is *not case sensitive*. It's just HTML tags are always in lower case in recent years.
> 
>> But I agree that this can be helpful for a certain amount of consistency across tests(they can still use other tags in uppercase).
> 
> Yep! In a way, this will enforce `<html>` in lower case, and I hope all other tags in the instructions.
> 
> 
> 
>> >  Although neither nor are required, I prefer to always add them. These two elements don't add much overhead, do they?
>> 
>> It is a matter of personal taste.
> 
> Yes, it is… which could create inconsistencies.
> 
>> Normally, I prefer to indent a content of such tags by extra spaces, and  
>> This can create additional formatting difficulties under the 80(120) character limit per line.  
>> In those cases, I would prefer to omit those tags.
> 
> I don't expect too many nesting levels in instructions. However, I agree it could be problematic…
> 
> In the sample in #15661, I keep `<html><body>` and the content on the same level.
> 
> Now that I looked at it again, I realised that I didn't follow the indentation consistently: first-level `<li>` aren't indented but third-level `<li>` are. I should correct this.
> 
> Because `<pre>` is used to format pieces of code, I decided not to indent the first-level `<li>` elements to avoid indentation of the code inside.

I don't have a problem with keeping it simple. If some one writing a test doesn't see the HTML interpreted, they'll quickly be able to figure out why.
One thing about these and the other enhancements I see is that there's an (increasing) need for a nice bit of documentation in PassFailJFrame itself about all its features. 
Easiest to do this as you are adding them, so a doc comment block can be started with this one.
Probably as a class comment.

Suggested text
/**
 * PassFailJFrame documentation
 * 
 * Instructions for the user can be either plain text or HTML as supported by Swing.
 * Text beginning with <html\> is presumed to be HTML.
*/

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/15660#discussion_r1332006327