doc: Improve introduction reading flow

To try the script we should suggest the stable versioned release not the
main trunk.

README.md

@@ -8,20 +8,12 @@
 A script without bells and whistles.
 Focuses on letting you quickly:
 
-- create notes for taskwarrior tasks
+- create new notes for taskwarrior tasks
-- edit notes for taskwarrior tasks
+- edit existing notes for taskwarrior tasks
 
 It does both by simply being invoked with `topen <task-id>`.
 
-Provide a taskwarrior task id or uuid and `topen` creates a new note file or lets
+Or it can be used directly from taskwarrior by being aliased in your `taskrc`:
-you edit an existing one. Additionally it adds a small annotation to the task
-to let you see that there exists a note file next time you view the task.
-
-Should just work as-is without additional configuration in most modern taskwarrior setups.
-
-Can be configured through environment variables or cli options, see below.
-
-Can be used as-is with the `topen` command or directly from taskwarrior by being aliased in your `taskrc`:
 
 ```conf
 alias.note=exec topen
@@ -30,8 +22,16 @@ alias.note=exec topen
 And you can open any note with your usual taskwarrior workflow,
 by doing `task note <id>`.
 
+Provide a taskwarrior task id or uuid and `topen` creates a new note file or lets
+you edit an existing one. Additionally it adds a small annotation to the task
+to let you see that there exists a note file next time you view the task.
+
 That's all there is to it.
 
+Everything should just work as-is without additional configuration in most modern taskwarrior setups.
+
+But if you want, many settings can be configured through your taskrc file, environment variables, or cli options, see below.
+
 ## Installation
 
 You can install the script with your favorite python environment manager:
@@ -52,7 +52,7 @@ Or just manually copy the `topen` file to a directory in your PATH.
 [tasklib](https://github.com/GothenburgBitFactory/tasklib) is the only dependency aside from the python standard library.
 
 If you just want to try the script out,
-feel free to do so by invoking it e.g. with `uvx git+https://git.martyoeh.me/Marty/topen.git`.
+feel free to do so by invoking it e.g. with `uvx topen`.
 
 If you want to install the trunk version instead of a versioned release simply substitute for the git path:
 

topen.py

@@ -93,8 +93,7 @@ def get_notes_file(uuid: str, notes_dir: Path, notes_ext: str) -> Path:
 def open_editor(file: Path, editor: str) -> None:
     """Opens a file with the chosen editor."""
     _ = whisper(f"Editing note: {file}")
-    proc = subprocess.Popen(f"{editor} {file}", shell=True)
+    _ = subprocess.run(f"{editor} {file}", shell=True)
-    _ = proc.wait()
 
 
 def add_annotation_if_missing(task: Task, annotation_content: str) -> None:
@@ -191,6 +190,7 @@ you view the task.
     _ = parser.add_argument(
         "-d",
         "--notes-dir",
+        metavar="DIR",
         help="Location of topen notes files",
     )
     _ = parser.add_argument(
@@ -198,15 +198,22 @@ you view the task.
         action="store_true",
         help="Silence any verbose displayed information",
     )
-    _ = parser.add_argument("--extension", help="Extension of note files")
+    _ = parser.add_argument(
+        "--extension", metavar="EXT", help="Extension of note files"
+    )
     _ = parser.add_argument(
         "--annotation",
+        metavar="NOTE",
         help="Annotation content to set within taskwarrior",
     )
-    _ = parser.add_argument("--editor", help="Program to open note files with")
-    _ = parser.add_argument("--task-rc", help="Location of taskwarrior config file")
     _ = parser.add_argument(
-        "--task-data", help="Location of taskwarrior data directory"
+        "--editor", metavar="CMD", help="Program to open note files with"
+    )
+    _ = parser.add_argument(
+        "--task-rc", metavar="FILE", help="Location of taskwarrior config file"
+    )
+    _ = parser.add_argument(
+        "--task-data", metavar="DIR", help="Location of taskwarrior data directory"
     )
 
     p = parser.parse_args()