Improving Boost Docs

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
44 messages Options
123
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Improving Boost Docs

Boost - Dev mailing list
I'm aware that at one point there was an initiative to improve boost
documentation.  See

https://svn.boost.org/trac10/wiki/ImprovingBoostDocs

It seems that the last movement here was 10 years ago.  Does anyone know
what the current status of this is?  Does anyone still work on it? Does
anyone know anything about it?  I'm just curious about this.

Robert Ramey


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

Re: Improving Boost Docs

Boost - Dev mailing list
2017-08-12 20:33 GMT+02:00 Robert Ramey via Boost <[hidden email]>:

> I'm aware that at one point there was an initiative to improve boost
> documentation.  See
>
> https://svn.boost.org/trac10/wiki/ImprovingBoostDocs
>
> It seems that the last movement here was 10 years ago.  Does anyone know
> what the current status of this is?  Does anyone still work on it? Does
> anyone know anything about it?  I'm just curious about this.
>

I do not know anything about the project, so I am not really addressing
your question,but I wonder how it is possible to get a unified look and
feel across all the libraries when library authors are given freedom to use
whatever format for their documentation, whatever tool, and whatever
approach to documentation.

Regards,
&rzej;

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

Re: Improving Boost Docs

Boost - Dev mailing list
On 8/14/17 12:40 AM, Andrzej Krzemienski via Boost wrote:

> I do not know anything about the project, so I am not really addressing
> your question,but I wonder how it is possible to get a unified look and
> feel across all the libraries when library authors are given freedom to use
> whatever format for their documentation, whatever tool, and whatever
> approach to documentation.

I don't think it is possible.

This leaves us with a couple of options:

a) Enforce the usage of boost book for documentation as condition of
acceptance and inclusion of a library in boost. This would guarantee
consistent look and feel across libraries.

b) Encourage everyone to "do their own thing".  Which would almost
certainly result in a wide variation of look and field.

c) Improve the boostbook documentation and related tooling to make it so
compelling that only an idiot or egomaniac would decide not to use it.
This would be the best of course.  But it's a lot of work and we're not
there yet.  And of course in any large organization, there's always a
couple of idiots/ecomaniacs or people who act that way on an occasional
basis.

Actually, this was the motivation for my post.  I think when this
initiative was announced we were on the right track.  But I think we
lost our way on this one.  I don't know if it's possible to all get back
on the same page, but it would be a good thing if we could.

Robert Ramey


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

Re: Improving Boost Docs

Boost - Dev mailing list
On 8/14/2017 10:37 AM, Robert Ramey via Boost wrote:

> On 8/14/17 12:40 AM, Andrzej Krzemienski via Boost wrote:
>
>> I do not know anything about the project, so I am not really addressing
>> your question,but I wonder how it is possible to get a unified look and
>> feel across all the libraries when library authors are given freedom
>> to use
>> whatever format for their documentation, whatever tool, and whatever
>> approach to documentation.
>
> I don't think it is possible.
>
> This leaves us with a couple of options:
>
> a) Enforce the usage of boost book for documentation as condition of
> acceptance and inclusion of a library in boost. This would guarantee
> consistent look and feel across libraries.
>
> b) Encourage everyone to "do their own thing".  Which would almost
> certainly result in a wide variation of look and field.
>
> c) Improve the boostbook documentation and related tooling to make it so
> compelling that only an idiot or egomaniac would decide not to use it.
> This would be the best of course.  But it's a lot of work and we're not
> there yet.  And of course in any large organization, there's always a
> couple of idiots/ecomaniacs or people who act that way on an occasional
> basis.
>
> Actually, this was the motivation for my post.  I think when this
> initiative was announced we were on the right track.  But I think we
> lost our way on this one.  I don't know if it's possible to all get back
> on the same page, but it would be a good thing if we could.

The main objection to the quickbook - boostbook - doxygen way of
generating documentation, as I understand it, is that it is very hard to
generate a different look-and-feel to the documentation from the
standard one created by the stylesheets. OTOH others think having the
same look-and-feel of all Boost docs is an advantage. So I do not think
there is any way around this basic disagreement.

I do understand that other issues have been mentioned, such as lack of
support for diagrams ( graphviz ? ) or formulas ( MathML ? ) directly in
quickbook. But we have the source for quickbook and can modify it
accordingly, so I do not think that quickbook is itself the problem. I
do agree that writing directly in boostbook ( or docbook ) is a real
pain, which I have always found I could forgo, but quickbook has always
been supremely easy to use for me.

>
> Robert Ramey


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

Re: Improving Boost Docs

Boost - Dev mailing list
On Mon, Aug 14, 2017 at 8:15 AM, Edward Diener via Boost
<[hidden email]> wrote:
> ...others think having the same look-and-feel of all
> Boost docs is an advantage.

I'm one of those people. Some of the folks working on Boost I have
interacted with seem to think that the success of a library or project
will/should depend solely on its technical merits. I don't share that
view, I think that the presentation matters. In other words the way
that the "product" (Boost, or a particular library in this case) is
"marketed" to users.

Engineers might find it distasteful or not "pure" that such factors
play a role in the success of a library but that is the reality.

For this reason I think that the uniformity of "look and feel" of the
Boost documentation is one of its strengths. It is a signal of
attention to quality. I know the toolchain can be difficult. I feel
that the results are worth it.

Thanks

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

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
2017-08-14 16:37 GMT+02:00 Robert Ramey via Boost <[hidden email]>:

> On 8/14/17 12:40 AM, Andrzej Krzemienski via Boost wrote:
>
> I do not know anything about the project, so I am not really addressing
>> your question,but I wonder how it is possible to get a unified look and
>> feel across all the libraries when library authors are given freedom to
>> use
>> whatever format for their documentation, whatever tool, and whatever
>> approach to documentation.
>>
>
> I don't think it is possible.
>
> This leaves us with a couple of options:
>
> a) Enforce the usage of boost book for documentation as condition of
> acceptance and inclusion of a library in boost. This would guarantee
> consistent look and feel across libraries.
>
> b) Encourage everyone to "do their own thing".  Which would almost
> certainly result in a wide variation of look and field.
>
> c) Improve the boostbook documentation and related tooling to make it so
> compelling that only an idiot or egomaniac would decide not to use it. This
> would be the best of course.  But it's a lot of work and we're not there
> yet.  And of course in any large organization, there's always a couple of
> idiots/ecomaniacs or people who act that way on an occasional basis.
>
> Actually, this was the motivation for my post.  I think when this
> initiative was announced we were on the right track.  But I think we lost
> our way on this one.  I don't know if it's possible to all get back on the
> same page, but it would be a good thing if we could.


I do not even know if there is a consensus about what "look and feel" is.
Is it only the fonts and colors, or is it also the same structure of
documentaion in all libraries: short intro first, then tutorial, then
reference section. If the latter, according to my knowledge, boostbook does
not offer the ability to generate reference from source code annotations,
so it might just put off people. You need to set up a collection of
additional tools.

This apart, some libraries have only plain HTML documentation, and some do
not have it at all, so they would benefit immediately from being converted
to boostbook.

Regards,
&rzej;

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

Re: Improving Boost Docs

Boost - Dev mailing list
On 8/14/17 8:29 AM, Andrzej Krzemienski via Boost wrote:

>
> I do not even know if there is a consensus about what "look and feel" is.
> Is it only the fonts and colors, or is it also the same structure of
> documentaion in all libraries: short intro first, then tutorial, then
> reference section. If the latter, according to my knowledge, boostbook does
> not offer the ability to generate reference from source code annotations,
> so it might just put off people. You need to set up a collection of
> additional tools.

No question that addressing this is very difficult.

> This apart, some libraries have only plain HTML documentation, and some do
> not have it at all, so they would benefit immediately from being converted
> to boostbook.

Hmmm, that's not all that clear to me.  Let's use the serialization
library as an example.  It is crafted with raw HTML.  It uses the
boost.css so it looks similar to many of the other boost libraries. It
was made before boostbook was available.  Writing in HTML was tedious -
but not nearly as complicated as using the tools now popular.  And once
it was done, it was pretty much done.  Whenever someone pointed out some
error or it needed a small enhancement, it is is pretty simple to
update.  It's been 15 years without much hassle.  What would be actually
gained by conversion to boostbook?  I don't know that we generate the
PDF anymore.  It looks pretty close the the official boostbook output.
And has my cool documentation navigator which would be lost.

As an aside, making the original version of the documentation was an
unbelievably contentious exercise involving acrimonious disputes between
David Abrahams and myself mostly.  What came out of this was:

a) Concepts must be addressed explicitly in the documentation of any C++
library which uses templates.

b) Concept checking must be part of any C++ library code which uses
template parameters.

c) "Concept" is a very, very, very unfortunate choice for the idea. It's
very misleading and confusing and has led many, many people to
understand the idea.  This believe is behind my preference for the term
"Type Requirements" when I can get a way with this.

d) A long, contentious, strident, mailing list interaction with David
Abrahams has to be the most unpleasant, and likely most unproductive way
to learn anything.  I've tried to keep this mind when promoting the
concept of "Concepts" (Damn - there's the confusion about "concept" again)>

Robert Ramey

> Regards,
> &rzej;
>
> _______________________________________________
> 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
|  
Report Content as Inappropriate

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Mon, Aug 14, 2017 at 8:43 AM, Robert Ramey via Boost
<[hidden email]> wrote:
> Right - I would like to see the tool chain much easier to use.

The QuickBook documentation format is very easy to use, and the
documentation for it is sufficient to get pretty good results:

<http://www.boost.org/doc/libs/1_64_0/doc/html/quickbook.html>

It is more difficult to set up Doxygen and the XSL stylesheets to
produce a QuickBook reference section, but I think that's an inherit
difficult problem.

I think the toolchain is more than adequate as-is for generating stock
QuickBook.

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

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On Mon, Aug 14, 2017 at 8:29 AM, Andrzej Krzemienski via Boost
<[hidden email]> wrote:
> I do not even know if there is a consensus about what "look and feel" is.

The "look and feel" is a subjective quality where the reader
recognizes a rendered subset of documentation as belonging to a larger
work based on visual elements. These elements include:

* Boost banner at the top of the page

* Sans-serif on white background

* 4-icon nav bar in top right and top left ( BACK, UP, HOME, FWD )

* Source code blocks are indented, in a fixed width font, with a thin
gray rectangle outlining the block

* Paragraphs flow to the width of the window in which they are rendered

* No frames or iframes (sorry Robert!)

* Table of contents, if present, is at the top of the page, surrounded
by a thin gray rectangle

* Standard dingbats (bullets for unordered lists)

* Standard admonition icons and formatting (thin gray rectangle), see:
<http://www.boost.org/doc/libs/1_64_0/doc/html/quickbook/syntax/block.html#quickbook.syntax.block.admonitions>

> Is it only the fonts and colors, or is it also the same structure of
> documentaion in all libraries: short intro first, then tutorial, then
> reference section.

Writing, like coding, is a creative endeavor and while there are
useful guidelines for how documentation should be structured, every
library is unique and each library author has to make the best choices
for how the library will be presented in the documentation. I don't
think it would be helpful to prescribe a meta template for the content
of the work. I DO think it is helpful to provide tips and tricks to
help writers get ideas for how to present their work. And also to
serve as inspiration when that inevitable writer's block strikes.

Thanks

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

Re: Improving Boost Docs

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

> The main objection to the quickbook - boostbook - doxygen way of
> generating documentation, as I understand it, is that it is very hard
> to generate a different look-and-feel to the documentation from the
> standard one created by the stylesheets. OTOH others think having the
> same look-and-feel of all Boost docs is an advantage. So I do not
> think there is any way around this basic disagreement.

If you want a different look and feel, then yes things could be a lot
better.  However, within boost the consistency is a good thing IMO.

BTW the look and feel is in 2 parts:

* Different stylesheet, fluorescent dancing C++ keywords etc.... this is
actually trivial to do.
* Different Docbook customisation layer (and yes there are some
formatting options that can only be addressed in XSL, not in XSL
params).  This is the hard one - or at least its the hard one if we're
using Jamfiles.  From the command line it's trivial if you don't mind
writing a... ahem... makefile ;)

BTW is there any reason to continue using the Boostbook customisation
layer?  Is anyone actually using it?  I'm fairly sure quickbook doesn't,
and it would sure simplify the build process to leave out one level of
XSL transformation.  Sadly we would need an XSL expert to sort that mess
out I suspect :(

>
> I do understand that other issues have been mentioned, such as lack of
> support for diagrams ( graphviz ? ) or formulas ( MathML ? ) directly
> in quickbook.

Since graphviz can generate SVG's, it would I assume be trivial for
quickbook to shell out to "dot" to render inline graphviz text.  Or you
can just invoke it yourself (though I accept this may be less convenient).

Equations are probably a more pressing need, and IMO it's a problem that
no one has properly solved (unless you live entirely within the LatTex
universe perhaps).  MathML is useless as a format to write in, comes in
2 flavours (presentation and content with different tools supporting
each - for example last I checked OpenOffice generates content, but most
presentation tools expect presentation format).   MathJax almost
completely solves these issues, and looks quite lovely... but... because
it relies on external Javascript files, it gets blocked by browsers
unless everything is on the server (ie not on the local disk).  
Boost.Math renders it's equations as SVG's which works well, but it's a
pain to author them separately from the actual text.  I'm sure we would
have more/better equations if they were inline in the quickbook.  We
could embed LaTex, but the conversion to SVG appears to be long and
flaky involving quite a few tools  (though it appears MathJax can do
this in one step, but there are some comments that it generate "odd" SVG
XML).  Might be worth looking into though.

Perhaps more pressing is the ability to generate a navigation panel -
all the information we need is present in the Docbook - and frankly I
simply cannot believe that the Docbook XSL stylesheets don't support
this already (Ah they do - sort of  - via a "webpage" project, but it's
not vanilla docbook).  Doing it ourselves probably means pre-processing
the generating HTML or something similarly yucky :(


> But we have the source for quickbook and can modify it accordingly, so
> I do not think that quickbook is itself the problem. I do agree that
> writing directly in boostbook ( or docbook ) is a real pain, which I
> have always found I could forgo, but quickbook has always been
> supremely easy to use for me.

+1, me too!

John.



---
This email has been checked for viruses by AVG.
http://www.avg.com


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

Re: Improving Boost Docs

Boost - Dev mailing list
AMDG

On 08/14/2017 11:37 AM, John Maddock via Boost wrote:

>
> If you want a different look and feel, then yes things could be a lot
> better.  However, within boost the consistency is a good thing IMO.
>
> BTW the look and feel is in 2 parts:
>
> * Different stylesheet, fluorescent dancing C++ keywords etc.... this is
> actually trivial to do.
> * Different Docbook customisation layer (and yes there are some
> formatting options that can only be addressed in XSL, not in XSL
> params).  This is the hard one - or at least its the hard one if we're
> using Jamfiles.  From the command line it's trivial if you don't mind
> writing a... ahem... makefile ;)
>
> BTW is there any reason to continue using the Boostbook customisation
> layer?  Is anyone actually using it?

  Yes.  Nobody writes it directly, but there's a
stylesheet that converts doxygen's XML output
into BoostBook.

>  I'm fairly sure quickbook doesn't,
> and it would sure simplify the build process to leave out one level of
> XSL transformation.  Sadly we would need an XSL expert to sort that mess
> out I suspect :(
>

In Christ,
Steven Watanabe


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

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> The main objection to the quickbook - boostbook - doxygen way of
> generating documentation, as I understand it, is that it is very hard to
> generate a different look-and-feel to the documentation from the
> standard one created by the stylesheets. OTOH others think having the
> same look-and-feel of all Boost docs is an advantage. So I do not think
> there is any way around this basic disagreement.

My main objection was that it's overly complicated and unnecessary.
It's an absolutely ridiculous toolchain, that one shouldn't have to
learn merely in order to write Docs.
If there had been an insistence on a particular look-and-feel with a
supplied .css, I would've been fine with that. Instead I gave up.

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

Re: Improving Boost Docs

Boost - Dev mailing list
On 8/14/2017 5:28 PM, Soul Studios via Boost wrote:
>> The main objection to the quickbook - boostbook - doxygen way of
>> generating documentation, as I understand it, is that it is very hard
>> to generate a different look-and-feel to the documentation from the
>> standard one created by the stylesheets. OTOH others think having the
>> same look-and-feel of all Boost docs is an advantage. So I do not
>> think there is any way around this basic disagreement.
>
> My main objection was that it's overly complicated and unnecessary.

Why do you find it overly complicated ?

> It's an absolutely ridiculous toolchain, that one shouldn't have to
> learn merely in order to write Docs.

The only thing you have to learn is Quickbook and doxygen. I see nothing
"ridiculous" in that. You can ignore boostbook/docbook completely.

> If there had been an insistence on a particular look-and-feel with a
> supplied .css, I would've been fine with that. Instead I gave up.

No one forces you to use Quickbook or doxygen. But your emotional
response to both is very surprising.


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

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 8/14/17 10:37 AM, John Maddock via Boost wrote:
> * Different Docbook customisation layer (and yes there are some
> formatting options that can only be addressed in XSL, not in XSL
> params).  This is the hard one - or at least its the hard one if we're
> using Jamfiles.  From the command line it's trivial if you don't mind
> writing a... ahem... makefile ;)

or a simple shell script
>
> BTW is there any reason to continue using the Boostbook customisation
> layer?  Is anyone actually using it?  I'm fairly sure quickbook doesn't,
> and it would sure simplify the build process to leave out one level of
> XSL transformation.  Sadly we would need an XSL expert to sort that mess
> out I suspect :(

I think there's a little more to this:

a) There are special tags like class, struct, etc. etc.  Which permit
tagging for different aspects of C++ syntax.  Somehow I doubt anyone is
using this stuff.  It would be pain to edit it and it would presume that
every class,struct etc would have the same documentation structure which
might be inconvenient.  Also the documentation for this is reference and
doesn't give much in the way of sample output etc.  Upshot I'm doubtful
that anyone is using it.

b) There is the xsl directory which includes special boost extenstions
to docbook tags.  I'm pretty sure that these matter.  For example it is
here that the program listing syntax coloring is implemented.  Modifying
this is very problematic due to xml/xsl syntax and lack of good tools.
I know this because I have tried to do it.

Due to b) I don't know if you want to leave out this level of
tranformation.  One can make good looking docs with docbook but it's
unclear what the boostbook transformation adds here.

>> I do understand that other issues have been mentioned, such as lack of
>> support for diagrams ( graphviz ? ) or formulas ( MathML ? ) directly
>> in quickbook.
>
> Since graphviz can generate SVG's, it would I assume be trivial for
> quickbook to shell out to "dot" to render inline graphviz text.  Or you
> can just invoke it yourself (though I accept this may be less convenient).

This one reason I'm not crazy about quickbook - it's not open ended enough.
>
> Equations are probably a more pressing need, and IMO it's a problem that
> no one has properly solved (unless you live entirely within the LatTex
> universe perhaps).  MathML is useless as a format to write in, comes in
> 2 flavours (presentation and content with different tools supporting
> each - for example last I checked OpenOffice generates content, but most
> presentation tools expect presentation format).  

Hmm - I had hopes for this.  I'll have to check it out.

> MathJax almost
> completely solves these issues, and looks quite lovely... but... because
> it relies on external Javascript files, it gets blocked by browsers
> unless everything is on the server (ie not on the local disk).

Ouch - and would close the door to pdf and ebook versions of the output.

> Boost.Math renders it's equations as SVG's which works well, but it's a
> pain to author them separately from the actual text.  I'm sure we would
> have more/better equations if they were inline in the quickbook.  We
> could embed LaTex, but the conversion to SVG appears to be long and
> flaky involving quite a few tools  (though it appears MathJax can do
> this in one step, but there are some comments that it generate "odd" SVG
> XML).  Might be worth looking into though.
>
> Perhaps more pressing is the ability to generate a navigation panel -
> all the information we need is present in the Docbook - and frankly I
> simply cannot believe that the Docbook XSL stylesheets don't support
> this already (Ah they do - sort of  - via a "webpage" project, but it's
> not vanilla docbook).  Doing it ourselves probably means pre-processing
> the generating HTML or something similarly yucky
I think this is eminently doable and not particularly difficult either.
The main obstacle is the xsl syntax which is like dragging one's
fingernails on a chalkboard.  I've toyed with taking it up myself as
I've had to become more familiar than I wanted to with xsl.  I also made
the (in)famous navigation panel for the serialization library.  We also
have a similar but likely better implementation of this idea with the
streams library.  So this should actually be moved to higher priority.
Implementing this would create a good incentive to keep using
boostbook/docbook and use it better since it would only include
documenation for those libraries which use boost/docbook.  It's a
textbook example of what xsl is meant to be used for.

>> But we have the source for quickbook and can modify it accordingly, so
>> I do not think that quickbook is itself the problem. I do agree that
>> writing directly in boostbook ( or docbook ) is a real pain, which I
>> have always found I could forgo, but quickbook has always been
>> supremely easy to use for me.

To me, there are couple of fatal mistakes

a) creating library documentation (html, pdf) not in the library
directory but in some "other" directory.
b) invoking the boost documentation build through bjam.

Without this, it would be much easier to tweak ones documentation build
to get it exactly right.

> +1, me too!
>
> John.
>
>
>
> ---
> This email has been checked for viruses by AVG.
> http://www.avg.com
>
>
> _______________________________________________
> 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
|  
Report Content as Inappropriate

Re: Improving Boost Docs

Boost - Dev mailing list
On Mon, Aug 14, 2017 at 8:31 PM, Robert Ramey via Boost wrote:

> On 8/14/17 10:37 AM, John Maddock via Boost wrote:
>>
>> BTW is there any reason to continue using the Boostbook customisation
>> layer?  Is anyone actually using it?  I'm fairly sure quickbook doesn't, and
>> it would sure simplify the build process to leave out one level of XSL
>> transformation.  Sadly we would need an XSL expert to sort that mess out I
>> suspect :(
>
>
> I think there's a little more to this:
>
> a) There are special tags like class, struct, etc. etc.  Which permit
> tagging for different aspects of C++ syntax.  Somehow I doubt anyone is
> using this stuff.  It would be pain to edit it and it would presume that
> every class,struct etc would have the same documentation structure which
> might be inconvenient.  Also the documentation for this is reference and
> doesn't give much in the way of sample output etc.  Upshot I'm doubtful that
> anyone is using it.
>

Is the Boost.Array documentation not using this?
https://github.com/boostorg/array/tree/develop/doc

Glen

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

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
> The only thing you have to learn is Quickbook and doxygen. I see nothing
> "ridiculous" in that. You can ignore boostbook/docbook completely.

 From what I recall there were about 12 different dependencies you had
to set up in order to render anything from quickbook, with unclear
guidelines, and no standard path for authoring quickbook. At any rate, I
just thought I'd offer my impression as someone new to boosts doc
process. I'm not interested in an argument.


>> If there had been an insistence on a particular look-and-feel with a
>> supplied .css, I would've been fine with that. Instead I gave up.
>
> No one forces you to use Quickbook or doxygen. But your emotional
> response to both is very surprising.

I don't agree with that.

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

Re: Improving Boost Docs

Boost - Dev mailing list
On 8/14/2017 9:13 PM, Soul Studios via Boost wrote:
>> The only thing you have to learn is Quickbook and doxygen. I see
>> nothing "ridiculous" in that. You can ignore boostbook/docbook
>> completely.
>
>  From what I recall there were about 12 different dependencies you had
> to set up in order to render anything from quickbook, with unclear
> guidelines, and no standard path for authoring quickbook. At any rate, I
> just thought I'd offer my impression as someone new to boosts doc
> process. I'm not interested in an argument.

There is full documentation for quickbook. It is a Boost tool that comes
with its own documentation, or you can regenerate the doc yourself.

I agree that the bjam setup needed to go from qbk files to html and/or
pdf output is not documented, as I think it should be in the Boost Build
docs.

You can take a look at the doc jamfile in numerous Boost libraries that
use quickbook to see how to set things up, including my own tti or vmd.
The main dependency for quickbook is boostbook/docbook, with alternate
dependencies on auto_index and doxygen. That is 3, not 12.

>
>
>>> If there had been an insistence on a particular look-and-feel with a
>>> supplied .css, I would've been fine with that. Instead I gave up.
>>
>> No one forces you to use Quickbook or doxygen. But your emotional
>> response to both is very surprising.
>
> I don't agree with that.

I understand the frustration in the almost total lack of formal docs for
going from quickbook to html/pdf. But quickbook itself is a piece of
cake, is very well documented, and blissfully easy to specify most
everything you need to do in creating library documentation.


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

Re: Improving Boost Docs

Boost - Dev mailing list
> You can take a look at the doc jamfile in numerous Boost libraries that
> use quickbook to see how to set things up, including my own tti or vmd.
> The main dependency for quickbook is boostbook/docbook, with alternate
> dependencies on auto_index and doxygen. That is 3, not 12.

A 'main' dependency is not 'all' dependencies.
I can't even find the documentation I tried to follow in order to do it,
but when I tried to build it, there were about 12 dependencies (it
may've shrunk since then, I don't know). XSLT, java, various others.
Most of them had no documentation.
You can break it down in a way that makes it sound like less than it is,
but overall I'm just not interested in the system.


> I understand the frustration in the almost total lack of formal docs for
> going from quickbook to html/pdf. But quickbook itself is a piece of
> cake, is very well documented, and blissfully easy to specify most
> everything you need to do in creating library documentation.

I think if you're already familiar with all of the technologies
involved, it's easy. But it's actually not from the point of view of
someone coming in on the 'ground floor'. I don't waste what little
energy I have learning technologies merely to build docs.
There seems to be tacit disapproval, reading through this, of people
building straight HTML for documentation, and I think that's a real shame.
I worked in XML/XSLT once and I understand the advantages, but if boost
is around longer than HTML, I'll be very, very surprised. And the
disadvantages of complication for something as transitory as a code
library is not worth it.

M

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

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 8/14/17 5:34 PM, Glen Fernandes via Boost wrote:

> On Mon, Aug 14, 2017 at 8:31 PM, Robert Ramey via Boost wrote:
>> On 8/14/17 10:37 AM, John Maddock via Boost wrote:
>>>
>>> BTW is there any reason to continue using the Boostbook customisation
>>> layer?  Is anyone actually using it?  I'm fairly sure quickbook doesn't, and
>>> it would sure simplify the build process to leave out one level of XSL
>>> transformation.  Sadly we would need an XSL expert to sort that mess out I
>>> suspect :(
>>
>>
>> I think there's a little more to this:
>>
>> a) There are special tags like class, struct, etc. etc.  Which permit
>> tagging for different aspects of C++ syntax.  Somehow I doubt anyone is
>> using this stuff.  It would be pain to edit it and it would presume that
>> every class,struct etc would have the same documentation structure which
>> might be inconvenient.  Also the documentation for this is reference and
>> doesn't give much in the way of sample output etc.  Upshot I'm doubtful that
>> anyone is using it.
>>
>
> Is the Boost.Array documentation not using this?
> https://github.com/boostorg/array/tree/develop/doc

Yep - there it is!
>
> Glen
>
> _______________________________________________
> 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
|  
Report Content as Inappropriate

Re: Improving Boost Docs

Boost - Dev mailing list
In reply to this post by Boost - Dev mailing list
On 14 August 2017 at 18:56, Steven Watanabe via Boost
<[hidden email]> wrote:
>
>   Yes.  Nobody writes it directly, but there's a
> stylesheet that converts doxygen's XML output
> into BoostBook.

My reference documentation is written directly in boostbook. The
documentation for the first libraries to use boostbook was written
entirely in boostbook, such as signals.

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