Bug 50923

Summary: Difficult to pick out valid values from config descriptions
Product: Tomcat 7 Reporter: Sebb <sebb>
Component: DocumentationAssignee: Tomcat Developers Mailing List <dev>
Severity: enhancement    
Priority: P2    
Version: trunk   
Target Milestone: ---   
Hardware: PC   
OS: Windows XP   
Attachments: Patch to add <entry> markers to http.xml and process them in XSL
Screenshot Fx zoomed

Description Sebb 2011-03-13 20:51:35 UTC
Created attachment 26766 [details]
Patch to add <entry> markers to http.xml and process them in XSL

It's quite difficult picking out the valid values from the configuration documentation.  For example, the clientAuth description under


does not make it easy to see that the permissible values are "true", "want" and "false", because the code font is not very different from the normal font.

It would be easier to see the values if they were in bold or otherwise high-lighted.

Rather than add fixed styling within the source XML files, maybe one could take advantage of the XSL processing and replace the <code> entries with some other markup to flag such values, e.g. <entry>true</entry>.

Sample patch attached.
Comment 1 Christopher Schultz 2011-09-20 21:55:50 UTC
I don't happen to like the tag <entry> but that's a matter of taste, I suppose. I think that instead of defining <entry> to emit <strong>"<code>(text)</code>"</strong>", CSS should be used instead. Maybe something like <span class="entry">(text)</span> or even <code class="entry">(text)</code> so it will degrade nicely when some idiot tries to view the documentation using NCSA Mosaic.

Are the values that difficult to pick-out of the text? <code> does a fine job on my display.
Comment 2 Sebb 2011-09-20 22:36:21 UTC
Created attachment 27546 [details]
Comment 3 Sebb 2011-09-20 22:36:39 UTC
Created attachment 27547 [details]
Comment 4 Sebb 2011-09-20 22:36:59 UTC
Created attachment 27548 [details]
Comment 5 Sebb 2011-09-20 22:37:29 UTC
Created attachment 27549 [details]
Screenshot Fx zoomed
Comment 6 Sebb 2011-09-20 22:43:24 UTC
Only when I zoom the Firefox display do I start to see a difference with the <code> sections.

I use a 17" screen, 1440x900 pixels, WinXP, in case that's relevant.

I don't really care whether HTML or CSS is used to improve the contrast.

Another point is that tagging the values helps distinguish them semantically, potentially allowing other useful processing.
Comment 7 Konstantin Kolinko 2011-09-26 06:52:00 UTC
I changed the color for <code> tags in trunk in r1175690.
Generated documentation is available at buildbot. Please review.

I am hesitant to introduce another tag.

BTW, the generated template uses <font> tags and other old markup. It would be nice to get rid of it at some day.
Comment 8 Sebb 2011-09-27 21:46:11 UTC




show the updated HTML.

Is there another buildbot place to check?
Comment 9 Konstantin Kolinko 2011-09-27 22:12:01 UTC
(In reply to comment #8)

The second one (tomcat8). Maybe it is cached in your browser, or maybe you are just not noticing.
Comment 10 Sebb 2011-09-27 23:49:08 UTC
OK, found the added style tag now (was looking in wrong place).

Unfotunately it does not make a noticeable difference to any of my browsers.
Comment 11 Konstantin Kolinko 2011-10-02 18:02:23 UTC
I used a more distinct color in r1178209.
Applied to TC7 in r1178210. Will be 7.0.23.

I have not touched older Tomcat versions, but I think it can be backported there.
Comment 12 Sebb 2011-10-02 21:52:52 UTC
That's marginally better, but it still does not stand out much.

How about using the background instead?

The following works much better for me:

 code {background-color:LightCyan;padding:0 0.1em;}
 code.attributeName {background-color:transparent;}
Comment 13 Konstantin Kolinko 2011-10-14 12:31:10 UTC
Using lightcyan background in r1183328.
Backported to TC7 in r1183329 for 7.0.23.
Comment 14 Sebb 2011-10-14 13:32:34 UTC

Hopefully that will be OK for everyone.