Cleaned up usage.md for clarity, formatting, and grammar. #956

guydebros · 2020-05-17T15:09:36Z

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

The code change is tested and works locally.
Tests pass. Your PR cannot be merged unless tests pass. --
poetry run behave
The code passes linting via
black (consistent code styling). --
poetry run black --check . --verbose --diff
The code passes linting via pyflakes
(logically errors and unused imports). -- poetry run pyflakes jrnl features
There is no commented out code in this PR.
Have you followed the guidelines in our Contributing document?
Have you checked to ensure there aren't other open
Pull Requests for the same update/change?
Have you added an explanation of what your changes do and why you'd like
us to include them?
Have you written new tests for your core changes, as applicable?

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.

wren · 2020-05-19T02:10:40Z

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.

wren

This is looking good. Just a few typo fixes, and we should be good. Thank you!

wren · 2020-05-22T17:55:29Z

docs/usage.md

+    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>`).


Unmatched ending parens.

wren · 2020-05-22T17:56:10Z

docs/usage.md

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


Unmatched ending parens.

No need for parens there, imo. Deleted.

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

wren · 2020-05-22T17:57:17Z

docs/usage.md

+    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>`).


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.

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?

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

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.

wren · 2020-05-22T18:28:42Z

docs/usage.md


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


Good catch! This is definitely against our code of conduct. Thank you for holding our feet to the fire. 🔥

lol, pun 🤣

wren · 2020-05-22T18:30:32Z

docs/usage.md


 ## Listing Journals

-You can list the journals accessible by jrnl
+You can list the journals accessible by `jrnl`:

 ```sh
 jrnl -ls


Ugh, we really need to fix the -ls command. It doesn't fit our own stated paradigm of single-dash/double-dash commands.

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?

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

wren · 2020-05-22T18:34:40Z

docs/usage.md


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


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.

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.

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

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.

-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?

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.

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

wren

💯

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

Cleaned up usage.md for clarity, formatting, and grammar.

6179ea4

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.

wren requested changes May 22, 2020

View reviewed changes

wren reviewed May 22, 2020

View reviewed changes

more changes to the usage page

bbefb89

Includes information about two new functions (`--delete`) and (`-contains`). It's starting to look quite different from the original...

wren approved these changes May 27, 2020

View reviewed changes

wren added the documentation Improvements or additions to documentation label May 27, 2020

wren merged commit ea14e48 into jrnl-org:develop May 27, 2020

guydebros deleted the docs-usage-edit branch May 28, 2020 00:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Cleaned up usage.md for clarity, formatting, and grammar. #956

Cleaned up usage.md for clarity, formatting, and grammar. #956

guydebros commented May 17, 2020

wren commented May 19, 2020

wren left a comment

wren May 22, 2020

wren May 22, 2020

guydebros May 22, 2020

wren May 22, 2020

wren May 22, 2020

guydebros May 22, 2020

wren May 22, 2020

guydebros May 22, 2020

wren May 22, 2020

guydebros May 22, 2020

wren May 22, 2020

guydebros May 22, 2020

guydebros May 22, 2020

wren May 22, 2020 •

edited

Loading

guydebros May 22, 2020

guydebros May 22, 2020

micahellison May 23, 2020

guydebros May 23, 2020

micahellison May 23, 2020

wren May 27, 2020

wren left a comment


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

Cleaned up usage.md for clarity, formatting, and grammar. #956

Cleaned up usage.md for clarity, formatting, and grammar. #956

Conversation

guydebros commented May 17, 2020

Checklist

wren commented May 19, 2020

wren left a 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

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

Choose a reason for hiding this comment

wren May 22, 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

wren left a comment

Choose a reason for hiding this comment

wren May 22, 2020 •

edited

Loading