On 5/28/11 May 28 -1:50 PM, Pascal Costanza wrote:
....
Well, as a minimum, I have two requests to make changes in the documentation:
- In Section 3.1, the documentation says the following: "The simplest way to add a path to your search path, say /home/luser/.asd-link-farm/ is to create the directory ~/.config/common-lisp/source-registry.conf.d/ and there create a file with any name of your choice but the type conf, for instance 42-asd-link-farm.conf containing the line: (:directory "/home/luser/.asd-link-farm/")"
This is very confusing, because the "old style" using asdf:*central-registry* is decidedly much simpler. So the sentence above needs some explanation in what sense the "new style" is simpler.
I would be happy to splice into the manual an account of the "old school" way to configure ASDF. I mostly still use this myself, albeit with the aid of a couple of ancillary libraries that are used at our company to make it possible to smoothly make consistent configurations across users without enforcing commonality in users' directory trees. Hence my configuration instructions are not easily portable. But I would be happy to merge contributions from you or others to the manual and wrangle the texinfo.
Until then, the manual states that asdf:*central-registry* is maintained for backwards compatibility, so I believe Fare is correct to refer to this as the simplest method, with the implicit qualifier of "current" or "going forward." Again, if you disagree strongly enough, you are more than welcome to supply a documentation patch.
- Section 5.3.6 should be renamed. The main body of the text is about how to
use logical pathnames with ASDF 2, and is not a "warning." The recommendation not to use logical pathnames should also be removed, because it is not substantiated (and is therefore not a "warning," because it doesn't say what the potentially bad effects of using logical pathnames are).
Actually, it does say what some problems are. E.g.,
The `asdf-output-translation' layer will avoid trying to resolve and translate logical-pathnames. The advantage of this is that you can define yourself what translations you want to use with the logical pathname facility. The disadvantage is that if you do not define such translations, any system that uses logical pathnames will behave differently under asdf-output-translations than other systems you use.
The non-uniformity of treatment here qualifies as a problem, IMO.
That said, I will push a patch with a more neutral title.
There are advantages and disadvantages with using both either logical pathnames or the ASDF 2 approach. Any future Common Lisp implementation that claims adherence to ANSI CL will support logical pathnames, and so it will be relatively straightforward to use logical pathnames in conjunction with ASDF 2, while ASDF 2 will probably need patching in order to support such a future Common Lisp system, which can be regarded as an advantage of logical pathnames over the ASDF 2 approach.
You are certainly free to do so. Our experience differs from yours.