fix `secref' docs; document some Latex macros available for redefinition

original commit: ef4ea236464dd300afadde0134813f23aa0afaf7

collects/scribblings/scribble/base.scrbl

@@ -433,9 +433,7 @@ Generates a literal hyperlinked URL.}
                  [#:underline? underline? any/c #t])
          element?]{
 
-Inserts the hyperlinked title of the section tagged @racket[tag], but
-elements in the title content with the @racket['aux] @tech{style property}
-are omitted in the hyperlink label.
+Inserts a reference to the section tagged @racket[tag].
 
 If @racket[#:doc module-path] is provided, the @racket[tag] refers to
 a tag with a prefix determined by @racket[module-path]. When
@@ -453,8 +451,18 @@ reach the @racket[tag] section. When @racket[#:doc] is not provided,
 the @racket[prefixes] path is relative to any enclosing section (i.e.,
 the youngest ancestor that produces a match).
 
-If @racket[underline?] is @racket[#f], then the hyperlink is rendered
-in HTML without an underline.}
+For HTML output, the generated reference is the hyperlinked title of
+the elements in the section's title content, except that elements with
+the @racket['aux] @tech{style property} are omitted in the hyperlink
+label. If @racket[underline?] is @racket[#f], then the hyperlink is
+rendered in HTML without an underline.
+
+For Latex output, the generated reference's format depends on the
+document style. By default, only the section number is shown in the
+reference, but the @racketmodname[scribble/manual] style shows the
+title after the section number. Customize the output (see
+@secref["config"]) by redefining the @ltx{BookRef}, @|etc|, macros (see
+@secref["builtin-latex"]).}
 
 
 @defproc[(Secref [tag string?]

collects/scribblings/scribble/config.scrbl

@@ -57,7 +57,7 @@ a @racket['multicommand] @tech{style property} for a @racket[nested-flow],
 then the style name is used as a command with multiple arguments.
 In addition, for an itemization, the style
 string is suffixed with @racket["Item"] and used as a CSS class or Latex
-macro name to use for the itemization's items (in place of @tt{item}
+macro name to use for the itemization's items (in place of @ltx{item}
 in the case of Latex).
 
 To add a mapping from your own style name to a CSS configuration, add
@@ -148,7 +148,7 @@ Two kinds of files implement the two kinds of configuration:
 @itemize[
 
  @item{A @deftech{prefix file} determines the @tt{DOCTYPE} line for
-       HTML output or the @tt{documentclass} configuration (and
+       HTML output or the @ltx{documentclass} configuration (and
        perhaps some addition package uses or other configurations) for
        Latex output.
 
@@ -215,3 +215,55 @@ languages like @racketmodname[scribble/manual] and
 @racket[latex-defaults] @tech{style property} to a main-document part only if
 it does not already have such a property added through the
 @racket[#:style] argument of @racket[title].
+
+@; ------------------------------------------------------------
+
+@section[#:tag "builtin-latex"]{Predefined Latex Macros}
+
+The @filepath{scribble.tex} Latex configuration includes several
+macros and environments that you can redefine to adjust the output
+style:
+
+@itemlist[
+
+ @item{@ltxd[0]{preDoc} --- called before the document content; the 
+       default does nothing, while the @racketmodname[scribble/manual]
+       configuration enabled @ltx{sloppy}.}
+
+ @item{@ltxd[0]{postDoc} --- called after the document content; the 
+       default does nothing.}
+
+ @item{@ltxd[0]{sectionNewpage} --- called before each top-level
+       section starts; the default does nothing, while the
+       @racketmodname[scribble/manual] configuration uses
+       @ltx{newpage} to start each chapter on a new page.}
+
+ @item{@ltxd[2]{SecRef} --- the first argument is a section number,
+       and the second argument is a section title. This macro is used
+       by @racket[secref] to reference a section (other than a
+       document or top-level section within a document), and the
+       default shows ``section'' followed by the section number
+       (ignoring the title). The @racketmodname[scribble/manual]
+       redefinition of this macro shows ``§'', the section number, and
+       the title in quotes.}
+
+ @item{@ltxd[2]{ChapRef} --- like @ltx{SecRef}, but for a top-level
+       section with a document. The default implementation defers to
+       @ltx{SecRef}.}
+
+ @item{@ltxd[2]{BookRef} --- like @ltx{SecRef}, but for a document (as
+       opposed to a section within the document). The default
+       implementation shows the title in italic.}
+
+ @item{@ltxd[2]{SecRefUC} --- like @ltx{SecRef}, but for @racket[Secref].
+       The default shows ``Section'' followed by the section number.}
+
+ @item{@ltxd[2]{ChapRefUC} --- like @ltx{SecRefUC}, but for a top-level
+       section with a document. The default implementation defers to
+       @ltx{SecRefUC}.}
+
+ @item{@ltxd[2]{SecRefUC} --- like @ltx{BookRef}, but for @racket[Secref].
+       The default shows defers to @ltx{BookRef}.}
+
+]
+

collects/scribblings/scribble/core.scrbl

@@ -485,11 +485,11 @@ line-wrapped, unless a vertical alignment is specified for the cell
 through a @racket[table-cells] or @racket[table-columns]
 @tech{style property}. To get a line-wrapped paragraph, use a
 @racket[compound-paragraph] or use an element with a string style and
-define a corresponding Latex macro in terms of @tt{parbox}. For Latex
+define a corresponding Latex macro in terms of @ltx{parbox}. For Latex
 output of blocks in the flow that are @racket[nested-flow]s,
 @racket[itemization]s, @racket[compound-paragraph]s, or
-@racket[delayed-block]s, the block is wrapped with @tt{minipage} using
-@tt{linewidth} divided by the column count as the width.}
+@racket[delayed-block]s, the block is wrapped with @ltxe{minipage} using
+@ltx{linewidth} divided by the column count as the width.}
 
 
 @defstruct[itemization ([style style?]
@@ -580,7 +580,7 @@ A @techlink{compound paragraph} has a @tech{style} and a list of
 For HTML, a @racket[paragraph] block in @racket[blocks] is rendered
 without a @tt{<p>} tag, unless the paragraph has a style with a
 non-@racket[#f] @tech{style name}. For Latex, each @tech{block} in
-@racket[blocks] is rendered with a preceding @tt{\noindent}, unless
+@racket[blocks] is rendered with a preceding @ltx{noindent}, unless
 the block has the @racket['never-indents] property (checking
 recursively in a @racket[nested-flow] or @racket[compound-paragraph]
 if the @racket[nested-flow] or @racket[compound-paragraph] itself has

collects/scribblings/scribble/utils.rkt

@@ -220,3 +220,10 @@
                   #,(if hidden? #'""
                         #'(textsample line in-text out-text more))))))]
       [_ (raise-syntax-error #f "no separator found in example text")])))
+
+(provide ltx ltxe ltxd)
+(define (ltx s) (tt "\\" s)) ; command
+(define (ltxe s) (tt s)) ; enviornment
+(define (ltxd n s)
+  (make-element #f (cons (index (list s) (ltx s))
+                         (for/list ([i (in-range n)]) (tt "{}")))))