Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Mateusz Łoskot (mateusz_at_[hidden])
Date: 2011-10-28 11:22:54

On 28 October 2011 11:21, Paul A. Bristow <pbristow_at_[hidden]> wrote:
>> -----Original Message-----
>> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
>> Matias Capeletto
>> Sent: Friday, October 28, 2011 9:58 AM
>> To: Discussion of Boost Documentation
>> Subject: Re: [Boost-docs] The beauty of LATEX
>
> <snip>
>> > Another example is footnotes, for docbook they're easy - you just
>> > write them inline. But when generating html for the web you have to
>> > place the footnotes in the correct location. To find the correct
>> > location you need to know about the structure.
>>
>> Indeed, but supporting this kind of things in HTML requires a bigger beast. Indexing, paging, footnotes... all
>> these goodies requires a full knowledge of the document and a heavy processing of it. To make a good job
>> we will need to replicate something like LaTeX. While this maybe a really good project, I think it is a lot
>> better to rely on it or on Docbook and leave them handle these tasks.
>
> I think handling Indexing (including C++ items that can only come from parsing the C++ code),
> paging, footnotes - is *really* important for good docs. Having these now is a big advance and I
> find myself using all of them even for libraries that I know well (may have written some part).

I'd go even further and expose search engine based on index.
Think Sphinx again. It is more convenient and easier to search Python
documentation
than browse its index.

(Disclaimer: I'm not suggesting use of Sphinx. I only use Sphinx as an
illustration to the idea.)

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