[asterisk-dev] [Code Review] Make inline documentation readable

[wdoekes]

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://reviewboard.asterisk.org/r/2224/#review7476
-----------------------------------------------------------

Ship it!


Looks good to me.

Wouldn't mind if this went into 1.8+.

- wdoekes


On Dec. 2, 2012, 1:56 p.m., Tilghman Lesher wrote:
> 
> -----------------------------------------------------------
> This is an automatically generated e-mail. To reply, visit:
> https://reviewboard.asterisk.org/r/2224/
> -----------------------------------------------------------
> 
> (Updated Dec. 2, 2012, 1:56 p.m.)
> 
> 
> Review request for Asterisk Developers.
> 
> 
> Summary
> -------
> 
> Currently, some of the color choices used by the inline documentation are extremely difficult to read.  For instance, if you use a terminal with a dark background, literals, values, and enums all present as dark blue on black, which is unreadable unless you squint at the screen, highlight the terms, or abandoning the inline documentation entirely to read about the options in a book.  This is no doubt good for book sales and increases the hits to online documentation, but it's not a good choice on our part.  Conversely, on screens with a light background, notes show up in yellow, which is also unreadable.
> 
> This patch fixes the problem by turning on the "bright" bit by default and turning it off when the background is indicated to be a light color (-W flag).
> 
> Note:  while this patch is against trunk, I don't see any reason why this could not go into every branch from 1.8 forward, because this is a long-standing gripe, doesn't change the behavior of Asterisk, and probably would be welcomed in every corner of the Asterisk community with the possible exception of book authors, who might lose a sale or two.
> 
> 
> Diffs
> -----
> 
>   /trunk/main/xmldoc.c 376993 
> 
> Diff: https://reviewboard.asterisk.org/r/2224/diff
> 
> 
> Testing
> -------
> 
> Looked at the output of "core show application Dial", which is the most prolifically documented application that we have, on terminals with both light backgrounds and dark backgrounds.  It is completely readable in both cases after the patch.  Before the patch, not so much.
> 
> 
> Thanks,
> 
> Tilghman
> 
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-dev/attachments/20121203/2ba32008/attachment.htm>