Re: [sca-bindings] Cross reference vs. hyperlinks

[Simon Nash <oasis@cjnash.com>]

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_Holdsworth@uk.ibm.com
> 
> 
> *Simon Nash <oasis@cjnash.com>*
> 
> 25/06/2009 08:43
> 
> 	
> To
> 	Simon Holdsworth/UK/IBM@IBMGB
> cc
> 	OASIS Bindings <sca-bindings@lists.oasis-open.org>
> 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 - Simon_Holdsworth@uk.ibm.com
>  >
>  >
>  > ------------------------------------------------------------------------
>  >
>  > /
>  > /
>  >
>  > /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/
> 
> 
> 
> 
> 
>