Commit 0943f47f authored by Jan Moringen's avatar Jan Moringen
Browse files

Doc: Markup improvements in defsystem grammar

* Mark meta-syntactic variables for non-constant, non-rule-name things
  such as symbol, string, pathname, etc.

* Use macros to cross-reference rule definitions and uses

* Replace "See below" with actual references to the sub-sections

* Rule changes:

  * Avoid having two rules named "system-option"

  * Remove repeated definition of "simple-component-name" rule

  * Add operation-name rule
parent b382ac13
......@@ -1416,104 +1416,119 @@ Presumably, the 4th form looks like @code{(defparameter *foo-version* "5.6.7")}.
@findex defsystem
@cindex DEFSYSTEM grammar
@c FIXME: @var typesetting not consistently used here. We should either expand
@c its use to everywhere, or we should kill it everywhere.
@example
system-definition := ( defsystem system-designator @var{system-option}*)
system-designator := simple-component-name | complex-component-name
simple-component-name := lower-case string | symbol
NOTE: Underscores are not permitted. See below.
complex-component-name := string | symbol
See below.
@macro defrule {NAME}
@anchor{rule-\NAME\}\NAME\ :=
@end macro
system-option := :defsystem-depends-on system-list
| :weakly-depends-on @var{system-list}
| :class class-name # @pxref{System class names}
| :build-operation @var{operation-name}
| system-option
| module-option
| option
@ifhtml
@macro refrule {NAME}
@ref{rule-\NAME\,\NAME\}
@end macro
@end ifhtml
# These are only available since ASDF 3 (actually its alpha release 2.27)
system-option := :homepage string
| :bug-tracker string
| :mailto string
| :long-name string
| :source-control source-control
| :version version-specifier
| :entry-point object # @pxref{Entry point}
@ifinfo
@macro refrule {NAME}
@ref{rule-\NAME\,\NAME\,\NAME\,\NAME\}
@end macro
@end ifinfo
source-control := (keyword string)
@ifnothtml
@ifnotinfo
@macro refrule {NAME}
\NAME\
@end macro
@end ifnotinfo
@end ifnothtml
module-option := :components component-list
@example
@defrule{system-definition} ( defsystem @refrule{system-designator} @refrule{system-option}* )
@defrule{system-designator} @refrule{simple-component-name}
| @refrule{complex-component-name}
# NOTE: Underscores are not permitted.
# @pxref{Simple component names,Simple component names,Simple component names}
@defrule{simple-component-name} @var{lower-case string} | @var{symbol}
# @pxref{Complex component names,Complex component names,Complex component names}
@defrule{complex-component-name} @var{string} | @var{symbol}
@defrule{system-option} :defsystem-depends-on @refrule{system-list}
| :weakly-depends-on @refrule{system-list}
| :class @var{class-name} # @pxref{System class names}
| :build-operation @refrule{operation-name}
| @refrule{system-option/asdf3}
| @refrule{module-option}
| @refrule{option}
# These are only available since ASDF 3 (actually its alpha release
# 2.27)
@defrule{system-option/asdf3} :homepage @var{string}
| :bug-tracker @var{string}
| :mailto @var{string}
| :long-name @var{string}
| :source-control @refrule{source-control}
| :version @refrule{version-specifier}
| :entry-point @var{object} # @pxref{Entry point}
@defrule{source-control} ( @var{keyword} @var{string} )
@defrule{module-option} :components @refrule{component-list}
| :serial [ t | nil ]
option :=
| :pathname pathname-specifier
| :default-component-class class-name
| :perform method-form
| :explain method-form
| :output-files method-form
| :operation-done-p method-form
| :if-feature feature-expression
| :depends-on ( @var{dependency-def}* )
| :in-order-to ( @var{dependency}+ )
@defrule{option} :pathname @refrule{pathname-specifier}
| :default-component-class @var{class-name}
| :perform @refrule{method-form}
| :explain @refrule{method-form}
| :output-files @refrule{method-form}
| :operation-done-p @refrule{method-form}
| :if-feature @refrule{feature-expression}
| :depends-on ( @refrule{dependency-def}* )
| :in-order-to ( @refrule{dependency}+ )
system-list := ( @var{simple-component-name}* )
@defrule{system-list} ( @refrule{simple-component-name}* )
component-list := ( @var{component-def}* )
@defrule{component-list} ( @refrule{component-def}* )
component-def := ( component-type simple-component-name @var{option}* )
@defrule{component-def} ( @refrule{component-type} @refrule{simple-component-name} @refrule{option}* )
component-type := :module | :file | :static-file | other-component-type
@defrule{component-type} :module | :file | :static-file | @refrule{other-component-type}
other-component-type := symbol-by-name
# @pxref{Component types}
@defrule{other-component-type} symbol-by-name # @pxref{Component types}
# This is used in :depends-on, as opposed to ``dependency,''
# which is used in :in-order-to
dependency-def := simple-component-name
| ( :feature @var{feature-expression} dependency-def )
# @pxref{Feature dependencies}
| ( :version simple-component-name version-specifier )
| ( :require module-name )
# ``dependency'' is used in :in-order-to, as opposed to
# ``dependency-def''
dependency := (dependent-op @var{requirement}+)
requirement := (required-op @var{required-component}+)
dependent-op := operation-name
required-op := operation-name
simple-component-name := string
| symbol
# This is used in :depends-on, as opposed to "dependency", which is used
# in :in-order-to
@defrule{dependency-def} @refrule{simple-component-name}
| ( :feature @refrule{feature-expression} @refrule{dependency-def} ) # @pxref{Feature dependencies}
| ( :version @refrule{simple-component-name} @refrule{version-specifier} )
| ( :require @var{module-name} )
pathname-specifier := pathname | string | symbol
NOTE: pathnames should be all lower case, and have no
underscores, although hyphens are permitted.
# "dependency" is used in :in-order-to, as opposed to "dependency-def"
@defrule{dependency} ( @refrule{dependent-op} @refrule{requirement}+ )
@defrule{requirement} ( @refrule{required-op} @var{required-component}+ )
@defrule{dependent-op} @refrule{operation-name}
@defrule{required-op} @refrule{operation-name}
# NOTE: pathnames should be all lower case, and have no underscores,
# although hyphens are permitted.
@defrule{pathname-specifier} @var{pathname} | @var{string} | @var{symbol}
@defrule{version-specifier} @var{string}
| ( :read-file-form @refrule{pathname-specifier} @refrule{form-specifier}? )
| ( :read-file-line @refrule{pathname-specifier} @refrule{line-specifier}? )
@defrule{line-specifier} :at @var{integer} # base zero
@defrule{form-specifier} :at [ @var{integer} | ( @var{integer}+ ) ]
version-specifier := string
| (:read-file-form <pathname-specifier> <form-specifier>?)
| (:read-file-line <pathname-specifier> <line-specifier>?)
line-specifier := :at integer # base zero
form-specifier := :at [ integer | ( integer+ )]
@defrule{method-form} ( @refrule{operation-name} @refrule{qual} @var{lambda-list} @Arest{} @var{body} )
@defrule{qual} @refrule{method-qualifier}?
@defrule{method-qualifier} :before | :after | :around
method-form := (operation-name qual lambda-list @Arest{} body)
qual := method-qualifier?
method-qualifier = :before | :after | :around
@defrule{feature-expression} @var{keyword}
| ( :and @refrule{feature-expression}* )
| ( :or @refrule{feature-expression}* )
| ( :not @refrule{feature-expression} )
feature-expression := keyword
| (:and @var{feature-expression}*)
| (:or @var{feature-expression}*)
| (:not @var{feature-expression})
@defrule{operation-name} @var{symbol}
@end example
@subsection System designators
......@@ -1522,6 +1537,7 @@ System designators are either simple component names, or
complex (``slashy'') component names.
@subsection Simple component names (@code{simple-component-name})
@anchor{Simple component names}
Simple component names may be written as either strings or symbols.
......@@ -1546,6 +1562,7 @@ problems will @emph{definitely} occur for users who have configured ASDF
using logical pathnames.
@subsection Complex component names
@anchor{Complex component names}
A complex component name is a master name followed by a slash, followed
by a subsidiary name. This allows programmers to put multiple system
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment