Add checking of Markdown documents to our linters #116

kcgen · 2020-01-06T06:44:24Z

This PR uses mdl (markdownlint) which has become a popular checker for Markdown files.

https://github.com/markdownlint/markdownlint (Ruby-based command-line version we're using)
https://github.com/DavidAnson/markdownlint (Node.JS HTTP-service based version)
https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint (and as a built-in checker for Visual Studio Code)

Links to our three current Markdown docs:

kcgen · 2020-01-06T06:45:08Z

.github/workflows/analysis.yml

          sudo pip3 install pylint beautifulsoup4 html5lib
+          sudo gem install mdl
+          sudo chmod go-w /usr/share/rust/.cargo/bin


On startup, Ruby prints a warning about a permission issue in this directory - so we fix it up silence this unrelated and distracting warning.

kcgen · 2020-01-06T06:46:24Z

.mdlrc

@@ -0,0 +1 @@
+rules "~MD005", "~MD033", "~MD046"


33 will complain about embedded HTML and didn't like <sup>, so that had to go.

5 would easily get confused with nested ordered lists.

46 was too restrictive by enforcing only one way to do code presentation. This harmed the ascii-presentation of the markdown files when it makes sense to mix simple indentation lines with multi-line code blocks ( ```).

Also re-order to perform shellcheck first because it requires the least installation work compared to pylint and markdownlint. The reason being if we're going to fail during shellcheck, then we fail faster (and leave heavier tasks for further down the line).

dreamer

Overall very cool checker - I think only tiny adjustments are needed.

dreamer · 2020-01-07T17:05:04Z

README.md

+<sup>＊- SDL 1.2 was last updated 2013-08-17 and SDL\_sound 2008-04-20</sup>
+
+<sup>† - 22.05 kHz, 44.1 kHz, 48 kHz; mono, stereo</sup>
+
+<sup>‡ - 44.1 kHz stereo only</sup>
+
+<sup>§ - Broken or unsupported in either SDL\_sound or DOSBox</sup>


Previously these lines used 2 spaces to break the line, which I presumed was correct markdown… Does it generate any warning? In this case, we don't want every annotation to be in a separate paragraph.

Yes, separate paragraphs is unnecessary visual bloat. Two (or more) spaces still generates:

README.md:48: MD009 Trailing spaces

README.md:49: MD009 Trailing spaces

README.md:50: MD009 Trailing spaces

Edit: Interesting.. Markdown uses the more explicit "\" to create a line-break without starting a new paragraph, similar to HTML's <br>. Will try that.

Edit 2: \ works!

Makes me think we can now safely add a "strip-trailing-whitespace" commit-hook, because nothing I know of should have trailing whitespace.. can you think of anything?

Nope, breaking space was the only thing - and the new way is better than having 2 trailing spaces :)

dreamer · 2020-01-07T17:10:32Z

README.md

-#### Fedora
-
-    $ sudo dnf install libpng SDL2 SDL2_net opusfile
+### Fedora


I think I made an error earlier - sections Linux, Windows, macOS should be subsections of "Development snapshot builds", and this would keep sections per distro at level 4, otherwise it might be visually hard to distinguish where next section starts.

Change it to:

### [Linux](…) … #### Fedora … ### [Windows](…) …

This way linter probably won't complain about nesting structure.

Yes, nice and consistent now.

dreamer · 2020-01-07T17:11:36Z

README.md

+    cd dosbox-staging
+    ./autogen.sh
+    ./configure
+    make


Maybe shell syntax highlight? :)

Will do - but I do like how tidy the raw text looked in your original version :-)
The linter didn't like the $ prefixes (they make it harder for users to copy and paste).

Fenced, along with a couple others.

dreamer · 2020-01-07T17:13:36Z

scripts/verify-markdown.sh

+# Based on `verify-bash.sh` by Patryk Obara <patryk.obara@gmail.com>
+# Copyright (C) 2019 licensed GPL-2.0-or-later


Eh, you can remove me - additional copyright line won't cause problems for scripts updating years in the future :).

sounds good; yeah, was just trying to show attribution - but yeah, too much of that would get cluttered!

kcgen · 2020-01-07T18:06:17Z

Squashed and pushed.
Turns out powershell can be highlighted too (MicrosoftDocs/PowerShell-Docs#1511), so I fenced that. Changed to PS> to PS:\> because that issue mentions GitHub will skip that prefix when users copy and paste from a powershell fenced block. (pretty cool).

dreamer

Looks great, thanks :)

kcgen commented Jan 6, 2020

View reviewed changes

kcgen force-pushed the kc/verify-md-1 branch from 5cb401f to 90a33bd Compare January 6, 2020 06:55

kcgen requested a review from dreamer January 6, 2020 06:56

kcgen self-assigned this Jan 6, 2020

kcgen added the enhancement New feature or enhancement of existing features label Jan 6, 2020

kcgen force-pushed the kc/verify-md-1 branch from 90a33bd to 89cb33c Compare January 7, 2020 03:35

dreamer reviewed Jan 7, 2020

View reviewed changes

Make MD docs comply with markdownlint

a007906

kcgen force-pushed the kc/verify-md-1 branch from 89cb33c to a007906 Compare January 7, 2020 18:02

kcgen requested a review from dreamer January 7, 2020 18:10

dreamer approved these changes Jan 7, 2020

View reviewed changes

dreamer merged commit a852fe3 into master Jan 7, 2020

kcgen deleted the kc/verify-md-1 branch January 10, 2020 07:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add checking of Markdown documents to our linters #116

Add checking of Markdown documents to our linters #116

kcgen commented Jan 6, 2020 •

edited

Loading

kcgen Jan 6, 2020 •

edited

Loading

kcgen Jan 6, 2020 •

edited

Loading

dreamer left a comment

dreamer Jan 7, 2020

kcgen Jan 7, 2020 •

edited

Loading

kcgen Jan 7, 2020

dreamer Jan 7, 2020

dreamer Jan 7, 2020

kcgen Jan 7, 2020

kcgen Jan 7, 2020

dreamer Jan 7, 2020

kcgen Jan 7, 2020 •

edited

Loading

kcgen Jan 7, 2020

dreamer Jan 7, 2020

kcgen Jan 7, 2020

kcgen Jan 7, 2020

kcgen commented Jan 7, 2020

dreamer left a comment

		# Based on `verify-bash.sh` by Patryk Obara <patryk.obara@gmail.com>
		# Copyright (C) 2019 licensed GPL-2.0-or-later

Add checking of Markdown documents to our linters #116

Add checking of Markdown documents to our linters #116

Conversation

kcgen commented Jan 6, 2020 • edited Loading

kcgen Jan 6, 2020 • edited Loading

Choose a reason for hiding this comment

kcgen Jan 6, 2020 • edited Loading

Choose a reason for hiding this comment

dreamer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kcgen Jan 7, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kcgen Jan 7, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kcgen commented Jan 7, 2020

dreamer left a comment

Choose a reason for hiding this comment

kcgen commented Jan 6, 2020 •

edited

Loading

kcgen Jan 6, 2020 •

edited

Loading

kcgen Jan 6, 2020 •

edited

Loading

kcgen Jan 7, 2020 •

edited

Loading

kcgen Jan 7, 2020 •

edited

Loading