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

On Mon, Aug 14, 2017 at 8:15 AM, Edward Diener via Boost 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

On Mon, Aug 14, 2017 at 8:43 AM, Robert Ramey via Boost 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.

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

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

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

Ouch - and would close the door to pdf and ebook versions of the output. 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

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

On 8/15/2017 1:51 PM, Robert Ramey via Boost wrote:

On 8/14/17 9:08 PM, Robert Ramey via Boost wrote:

...

On 8/14/17 5:34 PM, Glen Fernandes via Boost wrote:

...

...

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

Yep - there it is!

I spent a little time investigating this. As I'm sure everyone is tired of hearding I use XMLMind to edit/review docbook and boostbook files. Here is what I've discovered.

a) Boost.Array uses the boostbook tags to specify C++ constructs such as class, struct, etc within the XML version of the document.

b) These tags are used by the boostbook -> docbook xsl transform to generate boiler plate reference documentation.

c) This boostbook xml source has been edited from time to time by hand. They aren't ambitious edits so I'm guessing that the work involved was not hugely tedious or time consuming.

d) As part of this maintenance, a number of xml elements have been added which are not described in the boostbook DTD, Hence as a result, my XMLMind editor flags them as illegal boostbook xml tags. Also these tags are not described in the boostbook -> docbook xsl transform, so they don't appear in the output. A simple example of this is a new element named "maintainer" to specify the name of the library maintainer. Seems like a perfectly reasonable idea - except that without adding provision for this new tag in both the boostbook DTD and the boostbook -> docbook xsl transforms, it never appears in any documentation output.

e) quickbook developers made the decision not to use these tags. I'm guessing that if there is a DOxygen XML -> boostbook transform somewhere in the toolchain, it doesn't use these tags either. I good decision in my view as the boiler plate output for these tags is very much not to my taste.

So that is the current situation. I'm not sure what that means moving forward. I'm sort of thinking:

a) continue minor enhancements to quickboook as they become necessary and/or useful.

b) leave the processing of Doxygen -> quickbook/docbook? as it is. It's well know that I consider that Doxgen is harmful to good documentation. But until I get everyone else on board with this, it shouldn't be changed. It's easy to avoid using for those who have seen the light.

c) eliminate the usage of C++ specific tags from boostbook, boostbook->docbook xsl transforms. Hmmm - they don't do much harm. And messing with xsl is much worse than working with php - if you imagine such a thing. Also eliminating this would require updating the few libraries which use these tags. Not a bad thing overall, but probably not cost effective at this point.

d) One thing that I very much like and think is important is the usage of docbook. This gives access to some important (though kludgy) tools and the ability to transform formats and generate PDF, ebook etc.

In sort, simplifying the tool chain is pretty complicated. But the complexity of the tool chain is motivating people to avoid using it which I think is a bad thing. I would hope that some effort can be invested in option a) (incremental improvements to quickbook) to make it less tempting to move on to something which will only make things worse.

What ! Robert Ramey admitting that quickbook is not evil ? Thanks Robert, for at least investigating this and deciding that quickbook is usable, even if it is not your preferred choice. Maybe you can do the same with doxygen <g>. Whatever your objections it is eminently usable also, even while it is not perfect.

Robert Ramey

On 8/15/2017 4:18 PM, Robert Ramey via Boost wrote:

On 8/15/17 12:54 PM, Edward Diener via Boost wrote:

...

On 8/15/2017 1:51 PM, Robert Ramey via Boost wrote:

What ! Robert Ramey admitting that quickbook is not evil ? Thanks Robert, for at least investigating this and deciding that quickbook is usable, even if it is not your preferred choice. Maybe you can do the same with doxygen <g>. Whatever your objections it is eminently usable also, even while it is not perfect.

LOL - nothing's perfect. quickbook is improvable. On the otherhand there is often a temptation to improve something to try to make it do something that is so far beyond the original intent that you end up ruining it. I know this first hand as I've done it myself many times. And I believe that there are better free tools for doing this.

My beef with DOxygen goes much, much deeper. I'm aware of the idea that it is an implementation of literate programming and I'm credited it in the past for this reason. But there are at least two big problems with it.

a) It doesn't have a good way to specify and refer to type requirements (aka concepts). I think that these are more important to building a C++ program than most people do and Doxygen doesn't really support this. The most it has is TPARAM which is not enough.

b) It doesn't provide a good place/way for including program narative, examples, etc. This would not be a big deal as one could use it to generate the xml which could be transformed into a decent looking reference. But the major problem is that programmers believe that this serves the function of documentation and DOxygen supports what I believe is a misconception. When people are doing things wrong but think they are doing it right, that keeps us from moving forward.

I'm aware that all this is quite a mouthful and not convincing to most programmers. That's why I'm giving a presentation at CPPcon on the subject and my views on it. Turns out that it has been so over subscribed that We're going to charge $10 to attend. So if you're interested, sign up asap.

Are you aware that you can do free form documentation with doxygen as long as you use one of there many general syntaxes for starting/ending in-line documentation ? So obviously you can a) or b) with it. There is absolutely no reason to be constrained solely with using one of their keywords for everything you want to document.

...

...

Robert Ramey

My beef with DOxygen goes much, much deeper. I'm aware of the idea that it is an implementation of literate programming and I'm credited it in the past for this reason. But there are at least two big problems with it.

My main beef with Doxygen is reduced code-readability, which I think has been mentioned a number of times on this list by various others- M

On 16/08/2017 1:13 p.m., Vinnie Falco via Boost wrote:

On Tue, Aug 15, 2017 at 6:12 PM, Soul Studios via Boost wrote:

...

My main beef with Doxygen is reduced code-readability, which I think has been mentioned a number of times on this list by various others-

Yep, and every time someone brings this up I provide this counter-example of Doxygen-assisted output:

Not sure how that is meant to counter the claim of reduced code readability. It merely seems to demonstrate that Doxygen can be used to generate documentation- which seems obvious.

Oh...I thought you meant the readability of code appearing in Doxygen-assisted, generated pages.

Do you mean that the insertion of Javadoc-formatted comments before function declarations makes the code less readable?

Ah, I see :) Yes that's what I meant :)

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.

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.

On 15/08/2017 02:13, 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.

12? Please see: https://svn.boost.org/trac10/wiki/BoostDocs/GettingStarted, OK it looks a little intimidating at first, but there are only three required installs: xsltproc (you will almost certainly have this already on Linux). DocBook DTD DocBook XSL stylesheets After that Quickbook will build itself for you (from a Jamfile), so will auto_index if you want automatic indexing. But yes, we need to improve the getting started stuff.... John.

...

...

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 .

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

12? Please see: https://svn.boost.org/trac10/wiki/BoostDocs/GettingStarted, OK it looks a little intimidating at first, but there are only three required installs:

:) Ha. I read 7 required packages there, and 11 overall components in the diagram. I was compiling on windows, and it was worse there- as you can see on that same page - I couldn't even get it to work, and I came back to it intermittently over the course of about 6 months. If I ever gave it another shot, I would try it on linux, but to be honest, would probably just go down the straight HTML+CSS route.

On 8/15/17 7:01 PM, Gavin Lambert via Boost wrote:

On 16/08/2017 13:07, Soul Studios wrote: Granted I don't know anything about this and might just be misreading something, but from the minute I spent reading that page it does look like only three tools are required if you only want HTML output:

regardless of the details, just the look of the diagram is pretty intimidating. On the the other hand, once you the tools, scripts, etc installed, it's just a matter of calling boost build so everything is hidden. This makes it pretty simple ... until it doesn't which is just about always. I actually like the whole system and I think it's pretty well suited to boost. BUT, the combination with boost build and the desire to hide all the complexity makes it more difficult to use rather than easier. I think if we could work on this, we might persuade developers to stick with it rather than looking for alternatives. Robert Ramey

On 8/16/17 1:25 AM, Gavin Lambert via Boost wrote:

On 16/08/2017 17:39, Robert Ramey wrote:

...

regardless of the details, just the look of the diagram is pretty intimidating. On the the other hand, once you the tools, scripts, etc installed, it's just a matter of calling boost build so everything is hidden. This makes it pretty simple ... until it doesn't which is just about always.

I actually like the whole system and I think it's pretty well suited to boost. BUT, the combination with boost build and the desire to hide all the complexity makes it more difficult to use rather than easier. I think if we could work on this, we might persuade developers to stick with it rather than looking for alternatives.

So it needs better meta-documentation? :)

LOL - very clever. But I actually look at the problem in a different way. It's my view that when something is hard to describe/document it's a symptom that there is design error somewhere. So that it's time to step back and see what mistake you made which leads to something too complex to understand. With the boost documentation system there are couple of suspects: a) The embedding of the complex tool chain into bjam. Of course this is technically doable and results in a very slick - "do what I mean interface" (DWIM tm robert ramey). But with something this complex no one can anticipate all the exceptional cases and when they occur, the system leaves one bereft. b) The inclusion of all the specialized tags for C++ like class, struct, is meant to automate the production of boiler plate output for those C++ constructs. I understand the appeal of this - we're computer programmers and want to automate everything - but in this case it's a bridge too far. quickbook doesn't use these - a good choice in my opinion. A few hand edited boost book do uses these but the results are not satisfying in my opinion. To improve them, one would have to wade into XSL language - a place were few people want to go. In short, better documentation of the toolset wouldn't hurt, but I don't think it would solve the whole problem. Robert Ramey

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

On 16 Aug 2017 5:09 pm, "Vinnie Falco via Boost" wrote: On Wed, Aug 16, 2017 at 8:03 AM, Robert Ramey via Boost wrote:

b) The inclusion of all the specialized tags for C++ like class, struct, is meant to automate the production of boiler plate output for those C++ constructs. I understand the appeal of this - we're computer programmers and want to automate everything - but in this case it's a bridge too far. quickbook doesn't use these - a good choice in my opinion. A few hand edited boost book do uses these but the results are not satisfying in my opinion. To improve them, one would have to wade into XSL language - a place were few people want to go.

And again I will use this opportunity to point out that I have "gone there" by creating "docca", an XSL library which provides the component for transforming Doxygen XML output into QuickBook: https://github.com/vinniefalco/docca How does it compare to, or is it based on, the XSLT tools used by Boost Asio? Boost Geometry used to use it briefly with promising results but (maintenance) complexity overkill killed it. -- Mateusz Łoskot

On 8/16/17 8:23 AM, Dominique Devienne via Boost wrote:

On Wed, Aug 16, 2017 at 5:03 PM, Robert Ramey via Boost < boost@lists.boost.org> wrote:

...

[...]. To improve them, one would have to wade into XSL language - a place were few people want to go.

Actually, XSL is a natural fit for C++ devs IMHO.

It's both functional (so easy for template meta-programmers), and procedural (so easy for imperative language programmers).

Just read and invest time with the XPath and XSLT books from Dr Kay, and you're good to go :) Preferably 2.0 (this made me notice there's a new 3.0 just out !)

I think learning XPath/XSLT made me a better programmer even, broadening my CompSci horizons. Completely OT and FWIW, but I just couldn't resist. :) --DD

[1] https://en.wikipedia.org/wiki/Michael_Howard_Kay

Hmmm sounds like you're volunteering to spend time with this. Am I correct? Robert Ramey

Granted I don't know anything about this and might just be misreading something, but from the minute I spent reading that page it does look like only three tools are required if you only want HTML output:

* doxygen * xsltproc * quickbook

(And the latter is included in Boost sources, so really that's only two. The third install is if you want PDF output for anything other than Accumulators.)

All I can tell you is that I struggled with it. It may be easier on linux, I don't know. But almost everything lacked explanation, including the whole jamfile process (or if there was documentation, I couldn't find it).

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

On Mon, Aug 14, 2017 at 8:29 AM, Andrzej Krzemienski via Boost 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#qu...

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