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<mateusz-AT-loskot.net>  wrote:
>> On 02/10/11 23:03, Dave Abrahams wrote:
>>> on Thu Sep 29 2011, Mateusz Loskot<mateusz-AT-loskot.net>  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.

Sure.

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

Understood.

>>>> - 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:
>>>>
>>>> http://sphinx.pocoo.org/latest/builders.html
>>>
>>> (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.

Understood

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org