On 3/8/10 Mar 8 -6:35 PM, Faré wrote:
[...snip...]
I have committed a modification to the info file that attempts to reflect the following. For now the discussion will appear in the "defsystem grammar" section of the manual; I don't have time for farther-reaching changes right now.
Now supported (1.630): 1- the name is a string or symbol (the name of which will be downcased). It will be interpreted by merge-component-name-type as a /-separated path, using the type specified by the component class if any.
Added discussion of the way a simple-component-name (in the terms of the grammar) are interpreted.
At the expense of being a nitpicker, the obvious question is "what happens if there is no type specified by the component class? Are we guaranteeing then that the type will be empty?
I'm not documenting the type behavior for now, because it belongs somewhere else...
2- the :pathname specification overrides the name. It is interpreted similarly if a symbol or a string. It can also be a pathname, in which case it is not further interpreted.
What does it mean to say that it overrides the name? What happens if we have
(:file "foo/bar" :pathname "bletch")
do we get "bletch/foo/bar" or "bletch/bar". If the latter, I think it would be better simply to define this as an error condition.
I will wait for instructions about how to document this.
3- the parent's pathname from is an absolute pathname, with proper host and device.
?
4- the pathname obtained from 1 or 2 is merged with the one from 3 as with merge-pathnames*, i.e. if it's relative, then the parent's host and device are used.
Actually, now that we are using merge-pathnames* instead of merge-pathnames, I find that the default argument to merge-component-name-type becomes useless. Unless anyone objects, I will remove it in ASDF 1.631 (and rename the function).
Regarding 2, note that the only portable ways to obtain a pathname are a- #p"LOGICAL-HOST:logical;path;name" b- #.(make-pathname ...) c- More #. magic with merge-pathnames, *load-pathname*, *load-truename*, (user-homedir-pathname), etc.
Got it, I think.
In particular, non-logical namestrings are NOT portable, MUST NOT be used in a portable .asd file, and are otherwise not supported.
Therefore, I think the current behavior is 100% better than the previous one. It indeed needs to be better documented, though.
that would be nice.
I can't find my way through the texinfo documentation. Too much manual section management. Could we be using something nicer? ReST? Exscribe? Gary King's CL-Markdown?
Texinfo is standard and the toolchain is available to everyone.
CL-Markdown has a big dependency chain, and a brittle one.
If you use emacs, it will take care of all of the manual section management: Texinfo > Update every node, Texinfo > Node..., Texinfo > Create menu.... Similarly, emacs will take care of building for you, to a number of different formats.
So far, I'm pretty much the only one editing the manual. I promise to stop if the format changes.
Best, Robert