From 3d35ac1e4ec8c1f505bc78874baf12b5b0a80451 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sat, 12 Apr 2008 14:42:02 +0000
Subject: [PATCH] hierlist docs; fix latex/pdf output when a paragraph starts
 with n hspace

svn: r9276

original commit: 02fbaca2b7c8fdafe5b88b24dae2f4d46020eb36
---
 collects/scribble/latex-render.ss         |  5 +++--
 collects/scribble/manual.ss               | 26 +++++++++++++++--------
 collects/scribblings/scribble/style.scrbl | 22 +++++++++++++------
 3 files changed, 36 insertions(+), 17 deletions(-)

diff --git a/collects/scribble/latex-render.ss b/collects/scribble/latex-render.ss
index 43f851f4..8f0a31a0 100644
--- a/collects/scribble/latex-render.ss
+++ b/collects/scribble/latex-render.ss
@@ -146,8 +146,8 @@
                               (case (string-length s)
                                 [(0) (void)]
                                 [else
-                                 (printf "{~a}"
-                                         (regexp-replace* #rx"." s "\\\\hphantom{\\\\mytexttt{x}}"))]))]
+                                 (printf "\\mbox{\\hphantom{\\mytexttt{~a}}}"
+                                         (regexp-replace* #rx"." s "x"))]))]
                   [(newline) (printf "\\\\")]
                   [else (error 'latex-render "unrecognzied style symbol: ~s" style)])]
                [(string? style)
@@ -371,6 +371,7 @@
                   [(#\u03BB) (display "$\\lambda$")]
                   [(#\u039B) (display "$\\Lambda$")]
                   [(#\u03BC) (display "$\\mu$")]
+                  [(#\u03C0) (display "$\\pi$")]
                   [else (display c)]))
               (loop (add1 i))))))
 
diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
index 9e2a4c71..b5e16f2c 100644
--- a/collects/scribble/manual.ss
+++ b/collects/scribble/manual.ss
@@ -1929,7 +1929,7 @@
                                                         (list (make-element 'superscript
                                                                             (loop (caddr m))))
                                                         (loop (cadddr m))))]
-                                          [(regexp-match #px"^(.*)([()0-9{}\\[\\]])(.*)$" i)
+                                          [(regexp-match #px"^(.*)([()0-9{}\\[\\]\u03C0])(.*)$" i)
                                            => (lambda (m)
                                                 (append (loop (cadr m))
                                                         (list (caddr m))
@@ -2056,7 +2056,7 @@
 
   (define-struct decl (name super app-mixins intfs ranges mk-head body))
   (define-struct constructor (def))
-  (define-struct meth (name mode desc def))
+  (define-struct meth (names mode desc def))
   (define-struct spec (def))
   (define-struct impl (def))
 
@@ -2106,8 +2106,10 @@
                                     (cons super accum)))]))))]
            [ht (let ([ht (make-hasheq)])
                  (for-each (lambda (i)
-                             (when (meth? i) 
-                               (hash-set! ht (meth-name i) #t)))
+                             (cond
+                              [(meth? i)
+                               (for-each (lambda (name) (hash-set! ht name #t))
+                                         (meth-names i))]))
                            (decl-body decl))
                  ht)]
            [inh (apply
@@ -2164,10 +2166,16 @@
                                                              (decl-super decl)))
                                (id-info (decl-super decl)))
                           (map id-info (decl-intfs decl))
-                          (map (lambda (m)
-                                 (meth-name m))
-                               (filter meth? (decl-body decl)))))))))))
-
+                          (apply
+                           append
+                           (map (lambda (m) 
+                                  (let loop ([l (meth-names m)])
+                                    (cond
+                                     [(null? l) null]
+                                     [(memq (car l) (cdr l)) (loop (cdr l))]
+                                     [else (cons (car l) (loop (cdr l)))])))
+                                (filter meth? (decl-body decl))))))))))))
+    
   (define (build-body decl body)
     (append
      (map (lambda (i)
@@ -2445,7 +2453,7 @@
                                              (*xmethod/super (quote-syntax/loc cname) 'name1) "."))]
                                       [else
                                        null])])
-           #'(make-meth 'name1
+           #'(make-meth '(name ...)
                         'mode
                         (lambda () (make-splice (apply
                                                  append
diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl
index e9bd51de..4c25b138 100644
--- a/collects/scribblings/scribble/style.scrbl
+++ b/collects/scribblings/scribble/style.scrbl
@@ -10,13 +10,10 @@
 
 In the descriptive body of @scheme[defform], @scheme[defproc], etc.,
 do not start with ``This ...'' Instead, start with a sentence whose
-implicit subject is the form or value being described. Capitalize the first
-word. Thus, the
-description will often start with ``Produces.'' Refer to arguments and
-sub-forms by name.
+implicit subject is the form or value being described. Capitalize the
+first word. Thus, the description will often start with ``Returns'' or
+``Produces.''  Refer to arguments and sub-forms by name.
 
-@; [Eli] It's probably a good idea to say here that it's better to
-@;   refer to "functions" instead of "procedures".
 Do not use the word ``argument'' to describe a sub-form in a syntactic
 form; use the term ``sub-form'' instead, reserving ``argument'' for
 values or expressions in a function call.  Refer to libraries and
@@ -25,6 +22,7 @@ typeset a library or language name is called @scheme[schememodname]).
 Do not call an identifier (i.e., a syntactic element) a ``variable''
 or a ``symbol.'' Do not use the word ``expression'' for a form that is
 a definition or might be a definition; use the word ``form,'' instead.
+Prefer ``function'' to ``procedure.''
 
 Avoid cut-and-paste for descriptive text. If two functions are
 similar, consider documenting them together with
@@ -117,3 +115,15 @@ noun; use it as an annotation.
 Do not start a sentence with a Scheme variable name, since it is
 normally lowercase. For example, use ``The @scheme[_thing] argument
 is...'' instead of ``@scheme[_thing] is...''
+
+@section{Section Titles}
+
+Capitalize all words except articles (``the,'' ``a,'' etc.),
+prepositions, and conjunctions that are not at the start of the title.
+
+A manual title should normally start with a suitable keyword or key
+phrase (such as ``Scribble'' for this manual) that is in boldface. If
+the key word is primarily an executable name, use @scheme[exec]
+instead of @scheme[bold]. Optionally add further descriptive text in
+the title after a colon, where the text starting with the colon is not
+in boldface.