Disingenuous Behavior Discrepancies

[uvb1]

Using terminology from the README for relatability.

Issue:

Release 6c8e995 2023-11-29, broke diagnostics for both markdown inline links and markdown reference links.

Semantic Versioning has been in use. marksman --version has returned a major.minor version scheme of 1.0 both before and after this breaking release. A breakage such as this should be indicated by an increase in the major version according the rules of semantic versioning.

However, none of the following seem to have been performed:

• No increment in the major version.
• No indication in the release notes that a breakage would be introduced.
• No call out in the README that a breakage would be or had been introduced.

All functionality seems to work for wiki-links. However, marksman seems to have narrowed its primary focus to Wikis and made standard markdown a second class citizen.

For markdown links:

• Diagnostics do not work for markdown inline or markdown reference links.
• Hover does not work for markdown reference links.
• Go-to-definition does not work for markdown reference links.

Summary: The README is misleading.

The README starts by stating in bold that diagnostics are provided (no caveats are provided). Markdown link styles are then illustrated first, before wiki-links (implying they are a first class citizen). A small caveat later in the README only implies that "Marksman provides diagnostics for wiki-links." The demo and feature links don't call out these deficiencies for standard markdown links.

Recommendation:

Make it abundantly clear up front:

• That wiki-links are the focus and the only link type with full functionality.
• To existing users that this breaking change for markdown links was introduced.
• The intentions of the project going forward for support of markdown link functionality vs wiki-links.

[artempyanykh]

Hey @uvb1! Thanks for raising this. I understand that something about marksman doesn't match your expectations. What would be helpful is:

• if something doesn't work, please file a bug report with exact versions of the software you're using and instructions on how to reproduce. Or better yet, submit a PR with a fix.
• if there's a feature missing, please file a feature request, explaining with examples how you'd like things to work.

Responding to some of your comments:

All functionality seems to work for wiki-links. However, marksman seems to have narrowed its primary focus to Wikis and made standard markdown a second class citizen.

Could you elaborate how you draw this conclusion?

For markdown links:

Diagnostics do not work for markdown inline or markdown reference links. Hover does not work for markdown reference links. Go-to-definition does not work for markdown reference links.

All this functionality works for me. If it doesn't work for you, please file a bug report as per the above comment.

Semantic Versioning has been in use.

It's not and never was. This is not a library with an API that needs backwards compat. I try to make sure that features work consistently the way users would expect + more features are added over time. But this is a 'free time' project, so doing any sort of semver is out of scope.