Asciidoctor-pdf: Option to include the section number in a cross-reference

[vogella]

If the :sectnums: I think the cross-reference should include the section numbers or at least you should offer an option for it.

[mojavelinux]

In may ways, this ties back to an issue in core. See https://github.com/asciidoctor/asciidoctor/issues/858.

[mojavelinux]

In other words, the challenge is how and where to describe this. We know where to change the code. What we need to figure out how to tell the code what to write out.

[vogella]

I suggest to do it like DocBook

<xref linkend="tutorial__p2exportA" /> results from example in Section 31.8, “Create the initial product export” in one of my documents. I think that is a pretty decent result.

[mojavelinux]

The problem is, we can't do it just one way, because different people working in different scenarios will want different behavior. We have to have a way to specify it. (I'm also thinking this is an opportunity for an extension point to make further customization possible).

[vogella]

Just to explain this issue a bit more. I use frequently cross-links in my printouts for example:

See <<createtemplate>> to learn how to do this. 

This may result in:

See "Creating a template folder in Android Studio" to learn how to do this. 

Unfortunately without section this is very hard to print in a > 400 pages printout. Desired would be to have the section number:

See "4.5.2 Creating a template folder in Android Studio" to learn how to do this. 

[vogella]

I assume https://github.com/asciidoctor/asciidoctor-pdf/blob/1d7c91fbc1be7ec67200a5098989627396bdb0db/lib/asciidoctor-pdf/converter.rb#L1646 is the correct place to change this.

[fapdash]

I would like to start with this. From my understanding we need to implement this in the core, so that the reftext that gets accessed by the converter is already set correctly, is that right?

reftext = node.document.references[:ids][refid]

[vogella]

@fap- thanks for starting to work on this. The index (recently added) and the table of context already include the section number. So I assume this information is already available for the converter and no change is required.

@mojavelinux please feel free to correct me.

[fapdash]

From what I've seen the information is there but it isn't connected. (we can't get a section instance, who knows about it's sectnum, by it's refid)

asciidoctor/asciidoctor#858 and asciidoctor/asciidoctor#1132 seem to have a broader scope but I'm not sure if I understand everything correctly, as I haven't had prior experience with either AsciiDoctor or AsciiDoc.

My proposal would be to introduce {sectnum} and {sectname}.
{sectnum} getting substituted with section.sectnum and {sectname} with section.name.
So we could have:

:section-label: {chapter-label} {sectnum} {sectname} // global default

[id="X2",reftext="{chapter-label} {sectnum}"] // local
== Paragraphs

I think the right place to substitute would be in Parser.initialize_section but at this point the Section.number is still set to the default of '1' and only gets set correctly when the Section later gets added to it's parent.

[vogella]

@fap- maybe you can provide a PR for your suggestion? I know @mojavelinux is currently busy at the Devvox conference.

We have a clone at @vogellacompany which you can use for it. If you can adjust our Gradle script to use the vogellacompany clone, I can also test it with our PDF scripts.

[vogella]

@mojavelinux could you look at @fap- pull request? @fap- is available to adjust the pull request based on feedback from you.

[vogella]

Can this issue be targeted for the next pdf release? Without it references in printed material are not usable. We using a patched version with the patch from @fap- included since > 6 months and we are very happy with the result.

[mojavelinux]

Absolutely. The only hold up was that we needed to set the behavior in core (which defines terminology, settings, and expectations). With that in place, it's almost trivial to add this to Asciidoctor PDF because all the hard work is done.

As you can probably tell by now, I don't add features until I can be sure they fit consistently. But when we do it right, we get a lot more than just the feature in front of us.

[mojavelinux]

To prove my point, the way I implemented this feature in core, you don't even have to think about how to make formal cross reference text. It just happens automatically now...and it can be tuned using the xrefstyle attribute. Thus, your example from above can be written as:

:xrefstyle: full

See <<createtemplate>> to learn how to do this.

//...

==== Creating a template folder in Android Studio

And you'll see:

See Section 4.5.2, “Creating a template folder in Android Studio” to learn how to do this. 

[mojavelinux]

There's still an open question about whether to allow the word "Section" to be dropped.

See 4.5.2, “Creating a template folder in Android Studio” to learn how to do this. 

As it stands now, the xref won't show the number if you unset section-caption (e.g., :!section-caption:). Perhaps we should support that scenario. wdyt?

[vogella]

There's still an open question about whether to allow the word "Section" to be dropped.

Would be nice to have the option to drop the "section". But having the correct section link included in the printed text is much more important, so if that is hard to do I think it is OK to have the section included.

[mojavelinux]

Would be nice to have the option to drop the "section".

Consider that part done (in core). You just unset the section-refsig attribute. For details, see http://asciidoctor.org/docs/user-manual/#customizing-the-cross-reference-text.

[mojavelinux]

This is now ready to test in Asciidoctor PDF. See #834.