RFR: 8294158: HTML formatting for PassFailJFrame instructions

Mon Oct 23 21:13:40 UTC 2023

On Wed, 20 Sep 2023 18:05:31 GMT, Phil Race <prr at openjdk.org> wrote:

>> 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.
> */

@prrace I've added description on how to use `PassFailJFrame` to #15665, it handles both HTML formatting for instructions (this PR) as well as creating test UI by passing a method reference, or rather an implementation of an interface.

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

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