Re: Rendering of xref tag

[Daniel Carrera <dcarrera math toronto edu>]

I agree.  I also like the idea of having of adding "on page xx" for
documents intended for printing.  This strikes me as part of the purpose
of using DocBook and computers - to focus on content and let the computer
do the details depending on the output.

This should also be extended to the table of contents (hyperlinks in HTML,
page numbers in PS).

Daniel.

On Thu, 7 Feb 2002, Mark Levitt wrote:

> > I think that the "the section called " text is redundant and should be
> > removed. What do others think of this?
>
> Absolutely.
>
> >From a matter of principle, if authors aren't supposed to mess about with
> formatting and layout so we can focus on the words, then the formatting and
> layout shouldn't mess about with adding words *.  :)
>
> Beyond the principle of it, good technical writing uses plain, simple
> language. "The section called" adds nothing to the meaning of the sentence.
> You wouldn't ever say to someone, "Meet me at the street called Main" would
> you?
>
> > I also think that the quotation marks around the cross-reference text
> > are unnecessary - the text will be underlined, and a different color to
> > the surrounding text - I think that's enough to make the hyperlink stand
> > out.
>
> As for style, quotes should not be used for cross-reference. The only reason
> why you sometimes see quotes as cross-references is because early
> typewriters couldn't do italics. You also see two spaces after a period for
> the same reason (typewriters can't do kerning of fonts).
>
> For any output format that supports multiple typefaces, a cross reference
> should be in italic text.
>
> For output that supports hyperlinks (HTML, PDF, etc) the section name (in
> italic) should be the only text, as Eugene has it:
>
> >    For more information see To Modify a Panel With the Panel Properties
> > Dialog
>
> However, for output formats that are intended for print (PS, etc) the
> section name (in italics) should be followed by "on page xx." For example:
>
> For more information, see To Modify a Panel With the Panel Properties Dialog
> on page 23.
>
>
>
>
> ----- Original Message -----
> From: "Eugene O'Connor" <eugene oconnor sun com>
> To: <gnome-doc-list gnome org>
> Sent: Thursday, February 07, 2002 4:06 PM
> Subject: Rendering of xref tag
>
>
> > When I convert an XML file to HTML, the text 'the section called ""' is
> > added to every cross-reference (<xref> tags) in the document. So, for
> > example, my cross-references appear like this:
> >
> >    For more information see the section called "To Modify a Panel With
> > the Panel Properties Dialog".
> >
> > I think that the "the section called " text is redundant and should be
> > removed. What do others think of this?
> >
> > This is more of a problem when I create a bulleted list of links, which
> > appear like this:
> >
> >        * the section called "Mouse Skills"
> >        * the section called "Using Shortcut Keys"
> >        * the section called "Using Windows and Dialogs"
> >
> > I considered using the link tag instead, but I want the cross-reference
> > text to be automatically generated, rather than manually entered. This
> > makes more sense as it reduces the work when updating docs, and cuts the
> > risk of error.
> >
> > I also think that the quotation marks around the cross-reference text
> > are unnecessary - the text will be underlined, and a different color to
> > the surrounding text - I think that's enough to make the hyperlink stand
> > out.
> >
> > In summary, I think it would be better if the cross-reference text was
> > like this:
> >
> >    For more information see To Modify a Panel With the Panel Properties
> > Dialog'
> >
> > The title of the referred-to text would be formatted as a normal
> > hyperlink.
> >
> > What do other people think?
> >
> > Eugene
> > _______________________________________________
> > gnome-doc-list mailing list
> > gnome-doc-list gnome org
> > http://mail.gnome.org/mailman/listinfo/gnome-doc-list
> >
>
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> http://mail.gnome.org/mailman/listinfo/gnome-doc-list
>