Footnote text is duplicated in some cases

[alycm]

Just pulling a small comment on a PR out to an issue so that it does not get lost now that the PR is merged: https://github.com/KhronosGroup/OpenCL-Docs/pull/1018#issuecomment-1841029912

Related question, the way the footnotes are currently marked up as, more or less 'footnote:[{some attribute containing text}]' resulting in a lot of copies of some footnotes. I believe if they were re-done as '{some attribute containing footnote:label[text]}', each footnote would only appear once, yet would still work when they appear in refpages. I could pick this up in the draft extension integration branch, if you like.

This is particularly obvious in e.g. the OpenCL C spec.

Assigning to @bashbaug simply because initial question was directed at him.

[bashbaug]

Odd, I'm surprised I didn't notice this.

I was trying to follow "best practices" as described here: https://github.com/asciidoctor/asciidoctor-pdf/issues/1397

Specifically:

I strongly recommend against defining the footnote macro in an attribute. It's fine to define the text that way, but the macro should be defined at the point of use.

Maybe we need to re-think this, though. I'll try to play around with some options.

[bashbaug]

I've found a couple of possible ways to "fix" this and I would like input to decide what we want to do.

1. We could assign footnotes an ID every place they are used, say based on the attribute name. With this methoud our footnote include files are unchanged, but everywhere we use a footnote we would switch from text like this:

footnote:[{fn-float-conversion-rounding}]

to something like this:

footnote:float-conversion-rounding[{fn-float-conversion-rounding}]

Here "float-conversion-rounding" is the ID of the footnote, and as long as each footnote has the same ID they will not be duplicated.

2. We could update our footnote include files so each footnote looks something like this:

:fntext-cl_khr_fp16: pass:n[ \
Unless the *cl_khr_fp16* extension is supported and has been enabled. \
]
:fn-cl_khr_fp16: footnote:cl_khr_fp16[{fntext-cl_khr_fp16}]

And then everywhere the footnote is used we would switch from text like this:

footnote:[{fn-cl_khr_fp16}]

to something like this:

{fn-cl_khr_fp16}

It's possible we could this with a single attribute, but I can't figure out the right set of asciidoc substitutions to make this work, so I'd probably go with two attributes for now.

I have a slight preference for (2) since it seems less error-prone and it contains the complexity in the footnotes file, but it's only a slight preference.

Are there any other solutions we should try?

Note, there is one minor disadvantage of the de-duplicated footnote text: there can only be one "back link" to a footnote reference, so if you click to read a de-duplicated footnote, then follow the back-link back to the text, you may end up in a different place than you started.

[oddhack]

The cl_khr_fp16 one is particularly egregious because there are just so many of them (and also see my issues in #1044 regarding this extension and the current C spec). In #950 I am primarily using inline text for extension dependencies, matching API version dependencies, but haven't done much with the existing footnotes.