From 0dc7a3ea1b56a32b9506e9f1a884d7db5b883207 Mon Sep 17 00:00:00 2001 From: "Robert P. Goldman" <rpgoldman@gmail.com> Date: Sun, 6 Apr 2014 21:53:18 -0500 Subject: [PATCH] Killed many, many overfull lines in TeX output. I apparently have a high tolerance for drudgery. --- doc/asdf.texinfo | 163 ++++++++++++++++++++++++++++------------------- 1 file changed, 99 insertions(+), 64 deletions(-) diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo index 2e752f41..3cb5a8f5 100644 --- a/doc/asdf.texinfo +++ b/doc/asdf.texinfo @@ -632,12 +632,18 @@ ASDF, starting from easiest to the most complex: @itemize @bullet @item -Put all of your systems in subdirectories of +Put all of your systems in one of the standard locations, subdirectories +of +@itemize +@item @file{~/common-lisp/} or +@item @file{~/.local/share/common-lisp/source/}. -If you install software there, you don't need further configuration. -(NB: @file{~/common-lisp/} is only included in the default configuration -starting with ASDF 3.1.1 or later) +@end itemize +If you install software there, you don't need further +configuration.@footnote{@file{~/common-lisp/} is only included in +the default configuration +starting with ASDF 3.1.1 or later.} @item If you're using some tool to install software (e.g. Quicklisp), @@ -887,7 +893,7 @@ you may want to reset the ASDF configuration. For that you may use the following function: @defun clear-configuration - undoes any ASDF configuration, + Undoes any ASDF configuration regarding source-registry or output-translations. @end defun @@ -2354,9 +2360,10 @@ All components, regardless of type, have the following attributes. All attributes except @code{name} are optional. @subsubsection Name - +@findex coerce-name A component name is a string or a symbol. -If a symbol, its name is taken and lowercased. +If a symbol, its name is taken and lowercased. This translation is +performed by the exported function @code{coerce-name}. Unless overridden by a @code{:pathname} attribute, the name will be interpreted as a pathname specifier according @@ -2929,21 +2936,23 @@ CONFIGURATION := (:source-registry DIRECTIVE ...) DIRECTIVE := ;; INHERITANCE DIRECTIVE: ;; Your configuration expression MUST contain - ;; exactly one of either of these: - :inherit-configuration ; splices inherited configuration (often specified last) - | - :ignore-inherited-configuration ; drop inherited configuration (specified anywhere) - | + ;; exactly one of the following: + :inherit-configuration | + ;; splices inherited configuration (often specified last) or + :ignore-inherited-configuration | + ;; drop inherited configuration (specified anywhere) ;; forward compatibility directive (since ASDF 2.011.4), useful when - ;; you want to use new configuration features but have to bootstrap a - ;; the newer required ASDF from an older release that doesn't sport said features: - :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out + ;; you want to use new configuration features but have to bootstrap + ;; the newer required ASDF from an older release that doesn't + ;; support said features: + :ignore-invalid-entries | ;; add a single directory to be scanned (no recursion) (:directory DIRECTORY-PATHNAME-DESIGNATOR) | - ;; add a directory hierarchy, recursing but excluding specified patterns + ;; add a directory hierarchy, recursing but + ;; excluding specified patterns (:tree DIRECTORY-PATHNAME-DESIGNATOR) | ;; override the defaults for exclusion patterns @@ -2959,16 +2968,19 @@ DIRECTIVE := ;; This directive specifies that some default must be spliced. :default-registry -REGULAR-FILE-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a file -DIRECTORY-PATHNAME-DESIGNATOR := PATHNAME-DESIGNATOR ;; interpreted as a directory name +REGULAR-FILE-PATHNAME-DESIGNATOR + := PATHNAME-DESIGNATOR ; interpreted as a file +DIRECTORY-PATHNAME-DESIGNATOR + := PATHNAME-DESIGNATOR ; interpreted as a directory PATHNAME-DESIGNATOR := NIL | ;; Special: skip this entry. ABSOLUTE-COMPONENT-DESIGNATOR ;; see pathname DSL -EXCLUSION-PATTERN := a string without wildcards, that will be matched exactly - against the name of a any subdirectory in the directory component - of a path. e.g. @code{"_darcs"} will match @file{#p"/foo/bar/_darcs/src/bar.asd"} +EXCLUSION-PATTERN := a string without wildcards, that will be matched + exactly against the name of a any subdirectory in the directory + component of a path. e.g. @code{"_darcs"} will match + @file{#p"/foo/bar/_darcs/src/bar.asd"} @end example Pathnames are designated using another DSL, @@ -2979,36 +2991,50 @@ to be documented and exported at some point in the future. @example ABSOLUTE-COMPONENT-DESIGNATOR := (ABSOLUTE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) | - STRING | ;; namestring (better be absolute or bust, directory assumed where applicable). - ;; In output-translations, directory is assumed and **/*.*.* added if it's last. - ;; On MCL, a MacOSX-style POSIX namestring (for MacOS9 style, use #p"..."); - ;; Note that none of the above applies to strings used in *central-registry*, - ;; which doesn't use this DSL: they are processed as normal namestrings. - ;; however, you can compute what you put in the *central-registry* - ;; based on the results of say (asdf::resolve-location "/Users/fare/cl/cl-foo/") - PATHNAME | ;; pathname (better be an absolute path, or bust) - ;; In output-translations, unless followed by relative components, - ;; it better have appropriate wildcards, as in **/*.*.* - :HOME | ;; designates the user-homedir-pathname ~/ - :USER-CACHE | ;; designates the default location for the user cache - :HERE | ;; designates the location of the configuration file - ;; (or *default-pathname-defaults*, if invoked interactively) - :ROOT ;; magic, for output-translations source only: paths that are relative - ;; to the root of the source host and device - ;; Not valid anymore: :SYSTEM-CACHE (was a security hazard) + STRING | + ;; namestring (better be absolute or bust, directory assumed where + ;; applicable). In output-translations, directory is assumed and + ;; **/*.*.* added if it's last. On MCL, a MacOSX-style POSIX + ;; namestring (for MacOS9 style, use #p"..."); Note that none of the + ;; above applies to strings used in *central-registry*, which + ;; doesn't use this DSL: they are processed as normal namestrings. + ;; however, you can compute what you put in the *central-registry* + ;; based on the results of say + ;; (asdf::resolve-location "/Users/fare/cl/cl-foo/") + PATHNAME | + ;; pathname (better be an absolute path, or bust) + ;; In output-translations, unless followed by relative components, + ;; it better have appropriate wildcards, as in **/*.*.* + :HOME | ; designates the user-homedir-pathname ~/ + :USER-CACHE | ; designates the default location for the user cache + :HERE | + ;; designates the location of the configuration file + ;; (or *default-pathname-defaults*, if invoked interactively) + :ROOT + ;; magic, for output-translations source only: paths that are relative + ;; to the root of the source host and device + +They keyword :SYSTEM-CACHE is not accepted in ASDF 3.1 and beyond: it +was a security hazard. RELATIVE-COMPONENT-DESIGNATOR := (RELATIVE-COMPONENT-DESIGNATOR RELATIVE-COMPONENT-DESIGNATOR ...) | - STRING | ;; relative directory pathname as interpreted by parse-unix-namestring. - ;; In output translations, if last component, **/*.*.* is added - PATHNAME | ;; pathname; unless last component, directory is assumed. - :IMPLEMENTATION | ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64 - :IMPLEMENTATION-TYPE | ;; a directory based on lisp-implementation-type only, e.g. sbcl - :DEFAULT-DIRECTORY | ;; a relativized version of the default directory + STRING | + ;; relative directory pathname as interpreted by + ;; parse-unix-namestring. + ;; In output translations, if last component, **/*.*.* is added + PATHNAME | ; pathname; unless last component, directory is assumed. + :IMPLEMENTATION | + ;; directory based on implementation, e.g. sbcl-1.0.45-linux-x64 + :IMPLEMENTATION-TYPE | + ;; a directory based on lisp-implementation-type only, e.g. sbcl + :DEFAULT-DIRECTORY | + ;; a relativized version of the default directory :*/ | ;; any direct subdirectory (since ASDF 2.011.4) :**/ | ;; any recursively inferior subdirectory (since ASDF 2.011.4) :*.*.* | ;; any file (since ASDF 2.011.4) - ;; Not supported (anymore): :UID and :USERNAME + +The keywords :UID and :USERNAME are no longer supported. @end example For instance, as a simple case, my @file{~/.config/common-lisp/source-registry.conf}, @@ -3535,18 +3561,22 @@ DIRECTIVE := ;; INHERITANCE DIRECTIVE: ;; Your configuration expression MUST contain ;; exactly one of either of these: - :inherit-configuration | ; splices inherited configuration (often specified last) - :ignore-inherited-configuration | ; drop inherited configuration (specified anywhere) + :inherit-configuration | + ;; splices inherited configuration (often specified last) + :ignore-inherited-configuration | + ;; drop inherited configuration (specified anywhere) ;; forward compatibility directive (since ASDF 2.011.4), useful when ;; you want to use new configuration features but have to bootstrap a - ;; the newer required ASDF from an older release that doesn't sport said features: - :ignore-invalid-entries | ; drops subsequent invalid entries instead of erroring out + ;; the newer required ASDF from an older release that doesn't have + ;; said features: + :ignore-invalid-entries | ;; include a configuration file or directory (:include PATHNAME-DESIGNATOR) | - ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/ or something. + ;; enable global cache in ~/.common-lisp/cache/sbcl-1.0.45-linux-amd64/ + ;; or something. :enable-user-cache | ;; Disable global cache. Map / to / :disable-cache | @@ -3558,15 +3588,18 @@ DIRECTIVE := (DIRECTORY-DESIGNATOR (:function TRANSLATION-FUNCTION)) DIRECTORY-DESIGNATOR := - NIL | ;; As source: skip this entry. As destination: same as source - T | ;; as source matches anything, as destination leaves pathname unmapped. - ABSOLUTE-COMPONENT-DESIGNATOR ;; same as in the source-registry language + NIL | ; As source: skip this entry. As destination: same as source + T | ; as source matches anything, as destination + ; maps pathname to itself. + ABSOLUTE-COMPONENT-DESIGNATOR ; same as in the source-registry language TRANSLATION-FUNCTION := - SYMBOL | ;; symbol of a function that takes two arguments, - ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR - LAMBDA ;; A form which evalutates to a function taking two arguments consisting of - ;; the pathname to be translated and the matching DIRECTORY-DESIGNATOR + SYMBOL | ;; symbol naming a function that takes two arguments: + ;; the pathname to be translated and the matching + ;; DIRECTORY-DESIGNATOR + LAMBDA ;; A form which evalutates to a function taking two arguments: + ;; the pathname to be translated and the matching + ;; DIRECTORY-DESIGNATOR @end verbatim @@ -3607,12 +3640,14 @@ in your configuration file, or you may use @code{enable-asdf-binary-locations-compatibility} with @code{:centralize-lisp-binaries nil} which will do the same thing internally for you: -@verbatim - #.(let ((wild-subdir (make-pathname :directory '(:relative :wild-inferiors))) - (wild-file (make-pathname :name :wild :version :wild :type :wild))) - `((:root ,wild-subdir ,wild-file) ;; Or using the implicit wildcard, just :root - (:root ,wild-subdir :implementation ,wild-file))) -@end verbatim +@lisp +#.(let ((wild-subdir + (make-pathname :directory '(:relative :wild-inferiors))) + (wild-file + (make-pathname :name :wild :version :wild :type :wild))) + `((:root ,wild-subdir ,wild-file) + (:root ,wild-subdir :implementation ,wild-file))) +@end lisp Starting with ASDF 2.011.4, you can use the simpler: @code{`(:root (:root :**/ :implementation :*.*.*))} @@ -4153,7 +4188,7 @@ It is up to the user to make sure that reloading is possible and has the desired In some cases, extreme measures such as recursively deleting packages, unregistering symbols, defining methods on @code{update-instance-for-redefined-class} and much more are necessary for reloading to happen smoothly. -ASDF itself goes to extensive effort to make A hot upgrade possible +ASDF itself goes to extensive effort to make hot upgrade possible with respect to its own code, and what it does is ridiculously complex; look at the beginning of @file{asdf.lisp} to see what it does. @end defun -- GitLab