Asciidoctor :: Discussion

Create cross-reference to section number

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

7 messages Options

apj68

Jan 22, 2021; 12:41am

Create cross-reference to section number

Hi, asciiDoctors. . . Here's my ailment: I'm trying to create a troubleshooting outline something like this:

= Troubleshooting Widgets
:sectnum:
:sectnumlevels: 5
:!section-refsig:

// 1.0
[[iswidget]]
== Is there a widget?
=== Great! Go to <<iswunning>>.

// 2.0
[[iswunning]]
== Is this the widget wunning?
=== No, too bad, go to <<wonky>>
=== Yes, great!

// 3.0
[[wonky]]
== Is widget wonky?
=== Yes, too bad!
=== No, great!

Hopefully you get the idea. I would like to use short reference signifiers so that this appears like this:

1.0 Is there a widget?
1.1 Great! Go to 2.0.

2.0 Is this the widget wunning?
2.1 No, too bad, go to 3.0.
2.2 Yes, great!

3.0 Is widget wonky?
3.1 Yes, too bad!
3.2 No, great!

But, as far as I can understand it, to reference the automation section number I'd have to link to <<is_widget_wonky?>>. This would be hard because that level of document could be a pretty complicated phrase/question.

I'd rather not put a custom anchor and reftext because then I would have to constantly update the section numbers as the document changed.

Can anyone suggest any ideas?

Thanks!

Andy

mojavelinux

Jan 22, 2021; 12:50am

Re: Create cross-reference to section number

Administrator

I think what you're looking for is xrefstyle. See https://docs.asciidoctor.org/asciidoc/latest/macros/xref-text-and-style/#cross-reference-styles

-Dan

On Thu, Jan 21, 2021 at 5:41 PM apj68 [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi, asciiDoctors. . . Here's my ailment: I'm trying to create a troubleshooting outline something like this:

= Troubleshooting Widgets
:sectnum:
:sectnumlevels: 5
:!section-refsig:

// 1.0
[[iswidget]]
== Is there a widget?
=== Great! Go to <<iswunning>>.

// 2.0
[[iswunning]]
== Is this the widget wunning?
=== No, too bad, go to <<wonky>>
=== Yes, great!

// 3.0
[[wonky]]
== Is widget wonky?
=== Yes, too bad!
=== No, great!

Hopefully you get the idea. I would like to use short reference signifiers so that this appears like this:

1.0 Is there a widget?
1.1 Great! Go to 2.0.

2.0 Is this the widget wunning?
2.1 No, too bad, go to 3.0.
2.2 Yes, great!

3.0 Is widget wonky?
3.1 Yes, too bad!
3.2 No, great!

But, as far as I can understand it, to reference the automation section number I'd have to link to <<is_widget_wonky?>>. This would be hard because that level of document could be a pretty complicated phrase/question.

I'd rather not put a custom anchor and reftext because then I would have to constantly update the section numbers as the document changed.

Can anyone suggest any ideas?

Thanks!

Andy

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-tp8451.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 (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux

apj68

Jan 23, 2021; 4:43am

Re: Create cross-reference to section number

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. . .?

David Jencks

Jan 23, 2021; 4:54am

Re: Create cross-reference to section number

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

... [show rest of quote]

mojavelinux

Jan 23, 2021; 8:08am

Re: Create cross-reference to section number

Administrator

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
... [show rest of quote]

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

... [show rest of quote]

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

apj68

Jan 26, 2021; 12:46am

Re: Create cross-reference to section number

Great, thanks, Dan. That was my problem, it helps a lot, anyhow. I seem to have mixed results, sometimes it doesn't recognize the reference but maybe it's something in the way I'm doing it. I'm trying to narrow that down now.

Andy

apj68

Jan 26, 2021; 12:56am

Re: Create cross-reference to section number

All is good now. Thanks, Dan and David!

Andy