-
Notifications
You must be signed in to change notification settings - Fork 476
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Various README fixes #1093
Various README fixes #1093
Conversation
The two heading types are equivalent, but SETEXT headings only support two levels (=== and ---), and there are enough other headings to make it worthwhile to use ATX headings exclusively.
- Replace `’` with `'` globally. The Unicode version is more correct, but most modern Markdown converters apply SmartyPants conversions to automatically convert `'` to `’`. - Replace instances of `…` in code blocks with `...`. Left the Unicode `…` characters in place in prose as I don’t think that SmartyPants conversions handle those.
Removed the prefix `https://github.com/casey/just` from in-document URLs so that the links work in local Markdown viewers without redirecting to GitHub. As an example, `[much more](https://github.com/casey/just#manual)` becomes `[much more](#manual)`.
- This fixes various small formatting issues.
Modified the styling of `justfile` to always be presented in code format, including for the plural as `justfile`s. There are a couple of places where this has not been followed, such as in the function group title `#### Justfile and Justfile Directory`.
Changed indentation of `justfile` syntax to two spaces consistently.
- Fixed the use of the en-dash (`–`) where the em-dash (`—`) belongs. - Fixed the unnecessary use of backticks inside a syntax block. - Fixed a couple of sentence errors. - Fixed cases where text should have been been wrapped in code blocks and weren’t or were wrapped in other syntax markers.
Convert the in-line links to reference links. Note that the references immediately below the table are not sorted, but are presented in the order of appearance in the table.
This was placed under the `Functions` section, but belongs under the `Features` section. I moved it to a place that _seems_ to make sense.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Awesome! A couple things that I would change:
- I prefer using setext headings where possible, since I find them easier to read.
- I like replacing ’ with ', but I'd prefer to keep
…
instead of...
, I like the way that…
looks
Everything else is great. Thanks for splitting it up into separate commits, that's makes it much easier to review.
I’ll revert back to SETEXT later (I have to disable Neoformat because |
Sweet, the change you just pushed looks good to me. |
OK. I’ll get the headings changed and finalize this PR in a few hours. |
This should finalize the cleanup PR. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sweet, looks great. Thank you for persevering! This makes the readme much more consistent.
Depending on your preferences, @casey, I can open this as multiple PRs. I believe it will be faster to get them in place with one PR. As each change builds on the last but is otherwise isolated, I recommend reviewing this PR a commit at a time. What follows is a summary of the commits based on the commit messages for each.
Prefer ATX headings over SETEXT headings
The two heading types are equivalent, but SETEXT headings only support two levels (
===
[h1] and---
[h2]), and there are enough other headings to make it worthwhile to use ATX headings exclusively.Replace Unicode punctuation with ASCII punctuation
Replace
’
with'
globally. The Unicode version is more correct, but most modern Markdown converters apply SmartyPants conversions to automatically convert'
to’
.Replace instances of
…
in code blocks with...
. Left the Unicode…
characters in place in prose as I don’t think that SmartyPants conversions handle those.Changed in-document URLs to not go remote
Removed the prefix
https://github.com/casey/just
from in-document URLs so that the links work in local Markdown viewers without redirecting to GitHub.As an example,
[much more](https://github.com/casey/just#manual)
becomes[much more](#manual)
.Automatic
prettier
formattingMake the styling of
justfile
consistentModified the styling of
justfile
to always be presented in code format, including for the plural asjustfile
s. There are a couple of places where this has not been followed, such as in the function group title#### Justfile and Justfile Directory
.Fix a couple of link errors
Make
justfile
syntax indentation consistentChanged indentation of
justfile
syntax to two spaces consistently.Fix various errors
–
) where the em-dash (—
) belongs.Clean up the installation table
Convert the in-line links to reference links. Note that the references immediately below the table are not sorted, but are presented in the order of appearance in the table.
Fix a couple of wrong-level headings
Move
Dotenv Integration
sectionThis was placed under the
Functions
section, but belongs under theFeatures
section. I moved it to a place that seems to make sense.