search

ImageMagick / Usage-Markdown

Base text document processed with pandoc
12 stars 13 forks source link

Markdown documents should include anchor-name tags, so existing links will resolve #16

Closed emcconville closed 9 years ago

emcconville commented 9 years ago

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 of converting-color-to-gray-scale, so any existing links will not resolve.

Solution would be to include id block with ATX header.

## Converting Color to Gray-Scale {#grayscale}

Activity & Status

KurtPfeifle commented 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?)

emcconville commented 9 years ago

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.

KurtPfeifle commented 9 years ago

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.

emcconville commented 9 years ago

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.

emcconville commented 9 years ago

Updated description, and promoted issue to document-draft status.

emcconville commented 9 years ago

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.