Looking for help on preparing for review

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Looking for help on preparing for review

Boost - Dev mailing list
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.

Best regards,
Damian

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
Do you expect the errors that this will catch to be programmer bugs? If so,
abort should be the default.

On Mon, Jun 18, 2018 at 4:54 AM Damian Vicino via Boost <
[hidden email]> wrote:

> 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.
>
> Best regards,
> Damian
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
2018-06-18 5:53 GMT+02:00 Damian Vicino via Boost <[hidden email]>:

> 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.
>

Hi,
Some comments from the perspective of someone reading the docs for the
first time and trying to determine if this library would be useful.

1. The scope of the library.
It is not immediately clear what the scope of the library is. "safe_float"
resembles "safe_int", so my first thought is that safe_float does the same
for floats as safe_int does for ints. This seems confirmed by the statement
" Safe Float proposes implementing a drop-in replacement for floating point
numeric data types guaranteing that, when used in expressions in a C++
program, no incorrect arithmetic results will be produced without the
developer awareness." But that could not be possible/meaningful?

Type `int` can be thought of representing Integer numbers except that it
_very occasionally_ overflows: we might want to intercept these occasions,
but otherwise just let pretend `int` to be Integer number.

But what mathematical concept does `float` represent? A Real number? Or a
Rational number? It overflows very occasionally (and it makes sense to
detect those occasions), but it stores the inaccurate results _all the
time_. Trying to trap all these times is impractical: you will be reporting
errors all the time. Wen I decide to use type `float`, by definition I
accept (and desire) rounding errors.

You show examples where detecting overflow and underflow makes sense, and I
accept these as motivation for the library. But reporting assignment of 0.1
as an error is impractical. Maybe such library should only be checking for
underflows/overflows and undefined values and nothing else?

Also, when quoting David Goldberg, the docs mention, "Signed zero: In some
cases as discontinuous functions the negative zero have important use."
which implies that the library will somehow try to address "issues" with
negative zero, but I am not sure what these issues are, and the docs do not
mention this case anymore.

2. The concepts.
There is a section Concetps but it does not describe the FPT concepts as I
would expect, as other Boost Libraries do, e.g.:
https://www.boost.org/doc/libs/1_67_0/libs/beast/doc/html/beast/concepts/Body.html

Also it is not clear whether safe_float only works for `float`, `double`,
`long double`, or if it also works with my own float-like type?

Am I supposed to be able to build my own error-handling policies? I could
not find in the docs how I would define and plug one.

3. There is no synopsis of safe_float in the docs. (or of any other type.)


4. Minor typeos in the initial page:

"surprice " -> "surprise"

" guaranteing" --> " guaranteeing"

no_rounding-no_overflow_to_infinity  -->

no_rounding,no_overflow_to_infinity

Regards,
&rzej;

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
Maybe I am dense, but what is the difference between this and what I can
get from e.g. the Intel compiler by enabling FPEs?

Thanks,

Jeff

-fp-trap=<arg>[,<arg>,...]

          control floating point traps at program start.  <arg> can be of
the

          following values

            [no]divzero   - [Do not] trap on division by zero

            [no]inexact   - [Do not] trap on inexact result

            [no]invalid   - [Do not] trap on invalid operation

            [no]overflow  - [Do not] trap on overflow

            [no]underflow - [Do not] trap on underflow

            [no]denormal  - [Do not] trap on denormal

            all           - enable trap on all of the above

            none          - trap on none of the above

            common        - trap on most commonly used IEEE traps

                            (invalid, division by zero, overflow)




On Sun, Jun 17, 2018 at 8:53 PM, Damian Vicino via Boost <
[hidden email]> wrote:

> 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.
>
> Best regards,
> Damian
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/
> mailman/listinfo.cgi/boost
>



--
Jeff Hammond
[hidden email]
http://jeffhammond.github.io/

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
Hi Jeff,
Thanks for the comment, I will definitely work in a good answer and add the
question to the FAQ in the manual.

In general, the main differences I see are:
- Flexibility and more granular control: FPE is for all or nothing, while
safefloat can be used to enforce some checks for a subgroup of all the
floating point variables in the program or library. Also, safe_float may
provide different checks in different contexts, not an all or nothing flag.
- More options on how to react to failure. FPE will abort, while safefloat
library provides different strategies to act when a check fails, it may be
the case that you can expect a check to fail under certain conditions
(exceptional behavior). An alternative would be to manually check flags
after each operation, in place of doing that, safe float could throw an
exception that can be handled, or return an unexpected_value that can be
also handled.
- Multiplatform/compiler: safe_float is suppose to work in any compiler
implementing the c++ standard.

A real use case I had was that I wanted to capture the check failures in
logs but not failing in the wild (given service was running without check
for long time). I added safe_float with the "on_fail_cerr" policy, and that
provided some valuable insights in logs attached to bug reports. At the
time, we already diagnosed the bug and this only added more data to support
the bug, but having safe float before start could allow us to catch the bug
long time before.

Does this make sense?

Best regards,
Damian


2018-06-18 14:02 GMT-04:00 Jeff Hammond <[hidden email]>:

> Maybe I am dense, but what is the difference between this and what I can
> get from e.g. the Intel compiler by enabling FPEs?
>
> Thanks,
>
> Jeff
>
> -fp-trap=<arg>[,<arg>,...]
>
>           control floating point traps at program start.  <arg> can be of
> the
>
>           following values
>
>             [no]divzero   - [Do not] trap on division by zero
>
>             [no]inexact   - [Do not] trap on inexact result
>
>             [no]invalid   - [Do not] trap on invalid operation
>
>             [no]overflow  - [Do not] trap on overflow
>
>             [no]underflow - [Do not] trap on underflow
>
>             [no]denormal  - [Do not] trap on denormal
>
>             all           - enable trap on all of the above
>
>             none          - trap on none of the above
>
>             common        - trap on most commonly used IEEE traps
>
>                             (invalid, division by zero, overflow)
>
>
>
>
> On Sun, Jun 17, 2018 at 8:53 PM, Damian Vicino via Boost <
> [hidden email]> wrote:
>
>> 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.
>>
>> Best regards,
>> Damian
>>
>> _______________________________________________
>> Unsubscribe & other changes: http://lists.boost.org/mailman
>> /listinfo.cgi/boost
>>
>
>
>
> --
> Jeff Hammond
> [hidden email]
> http://jeffhammond.github.io/
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
Hi Andrzej,
Thanks for taking the time for reading it. I will reply interleaved to your
comments.


2018-06-18 8:09 GMT-04:00 Andrzej Krzemienski via Boost <
[hidden email]>:

> 2018-06-18 5:53 GMT+02:00 Damian Vicino via Boost <[hidden email]>:
>
> > 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.
> >
>
> Hi,
> Some comments from the perspective of someone reading the docs for the
> first time and trying to determine if this library would be useful.
>
> 1. The scope of the library.
> It is not immediately clear what the scope of the library is. "safe_float"
> resembles "safe_int", so my first thought is that safe_float does the same
> for floats as safe_int does for ints. This seems confirmed by the statement
> " Safe Float proposes implementing a drop-in replacement for floating point
> numeric data types guaranteing that, when used in expressions in a C++
> program, no incorrect arithmetic results will be produced without the
> developer awareness." But that could not be possible/meaningful?
>


Your initial impression is right. The goal is catching common errors or
"unexpected" behaviour from floating point uses.


>
> Type `int` can be thought of representing Integer numbers except that it
> _very occasionally_ overflows: we might want to intercept these occasions,
> but otherwise just let pretend `int` to be Integer number.
>
> But what mathematical concept does `float` represent? A Real number? Or a
> Rational number? It overflows very occasionally (and it makes sense to
> detect those occasions), but it stores the inaccurate results _all the
> time_. Trying to trap all these times is impractical: you will be reporting
> errors all the time. Wen I decide to use type `float`, by definition I
> accept (and desire) rounding errors.
>

I agree that use cases for catching the rounding are way less common than
others, and that makes a good cases not to check them by default. However,
the standard provides the flag "FE_INEXACT", so, if not adding complexity
to the implementation, I would like to have this particular check to
provide coverage of all std flags.


>
> You show examples where detecting overflow and underflow makes sense, and I
> accept these as motivation for the library. But reporting assignment of 0.1
> as an error is impractical. Maybe such library should only be checking for
> underflows/overflows and undefined values and nothing else?
>

I will set underflow/overflow/division_by_zero as default checks for all
operations, and allow to remove any other adding others to users when they
require to customize.


>
> Also, when quoting David Goldberg, the docs mention, "Signed zero: In some
> cases as discontinuous functions the negative zero have important use."
> which implies that the library will somehow try to address "issues" with
> negative zero, but I am not sure what these issues are, and the docs do not
> mention this case anymore.
>

Good catch, I summarized all the things mentioned in that paper to go over
the known problems of using raw FP, but I didn't mention that we are not
trying to address all the cases right away.



>
> 2. The concepts.
> There is a section Concetps but it does not describe the FPT concepts as I
> would expect, as other Boost Libraries do, e.g.:
> https://www.boost.org/doc/libs/1_67_0/libs/beast/doc/
> html/beast/concepts/Body.html
>
>
I will add this section.


> Also it is not clear whether safe_float only works for `float`, `double`,
> `long double`, or if it also works with my own float-like type?
>

I mentioned that library supports float, double, long double, and in the
future I plan to add support for multi-precision. I will make it more clear
from the start.


>
> Am I supposed to be able to build my own error-handling policies? I could
> not find in the docs how I would define and plug one.
>

Yes, I will add a short tutorial like text for this.


>
> 3. There is no synopsis of safe_float in the docs. (or of any other type.)
>
>
I will add.


>
> 4. Minor typeos in the initial page:
>
> "surprice " -> "surprise"
>
> " guaranteing" --> " guaranteeing"
>
> no_rounding-no_overflow_to_infinity  -->
>
> no_rounding,no_overflow_to_infinity
>

Fixing them.


>
> Regards,
> &rzej;
>


Thanks, I will try to address all this issues and come back with a new more
complete version of the doc soon.



>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/
> mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
2018-06-18 22:31 GMT+02:00 Damian Vicino via Boost <[hidden email]>:

> Hi Jeff,
> Thanks for the comment, I will definitely work in a good answer and add the
> question to the FAQ in the manual.
>
> In general, the main differences I see are:
> - Flexibility and more granular control: FPE is for all or nothing, while
> safefloat can be used to enforce some checks for a subgroup of all the
> floating point variables in the program or library. Also, safe_float may
> provide different checks in different contexts, not an all or nothing flag.
> - More options on how to react to failure. FPE will abort, while safefloat
> library provides different strategies to act when a check fails, it may be
> the case that you can expect a check to fail under certain conditions
> (exceptional behavior). An alternative would be to manually check flags
> after each operation, in place of doing that, safe float could throw an
> exception that can be handled, or return an unexpected_value that can be
> also handled.
> - Multiplatform/compiler: safe_float is suppose to work in any compiler
> implementing the c++ standard.
>
> A real use case I had was that I wanted to capture the check failures in
> logs but not failing in the wild (given service was running without check
> for long time). I added safe_float with the "on_fail_cerr" policy, and that
> provided some valuable insights in logs attached to bug reports. At the
> time, we already diagnosed the bug and this only added more data to support
> the bug, but having safe float before start could allow us to catch the bug
> long time before.
>
> Does this make sense?
>


It makes sense for me. Again, this explanation is worth adding in the docs
under a section like "why use this library rather than what we already
have".

Regards,
&rzej;


>
> Best regards,
> Damian
>
>
> 2018-06-18 14:02 GMT-04:00 Jeff Hammond <[hidden email]>:
>
> > Maybe I am dense, but what is the difference between this and what I can
> > get from e.g. the Intel compiler by enabling FPEs?
> >
> > Thanks,
> >
> > Jeff
> >
> > -fp-trap=<arg>[,<arg>,...]
> >
> >           control floating point traps at program start.  <arg> can be of
> > the
> >
> >           following values
> >
> >             [no]divzero   - [Do not] trap on division by zero
> >
> >             [no]inexact   - [Do not] trap on inexact result
> >
> >             [no]invalid   - [Do not] trap on invalid operation
> >
> >             [no]overflow  - [Do not] trap on overflow
> >
> >             [no]underflow - [Do not] trap on underflow
> >
> >             [no]denormal  - [Do not] trap on denormal
> >
> >             all           - enable trap on all of the above
> >
> >             none          - trap on none of the above
> >
> >             common        - trap on most commonly used IEEE traps
> >
> >                             (invalid, division by zero, overflow)
> >
> >
> >
> >
> > On Sun, Jun 17, 2018 at 8:53 PM, Damian Vicino via Boost <
> > [hidden email]> wrote:
> >
> >> 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.
> >>
> >> Best regards,
> >> Damian
> >>
> >> _______________________________________________
> >> Unsubscribe & other changes: http://lists.boost.org/mailman
> >> /listinfo.cgi/boost
> >>
> >
> >
> >
> > --
> > Jeff Hammond
> > [hidden email]
> > http://jeffhammond.github.io/
> >
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/
> mailman/listinfo.cgi/boost
>

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list


> -----Original Message-----
> From: Boost [mailto:[hidden email]] On Behalf Of Damian Vicino via Boost
> Sent: 18 June 2018 04:54
> To: [hidden email]
> 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
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
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 <[hidden email]>:

>
>
> > -----Original Message-----
> > From: Boost [mailto:[hidden email]] On Behalf Of Damian
> Vicino via Boost
> > Sent: 18 June 2018 04:54
> > To: [hidden email]
> > 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
Reply | Threaded
Open this post in threaded view
|

Re: Looking for help on preparing for review

Boost - Dev mailing list
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_should_know_about_floating-point_arithmetic-Goldberg-199
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#quickbook.syntax.phrase.font_styles

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 [hidden email] ?

Paul


---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
+44 (0) 1539 561830



> -----Original Message-----
> From: Boost [mailto:[hidden email]] On Behalf Of Damian Vicino via Boost
> Sent: 19 July 2018 04:14
> To: [hidden email]
> 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 <[hidden email]>:
>
> >
> >
> > > -----Original Message-----
> > > From: Boost [mailto:[hidden email]] On Behalf Of Damian
> > Vicino via Boost
> > > Sent: 18 June 2018 04:54
> > > To: [hidden email]
> > > 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


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost