Re: [boost] Looking for help on preparing for review

Pleased to help. The biggest example of documentation is Boost.Math https://github.com/boostorg/math/blob/develop/doc/math.qbk 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] [@http://www.karlin.mff.cuni.cz/~hron/NMMO403/What_every_computer_scientist_sh... 1.pdf What_every_computer_scientist_should_know_about_floating-point_arithmetic-Goldberg-1991, Karlin edited version] You may find https://github.com/boostorg/math/blob/develop/doc/html4_symbols.qbk 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 https://www.boost.org/doc/libs/1_67_0/doc/html/quickbook/syntax/phrase.html#... 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@hetp.u-net.com ? Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Damian Vicino via Boost Sent: 19 July 2018 04:14 To: boost@lists.boost.org 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 :

...

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Damian Vicino via Boost Sent: 18 June 2018 04:54 To: boost@lists.boost.org 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