There are quite a few references like this:

• :around-compile attribute

• :compile-check argument

• :encoding attribute

• :force-not feature

etc, etc.

I'm not sure where those attributes, arguments, and features are meant to be used. Examples would go a long way in explaining the context in which each thing might be used.

Indeed. I'll try to update the ASDF docs and provide links to public examples of usage of these features.

BTW, the quicklisp website is out of date.

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org A true intellectual is a man who, after reading a book and being convinced by its arguments, will shoot someone or, more likely, order someone shot. — John McCarthy

On Tue, Nov 27, 2012 at 10:59 PM, Robert Goldman rpgoldman@sift.info wrote:

On 11/27/12 Nov 27 -9:54 PM, Faré wrote:

...

...

There are quite a few references like this:

• :around-compile attribute

• :compile-check argument

• :encoding attribute

• :force-not feature

etc, etc.

I'm not sure where those attributes, arguments, and features are meant to be used. Examples would go a long way in explaining the context in which each thing might be used.

Indeed. I'll try to update the ASDF docs and provide links to public examples of usage of these features.

If you would like, I would be happy to try to help with the texinfo.

Sorry to have been so unavailable to help: I am having all sorts of family events, some good, some bad, and they have left me with little time to contribute to ASDF.

Cheers, r

I did a very quick pass at documenting compile-check, force-not, require-system, *load-system-operation*. Nothing great, but better than nothing.

Yes, another major pass at fixing asdf.texinfo would be great.

Robert, I hope everything is now going well with your family.

—♯ƒ • François-René ÐVB Rideau •Reflection&Cybernethics• http://fare.tunes.org The more one knows, the more one knows that one knows not. Science extends the field of our (meta)ignorance even more than the field of our knowledge.

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.

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

Perhaps a list member with more experience with texinfo has a suggestion?

Zach Beane xach@xach.com wrote:

Faré fahree@gmail.com writes:

...

I did a very quick pass at documenting compile-check, force-not, require-system, *load-system-operation*. Nothing great, but better than nothing.

Yes, another major pass at fixing asdf.texinfo would be great.

Robert, I hope everything is now going well with your family.

The TOC at the start of the manual is great, but the links it offers are pretty coarse, going only to each major section rather than to a specific subsection. That makes it somewhat difficult to link to documentation for a specific new feature. Is there any chance of making the links finer-grained?

Thanks, Zach

On 11/28/12 Nov 28 -8:39 AM, Zach Beane wrote:

rpgoldman@sift.info writes:

...

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.

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

Perhaps a list member with more experience with texinfo has a suggestion?

I think fewer than 0.0001% of readers will use an info browser to read the ASDF manual. Improving the HTML conversion is the ticket.

FWIW, I never use the HTML version. I always use info inside emacs (not the standalone version). If I want to read end-to-end, I use PDF, which has links without the annoying choppiness of a multi-page HTML document.

If you use emacs as your primary development environment, info is nicely integrated.

One of the advantages of Texinfo is that it provides HTML, PDF and info, for different customers.

On Wed, 2012-11-28 at 08:28 -0600, rpgoldman@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.

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

You might want to switch documentation format, and in that case Pandoc(http://johnmacfarlane.net/pandoc/) might help with the initial conversion.

On 11/28/12 Nov 28 -9:02 AM, Didier Verna wrote:

rpgoldman@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

On 11/28/12 Nov 28 -10:37 AM, Didier Verna wrote:

Robert Goldman rpgoldman@sift.info wrote:

...

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

It is. You can do that manually with anchors. Cf. @anchor{} and @ref{} (@xref, @pxref etc.)..

Great! Thanks! That seems like a much lower-cost solution than trying to redo all the node structure.

Best, r

Robert Goldman rpgoldman@sift.info writes:

On 11/28/12 Nov 28 -10:40 AM, Robert Goldman wrote:

...

On 11/28/12 Nov 28 -10:37 AM, Didier Verna wrote:

...

Robert Goldman rpgoldman@sift.info wrote:

...

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

It is. You can do that manually with anchors. Cf. @anchor{} and @ref{} (@xref, @pxref etc.)..

Great! Thanks! That seems like a much lower-cost solution than trying to redo all the node structure.

Zach --

If you have particular links that make you unhappy, even if you can just name them by function, not by link-name, that would make it more likely I would fix them...

If you visit http://l1sp.org/asdf/manual and click on the TOC entry "5.3.9 Serial dependencies", you are brought to "5 Defining systems with defsystem". It's not all that close to the actual desired target.

The same is true for all other subsection links in the TOC.

Zach

Robert Goldman rpgoldman@sift.info wrote:

Thanks. If I get some downtime, I'll try to either split these subsections into nodes (if anyone has an emacs command that will do that automagically, please LMK), or add anchors.

You may want to start with C-x h C-u M-x texinfo-insert-node-lines. This will create all missing nodes for every sectionning command and fill them up with the proper title. However, you will most probably need to update the structure afterwards.