Mathias Gaunard wrote:

On 10/10/13 21:00, Andrew Hundt wrote:

...

http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_referen...

This second link is the typical header documentation throughout boost. When I first started using boost it was months before I realized that in these header synopsis I could click on the words of the class to see the full documentation of that class, in this case "static_vector". Much of the time I just felt confused and lost. I think this is indicative of a layout and user interface that needs some improvement.

Documentation like this is generated by preprocessing Doxygen XML output to integrate it into Boostbook and have a good look for C++ references.

It has most of what you can expect from Doxygen + the Boostbook stuff which gives better cross-referencing than simple Doxygen.

Hmm - I looked at DOxygen and found it lacking for what I wanted. I'm also disappointed in the Doxygen generated documentation in boost which to me mostly parrots the source code. On the other hand, I think the approach (literate programming) has promise but it seemed to me that one would have to add a lot to Doxygen to generate what I would like to see. Maybe the "missing magic" is already in on our web site somewhere. Basically I don't see where we can coordinate Boostbook with Doxygen. Perhaps you could include the link which explains this. Robert Ramey

I personally don't understand how one cannot notice that the blue bits that become underlined when you hover them and change colors once visited are hyperlinks (especially since that's also true for any other hyperlink in Boost docs and most of the World Wide Web). What do you suggest would be better?

lol - I suppose you have a point. But I made the same oversight. What happened was that I saw what looked like raw header files fromatted to look good on the web page. It looked like color coding. It didn't occur to me immediately that they were links which pointed to documentation. I was expecting just the opposite - documentation linking to the the header files rather than other way around. Robert Ramey

On 10 October 2013 23:13, Niall Douglas wrote:

On 10 Oct 2013 at 14:58, Robert Ramey wrote:

...

...

Documentation like this is generated by preprocessing Doxygen XML output to integrate it into Boostbook and have a good look for C++ references.

...

It has most of what you can expect from Doxygen + the Boostbook stuff which gives better cross-referencing than simple Doxygen.

Hmm - I looked at DOxygen and found it lacking for what I wanted. I'm also disappointed in the Doxygen generated documentation in boost which to me mostly parrots the source code. On the other hand, I think the approach (literate programming) has promise but it seemed to me that one would have to add a lot to Doxygen to generate what I would like to see. Maybe the "missing magic" is already in on our web site somewhere. Basically I don't see where we can coordinate Boostbook with Doxygen. Perhaps you could include the link which explains this.

Boost.Geometry contains a utility called doxygen_xml2qbk which converts Doxygen XML into Quickbook.

Initially, for Boost.Geometry I ported Boost.Asio XSLT sheet to generate API reference. The work proved the XSLT application is scary and highly prone to the bus factor :-) So, Barend decided to write a custom utility in C++ that is much easier to reason about, hence maintain. But still, managing docs is PITA, IMHO. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On 11 October 2013 17:08, Niall Douglas wrote:

On 10 Oct 2013 at 23:26, Mateusz Loskot wrote:

...

...

Boost.Geometry contains a utility called doxygen_xml2qbk which converts Doxygen XML into Quickbook.

Initially, for Boost.Geometry I ported Boost.Asio XSLT sheet to generate API reference. The work proved the XSLT application is scary and highly prone to the bus factor :-) So, Barend decided to write a custom utility in C++ that is much easier to reason about, hence maintain.

Did you or Barend merge my patchset to doxygen_xml2qbk which I submitted on the boost issue tracker?

Yes, Barend has applied it about ~2 months ago. Thanks!

I'd really like it if you split out doxygen_xml2qbk into a standalone tool in Boost tools instead of hogging to yourselves in Geometry :)

Good idea.

doxygen_xml2qbk produced the best output of all the Boost documentation tools I tried.

Good to hear.

It has many problems, bugs and brittleness, but until it's standalone I can see there being some confusion (as evidenced by this thread) about what the tool does, that it exists, that it's useful and that yes it can be improved. Even with its warts, it's still the best out of anything I tried.

Ok, I will try to make it a standalone tool during next weeks. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On 11 October 2013 11:02, Mathias Gaunard wrote:

On 11/10/13 00:13, Niall Douglas wrote:

...

On 10 Oct 2013 at 14:58, Robert Ramey wrote:

...

...

Documentation like this is generated by preprocessing Doxygen XML output to integrate it into Boostbook and have a good look for C++ references.

...

It has most of what you can expect from Doxygen + the Boostbook stuff which gives better cross-referencing than simple Doxygen.

Hmm - I looked at DOxygen and found it lacking for what I wanted. I'm also disappointed in the Doxygen generated documentation in boost which to me mostly parrots the source code. On the other hand, I think the approach (literate programming) has promise but it seemed to me that one would have to add a lot to Doxygen to generate what I would like to see. Maybe the "missing magic" is already in on our web site somewhere. Basically I don't see where we can coordinate Boostbook with Doxygen. Perhaps you could include the link which explains this.

Boost.Geometry contains a utility called doxygen_xml2qbk which converts Doxygen XML into Quickbook.

Boostbook comes bundled with an XSLT stylesheet to convert Doxygen XML to Boostbook.

Yes, it does, but apparently it does not produce the quality Boost.Asio aimed for. The reference.xsl sheet produces clear index: http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference.html and neatly gathers overloads and specialisations in clickable way leading to documentation of particular version of an entity: http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference/read.html The typical Boost way is to drop in everything into single Synopsis section, like here: http://www.boost.org/doc/libs/1_54_0/libs/spirit/doc/html/spirit/qi/referenc... For Boost.Geometry, we wanted to achieve Boost.Asio's effect. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On 11 October 2013 13:42, Mathias Gaunard wrote:

On 11/10/13 12:12, Mateusz Loskot wrote:

...

Yes, it does, but apparently it does not produce the quality Boost.Asio aimed for.

The reference.xsl sheet produces clear index:

http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference.html

and neatly gathers overloads and specialisations in clickable way leading to documentation of particular version of an entity:

http://www.boost.org/doc/libs/1_54_0/doc/html/boost_asio/reference/read.html

I don't really know reference.xsl.

This is the one I'm referring to: https://svn.boost.org/svn/boost/trunk/libs/asio/doc/reference.xsl

The default Doxygen postprocessing ($BOOST_ROOT/tools/boostbook/xsl/doxygen/doxygen2boostbook.xsl) gives a list of header files with for each of them the symbols in them. Something like the Boost.Container docs that were referenced earlier in this thread: http://www.boost.org/doc/libs/1_54_0/doc/html/boost_container_header_referen...

IMHO, that is a useless kind of documentation. We've got IDEs and editors with decent code browsing capabilities for that.

So you say that reference.xsl (there are two of those, one in tools/boostbook/xsl, one in libs/asio/doc, which one do you mean?)

I mean the second one.

generates some other layout with a symbol-centric approach rather than a header-centric one?

Yes. The basic idea is this: If I click a function name, I get details of that function. If I a function has more overaloads, I get extra intermediate page - listing of overloads. If I click a parameter, I get corresponding concept with its requirements. For example, 1) one of overloads http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/async_rea... 2) click on template parameter AsyncReadStream http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/AsyncRead... Such documentation is based on the natural process of reasoning about C++ Code.

The doxygen_xml2qbk tool in Geometry doesn't seem to be really like Asio's documentation.

As I mentioned, we've reached Asio-like prototype some time ago [1] , but due to XSLT complexity we've switched to simple generator, though it's not as capable as Asio's, yet. [1] (links broken, no longer online) http://lists.boost.org/Archives/boost/2010/02/161827.php

It's not header-centric but otherwise it looks pretty much like standard doxygen2boostbook docs. Maybe people prefer this?

Might be users prefer it, At least, that's what Geometry team prefers :-)

I personally quite like the header-centric approach, but that may be because I'm just used to thinking in terms of header files first as the structure of a library.

I do as well, but I use code browsing tools for that.

In any case, I'd be interested to know more about the differences between doxygen2boostbook and xml2qbk to know which one I should use.

Barend described how it works for Geometry: http://barendgehrels.blogspot.co.uk/2010/12/doxygen-and-quickbook.html

...

The typical Boost way is to drop in everything into single Synopsis section, like here:

http://www.boost.org/doc/libs/1_54_0/libs/spirit/doc/html/spirit/qi/referenc...

I wouldn't call any of the Spirit docs "typical Boost way". This stuff is entirely handwritten as far as I know.

I find handwritten docs superior. The Doxygen comments make the code harder to browse, especially if programmers aspire to stick long essays with numerous code examples into them. IMHO, Doxygen comments should be very minimal and the bloat of documentation in separate Quickbook (or Markdown) files cross-referencing to symbols from code and Doxygen (separate plain text files with dosc make it easy to read without generating HTML/PDF, etc.) But, I guess we're getting into personal preferences There used to be a very long debate on boost-docs [1] about pros/cons of Doxygen and the outcome was within Boost, there are people who hate it and people who love it, hence best is to allow freedom of choice. [1] "Sphinx integration" thread :) http://lists.boost.org/boost-docs/2011/09/ http://lists.boost.org/boost-docs/2011/10 Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On 10 October 2013 23:47, Andrew Hundt wrote:

On Thu, Oct 10, 2013 at 6:01 PM, Niall Douglas wrote:

...

On 10 Oct 2013 at 15:00, Andrew Hundt wrote:

...

So, is there anything we can do about it?

I remember a couple of years ago Boost had a "Bug Sprint" with the goal of closing lots of open tickets. Perhaps we should do a "documentation sprint"?

Historically Boost's libraries were sorta seen as proto-standard libraries, so their documentation was written in the style of the ISO C++ standard i.e. it assumes you already understand the patterns used in the library, and all you need is the "how to use" detail.

I completely agree that boost docs should generally be a "how to use" guide. The additional steps I also think would be reasonable are for the "how to use" detail to be easier to browse around and links to all the existing examples and tests.

Something that would truly be great would be for each function to be called in some example.

That's what we aim in the API reference of Boost.Geometry - a reasonable self-contained example at the bottom of each page. For example http://www.boost.org/doc/libs/1_54_0/libs/geometry/doc/html/geometry/referen... AFAIR, we've got this idea from Boost.Spirit/ Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Friday, October 11, 2013 3:11 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

Andrew Hundt wrote:

...

I have to say Boost's documentation is generally excellent.

Thanks for indulging me - I trying hard not to rant.

I'll try hard too ;-) We *still* don't have a single example of using *ALL* the tools we already have to prepare documentation. All the examples of deficiencies you note *can* be met - except the docs being small files and quick to build (but size doesn't matter provided one can navigate around well). Quickbook provides a nice markup system for plain text - and it provides the hooks and eyes to get to code snippets and Doxygen comments. Doxygen (as used in this toolset) provides a way to add code comments to all the code elements - functions, data, macros etc. Using it with Quickbook is only a way to link these comments to the C++ reference section so that you can click on any function name and find its description, preconditions, post conditions, parameter and template parameters descriptions. *These descriptions are the key things that are missing for most Boost documentation*. The usefulness of the docs is mainly determined by the work that goes into these descriptions. Autoindex provides an index - automatically for all the above C++ elements, and manually given some work. All the index items are hyperlinks. Boost.Math shows this in action - though it needs more manually added index terms - more work! PDF single file that can be printed like a book (as well as HTML). Many libraries use some tools, but none use *ALL* of them. I've recently re-factored the circular_buffer library using all these tools. (But I'm not the author so I can't claim to make as good a job as someone who really understands the code could do - it's only a refactoring). Maybe you'd comment again when you've seen this example. Paul (The process of providing hyperlinking to docs move from sandbox to release is byzantine but this should get improved when we get GITized). --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

"Edward Diener" wrote in message news:l38fk4$p76$1@ger.gmane.org...

On 10/11/2013 4:52 AM, Paul A. Bristow wrote:

...

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Friday, October 11, 2013 3:11 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

Andrew Hundt wrote:

...

I have to say Boost's documentation is generally excellent.

Thanks for indulging me - I trying hard not to rant.

I'll try hard too ;-)

We *still* don't have a single example of using *ALL* the tools we already have to prepare documentation. All the examples of deficiencies you note *can* be met - except the docs being small files and quick to build (but size doesn't matter provided one can navigate around well).

Quickbook provides a nice markup system for plain text - and it provides the hooks and eyes to get to code snippets and Doxygen comments.

Doxygen (as used in this toolset) provides a way to add code comments to all the code elements - functions, data, macros etc. Using it with Quickbook is only a way to link these comments to the C++ reference section so that you can click on any function name and find its description, preconditions, post conditions, parameter and template parameters descriptions.

*These descriptions are the key things that are missing for most Boost documentation*.

The usefulness of the docs is mainly determined by the work that goes into these descriptions.

Autoindex provides an index - automatically for all the above C++ elements, and manually given some work. All the index items are hyperlinks. Boost.Math shows this in action - though it needs more manually added index terms - more work!

PDF single file that can be printed like a book (as well as HTML).

Many libraries use some tools, but none use *ALL* of them.

I've recently re-factored the circular_buffer library using all these tools.

(But I'm not the author so I can't claim to make as good a job as someone who really understands the code could do - it's only a refactoring).

Maybe you'd comment again when you've seen this example.

As you say the tools are there. But I do not think the difficulty of some of the docs are a matter of tools. I believe it is a matter of the structure of the documentation for some of the libraries and also that programmers typically are much more focused on correct code than they are on really good documentation. Some Boost documentation is really excellent while some other Boost documentation assumes a great deal on the part of the programmer using the library and explains much less of the general concepts of the libary than it could. I am one of those who believe that a thorough overview of a library is very important, even more important than examples, but then I am probably deficient myself in providing examples for libraries I write.

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

On 11/10/13 00:47, Andrew Hundt wrote:

I completely agree that boost docs should generally be a "how to use" guide. The additional steps I also think would be reasonable are for the "how to use" detail to be easier to browse around and links to all the existing examples and tests.

There are two parts to a documentation: - a reference documentation, which says non-ambiguously what a function does, what its preconditions are, which file it is in, etc. It is easy to agree upon the fact that this documentation should be written with Doxygen to ensure that it's always in sync with real code. - a tutorial, that explains the domain and how to approach using the library to solve some problems. This is better written separate from the library using Quickbook (or ReST or any other similar language). Standardizing all Boost documentation for the reference part would be great IMHO. Each library seems to do its own thing for this, with varying levels of quality.

On 11/10/13 15:31, TONGARI J wrote:

I think Doxygen is fine for "regular" libraries, but I always have a question: how could a library like Spirit be doucumented with it?

Same as any other library. You document the data types and the functions.

On 11/10/13 18:58, Felipe Magno de Almeida wrote:

On Fri, Oct 11, 2013 at 4:57 PM, Mathias Gaunard wrote:

...

On 11/10/13 15:31, TONGARI J wrote:

...

I think Doxygen is fine for "regular" libraries, but I always have a question: how could a library like Spirit be doucumented with it?

Same as any other library. You document the data types and the functions.

So you don't document the grammar?

The grammar is a property of the input, which is documented as part of the preconditions of each function.

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Rene Rivera Sent: Friday, October 11, 2013 6:04 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

I haven't read all of this thread.. But I find Doxygen documentation cumbersome and limited. For my Predef library I decided to extend quickbook to let me more directly document the structure of Predef. Which is not easy as it's *all* macro definitions. Perhaps my solutions could help the general mixing of source & documentation. For example this < http://www.boost.org/doc/libs/1_55_0b1/libs/predef/doc/html/predef/reference... acros.html#predef.reference.version_definition_macros.boost_predef_make_macros>

I think the C++ Reference section would look very similar using Doxygen comments on the macros themselves. And all the BOOST_PREDEF_MAKE_0X_VRP(V) would be hyperlinks. And the AutoIndex (macro only section if you want) would provide an alphabetical list of hyperlinks. It's the *combination* of Doxygen with Quickbook that is the key to getting everything hyperlinked (for use in text and C++ Reference section). Used this way Doxygen is only a tool for generating hyperlinks and linking them to the user provided comments on \pre \post \param \tparam \returns ... (Doxygen soon to use Clang and probably eventually the compiler output something from the compilation process) Hope this makes things clearer. Paul

On 11/10/13 20:49, Robert Ramey wrote:

Mathias Gaunard wrote:

...

On 11/10/13 15:31, TONGARI J wrote:

...

I think Doxygen is fine for "regular" libraries, but I always have a question: how could a library like Spirit be doucumented with it?

Same as any other library. You document the data types and the functions.

what about the type constraints - aka concepts? and templates?

What about them? No problem with any of those. Concepts being entities outside of the source code, you don't use Doxygen to define them. The definition of the concept has to be written in Boostbook. You can then reference your concept in Doxygen in the documentation of a function (template or not), or from Quickbook.

On 10/12/2013 9:48 AM, Robert Ramey wrote:

Mathias Gaunard wrote:

...

You can then reference your concept in Doxygen in the documentation of a function (template or not), or from Quickbook.

I realize this. It sounds like you're agreeing with me that Doxygen/Quickbook are not good tools for generating this (essential, for me) aspect of the reference documentation.

Right, because doxygen parses comments in C++, and concepts are not (yet) a standard part of C++. If and when they are, I'm sure doxygen will support them. I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose. For most of my libraries, I'm managed to press Doxygen/Boostbook into service and gotten something I'm mostly satisfied with. Less so for Accumulators, whose documentation is pretty poor, I freely admit. For Proto, doxygen was an abject failure. I used it once to get a crude reference section in Boostbook, then edited it by hand to correct all the flaws, add concept docs, and a complete class and function listing. I've since been maintaining it by hand, and it's awful. (Robert, can you please point me to the editor you use?) I'll add my voice to those who find the header-first reference layout less than ideal, although I say that without a concrete suggestion for improving it. -- Eric Niebler Boost.org http://www.boost.org

Mateusz Loskot wrote:

On 12 October 2013 18:59, Eric Niebler wrote:

...

I'll add my voice to those who find the header-first reference layout less than ideal, although I say that without a concrete suggestion for improving it.

My own impression, after numerous docs discussions, is that we've been exchanging random bullets of pros and cons, advantages and disadvantages, tool A vs tool B, example X vs example Y, but still, we haven't near to the point of a compromise on an ideal (or optimal) Boost documentation for a library.

I don't think the discussion is all THAT random. I've more or less expressed a desire for more formal, regular SGI like documentation and I don't think anyone has said that's not an unworthy goal. The fact that we don't have ideal tools makes it harder to atain this though. I don't feel we all have to agree.

If I was given unlimited time, a text editor and asked to handcraft HTML pages with ideal documentation for a library, I would have trouble to imagine a complete picture of it.

Ahhh - don't use your imagination!!! Look at the docs for our various libraries. These cover a wide span in library type and functionality, scale, toolset used. Ask yourself which of the libraries did you find the easiest to use? Which made you want to tear your hair out. I've mentioned some models - patterns and anti-patterns.

I may know my library well, but it does not mean I know how to describe it well. (I may be a capable mathematician, but a rubbish teacher :))

I totally get this. I made the serialization library and no one knew (or knows) it as well as I do. I wrote the first cut documentation and thought it was good. I caught hell for this. (I still say it wasn't THAT bad) but given the advice of a lot of really bad explainers here, and constant tweaks in response to users who complain about stuff, it's gotten to the point to where I don't get too many complaints.

I've been hoping the Boost community can take smallest Boost library which contains most of C++ elements and make its docs an example of systematic approach (a flowchart) on writing documentation for a Boost library.

We're on the same page here. I've mentioned a few libraries which I think should be used as models. I've also tried to make a sort of "form filling" approach to documentation of at least reference part of the documentation.

I know it may sound like delegating a work,

lol - well, that's what libraries are!

but I personally seek for mentoring here.

I think the fact that you're following this discussion - apparently others are as well - is a good start. Robert Ramey

Mateusz Loskot wrote:

On 12 October 2013 22:29, Robert Ramey wrote:

...

I've also tried to make a sort of "form filling" approach to documentation of at least reference part of the documentation.

I think a kind of a flowchart approach would be helpful:

<snip>

IOW, a systematic top-bottom approach to documenting.

a little to detailed for my taste. I prefer to focus slightly differently: Try to agree on what boost accept should contain, and leave the exact procedure and tools to be used to each author.

Each of those steps, apart form the last one, do not need to even mention any of Quickbook/Boostbook tools in details, but just minimum guidelines related to format of choice:

Absolutely agree. The requirements for documentation are separate from the tools required to creates documentation fullfilling any agreed upon requirements. Robert Ramey

Eric Niebler wrote:

On 10/12/2013 9:48 AM, Robert Ramey wrote:

...

Mathias Gaunard wrote:

...

You can then reference your concept in Doxygen in the documentation of a function (template or not), or from Quickbook.

I realize this. It sounds like you're agreeing with me that Doxygen/Quickbook are not good tools for generating this (essential, for me) aspect of the reference documentation.

Right, because doxygen parses comments in C++, and concepts are not (yet) a standard part of C++. If and when they are, I'm sure doxygen will support them.

I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose.

For most of my libraries, I'm managed to press Doxygen/Boostbook into service and gotten something I'm mostly satisfied with. Less so for Accumulators, whose documentation is pretty poor, I freely admit. For Proto, doxygen was an abject failure. I used it once to get a crude reference section in Boostbook, then edited it by hand to correct all the flaws, add concept docs, and a complete class and function listing. I've since been maintaining it by hand, and it's awful. (Robert, can you please point me to the editor you use?)

I use last free personal edition of XMLMind (version 5.1.1). http://www.blincubator.com/downloads/xxe-perso-5_1_1-setup.exe I describe how I setup for boost documentation here: http://rrsd.com/blincubator.com/tools_documentation/ and here you can see what the final product looks like for a small library http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_numeri... And while your at it - I'd very much appreciate some feedback on www.blincubator.com which is my take on how the sand box should work. Robert Ramey

On 12/10/13 19:59, Eric Niebler wrote:

I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose.

Maybe Quickbook could be extended to be able to output the required XML for concepts?

On 14 October 2013 18:39, Paul A. Bristow wrote:

...

From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Mathias Gaunard On 12/10/13 19:59, Eric Niebler wrote:

...

I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose.

Maybe Quickbook could be extended to be able to output the required XML for concepts?

What is required that is not already provided by Doxygen comments of type

\tparam \param \pre \post \returns etc?

If we have a concept like

template <class T> struct DefaultConstructable;

It will be possible to get a link to this from \tparam description

\tparam The type of the elements stored in the circular_buffer. T has to be DefaultConstructible. ----------------------------------------------------------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This sentence should not even appear there, but something like: \tparam The type of the elements stored in the circular_buffer. \modelof DefaultConstructible and that's important point of the whole debate, IMHO.

In the C++ reference section this will produce

Template Parameters

typename T

The type of the elements stored in the circular_buffer.

T has to be DefaultConstructible

(and circular_buffer and DefaultConstructible will both automatically be hyperlinks - this is what Doxygen really does for you).

If it was about hyperlinking stuff, we would have solved it already. It is about marking, extracting, formatting, synthesizing and interlinking all of the animals in the C++ vocabulary: If I have a concept EasilyDocumentable, how shall I stuff Doxygen with data to get page like this? http://www.boost.org/doc/libs/1_54_0/libs/utility/CopyConstructible.html hyperlinked to refinements and models as well. If I havea model well_documented, how...like this? http://www.boost.org/doc/libs/1_54_0/libs/fusion/doc/html/fusion/container/v... with "model of" list of corresponding concepts, valid expressions and semantics would be nice too. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On 15 October 2013 09:33, Paul A. Bristow wrote:

...

Mateusz Loskot wrote: On 14 October 2013 18:39, Paul A. Bristow wrote:

...

Mathias Gaunard wrote:

...

On 12/10/13 19:59, Eric Niebler wrote:

...

I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose.

Maybe Quickbook could be extended to be able to output the required XML for concepts?

What is required that is not already provided by Doxygen comments of type

\tparam \param \pre \post \returns etc?

If we have a concept like

template <class T> struct DefaultConstructable;

It will be possible to get a link to this from \tparam description

\tparam The type of the elements stored in the circular_buffer. T has to be DefaultConstructible.

---

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This sentence should not even appear there, but something like:

\tparam The type of the elements stored in the circular_buffer. \modelof DefaultConstructible

and that's important point of the whole debate, IMHO.

OK - modelof would be nice but:

1 We could get \modelof added to Doxygen.

Yes, that is a good idea.

2 The key information DefaultConstructible is present - a big improvement on the current situation. And if you go to the source hpp, you will also find the comment with this info.

It is present, but without important context and semantic. The lack of context and semantic in "raw docs" is what makes it hard to generate clear, consistent and friendly end-user documentation. All the gymnastics like Boost.Asio's XSLT, Boost.Geometry's doxygen_xml2qbk, etc. have been invented to apply the missing context and semantic to bits and pieces extracted by Doxygen.

...

It is about marking, extracting, formatting, synthesizing and interlinking all of the animals in the C++ vocabulary:

I have a long term vision of starting with Clang and adding the documenting-from-comments features, but we are way off that. A GSoC project?

The clang utilisation is what I have been thinking of myself, since I discovered http://jessevdk.github.io/cldoc/

We also perhaps don't want to put a lot of work into making BOOST_CONCEPTS work automatically, only to find that it obsolete if concepts are added to C++.

For a year or several, we should be using the tools we have to best.

Tools are crucial, but we haven't decided *what* those tools are supposed to do (extracting and hyperlinking bits of comments is not enough). Let's *forget* about the tools and focus on creating the "form filling" framework, creating the Boost documentation structure with gaps to be filled with content.

From the docs quality perspective, it does not really matter how we fill those gaps, manually or with the tools. Certainly, from productivity and such perspective, tools are crucial, but we still haven't decided what those tools would do :)

IMHO, we try to solve micro-problems of markup and tools too early, whereas we should rather stick to top-bottom approach.

...

If I have a concept EasilyDocumentable, how shall I stuff Doxygen with data to get page like this?

http://www.boost.org/doc/libs/1_54_0/libs/utility/CopyConstructible.html

If you wish I could tackle this now - but I'm too busy with a bout of industrial strength DIY at present ;-)

"how shall I stuff Doxygen"? Teach me please, I can wait :-)

But when I'm free, is this worth tackling?

I linked the "good examples" docs assuming those are exemplars we should try to aim, so where the doubt/question comes from?

...

If I have a model well_documented, how...like this?

http://www.boost.org/doc/libs/1_54_0/libs/fusion/doc/html/fusion/container/v...

...

with "model of" list of corresponding concepts, valid expressions and semantics would be nice too.

It's OK - but it's very much reference info - it doesn't have hyperlinks to explain much - not even links to the source files!

I can't get the importance of links to source files. That is secondary, if not a more remote, issue in the Boost docs project, IMHO.

As an test example, it's also a bit of a googly because Fusion a bit of a weird and wonderful meta-language-ish beast.

Another test-case example?

I'll follow Robert's suggestion: enable_if, Fusion, Iostreams, MPL, Spirit. Why? The meta aspect of a library bumps the complexity of documenting it, so it's good to tackle meta-language-ish beasts first. To summary, let me repeat what is *my* problem with documenting Boost, what I have been grinding in this thread in almost every post: 1. I have created my first library Boost.XYZ. 2. I haven't put a single line of C++ comment in Boost.XYZ sources. 3. I have collected all the tiniest details about every template, class, function, concept, pre-/post-condition, ... in my head. 4. I need forms or templates that I can fill with *all* those details I have collected about Boost.XYZ? 5. I will be filling those forms manually, in my favourite text editor. NOTE: I don't want to learn new language (yet [1]) to document my library, it must be no-brainer boring form filling [2] 6 .I will pass the filled forms (doc source files) to the Boost Documentation repo to generate HTML pages at http://www.boost.org/libs/xyz/ where *all* those details will be presented in canonical way (SGI STL, Robert's examples), using consistent formatting and typography, properly interlinked (concepts, refinements, models,...), <all the fancy output features here> 7. Where can I find the forms? [1] Learning new language or tool shall be necessary *only* if I want to use it, but may like manual labor of writing from top of my head [2] Implies easy automation with tools Are the expectations outlined above invalid and I'm misunderstanding the whole problem? If yes, then I'll rewind, go back and seek to learn the right way. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On 15/10/13 16:55, Bjorn Reese wrote:

On 10/15/2013 04:32 PM, Mateusz Loskot wrote:

...

The clang utilisation is what I have been thinking of myself, since I discovered http://jessevdk.github.io/cldoc/

New versions of Doxygen also uses clang.

I'm looking at this right now. Looks like you need to specify CLANG_ASSISTED_PARSING to YES and then you can pass options with CLANG_OPTIONS. It says that it makes parsing slower, but that's doubtful, since in my case clang compiles my stuff in seconds while Doyxgen takes several minutes to parse it. Anyone has some experience with this?

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Niall Douglas Sent: Tuesday, October 15, 2013 7:00 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

On 15 Oct 2013 at 18:46, Mathias Gaunard wrote:

...

...

New versions of Doxygen also uses clang.

I'm looking at this right now. Looks like you need to specify CLANG_ASSISTED_PARSING to YES and then you can pass options with CLANG_OPTIONS.

Last time I looked doxygen wasn't using libclang in the right way (i.e. via the json database for compile flags), and all that was going to be ripped out and replaced with the right way of invocation. Until that happens, I'd wait.

Agreed. By using Doxygen, all that we are really deciding to do now is to use the Doxygen *comments syntax* to describe our functions, classes etc. In future, I see the compiler associating comments and links with functions and classes etc. But the compiler is still far too stupid to write the descriptive comments that make sense to humans. (It might help with pre and post conditions.) So the author still has work to do. Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com

Mateusz Loskot wrote:

Tools are crucial, but we haven't decided *what* those tools are supposed to do (extracting and hyperlinking bits of comments is not enough).

Let's *forget* about the tools and focus on creating the "form filling" framework, creating the Boost documentation structure with gaps to be filled with content. From the docs quality perspective, it does not really matter how we fill those gaps, manually or with the tools. Certainly, from productivity and such perspective, tools are crucial, but we still haven't decided what those tools would do :)

IMHO, we try to solve micro-problems of markup and tools too early, whereas we should rather stick to top-bottom approach.

+1 Here's the link to my own proposal for a "form filling" approach: http://rrsd.com/blincubator.com/requirements_documentation/

...

As an test example, it's also a bit of a googly because Fusion a bit of a weird and wonderful meta-language-ish beast.

Another test-case example?

Here's my test case example: http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_numeri...

I'll follow Robert's suggestion: enable_if, Fusion, Iostreams, MPL, Spirit.

I'm sure there are others - I haven't studied all of boost in detail.

Why? The meta aspect of a library bumps the complexity of documenting it, so it's good to tackle meta-language-ish beasts first.

+1 - first decide what - then decide how - or better yet - let the person who does decide how.

To summary, let me repeat what is *my* problem with documenting Boost, what I have been grinding in this thread in almost every post:

1. I have created my first library Boost.XYZ. 2. I haven't put a single line of C++ comment in Boost.XYZ sources. 3. I have collected all the tiniest details about every template, class, function, concept, pre-/post-condition, ... in my head. 4. I need forms or templates that I can fill with *all* those details I have collected about Boost.XYZ? 5. I will be filling those forms manually, in my favourite text editor. NOTE: I don't want to learn new language (yet [1]) to document my library, it must be no-brainer boring form filling [2] 6 .I will pass the filled forms (doc source files) to the Boost Documentation repo to generate HTML pages at http://www.boost.org/libs/xyz/ where *all* those details will be presented in canonical way (SGI STL, Robert's examples), using consistent formatting and typography, properly interlinked (concepts, refinements, models,...), <all the fancy output features here> 7. Where can I find the forms?

http://rrsd.com/blincubator.com/tools_documentation/ describes what has worked for me.

[1] Learning new language or tool shall be necessary *only* if I want to use it, but may like manual labor of writing from top of my head [2] Implies easy automation with tools

Are the expectations outlined above invalid and I'm misunderstanding the whole problem? If yes, then I'll rewind, go back and seek to learn the right way.

The whole thrust of your email resonates with my feelings about the subject. Robert Ramey

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Paul A. Bristow Sent: Wednesday, October 16, 2013 10:17 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Tuesday, October 15, 2013 5:42 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

...

...

Another test-case example?

Here's my test case example:

http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_ numerics/master/safe_numeri cs/doc/html/index.html

OK - I'll rise to this challenge to convert to Quickbook and prepare C++ reference section using Doxygen comments (as best I can, not being the library author).

But not for a week or too - the cement dust level is too high ;-)

The dust level in my house has fallen below danger levels and so I have been able to spend some time working on Robert Ramey's challenge to document his proposed Boost Library version of Safe Integer. Like the previous challenge, it is a bit of a googly - it has about one class and 3 functions! In a sense the documentation for the user is trivial - once you have seem the examples, the rest of the docs is unlikely to be read. But the devil is in the details - they involve much meta-programming and will made my brain hurt. So there are two (unusually distinct) requirements for documentation - user, and author/maintainer. (Is a reason we have unmaintained libraries that the detailed documentation is poor?) Before you inspect the demonstration, some caveats: * This is a not a Boost library, nor even a draft library (Robert is already on version 3!). * I am not the author and I don't fully understand it. * There are bound to be mistakes. * It is not fully documented - this would be a waste of effort as it is under development. * Some comments are obviously contrived, just to demonstrate some features. * For my convenience, transferred all the code to the boost-sandbox file format, and changed all the header files. * Not GIT file layout compatible. What I want to show is how I think it is the *combination* of Quickbook, Doxygen comments providing for the C++ References section, and AutoIndex that is key to providing what all users want. I have produced two versions (automatically generated) which are for users, and another for author/maintainer that also documents all the namespace detail sections. The later is much longer of course. * Changed Boostbook.css to user different syntax colors (my personal choice - but I like it much better). * In the C++ Reference section only, always underline links to make them stand out better. I think it is much clearer when navigating around this section. Some of the desirable features that I hope this demonstrates: * Nice formatting with Quickbook. * Preparation of both html and pdf versions. The pdf version is a single standalone file that can be used offline. All the PDF document can easily be searched for any text using the Find function. * Code snippets and sample output - that have actually compiled and run (no typos!). * Links to the actual code examples. "You can see the full example code at example2.cpp" * Quickbook within code examples - making it easy to understand what the example demonstrates, and also include output. * Syntax colored code. * Lots of hyperlinking (but everyone does/should do that!). * Automatic legal stuff - copyright and license info on every page. * Links to Trac tickets (well, of course, actually there are none yet ;-) * Using Doxygen to generate Standalone Doxygen documention - a quick firststep to confirm that everything has been commented syntactically correctly and completely (you can get warnings for any undocumented items). (This avoids annoying errors showing up later - and inscrutably - at the slower-to-rebuild Quickbook stage). * Using Quickbook with Doxygen to prepare a Boost.Safe Numerics C++ Reference section. * Using Doxygen comments to record meaning of function parameters, template parameters * Using Doxygen \cond DETAIL... \endcond to Exclude items that are not relevant to users (but allow creating a separate set of docs with more to be visible to developers and maintainers where other stuff, for example in namespace detail, are also documented). * Since the Quickbook/Doxygen C++ Reference section is centered on the .hpp include files, also use AutoIndex so that all the functions, class, and macros are listed alphabetically. This means that if the function names is known, from the text, * Provide the compile-time 'return' from MPL using a Doxygen comment like "return maximum bits in Numeric types T and U" * Provide an index of other text terms (not just automatic functions, classes...) provided by the author (I'ver added a few ramdomish index terms into the file safe_numerics.idx). One of the limitations noted (and given as a reason for not using Doxygen) was that although Doxygen 'knows' about all the C++ language features, and has a \return comment item for this purpose, Doxygen does not recognise the compile-time computed 'return' of 'result' from a MPL template function. But this information can easily be provided as a plain comment, for example: //! @b return number of bits in type T. Concepts are a similar limitation, (until concepts are part of the C++ language). The Boost.GIL library pioneers a method of automatically providing concept using BOOST.Concept, and this could be used here. For now, I have used a simpler link to the concept like http://www.sgi.com/tech/stl/RandomAccessContainer.html. It is certainly true that the resulting documentation is much larger than one can produce manually and if read right through will appear highly repetitive. But disk space is no longer an issue and I believe that completeness is valuable - it does not matter that the same information is in two places because it makes is more likely that the reader will find it. For the author, much of the tedious part of writing the comments can be reduced by copy and paste of 'boilerplates of comments'. For the reader, the key is hyperlinking: the very many hyperlinks mean that the reader will never see the pages he is not interested in, but will always have the full information on the pages he does land on. The indexes mean that the reader can approach from a subject term, a function, class or MACRO name, or a filename.

-----Original Message----- From: Paul A. Bristow [mailto:pbristow@hetp.u-net.com] Sent: Tuesday, November 19, 2013 3:18 PM To: 'boost@lists.boost.org' Subject: RE: [boost] Improving Documentation

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Paul A. Bristow Sent: Wednesday, October 16, 2013 10:17 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: Tuesday, October 15, 2013 5:42 PM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

...

...

Another test-case example?

Here's my test case example:

http://htmlpreview.github.io/?https://raw.github.com/robertramey/saf e_ numerics/master/safe_numeri cs/doc/html/index.html

OK - I'll rise to this challenge to convert to Quickbook and prepare C++ reference section using Doxygen comments (as best I can, not being the library author).

But not for a week or too - the cement dust level is too high ;-)

The dust level in my house has fallen below danger levels and so I have been able to spend some time working on Robert Ramey's challenge to document his proposed Boost Library version of Safe Integer.

Like the previous challenge, it is a bit of a googly - it has about one class and 3 functions!

In a sense the documentation for the user is trivial - once you have seem the examples, the rest of the docs is unlikely to be read. But the devil is in the details - they involve much meta-programming and will made my brain hurt.

So there are two (unusually distinct) requirements for documentation - user, and author/maintainer. (Is a reason we have unmaintained libraries that the detailed documentation is poor?)

Before you inspect the demonstration, some caveats:

* This is a not a Boost library, nor even a draft library (Robert is already on version 3!). * I am not the author and I don't fully understand it. * There are bound to be mistakes. * It is not fully documented - this would be a waste of effort as it is under development. * Some comments are obviously contrived, just to demonstrate some features. * For my convenience, transferred all the code to the boost-sandbox file format, and changed all

header files. * Not GIT file layout compatible.

What I want to show is how I think it is the *combination* of Quickbook, Doxygen comments

for the C++ References section, and AutoIndex that is key to providing what all users want.

I have produced two versions (automatically generated) which are for users, and another for author/maintainer that also documents all the namespace detail sections. The later is much longer of course.

* Changed Boostbook.css to user different syntax colors (my personal choice - but I like it much better).

* In the C++ Reference section only, always underline links to make them stand out better. I

much clearer when navigating around this section.

Some of the desirable features that I hope this demonstrates:

* Nice formatting with Quickbook.

* Preparation of both html and pdf versions. The pdf version is a single standalone file that can be used offline. All the PDF document can easily be searched for any text using the Find function.

* Code snippets and sample output - that have actually compiled and run (no typos!).

* Links to the actual code examples. "You can see the full example code at example2.cpp"

* Quickbook within code examples - making it easy to understand what the example demonstrates, and also include output.

* Syntax colored code.

* Lots of hyperlinking (but everyone does/should do that!).

* Automatic legal stuff - copyright and license info on every page.

* Links to Trac tickets (well, of course, actually there are none yet ;-)

* Using Doxygen to generate Standalone Doxygen documention - a quick firststep to confirm that everything has been commented syntactically correctly and completely (you can get warnings for any undocumented items). (This avoids annoying errors showing up later - and inscrutably - at the slower-to- rebuild Quickbook stage).

* Using Quickbook with Doxygen to prepare a Boost.Safe Numerics C++ Reference section.

* Using Doxygen comments to record meaning of function parameters, template parameters

* Using Doxygen \cond DETAIL... \endcond to Exclude items that are not relevant to users (but allow creating a separate set of docs with more to be visible to developers and maintainers where other stuff, for example in namespace detail, are also documented).

* Since the Quickbook/Doxygen C++ Reference section is centered on the .hpp include files, also use AutoIndex so that all the functions, class, and macros are listed alphabetically. This means that if the function names is known, from the text,

* Provide the compile-time 'return' from MPL using a Doxygen comment like "return maximum bits in Numeric types T and U"

* Provide an index of other text terms (not just automatic functions, classes...) provided by the author (I'ver added a few ramdomish index terms into the file safe_numerics.idx).

One of the limitations noted (and given as a reason for not using Doxygen) was that although Doxygen 'knows' about all the C++ language features, and has a \return comment item for this purpose, Doxygen does not recognise the compile-time computed 'return' of 'result' from a MPL template function. But this information can easily be provided as a plain comment, for example: //! @b return number of bits in type T.

Concepts are a similar limitation, (until concepts are part of the C++ language). The Boost.GIL

pioneers a method of automatically providing concept using BOOST.Concept, and this could be used here. For now, I have used a simpler link to the concept like http://www.sgi.com/tech/stl/RandomAccessContainer.html.

It is certainly true that the resulting documentation is much larger than one can produce manually and if read right through will appear highly repetitive. But disk space is no longer an issue and I believe that completeness is valuable - it does not matter that the same information is in two places because it makes is more likely that the reader will find it. For the author, much of the tedious part of writing the comments can be reduced by copy and paste of 'boilerplates of comments'. For the reader, the key is hyperlinking: the very many hyperlinks mean that the reader will never see the pages he is not interested in, but will always have the full information on the pages he does land on. The indexes mean that

Sorry :-( Premature send - please ignore but watch this space for full message soon. Paul the providing think it is library the

reader can approach from a subject term, a function, class or MACRO name, or a filename.

On 14/10/13 19:39, Paul A. Bristow wrote:

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Mathias Gaunard Sent: Monday, October 14, 2013 10:55 AM To: boost@lists.boost.org Subject: Re: [boost] Improving Documentation

On 12/10/13 19:59, Eric Niebler wrote:

...

I've also been frustrated by the poor support for concepts in our documentation toolchain. "Just write your docs in Boostbook XML" is like telling people to program in assembly -- if assembly were extremely verbose.

Maybe Quickbook could be extended to be able to output the required XML for concepts?

What is required that is not already provided by Doxygen comments of type

\tparam \param \pre \post \returns etc?

Doxygen is for documenting entities of the C++ language within C++ source code. Concepts are not entities in that language and do not appear in the source code, and thus cannot be documented by Doxygen. I'm not talking about referencing a concept in the documentation of a function or class tempalte, that stuff is indeed done with Doxygen and causes no problems (\xmlonly<conceptname>MyConcept</conceptname>\endxmlonly, that you can wrap in a doxygen alias if you prefer to have \conceptref{MyConcept} instead) I'm talking about defining the concept itself in Boostbook, which is an XML format. See for example the various xml files at $BOOST_ROOT/libs/proto/doc/reference/concepts/ which generate http://www.boost.org/doc/libs/release/doc/html/proto/reference.html#proto.co... Interestingly, as far as I can tell, only Boost.ConceptCheck and Boost.Proto use the real Boostbook format for concepts (my own libraries not accepted into Boost also do) Writing those XML files by hand is indeed not great, and we could extend Quickbook or use another tool to generate them instead.

On 15/10/13 15:59, Felipe Magno de Almeida wrote:

On Tue, Oct 15, 2013 at 10:47 AM, Mathias Gaunard wrote:

...

[snip]

...

Writing those XML files by hand is indeed not great, and we could extend Quickbook or use another tool to generate them instead.

Having used quickbook, adding this support for quickbook would definitely be great! And we could have [conceptref ...] too.

Quickbook already has [conceptref ...], see the Quickbook reference: http://www.boost.org/doc/libs/release/doc/html/quickbook/ref.html Quickbook currently generates a subset of Boostbook, it has all the stuff to "link" or "reference" a function/class/macro/concept, but not the ability to define one.

On 11 Oct 2013 at 14:46, Mathias Gaunard wrote:

...

I completely agree that boost docs should generally be a "how to use" guide. The additional steps I also think would be reasonable are for the "how to use" detail to be easier to browse around and links to all the existing examples and tests.

There are two parts to a documentation: - a reference documentation, which says non-ambiguously what a function does, what its preconditions are, which file it is in, etc. It is easy to agree upon the fact that this documentation should be written with Doxygen to ensure that it's always in sync with real code. - a tutorial, that explains the domain and how to approach using the library to solve some problems. This is better written separate from the library using Quickbook (or ReST or any other similar language).

Standardizing all Boost documentation for the reference part would be great IMHO. Each library seems to do its own thing for this, with varying levels of quality.

I really think the Design Rationale, which is recommended by the Boost wiki, is absolutely vital and often the most important part of a Boost library's documentation. AFIO's design rationale is huge, because I recognised most will disagree with its design and/or not get the point of the library :) Boost libraries often make unusual design choices compared to say a Python or C# or especially Java equivalent. These choices are usually due to (a) C++ convention (b) the fact we can metaprogram the compiler (c) the unique algorithmic complexity guarantees C++ can make, which sometimes require inconvenience on the part of the programmer. A good design rationale tells you where the library author(s) was coming from, why they made the tradeoffs they did, and why some aspect of the library appears really stupid on the surface but in fact is a least worst choice given the alternatives. It's a bit philosophical sure, but it helps to save having to attend C++ Now presentations before you can even try to wrap your head around a library. It's also material that no tutorial nor reference documentation can convey. Niall -- Currently unemployed and looking for work. Work Portfolio: http://careers.stackoverflow.com/nialldouglas/

On 11 October 2013 12:08, Bjorn Reese wrote:

On 10/10/2013 09:00 PM, Andrew Hundt wrote:

...

So, is there anything we can do about it?

In addition to improving the documentation, we could consider a community wiki with additional tips and tricks, or links to existing articles or answers outside of boost.org, or <insert-your-suggestion- here>. This way the community is not restricted by "bottle-neck authors".

There is a wiki: https://svn.boost.org/trac/boost/wiki Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

On 11 October 2013 15:48, Bjorn Reese wrote:

On 10/11/2013 01:28 PM, Mateusz Loskot wrote:

...

There is a wiki: https://svn.boost.org/trac/boost/wiki

That wiki is more oriented towards Boost developers. I was thinking about a wiki directed towards Boost users.

AFAIU, it's orientation is at whatever the Boost Community wants it. I suppose that once Boost libraries move to separate repositories at GitHub or BitBucket or..., then it will be easier to maintain per-library Wiki, in more structured manner. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net