Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-28 11:51:21

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Mateusz Loskot
> Sent: Friday, October 28, 2011 12:23 PM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] The beauty of LATEX
> 
> 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.

Well -  there's some truth in that - I used to use the PDF version in preference to HTML just
because you can do a global search through the whole document.  But having got the index, thanks to
John's work, I prefer the index.  This is because you can see the section that the entry will take
you to.  For example, looking a skeleton doc now in HTML, if I look up C++, I see "About
multiprecision", "Document convention", "References", "C++ Reference", "System Architecture".  So
it's obvious which entry is most promising for what I might be seeking (and obvious that "Document
convention" almost certainly isn't).  If the first try isn't successful, you can go back to the
index for another try.  Since so few docs have been regenerated using John's auto-index, I don't
think people have got used to using it, and seem the benefit yet:  I hope all future docs will
provide indexes - if not why not!

So I still place 'index' in the essential list.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]