Subject: Re: [boost] Looking for help on preparing for review
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2018-07-20 09:26:17
Pleased to help.
The biggest example of documentation is Boost.Math
but you may find that a bit daunting.
Some references can be lifted from there and links provided using the [@https:// https://dl.acm.org/citation.cfm?id=103163 What
every computer scientist should know about floating-point arithmetic]
1.pdf What_every_computer_scientist_should_know_about_floating-point_arithmetic-Goldberg-1991, Karlin edited version]
You may find
useful for easy access to Unicode 'squiggles'.
https://github.com/boostorg/math/blob/develop/doc/math.css may give you some ideas on fonts.
But the main way to change fonts, for example to show code, is using Boost.Quickbook
and also using 'back tick' ` around words like `double` `float` ... to indicate that it is a C++ code word.
https://www.boost.org/doc/libs/1_67_0/tools/auto_index/doc/html/index.html is a main source for autoindexing. It needs some setup
in your user-config.jam
To make some concrete suggestions, you might like to give me read access to your source github site?
(or even write access to a branch on your github site)
contact me off list at pbristow_at_[hidden] ?
--- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830 > -----Original Message----- > From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Damian Vicino via Boost > Sent: 19 July 2018 04:14 > To: boost_at_[hidden] > Cc: Damian Vicino > Subject: Re: [boost] Looking for help on preparing for review > > Hi Paul, > I was working in the code for a while, and now I'm back into the > documentation land. > You mentioned there is a way to autogenerate the index and that I should > use better "fonts". > Can you point me to an example of how to do those things? > Best regards, > Damian > > 2018-06-23 6:43 GMT-04:00 Paul A. Bristow via Boost <boost_at_[hidden]>: > > > > > > > > -----Original Message----- > > > From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Damian > > Vicino via Boost > > > Sent: 18 June 2018 04:54 > > > To: boost_at_[hidden] > > > Cc: Damian Vicino > > > Subject: [boost] Looking for help on preparing for review > > > > > > Hi, > > > I'm preparing my library safe_float to be proposed for review. > > > > > > The library was born in the GSOC2015, but it never reached a review ready > > > state. My plan is to change that in the next few months. > > > > > > At this point, I'm looking for some volunteers to proof-read the > > > documentation. Code is going through major rewrite, and I will send > > another > > > mail looking for help with reviewing the code when that is done. > > > > > > The most current documentation can be read directly from the web here: > > > https://sdavtaker.github.io/safefloat/ > > > > > > Any comment is appreciated. > > > > I haven't had time to try safe_float 'in anger', but it looks potentially > > useful. > > > > I'll be pleased to help with proof-reading when you have done an update. > > I know from bitter experience how impossible it is to > > proof-read what you have written. Ping me off-list. > > > > Some initial comments on docs appearance (generally very nice) > > > > * An index might be useful. I can advise how to produce this > > automatically. > > > > * I find using a different font for all 'code' items helps reading quite a > > lot. You can spend many happy hours enclosed all > > safe_float to `safe_float` ... ;-) > > > > * links to the source example would be helpful. (And of course using code > > snippets ensures that WYSIWC 'what you see is what > > compiles'). > > > > It would be really nice if this played nicely with User-defined types like > > Boost.Multiprecision as well as the built-ins. I can't > > see any blindingly obvious reason why it would not work. Might get > > complex 'under-the-hood'? > > > > Some examples of how this plays with Boost.Math would also be useful as > > many users will naturally use these two together. > > Boost.Math already does some checking against getting 'incorrect' results > > of course, and has its own policy system, powerful if > > confusing. > > > > It is not clear to me if the 'no exceptions' camp can use this usefully in > > non-debug mode - the time when it will be most useful - > > users come up with input values that testers never dream of. > > > > You need to define 'incorrect' a bit more clearly? and I'd use the word > > 'silently' in describing on how C++ handles overflow etc by > > default. > > > > Looking good. > > > > Paul > > > > --- > > Paul A. Bristow > > Prizet Farmhouse > > Kendal UK LA8 8AB > > +44 (0) 1539 561830 > > > > > > > > > > > > > > > > > > > > > > _______________________________________________ > > Unsubscribe & other changes: http://lists.boost.org/ > > mailman/listinfo.cgi/boost > > > > _______________________________________________ > Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk