[DISCUSSION CHORE] Gently cleanup of ancillary doc files

[stevemeacham]

No description provided.

[stevemeacham]

I see little things in the ancillary files, such as inconsistent hyperlinks, capitalization, naming, some whitespace, and other drek like that. Fixing them would be good, for the reader, but could be a PITA for a reviewer looking at the diffs. Then again, it's just four files. What do you think? I'd be willing to do it if it's worth it. Perhaps the work could be broken up into a series of smaller, more focused single-task changes.

[nuggreat]

Submit it as one PR and then we will comment or add the changes once we see then. Also when you want to start discussion related to a set of files it helps if you name the files.

[stevemeacham]

I'm just considering HOWTO, LIB_MANAGER, README, and SUMMARY in this discussion. I haven't decided on a way to help out with the api or api docs yet. We have quite a lot of legacy code here. I'll do as you suggest, but probably wait to see what is decided on my other two outstanding PRs, to avoid a dirty merge later on.

[stevemeacham]

I've analyzed what I think needs to be done here and performed a local dry-run. I found that the changes are broad enough and varied enough the diffs suffer. Maybe this should be multiple issues, or multiple pull requests. I propose using four incremental commits updating the same pull request (does that make sense and work? I'm still learning the Git way). Maybe we could space them each about a week apart to not burden the maintainer(s) or anyone else.

Commit 1 - Start with the more inconsequential things, so the latter changes are easier to follow:

1. Spelling and Grammar, mostly courtesy of Grammarly. There have been previous commits for the same thing, so there are only a dozen or so left uncaught that I can see.
2. Consistent naming and capitalization. Things like GitHub, KerboScript, and KSLib.
3. Descriptive hyperlinks. There are only two links that I know of that need this, where the link text is simply "HERE".
4. Title-capitalization for headings.
5. Clean up some in-line code markdown where I've found inconsistencies or errors.

Commit 2 - Next I propose a markdown de-linting. A bit more behind-the-scenes, but it's really bad in some places.

1. Surround headings with blank lines
2. Surround lists with blank lines
3. Headings increment one level at a time only, and I suggest starting each .md file with a level-1 heading.
4. No punctuation at the end of a heading (i.e. ':').
5. Eliminate trailing spaces (there aren't that many, amazingly).
6. Add a newline at the end of the .md files. I should have done this in my footer updates last month :(.
7. NOT implement any inconsequential or religious changes, like spaces vs. tabs, single vs. multi-line paragraph text, or indentation, except where it is causing lint.

I believe all of the above add good things to our markdown - readability, accessibility, consistency, standards compliances, and progressively fewer editorial mistakes; All things that improve the experience of readers across all rendering engines.

Now that the mostly mechanical changes have been addressed, do some more localized heavy lifting:

Commit 3 - Remove a more significant type of lint - left-justify ordered and unordered lists in the markdown. They'd remain indented when rendered, but allows using actual standards-compliant lists that will render as an actual list in HTML rather than what we often have now: make-shift look-like-a-list-but-isn't. This is the need that initially inspired me to open this issue - having list items with both a dot and a number was the first indication.

Commit 4 - Make it easier for the readers to distinguish between prompts, commands, command outputs, and file excerpts, and to compare their terminal outputs with the expected outputs. To do so, I'd eliminate most inline shell command snippets and replace them with fenced code blocks of type 'shell' and 'console', show exactly what the user should expect to see and what they need to type. I've done about half of them experimentally in a test branch and they've turned out quite nicely.

[stevemeacham]

I'll take silence as agreement and start bundling up the first pull request early next week. Aloha.

[nuggreat]

Go ahead nothing of the stated goals looks bad, sorry about not getting back to you but well the elections have been kind of distracting.

Though something that I would consider adding to this would be shifting the hard coded URLs to relative links mostly applies to the summary document. When we created it I would have used relative links if I knew they where a thing on git but at the time I did not.

[stevemeacham]

Go ahead nothing of the stated goals looks bad, sorry about not getting back to you but well the elections have been kind of distracting.

Though something that I would consider adding to this would be shifting the hard coded URLs to relative links mostly applies to the summary document. When we created it I would have used relative links if I knew they where a thing on git but at the time I did not.

Good idea. I'll get that one too.

[stevemeacham]

Status update...I haven't started rebuilding this. My sister's whole household got COVID-19, and I lost a grandpa and a friend on Monday to COVID too, and may be losing a mom and/or her partner to it. Obviously hoping not. Also working to to get a job with the Hawaii PD and they're keeping me busy jumping through hoops. Assuming mom doesn't lose the battle, I can give this some attention later next week. Sorry for the delay. I know you've been waiting with bated breath LOL. My own kOS library and other forks (and even my save-games!) haven't gotten any attention this month either. Aloha.

[scimas]

My sincere condolences. Your and your family's health is far more important than anything here. Hope everyone else recovers, best wishes!