[racket] scribble secref does not render consistently between HTML and PDF

I'm inclined to call this a documentation bug, both because the docs
for `secref' are partly specific to HTML and because there's no
documentation of the Latex commands to redefine to control the
generated section reference.

For Latex/PDF output, the section title is currently only included for
the `scribble/manual' configuration, and not for the `scribble/base',
`scribble/sigplan', etc., configurations.

To change the output style, \renewcommand the following two-argument
Latex macros as needed. Each takes a section number (which is empty in
the case of "book") and a section name:

 \BookRef --- for a whole-document reference;
              uses \emph on title by default
 \ChapRef --- for a top-level section; 
              uses \SecRef by default
 \SecRef --- for a nested section;
             uses "section" and section number by default

 \BookRefUC --- `@Secref' variant of \BookRef;
                uses \BookRef by default
 \ChapRefUC --- `@Secref' variant of \ChapRef;
                uses \SecRefUC by default
 \SecRefUC  --- `@Secref' variant of \ShapRef;
                uses "Section" and section number by default


At Mon, 4 Apr 2011 11:05:54 +0100, Tim Brown wrote:
> I'm writing some general documentation with scribble and have, so far,
> been generating HTML output.
> 
> I'm now moving to PDF/Latex output, and the @secref calls are not being
> rendered consistently between my output formats. In --html, --htmls and
> --text rendering modes, secref renders the title of the section. But with
> --latex and --pdf, the link destination is rendered as the section number
> "section n.n" (this string is not hyperlinked, either -- something I can
> half tolerate, since it's going to printed media).
> 
> Scribble's secref documentation states:
> 
> > Inserts the hyperlinked title of the section tagged tag, but elements in
>              ^^^^^^^^^^^^^^^^^
> > the title content with the 'aux style property are omitted in the
> > hyperlink label.
> 
> My latex is:
> -----------------------------------------------------------------------
> $ pdflatex tim.tex
> This is pdfTeX, Version 3.1415926-1.40.11 (TeX Live 2010)
> restricted \write18 enabled.
> entering extended mode
> -----------------------------------------------------------------------
> 
> Is this a problem with scribble/latex/their interaction or my reading of
> the documentation?
> 
> Help much appreciated. Thanks,
> 
> Tim
> 
> 
> 
> Scribble source:
> -----------------------------------------------------------------------
> #lang scribble/base
> @section[#:tag "s-1"]{First Section}
> @section[#:tag "s-2"]{Second Section}
> Check out @secref{s-1} for more info!
> @(version)
> -----------------------------------------------------------------------
> 
> 
> Text output:
> -----------------------------------------------------------------------
> 
> 
> 
> 1. First Section
> 
> 
> 
> 2. Second Section
> 
> Check out First Section for more info!
> 
> 5.1
> 
> -----------------------------------------------------------------------
> 
> HTML output (snippet):
> -----------------------------------------------------------------------
> <div class="main">
> <h3>1<tt>&nbsp;</tt><a name="(part._s-1)"></a>First Section</h3>
> <h3>2<tt>&nbsp;</tt><a name="(part._s-2)"></a>Second Section</h3>
> <p>Check out <a href="#(part._s-1)" pltdoc="x">First Section</a>
> for more info!</p><p>5.1</p></div></div>
> <div id="contextindicator">&nbsp;</div>
> -----------------------------------------------------------------------
> 
> .tex output (from --latex):
> -----------------------------------------------------------------------
> 
> %   ...
> % Generated by `secref'; first arg is section number, second is section title:
> \newcommand{\BookRef}[2]{\emph{#2}}
> \newcommand{\ChapRef}[2]{\SecRef{#1}{#2}}
> \newcommand{\SecRef}[2]{section~#1}
> % Generated by `Secref':
> \newcommand{\BookRefUC}[2]{\BookRef{#1}{#2}}
> \newcommand{\ChapRefUC}[2]{\SecRefUC{#1}{#2}}
> \newcommand{\SecRefUC}[2]{Section~#1}
> %   ...
> %%% [snip]
> %   ...
> \section[First Section]{First Section}\label{t:x28part_x22sx2d1x22x29}
> 
> 
> 
> \sectionNewpage
> 
> \section[Second Section]{Second Section}\label{t:x28part_x22sx2d2x22x29}
> 
> Check out \ChapRef{1}{First Section} for more info!
> 
> 5.1
> -----------------------------------------------------------------------
> 
> BUT:.pdf output (cut and paste from acroread):
> -----------------------------------------------------------------------
> 1 First Section
> 2 Second Section
> Check out section 1 for more info!
> 5.1
> -----------------------------------------------------------------------
> 
> 
> --
> Tim Brown <tim.brown at cityc.co.uk>  | City Computing Limited            |
> T: +44 20 8770 2110                | City House, Sutton Park Road      |
> F: +44 20 8770 2130                | Sutton, Surrey, SM1 2AE, GB       |
> -----------------------------------------------------------------------|
> BEAUTY:  What's in your eye when you have a bee in your hand           |
> -----------------------------------------------------------------------'
> City Computing Limited registered in London No. 1767817.
> Registered Office: City House, Sutton Park Road, Sutton, Surrey, SM1 2AE
> VAT number 372 8290 34.
> 
> _________________________________________________
>   For list-related administrative tasks:
>   http://lists.racket-lang.org/listinfo/users