Re: [Boost-docs] Sphinx integration

Subject: Re: [Boost-docs] Sphinx integration
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2011-10-05 09:13:06

On 05/10/11 00:13, Dave Abrahams wrote:
> on Tue Oct 04 2011, Mateusz Loskot<> wrote:
>> On 02/10/11 23:03, Dave Abrahams wrote:
>>> on Thu Sep 29 2011, Mateusz Loskot<> wrote:
>>>> Doxygen does not support many of the terms/concepts/elements used across
>>>> Boost libraries. It is also becasue it is almost impossible to document
>>>> them well at source code levels.
>>>> However, things like "concept and model" exist at source code level,
>>> do not?---------------------------------^
>>> That's true of concepts unless you're using Boost.ConceptCheck. But
>>> even so, they will only be seen by Doxygen as regular C++ and not as the
>>> abstractions they represent. And there are no model declarations. :-(
>> I understand your question, but I meant it as it reads.
>> I assumed concepts have representation in C++ code, either using
>> Boost.ConceptCheck or custom implementation of concepts.
> Yes, they could. And we could #ifdef them out for tools (like existing
> C++ compilers) that don't support them.


>> So, I assumed they are documented and linked with corresponding
>> models.
> Generally speaking, models of auto concepts and of concepts matched by
> concept_map templates won't have any explicit link to the concept.


>>>> - integrate source level documentation with documentation dedicated to
>>>> end-user
>>> Again, could you be more specific? Is it deeper than simply allowing
>>> linking between the two?
>> Yes, I made it utterly unclear.
>> I meant what I have explained above now. It is to use source code
>> comments content as documentation content too, including interlinking
>> symbols (also concepts with models).
>> Simply, documentation of Boost.Asio is a good incarnation of the idea.
> OK. IMO you should think about literate programming as well in this
> design space.

Do you mean to start thinking about where are the gaps of missing
features in current Boost documentation tools? What tools should be
patched with the features I discuss here as missing?
BoostBook or QuickBook...or new tool(s)?

>>>> Sphinx can produce PDF and many more:
>>> (note: you'd need to pass through LaTeX as an intermediate format;
>>> Unless something has changed since I last look the reportlab stuff is
>>> geared to forms and is hopelessly weak when it comes to anything that
>>> needs real page layout/line breaking. That's what we did for C++
>>> Template Metaprogramming).
>> I see. I don't know if anything has changed. I have seen a few printouts
>> and they looked "not bad" though.
> Yeah, one or two pages, right? Or the page breaks were explicit?

Yes, short bits.

> Listen, you simply can't beat LaTeX for producing beautiful printed
> documentation or PDFs. IMO there's no point in trying to avoid it. FOP
> is a nightmare (or was, last time I looked, even version 2).

I agree completely.

>>> What's the solution? I think someone needs to survey the kinds of
>>> things people are doing with QuickBook and BoostBook, so that we can
>>> assess whether other systems can support our needs.
>> I'm willing to help with this.
>> Can we make a list of questions ("the kind of things") do we want to
>> answer with the survey?

Would you have anything to add here? Or, irrelevant?

>>> And while we're discussing alternate markup, I'd like to throw Markdown
>>> and Org-mode into the ring.
>> AFAIU, reStructuredText is extensible so it is possible to add custom
>> directives.
> Yes, but they're often a bit cumbersome.

Yes, getting it clear.

>> Markdown is not, but it's light.
> In addition to being able to do a few things that ReST cannot (the
> converse is also true), it's *very* widely-used, a fact which should not
> be taken lightly.


Best regards,

Mateusz Loskot,
Charter Member of OSGeo,
Member of ACCU,

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC