diff --git a/pkgs/racket-doc/scribblings/reference/exns.scrbl b/pkgs/racket-doc/scribblings/reference/exns.scrbl index e7f822ac73..124f71732c 100644 --- a/pkgs/racket-doc/scribblings/reference/exns.scrbl +++ b/pkgs/racket-doc/scribblings/reference/exns.scrbl @@ -981,6 +981,18 @@ Returns the @racket[srcloc]-getting procedure associated with @racket[v].} [span (or/c exact-nonnegative-integer? #f)]) #:inspector #f]{ +A @deftech{source location} is most frequently represented by a +@racket[srcloc] structure. More generally, a source location has the +same information as a @racket[srcloc] structure, but potentially +represented or accessed differently. For example, source-location +information is accessed from a @tech{syntax object} with functions +like @racket[syntax-source] and @racket[syntax-line], while +@racket[datum->syntax] accepts a source location as a list, vector, or +another syntax object. For ports, a combination of +@racket[object-name] and @racket[port-next-location] provides location +information, especially in a port for which counting has been enabled +through @racket[port-count-lines!]. + The fields of a @racket[srcloc] instance are as follows: @itemize[ diff --git a/pkgs/racket-doc/scribblings/reference/stx-ops.scrbl b/pkgs/racket-doc/scribblings/reference/stx-ops.scrbl index 8a1aac6878..083e1d98ef 100644 --- a/pkgs/racket-doc/scribblings/reference/stx-ops.scrbl +++ b/pkgs/racket-doc/scribblings/reference/stx-ops.scrbl @@ -35,7 +35,8 @@ Returns @racket[#t] if @racket[v] is a @tech{syntax object} and @defproc[(syntax-source [stx syntax?]) any/c]{ -Returns the source for the @tech{syntax object} @racket[stx], or @racket[#f] +Returns the source component of the @tech{source location} +for the @tech{syntax object} @racket[stx], or @racket[#f] if none is known. The source is represented by an arbitrary value (e.g., one passed to @racket[read-syntax]), but it is typically a file path string.} @@ -44,7 +45,8 @@ path string.} @defproc[(syntax-line [stx syntax?]) (or/c exact-positive-integer? #f)]{ -Returns the line number (positive exact integer) for the start of the +Returns the line number (positive exact integer) +of the @tech{source location} for the start of the @tech{syntax object} in its source, or @racket[#f] if the line number or source is unknown. The result is @racket[#f] if and only if @racket[(syntax-column stx)] produces @racket[#f]. See also @@ -54,7 +56,8 @@ source is unknown. The result is @racket[#f] if and only if @defproc[(syntax-column [stx syntax?]) (or/c exact-nonnegative-integer? #f)]{ -Returns the column number (non-negative exact integer) for the start +Returns the column number (non-negative exact integer) +of the @tech{source location} for the start of the @tech{syntax object} in its source, or @racket[#f] if the source column is unknown. The result is @racket[#f] if and only if @racket[(syntax-line stx)] produces @racket[#f]. See also @@ -64,7 +67,8 @@ column is unknown. The result is @racket[#f] if and only if @defproc[(syntax-position [stx syntax?]) (or/c exact-positive-integer? #f)]{ -Returns the character position (positive exact integer) for the start +Returns the character position (positive exact integer) +of the @tech{source location} for the start of the @tech{syntax object} in its source, or @racket[#f] if the source position is unknown. See also @secref["linecol"].} @@ -72,7 +76,8 @@ position is unknown. See also @secref["linecol"].} @defproc[(syntax-span [stx syntax?]) (or/c exact-nonnegative-integer? #f)]{ -Returns the span (non-negative exact integer) in characters of the +Returns the span (non-negative exact integer) in characters +of the @tech{source location} for @tech{syntax object} in its source, or @racket[#f] if the span is unknown.} diff --git a/pkgs/racket-doc/scribblings/reference/syntax-model.scrbl b/pkgs/racket-doc/scribblings/reference/syntax-model.scrbl index c753fa23a8..f5de4eb6cf 100644 --- a/pkgs/racket-doc/scribblings/reference/syntax-model.scrbl +++ b/pkgs/racket-doc/scribblings/reference/syntax-model.scrbl @@ -156,7 +156,7 @@ relevant. @section[#:tag "stxobj-model"]{Syntax Objects} A @deftech{syntax object} combines a simpler Racket value, such as a symbol or pair, with -@tech{lexical information}, source-location information, @tech{syntax properties}, and @tech{tamper +@tech{lexical information}, @tech{source-location} information, @tech{syntax properties}, and @tech{tamper status}. The @deftech{lexical information} of a @tech{syntax object} comprises a set of @tech{scope sets}, one for each @tech{phase level}. In particular, an @tech{identifier} is represented as a syntax object containing a @tech{symbol}, and its @tech{lexical information} can be combined with the global