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.
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.
Created attachment 27546 [details] Screenshot
Created attachment 27547 [details] Screenshot
Created attachment 27548 [details] Screenshot
Created attachment 27549 [details] Screenshot Fx zoomed
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.
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.
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?
(In reply to comment #8) The second one (tomcat8). Maybe it is cached in your browser, or maybe you are just not noticing.
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.
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.
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;}
Using lightcyan background in r1183328. Backported to TC7 in r1183329 for 7.0.23.
Thanks! Hopefully that will be OK for everyone.