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

@@ -13,6 +13,7 @@
 @interaction-eval[#:eval xml-eval (require xml)]
 @interaction-eval[#:eval xml-eval (require racket/list)]
 @interaction-eval[#:eval plist-eval (require xml/plist)]
+@(define reference '(lib "scribblings/reference/reference.scrbl"))
 
 @title{XML: Parsing and Writing}
 
@@ -38,7 +39,13 @@ It does not interpret namespaces either.
                      [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,30 +60,83 @@ 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, immediate instances of @racket[external-dtd]
+represent 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 type)
+   (write-xml (document (prolog '() type '())
+                        (element #f #f (document-type-name type) '() '())
+                        '())))
+ (show-doctype (document-type 'html (external-dtd "ignored") #f))
+ (show-doctype (document-type 'svg
+                              (external-dtd/public "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"
+                                                   "-//W3C//DTD SVG 1.1//EN")
+                              #f))
+ (show-doctype (document-type 'greeting (external-dtd/system "hello.dtd") #f))
+]
+
+@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?)]
@@ -86,21 +146,36 @@ Represents a processing instruction.}
                    [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)].
@@ -115,20 +190,65 @@ Represents an attribute within an element.}
 
 @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, this library 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 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
 @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].}
+]}
 
 @defstruct[(exn:invalid-xexpr exn:fail) ([code any/c])]{