[asdf-devel] ASDF 2.26 in Quicklisp

[Robert Goldman]

On 11/28/12 Nov 28 -9:02 AM, Didier Verna wrote:
> rpgoldman at sift.info wrote:
> 
>> As far as I can tell, this is a misfeature of texinfo. The links only
>> work to the node level (at least in the info browser). So we would
>> need to reactor the document into smaller nodes to fix that.
> 
>   That's not really a misfeature. That fact is that Texinfo uses nodes
>   as its primary sectionning mechanism. You need to think in terms of
>   node first when you write Texinfo. Every sectionning command that you
>   use should be associated with a node, and every node that has
>   sub-nodes should have a menu. It seems that you only have nodes for
>   chapters, which explains the shaky TOC.

This is a fair criticism, however Faré and I inherited the chapter-based
organization, and refactoring texinfo seems like a lot of work.

It would be worth redesigning the information flow at the same time if
we were to restructure.  Notably the discussion of the object model is
incomplete and somewhat messy.  There isn't a clear description of
protocols for extending the object model.  It would be very nice to have
that.

Cheers,
r

> 
>> Unfortunately, in addition to requiring some work, that would also
>> give us a document with very small pages, that would be a nuisance
>> when attempting to read in chunks (as opposed to jumping to a very
>> specific item).
> 
>   That is correct, although I don't find that this is such a nuisance,
>   since you have all the hyperlinks you want. Otherwise, what you can do
>   is generate a single web page for the whole doc (Cf. --no-split).

It's a nuisance if you read the info pages in emacs.  You get choppy
little bites instead of any kind of sensible flow.  E.g., to be able to
jump to a single function's documentation specifically, you have to
sacrifice the ability to have a screen that shows three related
functions together.  Unless I am missing something (I hope I am).

This can be somewhat ameliorated by making a single-page HTML document,
or using PDF, but even then the screens seem impoverished.

It would be nice if texinfo offered links to more specific locations
than nodes, but it sounds like that's not available.

Best,
r