[no subject]

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
>