Nonconforming syntax in multiple markdown files #792
Comments
|
@scottamain Thank you for looking into this! This will be a nice improvement to the state of the art. We had prior discussions about Markdown linting but haven't had the time to follow up yet. |
This is a first pass at some simple issues found by `markdownlint`, but more will come as I gradually enable some of the lint rules that are currently disabled. Also, fixing the spec will be a massive change so that will be a separate PR perhaps done once the spec is near a more final state. Partially fixes #792
|
Reopening the ticket because #793 said that it only partially fixes it. |
|
Not sure if this lint has been run on the Here are all md files in the repo. |
More fixes for #792 with expanded scope to MD files not under /docs. (Still not touching the spec yet.) This includes markdownlint fixes that could not be fixed by `markdownlint-cli`, such as line length (80 char), consistent list item indications, proper heading levels, removal of bash "$" character when not necessary ([rationale](https://cirosantilli.com/markdown-style-guide/#dollar-signs-in-shell-code); if the snippet includes multiple commands, then add a line break).
As per #792, here's a script to run `markdownlint`. The bash script includes usage instructions. You just need to pass it a file, directory, or glob pattern for the MD files you want to lint. It uses a Docker image because I fear the npm package version dependency hell, but the docker image is versioned.
|
Hehe, yeah @GleasonK I didn't do the rfc files in the first CL just to keep my first PR simple. I'm sure you saw I've now cleaned those ones as well. I think there's just two items remaining before closing this issue (in order):
|
Spoke with Eugene, totally fine to cause merge conflicts. There is only one open PR touching spec now, which makes this a good time to make that change. That plan sounds good to me. Got the script running locally, looks like its only spec: |
This will resolve issue openxla#792
|
Given that we have a CI job now which lints markdown files, I think we can close this ticket. |
What happened?
Although some MD parsers are pretty forgiving (including GitHub's), the current markdown files in stablehlo include a variety of syntax errors that do not conform to the basic MD syntax rules. Examples include improper indentation for lists, unescaped asterisks signs (meant for bold or italic text), and missing blank lines between headings and paragraphs.
We should follow traditional MD syntax rules to ensure well-structured files that are easy to read, use an agreed-upon structure that can be tested, and that are compatible with more than one MD parser.
The simplest solution is to markdownlint and fix various syntax and style issues.
We can submit fixes for individual files, and make exceptions as appropriate because this tool allows you to disable certain rules in the linter. Then, once the files are cleaned up, we should enable a GitHub Action to run markdownlint on all new pull requests with .md files so we can avoid re-introduction of syntax errors.
Steps to reproduce your issue
No response
Version information
No response
The text was updated successfully, but these errors were encountered: