formatting options for current time

and small changes to popup dialogs and help menu

and update README.md

Author: jm289765

README.md

@@ -1,53 +1,72 @@
-Highlights to Obsidian is a plugin for Calibre ebook manager that formats and sends highlights to Obsidian.md markdown editor. This plugin's calibre forum post can be found [here](https://www.mobileread.com/forums/showthread.php?t=351283).
 
-After installing, go to Preferences -> Toolbars & menus -> The main toolbar. The highlights to obsidian menu button is listed as H2O.
+# Highlights to Obsidian
 
----
+Highlights to Obsidian is a plugin for the calibre ebook manager that formats and sends highlights to Obsidian.md markdown editor. This plugin [can be found](https://www.mobileread.com/forums/showthread.php?t=351283) on the calibre forum.
 
-You can update the formatting of highlights sent to Obsidian in this plugin's config menu at Preferences -> Plugins -> User interface action -> Highlights to Obsidian.
+After installing, go to Preferences -> Toolbars & menus -> The main toolbar. The Highlights to Obsidian menu button is listed as H2O.
 
-If you don't want your first time sending new highlights to Obsidian to send all highlights, update the last send time in the config.
+1. [[#Useful Info]]
+2. [[#Formatting Options]]
+3. [[#Misc]]
 
-In the formatting config menu, the 'title' is the title of the note that a highlight will be sent to. The 'body' is the text that will be sent to that note for each highlight. The 'header' will be sent to each note exactly once when you send highlights.
+## Useful Info
 
-Sometimes, if you send highlights while your obsidian vault is closed, not all highlights will be sent. If this happens, you can use the "Resend Previously Sent Highlights" function.
+- You can update the formatting of highlights sent to Obsidian in the config menu at Preferences -> Plugins -> User interface action -> Highlights to Obsidian.
 
-You can set keyboard shortcuts in Preferences -> Shortcuts -> H2O. Some available keyboard shortcuts include CTRL+S, CTRL+E, CTRL+G, CTRL+H, CTRL+J, and CTRL+K.
+- If you don't want the first time sending new highlights to send all of your highlights, you can update the last send time in the config.
 
----
+- In the formatting config menu, the 'title' is the title of the note that a highlight will be sent to. The 'body' is the text that will be sent to that note for each highlight. The 'header' will be sent to each note exactly once when you send highlights.
 
-Available formatting options are as follows:
+- In a note's title, you can include slashes "/" to specify what folder the note should be in.
 
+- Sometimes, if you send highlights while your Obsidian vault is closed, not all highlights will be sent. If this happens, you can use the "Resend Previously Sent Highlights" function.
+
+- You can set keyboard shortcuts in Preferences -> Shortcuts -> H2O.
+
+- Due to URI length limits, H2O can only send a few thousand words to a single note at once. Extra text will be sent to different notes with increasing numbers added to the end of the title.
+
+## Formatting Options
+
+For an example of how to use these, see the default format settings in the plugin's config menu.
+
+**Book:**
 - {title}: Title of the book the highlight is in.
 - {authors}: Authors of the book the highlight is in.
+- {bookid}: The book's ID in calibre. 
+
+**Highlight:**
 - {highlight}: The highlighted text.
 - {blockquote}: The highlighted text, formatted as a blockquote. an arrow and a space "> " are added to the beginning of each line.
 - {notes}: The user's notes on this highlight, if any notes exist. There is a config option that allows you to set different formatting depending on whether a highlight includes notes.
-- {date}: Date the highlight was made, formatted as YYYY-MM-DD
-- {time}: Time the highlight was made, formatted as HH:MM:SS
-- {datetime}: Date and time highlight was made, formatted as YYYY-MM-DD HH:MM:SS
-- {localdate}, {localtime}, {localdatetime}
-- {timezone}: The timezone that your computer is currently set to. Note that this may not always match the timezone the highlight was made in. This uses the full name, as in "Coordinated Universal Time", instead of the abbreviation, as in "UTC".
-- {utcoffset} or {timeoffset}: The UTC offset of your computer's current time zone. For example, UTC time gives +0:00. EST time can be -4:00 or -5:00, depending on daylight savings time.
-- {day}: Day of the month the highlight was made, as in 3 or 17
-- {month}: Month the highlight was made, as in 4 for April or 10 for October
-- {year}: Full year the highlight was made, as in 2022
-- {localday}, {localmonth}, {localyear}
-- {utcnow}: current UTC time, formatted same as {datetime}.
-- {localnow}
 - {url}: A [calibre:// url](https://manual.calibre-ebook.com/url_scheme.html) to open the ebook viewer to this highlight. Note that this may not work if your library's name contains unsafe URL characters. Numbers, letters, spaces, underscores, and hyphens are all safe.
 - {location}: The highlight's EPUB CFI location in the book. For example, "/2/8/6/5:192". As a sort key, this will order highlights by their position in the book.
-- {timestamp}: The highlight's Unix timestamp. This is the default sort key used to determine what order to send highlights in.
+- {timestamp}: The highlight's Unix timestamp. As a sort key, this will order highlights by when they were made.
+- {uuid}: The highlight's unique ID in calibre. For example, "TlNlh8_I5VGKUtqdfbOxDw".
+
+**Time:**
+- {date}: Date the highlight was made, formatted as YYYY-MM-DD.
+- {time}: Time the highlight was made, formatted as HH:MM:SS.
+- {datetime}: Date and time highlight was made, formatted as YYYY-MM-DD HH:MM:SS.
+- {day}: Day of the month the highlight was made, as in 3 or 17.
+- {month}: Month the highlight was made, as in 4 for April or 10 for October.
+- {year}: Full year the highlight was made, as in 2022.
+- {hour}: Hour the highlight was made, based on a 24-hour (not 12-hour) system.
+- {minute}: Minute the highlight was made.
+- {second}: Second the highlight was made.
+- {utcnow}: current time, formatted same as {datetime}.
+- {datenow}: Current date, formatted same as {date}.
+- {timenow}: Current time, formatted same as {time}.
+- {timezone}: The timezone that your computer is currently set to. Note that this may not always match the timezone the highlight was made in. Also note that this might use the full name "Coordinated Universal Time" instead of the abbreviation "UTC".
+- {utcoffset}: The UTC offset of your computer's current time zone. For example, UTC time gives +0:00. EST time can be -4:00 or -5:00, depending on daylight savings time.
+- All time options use UTC by default. To use your computer's local time zone instead, add "local" to the beginning: {localdate}, {localtime}, {localdatetime}, {localday}, {localmonth}, {localyear}, {localhour}, {localminute}, {localsecond}, {localnow}, {localdatenow}, {localtimenow}.
+
+**Highlights to Obsidian:**
 - {totalsent}: The total number of highlights being sent.
 - {booksent}: The total number of highlights being sent to this Obsidian note.
 - {highlightsent}: This highlight's position in the highlights being sent to this note. For example, "{highlightsent} out of {booksent}" might result in "3 out of 5".
-- {bookid}: The book's ID in calibre. 
-- {uuid}: The highlight's unique ID in calibre. For example, "TlNlh8_I5VGKUtqdfbOxDw".
-
-For an example of how to use these, see the default format settings in the plugin's config.
 
----
+## Misc
 
-Formatting options are based on the [Obsidian Clipper](https://github.com/jplattel/obsidian-clipper) Chrome extension.
+This plugin is loosely based on the [Obsidian Clipper](https://github.com/jplattel/obsidian-clipper) Chrome extension.
 
-h2o-index.txt is for the [plugin index page](https://www.mobileread.com/forums/showthread.php?t=118764) on the Calibre forum.
+The file `h2o-index.txt` is for the [plugin index page](https://www.mobileread.com/forums/showthread.php?t=118764) on the calibre forum.

h2o/button_actions.py

@@ -10,15 +10,17 @@ def help_menu(parent):
     title = "Highlights to Obsidian Help Menu"
     body = "You can update the formatting of highlights sent to Obsidian in this plugin's config menu at " + \
            "Preferences -> Plugins -> User interface action -> Highlights to Obsidian.\n\n" + \
-           "If you don't want your first time sending new highlights to Obsidian to send all highlights, " + \
+           "If you don't want the first time sending new highlights to Obsidian to send all highlights, " + \
            "update the last send time in the config.\n\n" + \
            "In the formatting config menu, the 'title' is the title of the note that a highlight will be " + \
            "sent to. The 'body' is the text that will be sent to that note for each highlight. The " + \
            "'header' will be sent to each note exactly once when you send highlights.\n\n" + \
+           "In a note's title, you can include slashes \"/\" to specify what folder the note should be in.\n\n" + \
            "Sometimes, if you send highlights while your obsidian vault is closed, not all highlights will " + \
            "be sent. If this happens, you can use the \"Resend Previously Sent Highlights\" function.\n\n" + \
-           "You can set keyboard shortcuts in Preferences -> Shortcuts -> H2O. " + \
-           "Some available keyboard shortcuts include CTRL+S, CTRL+E, CTRL+G, CTRL+H, CTRL+J, and CTRL+K."
+           "You can set keyboard shortcuts in calibre's Preferences -> Shortcuts -> H2O.\n\n" + \
+           "Due to URI length limits, H2O can only send a few thousand words to a single note at once. Extra text " \
+           "will be sent to different notes with increasing numbers added to the end of the title."
     info_dialog(parent, title, body, show=True)
 
 
@@ -59,11 +61,11 @@ def make_sender() -> HighlightSender:
             # timezone changes.
             prefs["last_send_time"] = strftime("%Y-%m-%d %H:%M:%S", gmtime())
 
-        info = f"Success: {amt} highlight{' has' if amt == 1 else 's have'} been sent to obsidian."
+        info = f"Success: {amt} highlight{' has' if amt == 1 else 's have'} been sent to Obsidian."
         if prefs['highlights_sent_dialog']:
             info_dialog(parent, "Highlights Sent", info, show=True)
     else:
-        info_dialog(parent, "No Highlights Sent", "No highlights to send.", show=True)
+        info_dialog(parent, "No Highlights Sent", "There are no highlights to send.", show=True)
 
     return amt
 
@@ -100,7 +102,7 @@ def send_all_highlights(parent, db):
     """
     if prefs['confirm_send_all']:
         confirm = QMessageBox()
-        confirm.setText("Are you sure you want to send ALL highlights to obsidian? This cannot be undone.")
+        confirm.setText("Are you sure you want to send ALL highlights to Obsidian? This cannot be undone.")
         confirm.setStandardButtons(QMessageBox.Yes | QMessageBox.No)
         confirm.setIcon(QMessageBox.Question)
         confirmed = confirm.exec()
@@ -151,7 +153,7 @@ def send_all_selected_highlights(parent, db):
 
     if prefs['confirm_send_all']:
         confirm = QMessageBox()
-        confirm.setText("Are you sure you want to send ALL highlights of the selected books to obsidian? This cannot be undone.")
+        confirm.setText("Are you sure you want to send ALL highlights of the selected books to Obsidian? This cannot be undone.")
         confirm.setStandardButtons(QMessageBox.Yes | QMessageBox.No)
         confirm.setIcon(QMessageBox.Question)
         confirmed = confirm.exec()

h2o/config.py

@@ -161,19 +161,14 @@ def make_format_info_label(self):
         # list of formatting options
         format_options = [
             "title", "authors",
-            "highlight", "blockquote",
-            "notes", "date",
-            "localdate", "time",
-            "localtime", "datetime",
-            "localdatetime", "timezone",
-            "utcoffset", "day",
-            "localday", "month",
-            "localmonth", "year",
-            "localyear", "utcnow",
-            "localnow", "url",
-            "location", "timestamp",
-            "totalsent", "booksent",
-            "highlightsent",
+            "highlight", "blockquote", "notes",
+            "date", "time", "datetime",
+            "day", "month", "year",
+            "hour", "minute", "second",
+            "utcnow", "datenow", "timenow",
+            "timezone", "utcoffset",
+            "url", "location", "timestamp",
+            "totalsent", "booksent", "highlightsent",
             "bookid", "uuid",
         ]
         f_opt_str = "'" + "', '".join(format_options) + "'"
@@ -193,8 +188,12 @@ def make_format_info_label(self):
         self.note_format_list_label = QLabel(one_str, self)
         self.l.addWidget(self.note_format_list_label)
 
-        time_note = QLabel("Note that times are the time the highlight was made, not the current time " + \
-                           "(except 'utcnow' and 'localnow').")
+        local_note = QLabel("All times use UTC by default. To use local time instead, add 'local' " +
+                            "to the beginning: {localdatetime}, {localnow}, etc.")
+        self.l.addWidget(local_note)
+
+        time_note = QLabel("Note that all times, except 'now' times, are the time the highlight was made, not the " +
+                           "current time.")
         self.l.addWidget(time_note)
 
     def save_settings(self):

h2o/highlight_sender.py

@@ -14,7 +14,8 @@
 title_default_format = "Books/{title} by {authors}"
 body_default_format = "\n[Highlighted]({url}) on {date} at {time} UTC {timeoffset}:\n{blockquote}\n\n{notes}\n\n---\n"
 no_notes_default_format = "\n[Highlighted]({url}) on {date} at {time} UTC {timeoffset}:\n{blockquote}\n\n---\n"
-header_default_format = ""  # by default, no header
+header_default_format = "\n{booksent} highlights sent to this note on {datenow} at {timenow} UTC.\n\n---\n"
+
 sort_key_default = "location"
 
 
@@ -100,16 +101,28 @@ def make_time_format_dict(data: Dict) -> Dict[str, str]:
         # https://github.com/kovidgoyal/calibre/blob/master/src/calibre/gui2/library/annotations.py#L34
         # todo: timezone currently displays "Coordinated Universal Time" instead of the abbreviation, "UTC"
         "timezone": h_local.tzname(),  # local timezone
+        "localtimezone": h_local.tzname(),  # so that the config menu's explanation doesn't confuse users
         "utcoffset": utc_offset,
+        "localoffset": utc_offset,  # so that the config menu's explanation doesn't confuse users
         "timeoffset": utc_offset,  # for backwards compatibility
         "day": str(h_time.day),
         "localday": str(h_local.day),
         "month": str(h_time.month),
         "localmonth": str(h_local.month),
         "year": str(h_time.year),
         "localyear": str(h_local.year),
+        "hour": str(h_time.hour),
+        "localhour": str(h_local.hour),
+        "minute": str(h_time.minute),
+        "localminute": str(h_local.minute),
+        "second": str(h_time.second),
+        "localsecond": str(h_local.second),
         "utcnow": time.strftime("%Y-%m-%d %H:%M:%S", utc),
+        "datenow": time.strftime("%Y-%m-%d", utc),
+        "timenow": time.strftime("%H:%M:%S", utc),
         "localnow": time.strftime("%Y-%m-%d %H:%M:%S", local),
+        "localdatenow": time.strftime("%Y-%m-%d", local),
+        "localtimenow": time.strftime("%H:%M:%S", local),
         "timestamp": str(h_time.timestamp()),  # Unix timestamp of highlight time. uses UTC.
     }
 
@@ -209,6 +222,9 @@ def make_format_dict(data, calibre_library: str, book_titles_authors: Dict[int,
 
     # formatting options are based on https://github.com/jplattel/obsidian-clipper
 
+    # todo: could be optimized by taking as input the formatting options that are needed, and then
+    #  only calculating values for those options
+
     # if you add a format option, also update the format_options local variable in config.py and the docs in README.md
     time_options = make_time_format_dict(data)
     highlight_options = make_highlight_format_dict(data, calibre_library)
@@ -383,7 +399,7 @@ def is_valid_highlight(_dat: Dict):
             if _annot.get("removed"):
                 return False  # don't try to send highlights that have been removed
 
-            if not condition(_dat):
+            if not condition(_dat):  # or return condition(_dat)
                 return False  # user-defined condition must be true for this highlight
 
             return True