Re: integrating Joram's 'visualindex'

[Werner LEMBERG]

>> Well, it's not about the existing layout – even if we are going to
>> use double-sided formatting, it wouldn't change much (besides some
>> shifts in page numbering).  The thing is that only in double-sided
>> mode I can easily arrange the documentation to make the visual
>> index appear on facing pages.
> 
> [...]  In the NR, there are some sections of prose followed by
> relevant code snippets and the rendered result that sometimes
> awkwardly span across a page break, requiring flipping back and
> forth.

Indeed, this can be manually improved by inserting proper `@need`
instructions.  Note that it can only be improved and not fixed; in
general, it is impossible to have a book-like layout with so many
examples and just a few words plain text inbetween.  With 'book-like'
I mean non-ragged page bottoms that don't have excessive vertical
space on the pages.

> For single-sided formatting, the only option is to try to fit things
> to one page; but with double-sided formatting, you would have the
> option to utilize facing pages.

This is a *hard* problem.  Knuth's TeX engine has no support for that.
There is active research to implement something like that for LaTeX
using LuaTeX.  But even if this might be possible to a certain extent,
there are far too much examples to achieve good results for all of
them.

> But again, I do not think double-sided formatting is strictly
> required for much of the existing content.  The new visual index
> would be one of the few things that I think benefits reliably laying
> out side-by-side.

Well, we don't have to take care of it at all; it's just inserting
this single line of code I mentioned, and everything else is happening
automatically.

BTW, it would also make sense to improve the appendix holding the
cheat sheet to cover exactly two pages; this could be a second benefit
of two-side layout.


    Werner