Skip to content
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

Merged
merged 14 commits into from
Feb 8, 2022
Merged

Various README fixes #1093

merged 14 commits into from
Feb 8, 2022

Conversation

halostatue
Copy link
Contributor

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 formatting

  • This fixes various small formatting issues.

Make the styling of justfile consistent

Modified the styling of justfile to always be presented in code format, including for the plural as justfiles. 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 consistent

Changed indentation of justfile syntax to two spaces consistently.

Fix various errors

  • 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.

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 section

This was placed under the Functions section, but belongs under the Features section. I moved it to a place that seems to make sense.

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.
Copy link
Owner

@casey casey left a 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.

@halostatue
Copy link
Contributor Author

I’ll revert back to SETEXT later (I have to disable Neoformat because prettier automatically changes SETEXT headings to ATX headings), but I’d like you to look at the commit I’m pushing up now where I am doing a replace of all ... with . This only affects code wrapped text (`text`) and fenced blocks (```…```) to see if there are spots where you don’t want instead of ....

@casey
Copy link
Owner

casey commented Feb 8, 2022

Sweet, the change you just pushed looks good to me.

@halostatue
Copy link
Contributor Author

OK. I’ll get the headings changed and finalize this PR in a few hours.

@halostatue
Copy link
Contributor Author

This should finalize the cleanup PR.

Copy link
Owner

@casey casey left a 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.

@casey casey enabled auto-merge (squash) February 8, 2022 20:26
@casey casey merged commit 4882b5a into casey:master Feb 8, 2022
@halostatue halostatue deleted the tweak-readme-formatting branch February 8, 2022 22:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants