From a38f6d50f58296622ce16b8f0a10c5ff7867760d Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 4 Apr 2011 11:26:41 -0600 Subject: [PATCH] fix `secref' docs; document some Latex macros available for redefinition original commit: ef4ea236464dd300afadde0134813f23aa0afaf7 --- collects/scribblings/scribble/base.scrbl | 18 +++++-- collects/scribblings/scribble/config.scrbl | 56 +++++++++++++++++++++- collects/scribblings/scribble/core.scrbl | 8 ++-- collects/scribblings/scribble/utils.rkt | 7 +++ 4 files changed, 78 insertions(+), 11 deletions(-) diff --git a/collects/scribblings/scribble/base.scrbl b/collects/scribblings/scribble/base.scrbl index 95a39c1f..3d2f68a7 100644 --- a/collects/scribblings/scribble/base.scrbl +++ b/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?] diff --git a/collects/scribblings/scribble/config.scrbl b/collects/scribblings/scribble/config.scrbl index 190e49ad..9db62869 100644 --- a/collects/scribblings/scribble/config.scrbl +++ b/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}.} + +] + diff --git a/collects/scribblings/scribble/core.scrbl b/collects/scribblings/scribble/core.scrbl index 822f2bd8..2a39f127 100644 --- a/collects/scribblings/scribble/core.scrbl +++ b/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{

} 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 diff --git a/collects/scribblings/scribble/utils.rkt b/collects/scribblings/scribble/utils.rkt index c0c9ac31..fa4459c5 100644 --- a/collects/scribblings/scribble/utils.rkt +++ b/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 "{}")))))