Github user alanconway commented on the pull request:
https://github.com/apache/qpid-proton/pull/68#issuecomment-188279273
What Andrew said. Sphinx handles this properly, the source .rst files have
links to other .rst files - works nicely for dispatch docs. The HTML generator
converts local .rst links to .html in the generated html. We could modify our
HTML generator to do the same.
Rant: This is a symptom of the fundamental problem with markdown: it was
designed as a hack to generate HTML but touted as a generic markup language. So
in practice markdown documents are riddled with HTML specific assumptions, like
using .html in links, which break as soon as you try to use them in a new
context. It's a pity because MD is so close to being a useful markup language
that it consistently fools people. RST is much better but less popular, which
means it's not really better since standard markup is only standard if it's
widely used :(
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
