search

mle86 / man-to-md

Converts man pages to Markdown
GNU General Public License v3.0
62 stars 7 forks source link

handling of automatic <a> anchors with headers #8

Open vapier opened 4 years ago

vapier commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

(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 commented 4 years ago

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.