search

jetty / jetty.project

Eclipse Jetty® - Web Container & Clients - supports HTTP/2, HTTP/1.1, HTTP/1.0, websocket, servlets, and more
https://eclipse.dev/jetty
Other
3.86k stars 1.91k forks source link

Review cross reference syntax #716

Closed sbordet closed 7 years ago

sbordet commented 8 years ago

Currently the documentation uses 3 different ways to cross reference sections:

We should standardize on just one way to do it.

I think the original Asciidoc syntax is <<id,caption>>.

The xref macro I think it only works for HTML output (not PDF) - this needs to be confirmed.

The link syntax is not for cross references, so perhaps we should not use it - although it seems to work for HTML.

In any case a bit of research should be done, also in the Asciidoctor forums, to see what's the best method and then use that.

WalkerWatch commented 8 years ago

@sbordet I wonder if this was a result of the translation of the old documentation to asciidoc. It is definitely something that I wondered about as well and will dive more deeply in to.

@jmcc0nn3ll Was there any specific callout to how links were being handled when you ran the documents through conversion?

sbordet commented 8 years ago

Yep, could just be the translation. Should be easy to verify how they render in PDF and do a bit of research on what is the preferred way, to avoid that AsciiDoctor changes preference later (it happened with monospaced text - I had to find every place I was using monospaced text in the CometD docs).

jmcc0nn3ll commented 8 years ago

Conceptually I am a fan of link: for links to external resources and xref: for links to places internal to the documentation in question. However, I believe that xref: was the only one of the two that provides a mechanism to use the subject of the section you are linking to as link text. So I believe the current way the linking is structured is link: for when you want to control the text of the rendered link and xref: when you want to pull the section title in as the text of the link itself.

WalkerWatch commented 7 years ago

As I look back on this, I am going to remove the <<id,caption>> usages (of which there are few in the documentation). They are valid, but link: seems to be far more common in asciidoctor. As for xref I like their usage as capturing title text, and will verify all our current usages conform to this (which I believe most do).