Boost logo

Boost :

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

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

Paul

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