Asciidoctor :: Discussion - Re: Create cross-reference to section number

Re: Create cross-reference to section number

Posted by mojavelinux on Jan 23, 2021; 8:08am
URL: https://discuss.asciidoctor.org/Create-cross-reference-to-section-number-tp8451p8456.html

Agreed, if you want to refer to a section by a label (aka ID), you need to assign it one. The following works:

:sectnums:
:xrefstyle: short
:section-refsig:

== Do you need to check the URL?

Goto <<checkurl>>.

[#checkurl]
=== Does http://www.example.com:1090 bring you to a valid location?

However, it does not work if you do this:

== Do you need to check the URL? Goto <<checkurl>>.

The reason is because the processor will convert the section title eagerly in order to assign an ID. And when it is converted, the target is not yet defined. You can fix this by assigning an ID to the section, even if you never reference it. It prevents the processor from auto-generating ID, which is what triggers the eager conversion. Here's the complete working example:

:sectnums:
:xrefstyle: short
:section-refsig:

[#ask-to-checkurl]

== Do you need to check the URL? Goto <<checkurl>>.

[#checkurl]
=== Does http://www.example.com:1090 bring you to a valid location?

I hope that helps!

Best Regards,

-Dan

On Fri, Jan 22, 2021 at 9:54 PM David Jencks [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I think there are two aspects here:

- The id of the section. This is what you have to put in your link to say where to go. The auto-generated ids can get pretty long, but you can assign a suitable id yourself of any length. I think this would take care of the aspect you mention here.

- The generated ref text. I believe from what you say here that Dan’s advice provides a suitable solution for this.

These are independent concerns. How to assign a custom id is discussed here: https://docs.asciidoctor.org/asciidoc/latest/sections/custom-ids/

Did I miss something?

On Jan 22, 2021, at 8:43 PM, apj68 [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks, I did see that which works for getting the section number but mainly my challenge is how can I create a link to the section using a reference name that I can easily write in my link? For example, I'm linking to what could be long "section" titles:

=== Does http://www.example.com:1090 bring you to a valid location?

Unlike something like:

=== Simple Section

Which I believe I could link to with link:#simple_section.

I do understand with short xrefstyle links I can get just the number but how can I create a reference to the first section mentioned above? My struggle is how to link to the section. What I'd _like_ to do is something like this:

== Do you need to check the URL? Goto <<checkurl>>.

=== Does http://www.example.com:1090 bring you to a valid location? [[checkurl]]

But I want the generated link to be the section number (i.e., "Goto 1.1" rather than "Goto checkurl"). I also don't want to put a custom reftext because then I'll have to maintain that if the section changes. That is:

=== Does http://www.example.com:1090 bring you to a valid location? [[checkurl,"1.1"]]

I hope this is making sense. . .?

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

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

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

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

Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux