Thanks for the clarification. Even with the way you have done it,
I prefer the bookmark approach of using just the [crossref] as
the clickable link rather than having the lengthier phrase
"name of spec [crossref]" as clickable, which seems more cumbersome.
When using the other approach, I think a short name for the spec
should appear in plain text, followed by the clickable [crossref] tag.
For example, this would result in text like "... as stated in
WSDL 1.1 [WSDL] ..." and not "... as stated in [WSDL] ..."
There's no right or wrong way, but the SCA specs should be consistent.
Simon
Simon Holdsworth wrote:
>
> Ah, I think you misunderstand. The hyperlinks I was referring to within
> the document body refer to the location in the document where the
> reference is defined, not directly to external locations, so essentially
> the same as a cross reference. The problem with cross reference is that
> the text that links to the reference section can only be the bookmark
> name. With a hyperlink you can have one link that is "SCA Assembly
> Specification [SCA-Assembly]". With cross reference you can make the
> "[SCA-Assembly]" clickable, but not the "SCA Assembly Specification", I
> believe.
>
> Regards, Simon
>
> Simon Holdsworth
> STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair
> MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
> Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
> Internet -
>
>
> *Simon Nash <>*
>
> 25/06/2009 08:43
>
>
> To
> Simon Holdsworth/UK/IBM@IBMGB
> cc
> OASIS Bindings <>
> Subject
> Re: [sca-bindings] Cross reference vs. hyperlinks
>
>
>
>
>
>
>
>
> Simon,
> In the Java specs, external references are represented by an internal
> cross-reference to the relevant item in section 1.2, which contains a
> full list of related documents with external hyperlinks.
>
> I think this approach works well and is better than having external
> hyperlinks scattered through the document.
>
> Simon
>
> Simon Holdsworth wrote:
> >
> > Folks,
> >
> > In making final edits to the JMS binding spec, I see that there is some
> > inconsistency in the way that links to external references are handled.
> >
> > In some cases, the link is a cross-reference, using the reference text
> > (e.g. [JMS])
> >
> > In others, the link is a hyperlink, using the reference text, but
> > without the square brackets (e.g. [_RFC2119_] )
> >
> > In others, the link is a hyperlink, using the reference text including
> > square brackets.
> >
> > The difference between cross-references and hyperlinks is that the
> > hyperlinks appear with a different style in the Word document, and can
> > have any text associated with them, cross-references do not appear with
> > a different style, and the text is limited to something derived from the
> > target of the cross-reference.
> >
> > In the version of the document I'm uploading, I'm updating all external
> > references to be hyperlinks, where the text of the hyperlink is the
> > textual reference plus the tag in square brackets; another item to add
> > to the list for editorial consistency.
> >
> > Regards, Simon
> >
> > Simon Holdsworth
> > STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC
> Chair
> > MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
> > Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
> > Internet -
> >
> >
> > ------------------------------------------------------------------------
> >
> > /
> > /
> >
> > /Unless stated otherwise above:
> > IBM United Kingdom Limited - Registered in England and Wales with number
> > 741598.
> > Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire
> PO6 3AU/
> >
> >
> >
> >
> >
> >
>
>
>
>
>
>
> ------------------------------------------------------------------------
>
> /
> /
>
> /Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with number
> 741598.
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU/
>
>
>
>
>
>
