Re: [boost] [doc] Liven up Boost Documentation with Java Script?

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-02-24 14:05:11

On 2/24/16 10:16 AM, Paul Fultz II wrote:

>> I'm very familiar wiht Paul Fultz TICK library documentation and found
>> it to be unworthy of the underlying package.  Most of the problem is the
>> text, reference, lack of examples, weak tutorial etc.  But the
>> presentation as a web page is quite different that the boost libraries.
>> It's jaring and not as effective.  There is also - as far as know anyway
>> to produce a PDF version of the documentation.  This last is something
>> the Boost Documentation system can do - albiet reserved for those who
>> prefer to do their own dentistry.
>>
>
> The Tick library is "unworthy" of a formal review currently, and the
> documentation is lacking because I have been working on preparing the
> Boost.Fit library for formal review(which starts next week).

Fine, I like the TICK package and I think it will be much better if more 
time can be invested in the documentation.

> You can see the
> documentation for Boost.Fit here:
>
> http://pfultz2.github.io/Fit/doc/html/
>
> It is much more complete with the boost look and feel, while being generated
> using the same "underlying package" that both Boost.Tick and Boost.DI uses.
>
> Also a PDF can be generated using `mkdocs2pandoc` tool.
>

My point is that there are two ways to go:

a) convince boost library developers to create a whole new markup for 
their documentation so they can test/use your proposed infrastructure to 
add commenting to their documentation.

b) make a small optional add-on to boost book using xslt which would 
work with the markup they already have.

Now step back and consider which of the two strategies is more likely to 
result in convincing boost library authors to experiment with including 
commenting with their documentation?

Robert Ramey