Cleaned up usage.md for clarity, formatting, and grammar. #956
Conversation
While working on it, I hard-wrapped the lines to 80 characters. Hope that doesn't complicate things. Note: I changed the Steve Buscemi quote to maintain compliance with the Code of Conduct.
|
Thank you for helping clean up the documentation! This is just to let you know that we know this is here, and will give a proper review soon. |
docs/usage.md
Outdated
| reserved characters can be escaped using `\`, this is not ideal for | ||
| long-form writing. The solution: first enter `jrnl` and hit `return`. You | ||
| can then enter the text of your journal entry. Alternatively, you can `use | ||
| an external editor <advanced>`). |
docs/usage.md
Outdated
| reason being that the `*` sign has a special meaning on most shells). | ||
| Make sure that the asterisk sign is **not** surrounded by whitespaces. `jrnl | ||
| Best day of my life! *` will not work because the `*` sign has a special | ||
| meaning in most shells). |
There was a problem hiding this comment.
No need for parens there, imo. Deleted.
There was a problem hiding this comment.
Yup, I agree this reads better without the parens, but you seem to have left the ending one here as a typo (the opening one is already gone).
docs/usage.md
Outdated
| reserved characters can be escaped using `\`, this is not ideal for | ||
| long-form writing. The solution: first enter `jrnl` and hit `return`. You | ||
| can then enter the text of your journal entry. Alternatively, you can `use | ||
| an external editor <advanced>`). |
There was a problem hiding this comment.
Optional, since this was already an issue:
Instead of using the code formatting for "use an external editor", can it be a link to the relevant section? It's not code, and it'd be good to lead the user to continue reading if they are interested.
There was a problem hiding this comment.
I think that was like that before, and I'm not sure why (novice here). You're right, it should be a link to the other page. How do you do that?
There was a problem hiding this comment.
I think it was just an accident in the documentation (our documentation needs some love, which is why I appreciate your PRs so much).
To make links in markdown, you put the text in square brackets, and the link immediately following it in parens. Here's an example from our current recipes file:
[external editor](./advanced.md)
The above will link the text "external editor" to the advanced page.
If you're interested in learning more about markdown syntax (which is what our documentation uses), I recommend this guide (just let me know if you have any questions).
There was a problem hiding this comment.
Thanks! I'm totally down with the mark...down... (Austin Powers joke?) but I'm a total rookie when it comes to linking to pages on servers.
docs/usage.md
Outdated
|
|
||
| ```sh | ||
| jrnl today at 3am: I just met Steve Buscemi in a bar! He looked funny. | ||
| jrnl today at 3am: I just met Steve Buscemi in a bar! He was on fire. |
There was a problem hiding this comment.
Good catch! This is definitely against our code of conduct. Thank you for holding our feet to the fire. 🔥
docs/usage.md
Outdated
|
|
||
| ## Listing Journals | ||
|
|
||
| You can list the journals accessible by jrnl | ||
| You can list the journals accessible by `jrnl`: | ||
|
|
||
| ```sh | ||
| jrnl -ls |
There was a problem hiding this comment.
Ugh, we really need to fix the -ls command. It doesn't fit our own stated paradigm of single-dash/double-dash commands.
There was a problem hiding this comment.
Seems to me like the writing/reading/filtering commands use a single dash and the export/import/edit/setup commands use double dashes. Why not jrnl --list or something like that?
There was a problem hiding this comment.
Seems to me like the writing/reading/filtering commands use a single dash and the export/import/edit/setup commands use double dashes.
Duh. It even says that in the file we're discussing. 🤦
docs/usage.md
Outdated
|
|
||
| You can also use this feature for deleting entries from your journal | ||
| You can also use this feature for deleting entries from your journal. Open an external editor with the entries you want to delete... |
There was a problem hiding this comment.
Optional:
We actually have a --delete command now (was just released with v2.4.2). If you could mention that here, it would be great.
It's also ok if not; we can add it later.
There was a problem hiding this comment.
Back in the day there was an example about deleting all entries related to an ex. I ended up needing to do that (bummer), but instead of deleting the entries, I moved them into another journal. Is that something that could be automated? Something like jrnl -s 'ex' > ~/ex.md && jrnl -s 'ex' --delete? Maybe it could be jrnl -s 'string' --move -o ~/string.md -- just spitballing.
There was a problem hiding this comment.
...oh yeah, and more to the point, I'll add the reference to the --delete command. Are there other new things that you'd like me to add while I'm at it?
There was a problem hiding this comment.
It looks like jrnl -contains also isn't documented. I think including that would cover everything.
As for moving entries, feel free to create a feature request issue if you're interested in the feature. Alternatively, if you want to spell out a recipe for that, the recipes section of the documentation could be a good place for this.
There was a problem hiding this comment.
-contains is just a search for a specific string, right? By the way, as of a few years ago I was worried that jrnl was abandonware. When did all of this new activity start?
There was a problem hiding this comment.
Yes, that's correct, -contains is a case-insensitive string search.
As for the activity, @wren and I noticed that this project was running into some issues a year ago, and after some chatting with the project's founder, we joined as maintainers. Once we got a regular routine along with some resolutions to compatibility and build issues, the community showed up with a bunch of new features like -contains and -delete.
There was a problem hiding this comment.
@guydebros Thank you for all the hard work on this; it's looking great.
For your idea about a move command, can you please put into a new ticket, so we can discuss the pros/cons of the proposal?
Includes information about two new functions (`--delete`) and (`-contains`). It's starting to look quite different from the original...
* Cleaned up usage.md for clarity, formatting, and grammar. While working on it, I hard-wrapped the lines to 80 characters. Hope that doesn't complicate things. Note: I changed the Steve Buscemi quote to maintain compliance with the Code of Conduct. * more changes to the usage page Includes information about two new functions (`--delete`) and (`-contains`). It's starting to look quite different from the original...
While working on it, I hard-wrapped the lines to 80 characters. Hope that doesn't complicate things.
Note: I changed the Steve Buscemi quote to maintain compliance with the Code of Conduct.
Checklist
poetry run behaveblack (consistent code styling). --
poetry run black --check . --verbose --diff(logically errors and unused imports). --
poetry run pyflakes jrnl featuresPull Requests for the same update/change?
us to include them?