Document ASDF :version in manual

[Robert P. Goldman]

The proper use of the :version keyword in ASDF, both in specifying a system and a system's dependencies, is more complicated than one might think.

Add a page to the texinfo manual to document this, and link it from the defsystem grammar.

[Faré (fahree)]

Downgrading to version 2.1, since lack of documentation is no regression as compared to what was before.

[Faré (fahree)]

There is now *SOME* documentation of :version in asdf.texinfo.

It's a bit scarce, though, and it says the system name must be a string, though a symbol will do too.

Robert: Shall I mark this as fixed? Do you want to document it better?

[Robert P. Goldman (rpgoldman)]

The current documentation states:

Version specifiers are parsed as period-separated lists of integers.
I.e., in the example, `0.2.1' is to be interpreted, roughly speaking,
as `(0 2 1)'. In particular, version `0.2.1' is interpreted the same as
`0.0002.1' and is strictly version-less-than version `0.20.1', even
though the two are the same when interpreted as decimal fractions.

and

   * Make sure you know how the `:version' numbers will be parsed! They
     are parsed as period-separated lists of integers. I.e., in the
     example, `0.2.1' is to be interpreted, roughly speaking, as `(0 2
     1)'. In particular, version `0.2.1' is interpreted the same as
     `0.0002.1' and is strictly version-less-than version `0.20.1',
     even though the two are the same when interpreted as decimal
     fractions.

I think this is the critical piece of information. Actually, I think an improvement would be to add documentation of version-specifies, so maybe we should add that. I don't see that the current top level tree structure has a place to put documentation of this function. Maybe we should have functions under the object model...

[Robert P. Goldman (rpgoldman)]

I will attach a proposed patch to asdf.texinfo to provide version-satisfies documentation. In the past, someone complained about my messing with the node headers, as providing "false positive" diffs. Unfortunately, I couldn't get this to compile without jiggering the headers, given my limited knowledge of texinfo. LMK if this is acceptable. If so, you could apply and push, or I could.

[Robert P. Goldman (rpgoldman)]

I will attach a proposed patch to asdf.texinfo to provide version-satisfies documentation. In the past, someone complained about my messing with the node headers, as providing "false positive" diffs. Unfortunately, I couldn't get this to compile without jiggering the headers, given my limited knowledge of texinfo. LMK if this is acceptable. If so, you could apply and push, or I could.

[Faré (fahree)]

Is this done or still in progress?

[Robert P. Goldman (rpgoldman)]

I don't believe that the patch attached to comment #5 was ever pushed. Would you give it a go the next time you push a version?

[Faré (fahree)]

Yes it was pushed some time ago, except for a TOC @c comment, that I just pushed.

Is anything more needed? If not, can we close this bug as Fix Released (if the comment doesn't matter) or Fix Committed (if it does)?

[Robert P. Goldman (rpgoldman)]

Done!