Asciidoctor :: Discussion

asciidoctor cross reference formatting

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

instinctive

Oct 18, 2019; 9:09pm

asciidoctor cross reference formatting

3 posts

My cross references are surrounded by brackets: <<apple>> => [apple].
How can I get rid of those square brackets? I just want the anchor text!

Thank you!

$ asciidoctor --version
Asciidoctor 1.5.6.1 [http://asciidoctor.org]
Runtime Environment (ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
$ cat apple.adoc
[[apple]]A paragraph about apples.

A paragraph about <<apple>> pie.
$ asciidoctor apple.adoc
$ grep apple apple.html
A paragraph about apples.
A paragraph about [apple] pie.

mojavelinux

Oct 18, 2019; 11:41pm

Re: asciidoctor cross reference formatting

Administrator

2681 posts

You need to specify reftext. Section titles have implied reftext. Other blocks don't.

It would look something like:

[[apple-pie,Apple Pie]]

A paragraph about apple pie.

[#apple-pie,reftext=Apple Pie]

A paragraph about apple pie.

Read about <<apple-pie>>.

Best,

-Dan

On Fri, Oct 18, 2019 at 3:09 PM instinctive [via Asciidoctor :: Discussion] <[hidden email]> wrote:

My cross references are surrounded by brackets: <<apple>> => [apple].
How can I get rid of those square brackets? I just want the anchor text!

Thank you!

$ asciidoctor --version
Asciidoctor 1.5.6.1 [http://asciidoctor.org]
Runtime Environment (ruby 2.6.3p62 (2019-04-16 revision 67580) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
$ cat apple.adoc
[[apple]]A paragraph about apples.

A paragraph about <<apple>> pie.
$ asciidoctor apple.adoc
$ grep apple apple.html
A paragraph about apples.
A paragraph about [apple] pie.

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/asciidoctor-cross-reference-formatting-tp7253.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

instinctive

Oct 19, 2019; 12:31am

Re: asciidoctor cross reference formatting

3 posts

Thanks so much for the reply. Indeed, this fixes the problem, and I'm
grateful that it suffices to specify the reftext at the anchor site and not
in every link reference.

However, I'm confused as to why the default behavior does not use
implied reftext, and why the default is square brackets. This default
behavior is not illuminated anywhere in the asciidoctor user manual
that I can find.

So now I must double every anchor:

[[anchor-foo,anchor-foo]]
[[anchor-bar,anchor-bar]]

Thanks again for the speedy reply, and your work on this great tool.

mojavelinux

Oct 19, 2019; 12:33am

Re: asciidoctor cross reference formatting

Administrator

2681 posts

For a paragraph, what text would you expect to be used? Is the reftext going to take the whole paragraph? The ID in square bracket is an indication that there's no reftext (explicit or implied). So it's kind of a placeholder until you fill it in.

Best,

-Dan

On Fri, Oct 18, 2019 at 6:31 PM instinctive [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks so much for the reply. Indeed, this fixes the problem, and I'm
grateful that it suffices to specify the reftext at the anchor site and not
in every link reference.

However, I'm confused as to why the default behavior does not use
implied reftext, and why the default is square brackets. This default
behavior is not illuminated anywhere in the asciidoctor user manual
that I can find.

So now I must double every anchor:

[[anchor-foo,anchor-foo]]
[[anchor-bar,anchor-bar]]

Thanks again for the speedy reply, and your work on this great tool.

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/asciidoctor-cross-reference-formatting-tp7253p7255.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

instinctive

Oct 19, 2019; 5:47am

Re: asciidoctor cross reference formatting

3 posts

tbh I would just expect the text of the anchor/xref, as given, if there is no reftext.
My use case: I am auto-generating AsciiDoc, where symbols link to the paragraph
in which they are defined. So the anchor text, as given, is exactly what I want,
since it IS the symbol.

mojavelinux

Oct 19, 2019; 7:08am

Re: asciidoctor cross reference formatting

Administrator

2681 posts

Oh, you can accomplish that. The syntax is as follows:

<<apple,apple>>

You also have the option of overriding the built-in converter and customizing the fallback text that way.

Best,

-Dan

On Fri, Oct 18, 2019 at 11:47 PM instinctive [via Asciidoctor :: Discussion] <[hidden email]> wrote:

tbh I would just expect the text of the anchor/xref, as given, if there is no reftext.
My use case: I am auto-generating AsciiDoc, where symbols link to the paragraph
in which they are defined. So the anchor text, as given, is exactly what I want,
since it IS the symbol.

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/asciidoctor-cross-reference-formatting-tp7253p7257.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux