xml: make structs serializable, but enforce contracts

Also, tweak docs and add `no-external-dtd`.

Increment version to 8.17.0.5.

Related to: racket/scribble#498
Related to: racket#5282
Related to: racket/rhombus#644

Author: LiberalArtist

pkgs/base/info.rkt

@@ -14,7 +14,7 @@
 
 ;; In the Racket source repo, this version should change exactly when
 ;; "racket_version.h" changes:
-(define version "8.17.0.4")
+(define version "8.17.0.5")
 
 (define deps `("racket-lib"
                ["racket" #:version ,version]))

pkgs/racket-doc/scribblings/reference/serialization.scrbl

@@ -40,7 +40,7 @@ by deserialization produces a value with the same graph structure and
 mutability as the original value, but the serialized value is a plain
 tree (i.e., no sharing).
 
-The following kinds of values are serializable:
+The following kinds of values are @deftech{serializable}:
 
 @itemize[
 
@@ -575,10 +575,10 @@ transfers the field values of this instance into @racket[x].}
 
 @; ----------------------------------------------------------------------
 
-@defthing[prop:serializable property?]{
+@defthing[prop:serializable struct-type-property?]{
 
 This property identifies structures and structure types that are
-serializable. The property value should be constructed with
+@tech{serializable}. The property value should be constructed with
 @racket[make-serialize-info].}
 
 @; ----------------------------------------------------------------------

pkgs/racket-doc/xml/xml.scrbl

@@ -5,14 +5,17 @@
           (for-label racket/base
                      racket/contract
                      racket/list
+                     racket/port
                      xml
                      xml/plist))
 
 @(define xml-eval (make-base-eval))
 @(define plist-eval (make-base-eval))
 @interaction-eval[#:eval xml-eval (require xml)]
 @interaction-eval[#:eval xml-eval (require racket/list)]
+@interaction-eval[#:eval xml-eval (require racket/port)]
 @interaction-eval[#:eval plist-eval (require xml/plist)]
+@(define reference '(lib "scribblings/reference/reference.scrbl"))
 
 @title{XML: Parsing and Writing}
 
@@ -30,15 +33,25 @@ Declaration (DTD) processing, including preservation of DTDs in read documents,
 It also does not expand user-defined entities or read user-defined entities in attributes.
 It does not interpret namespaces either.
 
+@local-table-of-contents[]
+
 @; ----------------------------------------------------------------------
 
 @section{Datatypes}
 
+@subsection{Structures}
+
 @defstruct[location ([line (or/c #f exact-nonnegative-integer?)]
                      [char (or/c #f exact-nonnegative-integer?)]
                      [offset exact-nonnegative-integer?])]{
 
-Represents a location in an input stream. The offset is a character offset unless @racket[xml-count-bytes] is @racket[#t], in which case it is a byte offset.}
+ Represents a location in an input stream. The offset is a
+ character offset unless @racket[xml-count-bytes] is
+ @racket[#t], in which case it is a byte offset.
+
+ @history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+ ]}
 
 @defthing[location/c contract?]{
  Equivalent to @racket[(or/c location? symbol? #f)].
@@ -53,82 +66,200 @@ Represents a source location. Other structure types extend
 When XML is generated from an input stream by @racket[read-xml],
 locations are represented by @racket[location] instances. When XML
 structures are generated by @racket[xexpr->xml], then locations are
-symbols.}
+symbols.
+
+@margin-note{Immediate instances of @racket[source] are not
+  @tech[#:doc reference]{serializable}. The @racketmodname[xml] library
+  only uses @tech[#:doc reference #:key "structure subtypes"]{subtypes}
+  of @racket[source].}
+}
 
 @deftogether[(
 @defstruct[external-dtd ([system string?])]
 @defstruct[(external-dtd/public external-dtd) ([public string?])]
 @defstruct[(external-dtd/system external-dtd) ()]
+@defthing[no-external-dtd external-dtd? #:value (external-dtd "")]
 )]{
 
-Represents an externally defined DTD.}
+Represents an externally defined DTD.
+
+As a special case, an immediate instance of @racket[external-dtd]
+represents the @emph{absence} of an external DTD, and its @racket[system]
+field is ignored. The @racket[no-external-dtd] value is provided
+for clarity, but any immediate instance of @racket[external-dtd]
+has the same meaning.
+
+@examples[
+ #:eval xml-eval
+ (define (show-doctype name dtd)
+   (write-xml (document (prolog '() (document-type name dtd #f) '())
+                        (element #f #f name '() '())
+                        '())))
+ (show-doctype
+  'svg
+  (external-dtd/public "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"
+                       "-//W3C//DTD SVG 1.1//EN"))
+ (show-doctype 'greeting (external-dtd/system "hello.dtd"))
+ (show-doctype 'html (external-dtd "ignored"))
+ (show-doctype 'html no-external-dtd)
+]
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+ #:changed "8.17.0.5" @elem{Added @racket[no-external-dtd].}
+]}
 
 @defstruct[document-type ([name symbol?]
                           [external external-dtd?]
                           [inlined #f])]{
 
-Represents a document type.}
+Represents a document type. For examples, see @racket[external-dtd].
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defstruct[comment ([text string?])]{
 
-Represents a comment.}
+Represents a comment.
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defstruct[(p-i source) ([target-name symbol?]
                          [instruction string?])]{
 
-Represents a processing instruction.}
+Represents a processing instruction.
+
+@examples[
+ #:eval xml-eval
+ (write-xml (document (prolog (list (p-i #f #f 'xml "version=\"1.0\""))
+                              #f
+                              '())
+                      (element #f #f 'x '() '())
+                      '()))
+]
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defthing[misc/c contract?]{
- Equivalent to @racket[(or/c comment? p-i?)]
+Equivalent to @racket[(or/c comment? p-i?)].
 }
 
 @defstruct[prolog ([misc (listof misc/c)]
                    [dtd (or/c document-type #f)]
                    [misc2 (listof misc/c)])]{
 Represents a document prolog. 
-}
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defstruct[document ([prolog prolog?]
                      [element element?]
                      [misc (listof misc/c)])]{
-Represents a document.}
+Represents a document.
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defstruct[(element source) ([name symbol?]
                              [attributes (listof attribute?)]
                              [content (listof content/c)])]{
-Represents an element.}
+Represents an element.
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defstruct[(attribute source) ([name symbol?] [value (or/c string? permissive/c)])]{
 
-Represents an attribute within an element.}
+Represents an attribute within an element.
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defthing[content/c contract?]{
  Equivalent to @racket[(or/c pcdata? element? entity? comment? cdata? p-i? permissive/c)].
 }
 
 @defthing[permissive/c contract?]{
- If @racket[(permissive-xexprs)] is @racket[#t], then equivalent to @racket[any/c], otherwise equivalent to @racket[(make-none/c 'permissive)]}
+If @racket[(permissive-xexprs)] is @racket[#t], then equivalent to @racket[any/c],
+otherwise equivalent to @racket[(make-none/c 'permissive)]}.
 
 @defproc[(valid-char? [x any/c]) boolean?]{
  Returns true if @racket[x] is an exact-nonnegative-integer whose character interpretation under UTF-8 is from the set ([#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]), in accordance with section 2.2 of the XML 1.1 spec.
 }
 
 @defstruct[(entity source) ([text (or/c symbol? valid-char?)])]{
 
-Represents a symbolic or numerical entity.}
+Represents a symbolic @deftech{entity} reference
+or a numerical @deftech{character reference}.
+
+As a special case, @racket[read-xml] parses references to the @deftech{predefined entities}
+into @racket[pcdata] values, so it does not generate @racket[entity] values containing
+@racket['lt], @racket['gt], @racket['amp], @racket['apos], or @racket['quot].
+Nonetheless, such @racket[entity] values may be created programmatically.
+
+@examples[
+ #:eval xml-eval
+ (for/list ([s '(lt gt amp apos quot)])
+   (with-output-to-string
+     (λ ()
+       (write-xml/content (entity #f #f s)))))
+ (read-xml/element
+  (open-input-string "<x> &lt;&gt;&amp;&apos;&quot; </x>"))
+]
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defstruct[(pcdata source) ([string string?])]{
 
-Represents PCDATA content.}
+Represents textual content, i.e@._ what the
+@link["https://www.w3.org/TR/REC-xml/#dt-chardata"]{XML specification} calls
+@deftech{character data}.
+
+More specifically, this library has several representations for
+@tech{character data} corresponding to different concrete syntaxes in XML.
+The @racket[pcdata] struct represents character data that is neither
+encoded by a @tech{character reference} or user-defined @tech{entity},
+which use @racket[entity], nor written in a @racket[cdata] section.
+References to the @tech{predefined entities} can be represented by either @racket[pcdata]
+or @racket[entity], but this library always uses @racket[pcdata] when parsing.
+
+@margin-note{The @racket[pcdata] struct is a bit of a misnomer.
+In XML, @litchar{PCDATA} is a keyword used to declare that an element contains
+``@link["https://www.w3.org/TR/REC-xml/#sec-mixed-content"]{mixed content},''
+i.e@._ @tech{character data} potentially interspersed with child elements,
+but the @racket[pcdata] struct specifically represents @tech{character data}.
+Historically, the term meant ``parsed character data.''
+}
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
 
 @defstruct[(cdata source) ([string string?])]{
 
-Represents CDATA content.
+Represents a CDATA section.
 
-The @racket[string] field is assumed to be of the form
+The @racket[_string] field is assumed to be of the form
 @litchar{<![CDATA[}@nonterm{content}@litchar{]]>} with proper quoting
 of @nonterm{content}. Otherwise, @racket[write-xml] generates
-incorrect output.}
+ill-formed output.
+
+@history[
+ #:changed "8.17.0.5" @elem{Added support for serialization with @racketmodname[racket/serialize].}
+]}
+
+@subsection{Exceptions}
 
 @defstruct[(exn:invalid-xexpr exn:fail) ([code any/c])]{
 
@@ -140,6 +271,8 @@ of the input to @racket[validate-xexpr].}
  Raised by @racket[read-xml] when an error in the XML input is found.
 }
 
+@subsection{X-expressions}
+
 @defproc[(xexpr? [v any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[v] is a @tech{X-expression}, @racket[#f] otherwise.
@@ -165,11 +298,14 @@ A pair represents an element, optionally with attributes. Each
 attribute's name is represented by a symbol, and its value is
 represented by a string.
 
-A @racket[_symbol] represents a symbolic entity. For example,
-@racket['nbsp] represents @litchar{&nbsp;}.
+A @racket[_symbol] represents a symbolic @tech{entity} reference.
+For example, @racket['nbsp] represents @litchar{&nbsp;}.
+@margin-note{Note that @racket[string->xexpr] and other parsing
+procedures represent references to the @tech{predefined entities}
+as strings instead of symbols.}
 
-A @racket[valid-char?] represents a numeric entity. For example,
-@racketvalfont{#x20} represents @litchar{&#x20;}.
+A @racket[valid-char?] represents a numerical @tech{character reference}.
+For example, @racketvalfont{#x20} represents @litchar{&#x20;}.
 
 A @racket[_cdata] is an instance of the @racket[cdata] structure type,
 and a @racket[_misc] is an instance of the @racket[comment] or
@@ -181,7 +317,7 @@ and a @racket[_misc] is an instance of the @racket[comment] or
 ]}
 
 @defthing[xexpr/c contract?]{
- A contract that is like @racket[xexpr?] except produces a better error
+ A contract that is like @racket[xexpr?], but produces a better error
  message when the value is not an @tech{X-expression}.
 
 @history[
@@ -206,7 +342,7 @@ from @racketmodname[xml] with minimal dependencies.
 @defproc[(read-xml [in input-port? (current-input-port)]) document?]{
 
 Reads in an XML document from the given or current input port. XML
-documents contain exactly one element, raising @racket[xml-read:error]
+documents contain exactly one element, raising @racket[exn:xml]
 if the input stream has zero elements or more than one element.
 
 Malformed xml is reported with source locations in the form
@@ -229,7 +365,9 @@ about creating ports that return non-character values.
 
 @defproc[(read-xml/document [in input-port? (current-input-port)]) document?]{
 
-Like @racket[read-xml], except that the reader stops after the single element, rather than attempting to read "miscellaneous" XML content after the element. The document returned by @racket[read-xml/document] always has an empty @racket[document-misc].}
+Like @racket[read-xml], except that the reader stops after the single element,
+rather than attempting to read ``miscellaneous'' XML content after the element.
+The document returned by @racket[read-xml/document] always has an empty @racket[document-misc].}
 
 @defproc[(read-xml/element [in input-port? (current-input-port)]) element?]{