Closed emcconville closed 9 years ago
In that case it would be better to forego the automatic generation of cross ref links, yes.
But don't use HTML where there's no need to: Do it the Pandoc Markdown way, and insert it as an ID like {#grayscale}
on the same line as the header:
## Converting Color to Gray-Scale {#grayscale}
This will then work in all output formats. Any HTML code inserted will be ignored in all non-HTML target formats. (We may want to target PDF or other formats at some stage, no?)
Are there any additional benefits that may be lost if we do not leverage automatic ref links? If not, I'm in favor of {#ref_id}
approach.
The only benefit of auto-ref-linking is: it could be less manual work on us, and less error prone -- if we write something from scratch!
But it is different if you have to process existing docu.
There are fixed rules (explained in the Pandoc documentation) how the IDs of auto-ref-links are constructed. We could still replace the existing #ref_ids
in the text by these, but it is very likely more work (and if it is just because the same ID appears more than once in the text).
Instead, we should comb through the existing #ref_ids
in the text and add the {#ref_id}
to the appropriate headline only once.
Quick grepping through the documents. Adding the {#ref_id}
seems like the correct path. However some #ref_ids
are shared a crossed documents. Example:
#intro : /anim_opt/index.html
#intro : /antialiasing/index.html
#intro : /color_basics/index.html
#intro : /convolve/index.html
#intro : /draw/index.html
#intro : /layers/index.html
#intro : /mapping/index.html
#intro : /morphology/index.html
#intro : /quantize/index.html
#intro : /windows/index.html
This could be an issue when generating PDF & ePub as defining {#ref_id}
will exclude pandoc fixed rule auto-ref. I would guess these duplicate #ref_ids
should be catalogued, and namespaced.
Perhaps
#antialiasing-intro : /antialiasing/index.html
#convolve-intro : /convolve/index.html
... etc ...
It would cause some backwards compatibility links to fail, but might be necessary.
Updated description, and promoted issue to document-draft status.
After applying the drafted solution to the document base, I'm satisfied with the results & promoting to document standard (for future refs).
Small issues
The inline HTML anchor tag (<a name="ref"></a>
) was used to resolved additional legacy, and non-header references. Ideally they will be removed in a future iteration.
With ATX headers, cross reference link are generated automatically, but may not be backwards compatible with existing links.
For example. http://www.imagemagick.org/Usage/color_mods/#grayscale points to ATX header Converting Color to Gray-Scale. This header will have a new generated
id
ofconverting-color-to-gray-scale
, so any existing links will not resolve.Solution would be to include
id
block with ATX header.Activity & Status