handling of automatic <a> anchors with headers

[vapier]

most common markdown renderers i'm familiar with automatically create anchors for # headers. there's no need to generate <a name=...> tags for them.

[mle86]

Yes, GitHub and most other Markdown renderers output sane anchors (such as “See Also: Chapter 5” → #see-also-chapter-5,
but I've seen renderers with a different output style (#seealsochapter5).

Since the script now supports links to anchors (.\" LINK-TO SECTION TITLE), the script needs to know the exact anchor name -- and the easiest way to accomplish that is to output them itself.

That may of course result in duplicate anchors but since they're both in the same position, that shouldn't be a problem.

[mle86]

(But I've noticed a related problem: sometimes different sections have the same name, such as “Examples” sub-sections. Those should of course get different anchor names. GitHub's renderer uses #examples-1 anchors in these cases. But implementing something similar in my script would be rather complicated right now as there's no way to reference a section other than by its exact title.)

[vapier]

the lack of standardization in automatic anchor link generation is a great point as a generalized tool. maybe for people who only ever target one renderer could have an option to skip the automatic generation ? that way you could put a comment in noting the lack of standardization which is why the are created in the first place.