new feature: internal link to reference number

[ivotron]

Add the ability of inserting the number of an internal section reference instead of the name.

The motivation comes straight from LaTeX, where the following:

We first describe foo in Section \ref{foo}.

assuming that foo is section number 2, is displayed like:

We first describe foo in Section 2

in the generated PDF.

Would it be possible to add this at the markdown level? Something like the following would rock:

We first describe foo in Section [#foo].

this, together with #813 and the "abstract section" feature of the new YAML header feature, in my opinion, make many academics rejoice (including myself), since it becomes possible to write, in their entirety, a large category of papers in pure markdown (i.e. free of LaTeX commands)

[bjornbm]

I support this proposal. As far as I am concerned a command line flag would be an acceptable solution not requiring a syntax change, and also a natural solution as we already use --number-sections to get section numbering in the first place.

I propose a --reference-section-numbers flag for this feature, but don't feel strongly about the name. Unnumbered sections should be referenced by name as per the current behavior, even if --reference-section-numbers is set.

[s7726]

I'm in full support of this feature but would like to see it implemented in a way that allows the section reference preference of textual vs numeric to be encoded in the document rather than by command line.

The context of the reference should dictate how the reference is written.

Examples:

Please see the [References] section.

or

The thing should do something as per Section [#Things To Be Done]

In the first example a command line arg would translate that to something like

Please see the 7 section.

Which is not the intended output.

[bjornbm]

Fair enough and good example. I presume that if --number-sections is not set [#Introduction] would behave exactly like [Introduction], i.e. create a textual link.

However, if the deviation from numeric is an exception rather than the norm, one could always use [References][References] to create a textual link with the command line approach. And I would argue that [References][] should also always produce a textual link, which might result in fewer extra characters that adding lots of # elsewhere would. I don't feel strongly about this either way though and am fine with your proposals (@ivotron and @s7726).

[MrLoh]

I'm very much for this too. Would consider to see wether I can implement this in the nearer future, if there is greenlight from @jgm to accept a pull request. I think matching [#label] when a --reference-section-number is set and translating it to \ref{label} would be best, maybe with an option to use the hyperref's package \autoref{label} which creates a link of type section 2 where the whole word is the link.

[wladston]

Have you seen this? https://github.com/lierdakil/pandoc-crossref

[ivotron]

I've been using pandoc-crossref, it's great

[ickc]

Hi, I searched autoref and find this issue.

I found that currently pandoc use \protect\hyperlink to refer to other sections, but not \autoref. Being able to refer to the section is much better than just have a link to an (unknown) section.

Could @jgm comment on this?

Would consider to see wether I can implement this in the nearer future, if there is greenlight from @jgm to accept a pull request.