-
Notifications
You must be signed in to change notification settings - Fork 499
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Option to include the section number in a cross-reference #464
Comments
In may ways, this ties back to an issue in core. See asciidoctor/asciidoctor#858. |
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. |
I suggest to do it like DocBook
|
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). |
Just to explain this issue a bit more. I use frequently cross-links in my printouts for example:
This may result in:
Unfortunately without section this is very hard to print in a > 400 pages printout. Desired would be to have the section number:
|
I assume asciidoctor-pdf/lib/asciidoctor-pdf/converter.rb Line 1646 in 1d7c91f
|
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?
|
@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. |
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}.
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. |
@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. |
@mojavelinux could you look at @fap- pull request? @fap- is available to adjust the pull request based on feedback from you. |
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. |
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. |
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
And you'll see:
|
There's still an open question about whether to allow the word "Section" to be dropped.
As it stands now, the xref won't show the number if you unset |
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. |
Consider that part done (in core). You just unset the |
- add support for the xrefstyle attribute, which allows the style of cross reference text to be controlled - add fallback to old behavior when using Asciidoctor < 1.5.6
This is now ready to test in Asciidoctor PDF. See #834. |
If the :sectnums: I think the cross-reference should include the section numbers or at least you should offer an option for it.
The text was updated successfully, but these errors were encountered: