From 9f5fe0859d8eca5c7ddb4d126c09744b6921c5c0 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 21 Aug 2017 08:41:09 -0600
Subject: [PATCH] change base handling of convertible values as content

If a value is convertible to 'text, then use that conversion.

Otherwise, convert using `write` instead of always using "???".

Also, correct documentation to include convertible values among
the valid forms of content, and document the new conversion rules
there.
---
 scribble-doc/scribblings/scribble/core.scrbl  | 14 ++++++++++++-
 scribble-lib/info.rkt                         |  2 +-
 scribble-lib/scribble/base-render.rkt         |  6 +++++-
 .../tests/scribble/docs/convertible.scrbl     | 21 +++++++++++++++++++
 .../tests/scribble/docs/convertible.txt       |  3 +++
 5 files changed, 43 insertions(+), 3 deletions(-)
 create mode 100644 scribble-test/tests/scribble/docs/convertible.scrbl
 create mode 100644 scribble-test/tests/scribble/docs/convertible.txt

diff --git a/scribble-doc/scribblings/scribble/core.scrbl b/scribble-doc/scribblings/scribble/core.scrbl
index bb89ae1a..7ddaa54f 100644
--- a/scribble-doc/scribblings/scribble/core.scrbl
+++ b/scribble-doc/scribblings/scribble/core.scrbl
@@ -119,7 +119,8 @@ A @deftech{block} is either a @techlink{table}, an
              @itemize[
 
              @item{A @deftech{content} can be a string, one of a few
-                   symbols, an instance of @racket[element] (possibly
+                   symbols, a convertible value in the sense of @racket[convertible?],
+                   an instance of @racket[element] (possibly
                    @racket[link-element], etc.), a @racket[multiarg-element], a
                    @techlink{traverse element}, a @techlink{part-relative element}, a
                    @techlink{delayed element}, or a list of content.
@@ -144,6 +145,13 @@ A @deftech{block} is either a @techlink{table}, an
                          rendered as the corresponding HTML entity
                          (even for Latex output).}
 
+                   @item{A convertible value in the sense of @racket[convertible?]
+                         is used in a renderer-specific way, but values convertible
+                         to @racket['text] renders the same as the resulting
+                         string. If a renderer is not able to convert the value
+                         to a known format, the value is converted to a string
+                         using @racket[write].}
+
                    @item{An instance of @racket[element] has a
                          @techlink{content} plus a @tech{style}. The style's
                          interpretation depends on the renderer, but it
@@ -230,6 +238,10 @@ A @deftech{block} is either a @techlink{table}, an
 
 ]
 
+@history[#:changed "1.23" @elem{Changed the handling of @racket[convertible?]
+                                values to recognize a @racket['text] conversion
+                                and otherwise use @racket[write].}]
+
 @; ------------------------------------------------------------------------
 
 @section[#:tag "tags"]{Tags}
diff --git a/scribble-lib/info.rkt b/scribble-lib/info.rkt
index 308acee3..f3ea6c15 100644
--- a/scribble-lib/info.rkt
+++ b/scribble-lib/info.rkt
@@ -23,4 +23,4 @@
 
 (define pkg-authors '(mflatt eli))
 
-(define version "1.22")
+(define version "1.23")
diff --git a/scribble-lib/scribble/base-render.rkt b/scribble-lib/scribble/base-render.rkt
index 1eded97b..37726f29 100644
--- a/scribble-lib/scribble/base-render.rkt
+++ b/scribble-lib/scribble/base-render.rkt
@@ -973,7 +973,11 @@
          (render-content (traverse-element-content i ri) part ri)]
         [(part-relative-element? i)
          (render-content (part-relative-element-content i ri) part ri)]
-        [(convertible? i) (list "???")]
+        [(convertible? i)
+         (define s (convert i 'text))
+         (if (string? s)
+             (render-other s part ri)
+             (render-other (format "~s" i) part ri))]
         [else (render-other i part ri)]))
 
     (define/public (render-other i part ri)
diff --git a/scribble-test/tests/scribble/docs/convertible.scrbl b/scribble-test/tests/scribble/docs/convertible.scrbl
new file mode 100644
index 00000000..b99de3a9
--- /dev/null
+++ b/scribble-test/tests/scribble/docs/convertible.scrbl
@@ -0,0 +1,21 @@
+#lang scribble/base
+@(require file/convertible)
+
+@(struct s ()
+   #:property
+   prop:convertible
+   ;; Not actually convertible to anything:
+   (lambda (v req default)
+     default))
+
+@(struct c ()
+   #:property
+   prop:convertible
+   (lambda (v req default)
+     (cond
+       [(eq? req 'text) "hello"]
+       [else default])))
+
+@(s)
+
+@(c)
diff --git a/scribble-test/tests/scribble/docs/convertible.txt b/scribble-test/tests/scribble/docs/convertible.txt
new file mode 100644
index 00000000..f27bd34d
--- /dev/null
+++ b/scribble-test/tests/scribble/docs/convertible.txt
@@ -0,0 +1,3 @@
+#<s>
+
+hello