Bug 50923 - Difficult to pick out valid values from config descriptions
Difficult to pick out valid values from config descriptions
Status: RESOLVED FIXED
Product: Tomcat 7
Classification: Unclassified
Component: Documentation
trunk
PC Windows XP
: P2 enhancement (vote)
: ---
Assigned To: Tomcat Developers Mailing List
:
Depends on:
Blocks:
  Show dependency tree
 
Reported: 2011-03-13 20:51 UTC by Sebb
Modified: 2011-10-14 13:32 UTC (History)
0 users



Attachments
Patch to add <entry> markers to http.xml and process them in XSL (26.59 KB, patch)
2011-03-13 20:51 UTC, Sebb
Details | Diff
Screenshot (32.96 KB, image/jpeg)
2011-09-20 22:36 UTC, Sebb
Details
Screenshot (21.19 KB, image/jpeg)
2011-09-20 22:36 UTC, Sebb
Details
Screenshot (24.08 KB, image/jpeg)
2011-09-20 22:36 UTC, Sebb
Details
Screenshot Fx zoomed (31.33 KB, image/jpeg)
2011-09-20 22:37 UTC, Sebb
Details

Note You need to log in before you can comment on or make changes to this bug.
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

http://tomcat.apache.org/tomcat-7.0-doc/config/http.html#SSL_Support

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]
Screenshot
Comment 3 Sebb 2011-09-20 22:36:39 UTC
Created attachment 27547 [details]
Screenshot
Comment 4 Sebb 2011-09-20 22:36:59 UTC
Created attachment 27548 [details]
Screenshot
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
Neither

http://ci.apache.org/projects/tomcat/tomcat7/docs/config/http.html#SSL_Support

nor

http://ci.apache.org/projects/tomcat/tomcat8/docs/config/http.html#SSL_Support

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
Thanks!

Hopefully that will be OK for everyone.