diff --git a/Cargo.lock b/Cargo.lock index cd460b57..4538b4c0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -105,7 +105,7 @@ checksum = "0ae92a5119aa49cdbcf6b9f893fe4e1d98b04ccbf82ee0584ad948a44a734dea" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -220,7 +220,7 @@ checksum = "3b43422f69d8ff38f95f1b2bb76517c91589a924d1559a0e935d7c8ce0274c11" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -255,7 +255,7 @@ checksum = "c6fa2087f2753a7da8cc1c0dbfcf89579dd57458e36769de5ac750b4671737ca" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -578,7 +578,7 @@ checksum = "93698b29de5e97ad0ae26447b344c482a7284c737d9ddc5f9e52b74a336671bb" dependencies = [ "chrono", "chrono-tz-build", - "phf", + "phf 0.11.2", ] [[package]] @@ -588,8 +588,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0c088aee841df9c3041febbb73934cfc39708749bf96dc827e3359cd39ef11b1" dependencies = [ "parse-zoneinfo", - "phf", - "phf_codegen", + "phf 0.11.2", + "phf_codegen 0.11.2", ] [[package]] @@ -999,7 +999,7 @@ checksum = "de0d48a183585823424a4ce1aa132d174a6a81bd540895822eb4c8373a8e49e8" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -1092,6 +1092,20 @@ dependencies = [ "synstructure", ] +[[package]] +name = "fast_html2md" +version = "0.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dbfeb805e97290b9f4c50dd97796604ec031993f211a70b1f6741405b2950656" +dependencies = [ + "html5ever", + "jni 0.19.0", + "lazy_static", + "markup5ever_rcdom", + "percent-encoding", + "regex", +] + [[package]] name = "fastrand" version = "2.1.0" @@ -1187,7 +1201,7 @@ checksum = "1a5c6c585bc94aaf2c7b51dd4c2ba22680844aba4c687be581871a6f518c5742" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -1662,26 +1676,16 @@ dependencies = [ [[package]] name = "html5ever" -version = "0.27.0" +version = "0.26.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c13771afe0e6e846f1e67d038d4cb29998a6779f93c809212e4e9c32efd244d4" +checksum = "bea68cab48b8459f17cf1c944c67ddc572d272d9f2b274140f223ecb1da4a3b7" dependencies = [ "log", "mac", "markup5ever", "proc-macro2", "quote", - "syn 2.0.66", -] - -[[package]] -name = "htmlproc" -version = "0.3.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a237738d3b811035a3b208d75d116ad24bfd23552bbfef58b62a56a3f01b801d" -dependencies = [ - "html5ever", - "markup5ever_rcdom", + "syn 1.0.109", ] [[package]] @@ -1850,7 +1854,7 @@ checksum = "c34819042dc3d3971c46c2190835914dfbe0c3c13f61449b2997f4e9722dfa60" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -1868,6 +1872,20 @@ version = "1.0.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b" +[[package]] +name = "jni" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6df18c2e3db7e453d3c6ac5b3e9d5182664d28788126d39b91f2d1e22b017ec" +dependencies = [ + "cesu8", + "combine", + "jni-sys", + "log", + "thiserror", + "walkdir", +] + [[package]] name = "jni" version = "0.21.1" @@ -2851,13 +2869,13 @@ checksum = "3e2e65a1a2e43cfcb47a895c4c8b10d1f4a61097f9f254f183aee60cad9c651d" [[package]] name = "markup5ever" -version = "0.12.1" +version = "0.11.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "16ce3abbeba692c8b8441d036ef91aea6df8da2c6b6e21c7e14d3c18e526be45" +checksum = "7a2629bb1404f3d34c2e921f21fd34ba00b206124c81f65c50b43b6aaefeb016" dependencies = [ "log", - "phf", - "phf_codegen", + "phf 0.10.1", + "phf_codegen 0.10.0", "string_cache", "string_cache_codegen", "tendril", @@ -2865,9 +2883,9 @@ dependencies = [ [[package]] name = "markup5ever_rcdom" -version = "0.3.0" +version = "0.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "edaa21ab3701bfee5099ade5f7e1f84553fd19228cf332f13cd6e964bf59be18" +checksum = "b9521dd6750f8e80ee6c53d65e2e4656d7de37064f3a7a5d2d11d05df93839c2" dependencies = [ "html5ever", "markup5ever", @@ -2885,16 +2903,6 @@ dependencies = [ "rayon", ] -[[package]] -name = "mdka" -version = "1.2.9" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8de0aa945003ae4ef4a42b21c040e997843005f3f50fc09d5bc7cbc9c29142a0" -dependencies = [ - "html5ever", - "markup5ever_rcdom", -] - [[package]] name = "memchr" version = "2.7.4" @@ -3083,7 +3091,7 @@ checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -3383,7 +3391,7 @@ dependencies = [ "pest_meta", "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -3407,6 +3415,15 @@ dependencies = [ "indexmap", ] +[[package]] +name = "phf" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fabbf1ead8a5bcbc20f5f8b939ee3f5b0f6f281b6ad3468b84656b658b455259" +dependencies = [ + "phf_shared 0.10.0", +] + [[package]] name = "phf" version = "0.11.2" @@ -3416,6 +3433,16 @@ dependencies = [ "phf_shared 0.11.2", ] +[[package]] +name = "phf_codegen" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fb1c3a8bc4dd4e5cfce29b44ffc14bedd2ee294559a294e2a4d4c9e9a6a13cd" +dependencies = [ + "phf_generator 0.10.0", + "phf_shared 0.10.0", +] + [[package]] name = "phf_codegen" version = "0.11.2" @@ -3598,9 +3625,9 @@ dependencies = [ [[package]] name = "proc-macro2" -version = "1.0.85" +version = "1.0.86" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "22244ce15aa966053a896d1accb3a6e68469b97c7f33f284b99f0d576879fc23" +checksum = "5e719e8df665df0d1c8fbfd238015744736151d4445ec0836b8e628aae103b77" dependencies = [ "unicode-ident", ] @@ -3621,7 +3648,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8021cf59c8ec9c432cfc2526ac6b8aa508ecaf29cd415f271b8406c1b851c3fd" dependencies = [ "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -3951,9 +3978,9 @@ checksum = "61697e0a1c7e512e84a621326239844a24d8207b4669b41bc18b32ea5cbf988b" [[package]] name = "serde" -version = "1.0.203" +version = "1.0.204" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7253ab4de971e72fb7be983802300c30b5a7f0c2e56fab8abfc6a214307c0094" +checksum = "bc76f558e0cbb2a839d37354c575f1dc3fdc6546b5be373ba43d95f231bf7c12" dependencies = [ "serde_derive", ] @@ -3983,13 +4010,13 @@ dependencies = [ [[package]] name = "serde_derive" -version = "1.0.203" +version = "1.0.204" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "500cbc0ebeb6f46627f50f3f5811ccf6bf00643be300b4c3eabc0ef55dc5b5ba" +checksum = "e0cd7e117be63d3c3678776753929474f3b04a43a080c744d6b0ae2a8c28e222" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -4011,7 +4038,7 @@ checksum = "6c64451ba24fc7a6a2d60fc75dd9c83c90903b19028d4eff35e88fc1e86564e9" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -4200,7 +4227,7 @@ dependencies = [ "proc-macro2", "quote", "rustversion", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -4225,9 +4252,9 @@ dependencies = [ [[package]] name = "syn" -version = "2.0.66" +version = "2.0.68" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c42f3f41a2de00b01c0aaad383c5a45241efc8b2d1eda5661812fda5f3cdcff5" +checksum = "901fa70d88b9d6c98022e23b4136f9f3e54e4662c3bc1bd1d84a42a9a0f0c1e9" dependencies = [ "proc-macro2", "quote", @@ -4369,7 +4396,7 @@ checksum = "46c3384250002a6d5af4d114f2845d37b57521033f30d5c3f46c4d70e1197533" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -4510,7 +4537,7 @@ dependencies = [ [[package]] name = "tpnote" -version = "1.24.5" +version = "1.24.6" dependencies = [ "clipboard-rs", "directories", @@ -4533,7 +4560,7 @@ dependencies = [ "thiserror", "time", "toml 0.8.14", - "tpnote-lib 0.35.1 (registry+https://github.com/rust-lang/crates.io-index)", + "tpnote-lib 0.35.2 (registry+https://github.com/rust-lang/crates.io-index)", "webbrowser", "win32job", "windows-sys 0.52.0", @@ -4543,15 +4570,14 @@ dependencies = [ [[package]] name = "tpnote-lib" -version = "0.35.1" +version = "0.35.2" dependencies = [ + "fast_html2md", "html-escape", - "htmlproc", "latex2mathml", "lazy_static", "lingua", "log", - "mdka", "parking_lot", "parse-hyperlinks", "parse-hyperlinks-extras", @@ -4575,17 +4601,16 @@ dependencies = [ [[package]] name = "tpnote-lib" -version = "0.35.1" +version = "0.35.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "795cccf40bd6ce8bebb2c3e1a45233a6e5cfde1a405b6de0ea64b021d8a3d7a0" +checksum = "b829bb34143fa68977b3987dc0f80fb3c3f68fe3c1771891138487ff06f3e108" dependencies = [ + "fast_html2md", "html-escape", - "htmlproc", "latex2mathml", "lazy_static", "lingua", "log", - "mdka", "parking_lot", "parse-hyperlinks", "parse-hyperlinks-extras", @@ -4626,7 +4651,7 @@ checksum = "34704c8d6ebcbc939824180af020566b01a7c01f80641264eba0999f6c2b6be7" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -4868,7 +4893,7 @@ dependencies = [ "once_cell", "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", "wasm-bindgen-shared", ] @@ -4890,7 +4915,7 @@ checksum = "e94f17b526d0a461a191c78ea52bbce64071ed5c04c9ffe424dcb38f74171bb7" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", "wasm-bindgen-backend", "wasm-bindgen-shared", ] @@ -4993,7 +5018,7 @@ dependencies = [ "block2", "core-foundation", "home", - "jni", + "jni 0.21.1", "log", "ndk-context", "objc2", @@ -5098,7 +5123,7 @@ checksum = "f6fc35f58ecd95a9b71c4f2329b911016e6bec66b3f2e6a4aad86bd2e99e2f9b" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -5109,7 +5134,7 @@ checksum = "08990546bf4edef8f431fa6326e032865f27138718c587dc21bc0265bbcb57cc" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -5426,9 +5451,9 @@ checksum = "791978798f0597cfc70478424c2b4fdc2b7a8024aaff78497ef00f24ef674193" [[package]] name = "xml5ever" -version = "0.18.1" +version = "0.17.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9bbb26405d8e919bc1547a5aa9abc95cbfa438f04844f5fdd9dc7596b748bf69" +checksum = "4034e1d05af98b51ad7214527730626f019682d797ba38b51689212118d8e650" dependencies = [ "log", "mac", @@ -5491,7 +5516,7 @@ dependencies = [ "proc-macro-crate 3.1.0", "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", "zvariant_utils", ] @@ -5523,7 +5548,7 @@ checksum = "15e934569e47891f7d9411f1a451d947a60e000ab3bd24fbb970f000387d1b3b" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] [[package]] @@ -5572,7 +5597,7 @@ dependencies = [ "proc-macro-crate 3.1.0", "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", "zvariant_utils", ] @@ -5584,5 +5609,5 @@ checksum = "fc242db087efc22bd9ade7aa7809e4ba828132edc312871584a6b4391bdf8786" dependencies = [ "proc-macro2", "quote", - "syn 2.0.66", + "syn 2.0.68", ] diff --git a/Cargo.toml b/Cargo.toml index 925812d8..8d97fa28 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -15,7 +15,7 @@ license = "MIT/Apache-2.0" readme = "README.md" repository = "https://gitlab.com/getreu/tp-note" rust-version = "1.77.2" -version = "1.24.5" +version = "1.24.6" [profile.release] strip = "symbols" diff --git a/docs/build/man/man1/tpnote.1 b/docs/build/man/man1/tpnote.1 index f01b4c5d..8cb0d0ec 100644 --- a/docs/build/man/man1/tpnote.1 +++ b/docs/build/man/man1/tpnote.1 @@ -1,61 +1,61 @@ '\" t -.\" Automatically generated by Pandoc 3.1.11.1 +.\" Automatically generated by Pandoc 3.1.9 .\" -.TH "TP\-NOTE" "1" "2024\-07\-04" "Version 1.24.5" "Tp\-Note documentation" +.TH "TP-NOTE" "1" "2024-07-09" "Version 1.24.6" "Tp-Note documentation" .SH NAME -Tp\-Note: Markup enhanced granular note\-taking +Tp-Note: Markup enhanced granular note-taking .PP Save and edit your clipboard content as a note file. .SH SYNOPSIS .IP .EX -tpnote [\-a ] [\-b] [\-c ] [\-C ] [\-d ] [\-e] - [\-l ] [\-p ] [\-n] [\-t] [\-u] [\-v] [\-V] - [\-x |\[aq]\[aq]|\[aq]\-\[aq]] +tpnote [-a ] [-b] [-c ] [-C ] [-d ] [-e] + [-l ] [-p ] [-n] [-t] [-u] [-v] [-V] + [-x |\[aq]\[aq]|\[aq]-\[aq]] [|] .EE .SH DESCRIPTION -Tp\-Note is a note\-taking tool and a template system, that synchronizes +Tp-Note is a note-taking tool and a template system, that synchronizes the note\[cq]s metadata with its filename. -Tp\-Note analyses its environment and the clipboard content and stores +Tp-Note analyses its environment and the clipboard content and stores the result in variables. New notes are created by filling these variables in predefined and -customizable \f[I]Tera\f[R]\-templates. +customizable \f[I]Tera\f[R]-templates. In case the first positional parameter `\f[CR]\f[R]' points to an -existing Tp\-Note file, the note\[cq]s metadata is parsed and, if +existing Tp-Note file, the note\[cq]s metadata is parsed and, if necessary, its filename is adjusted. -For all other file types, Tp\-Note creates a new note in the same +For all other file types, Tp-Note creates a new note in the same directory annotating the file. If the positional parameter `\f[CR]\f[R]' points to an existing directory (or, when omitted, the current working directory), a new note is created in that directory. -After creation, Tp\-Note launches the systems file editor. +After creation, Tp-Note launches the systems file editor. Although the configurable default templates are written for Markdown, -Tp\-Note is not tied to any specific markup language. -However, Tp\-Note comes with an optional viewer feature, that currently +Tp-Note is not tied to any specific markup language. +However, Tp-Note comes with an optional viewer feature, that currently renders only Markdown, ReStructuredText and HTML input. In addition, there is some limited support for Asciidoc and WikiText. Finally, the note\[cq]s rendition is live updated and displayed in the user\[cq]s web browser. .PP -After the user finished editing, Tp\-Note analyses potential changes in +After the user finished editing, Tp-Note analyses potential changes in the notes metadata and renames, if necessary, the file, so that its metadata and filename are in sync again. Finally, the resulting path is printed to `\f[CR]stdout\f[R]', log and error messages are dumped to `\f[CR]stderr\f[R]'. .PP -This document is Tp\-Note\[cq]s technical reference. +This document is Tp-Note\[cq]s technical reference. More information can be found in \c .UR https://blog.getreu.net/projects/tp-note/tpnote--manual.html -Tp\-Note\[cq]s user manual +Tp-Note\[cq]s user manual .UE \c \ and at \c .UR https://blog.getreu.net/projects/tp-note/ -Tp\-Note\[cq]s project page +Tp-Note\[cq]s project page .UE \c \&. .SH CREATING NOTE FILES -Tp\-Note operates in 5 different modes, depending on its command line +Tp-Note operates in 5 different modes, depending on its command line arguments and the clipboard state. Each mode is associated with one content template and one filename template. @@ -66,7 +66,7 @@ with the templates: `\f[CR]tmpl.from_dir_content\f[R]' and By default, the new note\[cq]s title is the parent\[cq]s directory name. The newly created file is then opened with an external text editor, allowing it to change the proposed title and add other content. -When the text editor closes, Tp\-Note synchronizes the note\[cq]s +When the text editor closes, Tp-Note synchronizes the note\[cq]s metadata and its filename. This operation is performed with the `\f[CR]tmpl.sync_filename\f[R]' template. @@ -75,32 +75,32 @@ Example: the clipboard is empty and `\f[CR]\f[R]' is a directory (or empty): .IP .EX -tpnote \[dq]./03\-Favorite Readings/\[dq] +tpnote \[dq]./03-Favorite Readings/\[dq] .EE .PP or .IP .EX -cd \[dq]./03\-Favorite Readings\[dq] +cd \[dq]./03-Favorite Readings\[dq] tpnote .EE .PP creates the document: .IP .EX -\&./03\-Favorite Readings/20211031\-Favorite Readings\-\-Note.md +\&./03-Favorite Readings/20211031-Favorite Readings--Note.md .EE .PP with the content: .IP .EX -\-\-\- +--- title: Favorite Readings subtitle: Note author: Getreu -date: 2021\-10\-31 -lang: en\-GB -\-\-\- +date: 2021-10-31 +lang: en-GB +--- .EE .SS Create a new note based on clipboard data When `\f[CR]\f[R]' is a directory and the clipboard is not empty, @@ -117,7 +117,7 @@ The new note is then created with the `\f[CR]tmpl.from_clipboard_filename\f[R]' templates. Finally, the newly created note file is opened again with some external text editor. -When the user closes the text editor, Tp\-Note synchronizes the +When the user closes the text editor, Tp-Note synchronizes the note\[cq]s metadata and its filename with the template `\f[CR]tmpl.sync_filename\f[R]'. .PP @@ -145,50 +145,50 @@ When no mouse and clipboard is available, the clipboard feature can be simulated by feeding the clipboard data into \f[CR]stdin\f[R]. .IP .EX -echo \[dq][The Rust Book]()\[dq] | tpnote +echo \[dq][The Rust Book]()\[dq] | tpnote .EE .PP -Tp\-Note behaves here as if the clipboard contained the string: -\[lq]\f[CR][The Rust Book]()\f[R]\[rq]. +Tp-Note behaves here as if the clipboard contained the string: +\[lq]\f[CR][The Rust Book]()\f[R]\[rq]. .PP -When you pipe HTML into Tp\-Note, make sure that the stream starts with +When you pipe HTML into Tp-Note, make sure that the stream starts with either `\f[CR]

Hello World

\[aq]| tpnote .EE .SS The clipboard contains a string -Example: While launching Tp\-Note the clipboard contains the string: +Example: While launching Tp-Note the clipboard contains the string: \[lq]\f[CR]Who Moved My Cheese?\[rs]n\[rs]nChapter 2\f[R]\[rq] and `\f[CR]\f[R]' is a directory. .IP .EX -tpnote \[dq]./03\-Favorite Readings/\[dq] +tpnote \[dq]./03-Favorite Readings/\[dq] .EE .PP Or: .IP .EX -cd \[dq]./03\-Favorite Readings/\[dq] +cd \[dq]./03-Favorite Readings/\[dq] tpnote .EE .PP This creates the document: .IP .EX -\&./03\-Favorite Readings/20211031\-Who Moved My Cheese\-\-Note.md +\&./03-Favorite Readings/20211031-Who Moved My Cheese--Note.md .EE .PP with the content: .IP .EX -\-\-\- +--- title: Who Moved My Cheese subtitle: Note author: Getreu -date: 2021\-10\-31 -lang: en\-GB -\-\-\- +date: 2021-10-31 +lang: en-GB +--- Who Moved My Cheese? @@ -202,7 +202,7 @@ header\[cq]s `\f[CR]title:\f[R]' field. Then, it copies the entire clipboard content into the body of the document. However, if desired or necessary, it is possible to modify all templates -in Tp\-Note\[cq]s configuration file. +in Tp-Note\[cq]s configuration file. Note, that not only the note\[cq]s content is created with a template, but also its filename: The `\f[CR]tmpl.from_clipboard_filename\f[R]' filename template concatenates the current date, the note\[cq]s title @@ -210,58 +210,58 @@ and subtitle. .SS The clipboard contains a hyperlink Example: `\f[CR]\f[R]' is a directory, the clipboard is not empty and it contains the string: -`\f[CR]I recommend:\[rs]n[The Rust Book](https://doc.rust\-lang.org/book/)\f[R]'. +`\f[CR]I recommend:\[rs]n[The Rust Book](https://doc.rust-lang.org/book/)\f[R]'. .IP .EX tpnote \[aq]./doc/Lecture 1\[aq] .EE .PP -Tp\-Note\[cq]s templates `\f[CR]tmpl.from_clipboard_content\f[R]' and +Tp-Note\[cq]s templates `\f[CR]tmpl.from_clipboard_content\f[R]' and `\f[CR]tmpl.from_clipboard_filename\f[R]' create the following document: .IP .EX -\&./doc/Lecture 1/20211031\-The Rust Book\-\-Notes.md +\&./doc/Lecture 1/20211031-The Rust Book--Notes.md .EE .IP .EX -\-\-\- +--- title: The Rust Book subtitle: URL author: Getreu -date: 2021\-10\-31 -lang: en\-GB -\-\-\- +date: 2021-10-31 +lang: en-GB +--- I recommend: -[The Rust Book]() +[The Rust Book]() .EE .PP -When analysing the clipboard\[cq]s content, Tp\-Note searches for +When analysing the clipboard\[cq]s content, Tp-Note searches for hyperlinks in Markdown, ReStructuredText, Asciidoc and HTML format. When successful, the content template uses the link text of the first hyperlink found as document title. .SS The clipboard contains a string with a YAML header Example: `\f[CR]\f[R]' is a directory, the clipboard is not empty and contains the string: -`\f[CR]\-\-\-\[rs]ntitle: Todo\[rs]nfile_ext: mdtxt\[rs]n\-\-\-\[rs]nnothing\f[R]'. +`\f[CR]---\[rs]ntitle: Todo\[rs]nfile_ext: mdtxt\[rs]n---\[rs]nnothing\f[R]'. .IP .EX tpnote .EE .PP -This creates the note: `\f[CR]20230915\-Todo.mdtxt\f[R]' with the +This creates the note: `\f[CR]20230915-Todo.mdtxt\f[R]' with the following content: .IP .EX -\-\-\- +--- title: Todo subtitle: Note author: Getreu -date: 2023\-09\-15 -lang: fr\-FR +date: 2023-09-15 +lang: fr-FR file_ext: mdtxt -\-\-\- +--- nothing .EE @@ -278,41 +278,41 @@ Note, that the same result can also be achieved without clipboard input by typing in a terminal: .IP .EX -echo \-e \[dq]\-\-\-\[rs]ntitle: Todo\[rs]nfile_ext: mdtxt\[rs]n\-\-\-\[rs]n\[rs]nnothing\[dq] | tpnote +echo -e \[dq]---\[rs]ntitle: Todo\[rs]nfile_ext: mdtxt\[rs]n---\[rs]n\[rs]nnothing\[dq] | tpnote .EE .PP Furthermore, this operation mode is very handy with pipes in general, as shows the following example: it downloads some webpage, converts it to -Markdown and copies the result into a Tp\-Note file. +Markdown and copies the result into a Tp-Note file. The procedure preserves the webpage\[cq]s title in the note\[cq]s title: .IP .EX curl \[aq]https://blog.getreu.net\[aq] \[rs] -| pandoc \-\-standalone \-f html \-t markdown_strict+yaml_metadata_block \[rs] +| pandoc --standalone -f html -t markdown_strict+yaml_metadata_block \[rs] | tpnote .EE .PP creates the note file -`\f[CR]20230919\-Jens Getreu\[aq]s blog\-\-Note.md\f[R]' with the +`\f[CR]20230919-Jens Getreu\[aq]s blog--Note.md\f[R]' with the webpage\[cq]s content converted to Markdown: .IP .EX -\-\-\- +--- title: Jens Getreu\[aq]s blog subtitle: Note author: Getreu -date: 2023\-09\-15 +date: 2023-09-15 lang: en -viewport: width=device\-width, initial\-scale=1.0, maximum\-scale=1 -\-\-\- +viewport: width=device-width, initial-scale=1.0, maximum-scale=1 +--- Jens Getreu\[aq]s blog -\- [Home](https://blog.getreu.net) -\- [Categories](https://blog.getreu.net/categories) +- [Home](https://blog.getreu.net) +- [Categories](https://blog.getreu.net/categories) .EE -.SS Create a new note annotating a non Tp\-Note file +.SS Create a new note annotating a non Tp-Note file When `\f[CR]\f[R]' points to an existing file, whose file extension is other than `\f[CR].md\f[R]', a new note is created with a similar filename and a reference to the original file is copied into the @@ -322,7 +322,7 @@ The logic of this is implemented in the templates: `\f[CR]tmpl.annotate_file_content\f[R]' and `\f[CR]tmpl.annotate_file_filename\f[R]'. Once the file is created, it is opened with an external text editor. -After editing the file, it will be \- if necessary \- renamed to be in +After editing the file, it will be - if necessary - renamed to be in sync with the note\[cq]s metadata. .PP Example: @@ -336,73 +336,73 @@ tpnote \[dq]Classic Shell Scripting.pdf\[dq] creates the note: .IP .EX -Classic Shell Scripting.pdf\-\-Note.md\[dq] +Classic Shell Scripting.pdf--Note.md\[dq] .EE .PP with the content: .IP .EX -\-\-\- +--- title: Classic Shell Scripting.pdf subtitle: Note author: Getreu -date: 2023\-09\-15 -lang: en\-US -\-\-\- +date: 2023-09-15 +lang: en-US +--- [Classic Shell Scripting.pdf]() .EE .PP The configuration file variable `\f[CR]filename.extensions\f[R]' list -all the file extensions that Tp\-Note recognizes as own file types. +all the file extensions that Tp-Note recognizes as own file types. Only foreign file types can be annotated. .PP Note that the file annotation mode also reads the clipboard\[cq]s content: when it is not empty, its data is appended to the new note\[cq]s body. -.SS Convert a text file into a Tp\-Note file +.SS Convert a text file into a Tp-Note file Consider the content of the following text file -`\f[CR]Ascii\-Hangman\-\-A game for children.md\f[R]' whose creation -date is 13 March 2022: +`\f[CR]Ascii-Hangman--A game for children.md\f[R]' whose creation date +is 13 March 2022: .IP .EX A little game designed for primary kids to revise vocabulary in classroom. .EE .PP -To convert the text file into a Tp\-Note file type: +To convert the text file into a Tp-Note file type: .IP .EX -tpnote \-\-add\-header \-\-batch \[dq]Ascii\-Hangman\-\-A game for children.md\[dq] +tpnote --add-header --batch \[dq]Ascii-Hangman--A game for children.md\[dq] .EE .PP -NB: the `\f[CR]\-\-add\-header\f[R]' flag is actually not necessary, as -it is enabled by default through the configuration file variable +NB: the `\f[CR]--add-header\f[R]' flag is actually not necessary, as it +is enabled by default through the configuration file variable `\f[CR]arg_default.add_header = true\f[R]'. .PP -As a result of the above command, Tp\-Note converts the filename into: +As a result of the above command, Tp-Note converts the filename into: .IP .EX -20220313\-Ascii\-Hangman\-\-A game for children.md +20220313-Ascii-Hangman--A game for children.md .EE .PP and prepends a YAML header to the file\[cq]s content: .IP .EX -\-\-\- -title: Ascii\-Hangman +--- +title: Ascii-Hangman subtitle: A game for children author: Getreu -date: 2022\-03\-13 -lang: en\-US +date: 2022-03-13 +lang: en-US -orig_name: Ascii\-Hangman\-\-A game for children.md -\-\-\- +orig_name: Ascii-Hangman--A game for children.md +--- A little game designed for primary kids to revise vocabulary in classroom. .EE -.SS Use Tp\-Note in shell scripts +.SS Use Tp-Note in shell scripts .IP \[bu] 2 -\f[B]Use case: download a webpage and store it as Tp\-Note file\f[R] +\f[B]Use case: download a webpage and store it as Tp-Note file\f[R] .RS 2 .PP Using the method displayed above you can save time and create a script @@ -419,15 +419,15 @@ Insert the following content: curl \[dq]$1\[dq] | tpnote .EE .PP -Instead of Tp\-Note\[cq]s internal HTML to Markdown converter, you can +Instead of Tp-Note\[cq]s internal HTML to Markdown converter, you can alternatively use the external `\f[CR]pandoc\f[R]' converter. This method offers the advantage to also convert the HTML page\[cq]s metadata. -Currently, Tp\-Note\[cq]s internal converter lacks this feature. +Currently, Tp-Note\[cq]s internal converter lacks this feature. .IP .EX #!/bin/sh -curl \[dq]$1\[dq] | pandoc \-\-standalone \-f html \-t markdown_strict+yaml_metadata_block | tpnote +curl \[dq]$1\[dq] | pandoc --standalone -f html -t markdown_strict+yaml_metadata_block | tpnote .EE .PP Do not forget to make it runnable: @@ -444,27 +444,27 @@ download \[aq]https://blog.getreu.net\[aq] .RE .SH NOTE FILE MANIPULATION .SS Editing notes -Unless invoked with `\f[CR]\-\-batch\f[R]' or `\f[CR]\-\-view\f[R]', -Tp\-Note launches an external text editor after creating a new note. +Unless invoked with `\f[CR]--batch\f[R]' or `\f[CR]--view\f[R]', Tp-Note +launches an external text editor after creating a new note. This also happens when `\f[CR]\f[R]' points to an existing -`\f[CR].md\f[R]'\-file. +`\f[CR].md\f[R]'-file. .PP Example: edit the note from the previous example: .IP .EX -cd \[dq]./03\-Favorite Readings\[dq] -tpnote 20211031\-Favorite Readings\-\-Note.md +cd \[dq]./03-Favorite Readings\[dq] +tpnote 20211031-Favorite Readings--Note.md .EE .SS Viewing notes -Once Tp\-Note has launched the user\[cq]s file editor, it opens the note +Once Tp-Note has launched the user\[cq]s file editor, it opens the note file, renders its content to HTML, launches the user\[cq]s web browser -and connects it to Tp\-Note\[cq]s internal web server. -Then, Tp\-Note watches the note file and re\-renders the viewed HTML -when the content changes. +and connects it to Tp-Note\[cq]s internal web server. +Then, Tp-Note watches the note file and re-renders the viewed HTML when +the content changes. The note\[cq]s file extension determines which internal renderer is activated. .PP -Tp\-Note\[cq]s note built\-in viewer comprises three markup language +Tp-Note\[cq]s note built-in viewer comprises three markup language renders: .IP \[bu] 2 `\f[CR]Markdown\f[R]'_ (file extension \f[CR].md\f[R]) @@ -514,16 +514,16 @@ The purpose of this renderer is to make hyperlinks written in Markdown, ReStructuredText, Asciidoc, HTML, Wikitext syntax clickable. Only hyperlinks are rendered, all other text is shown verbatim. .PP -Tp\-Note\[cq]s webserver streams large media files without loading them +Tp-Note\[cq]s webserver streams large media files without loading them into memory. Just refer to the media file as local link: `\f[CR][my video]()\f[R]'. Make sure, that the file extension of the video file is registered with `\f[CR]viewer.served_mime_types\f[R]'. .SS Automatic filename synchronization before and after editing -Before launching the text editor and after closing it, Tp\-Note +Before launching the text editor and after closing it, Tp-Note synchronizes the filename with the note\[cq]s metadata. -When the user changes the metadata of a note, Tp\-Note will replicate +When the user changes the metadata of a note, Tp-Note will replicate that change in the note\[cq]s filename. As a result, \f[I]all your note\[cq]s filenames always correspond to their metadata\f[R], which helps to retrieve your notes in large data @@ -532,39 +532,39 @@ pools. Example: .IP .EX -tpnote \[dq]20200306\-Favorite Readings\-\-Note.md\[dq] +tpnote \[dq]20200306-Favorite Readings--Note.md\[dq] .EE .PP -The way how Tp\-Note synchronizes the note\[cq]s metadata and filename -is defined in the template `\f[CR]tmpl.sync_filename\f[R]'. +The way how Tp-Note synchronizes the note\[cq]s metadata and filename is +defined in the template `\f[CR]tmpl.sync_filename\f[R]'. .PP -Once Tp\-Note opens the file in your text editor, let\[cq]s assume you +Once Tp-Note opens the file in your text editor, let\[cq]s assume you decide to change the title in the note\[cq]s YAML metadata section from `\f[CR]title: Favorite Readings\f[R]' to `\f[CR]title: Introduction to bookkeeping\f[R]'. -After closing the text editor, Tp\-Note updates the filename +After closing the text editor, Tp-Note updates the filename automatically: .IP .EX -20200306\-Introduction to bookkeeping\-\-Note.md +20200306-Introduction to bookkeeping--Note.md .EE .PP Note: the sort tag `\f[CR]20200306\f[R]' has not changed. The filename synchronization mechanism by default never does. (See below for more details about filename synchronization). .SS Printing note files -Tp\-Note renders note files to HTML. +Tp-Note renders note files to HTML. The latter is either shown in the browser or can be exported with -`\f[CR]\-\-export\f[R]'. +`\f[CR]--export\f[R]'. When exporting to HTML, hyperlinks are passed through an internal link rewriting engine that can be parametrized with -`\f[CR]\-\-export\-link\-rewriting\f[R]'. +`\f[CR]--export-link-rewriting\f[R]'. The easiest way to print the resulting HTML, is to pipe it through an HTML to PDF converter, e.g.\ \f[I]weasyprint\f[R] or \f[I]wkhtmktopdf\f[R]. .IP .EX -tpnote \-\-export=\- mynote.md | weasyprint \- mynote.md.pdf +tpnote --export=- mynote.md | weasyprint - mynote.md.pdf .EE .PP I prefer \f[I]weasyprint\f[R] over \f[I]wkhtmltopdf\f[R] because the @@ -577,7 +577,7 @@ CSS Paged Media You can change the default page layout by modifying the HTML template with the `\f[CR]tmpl_html.exporter_doc_css\f[R]' configuration file variable. -.SS Use Tp\-Note in shell scripts +.SS Use Tp-Note in shell scripts .IP \[bu] 2 \f[B]Use case: synchronize recursively filenames and metadata\f[R] .RS 2 @@ -586,7 +586,7 @@ The following synchronizes bidirectionally all filenames with the note\[cq]s YAML header data. .IP .EX -TPNOTE_USER=\[dq]John\[dq] find . \-type f \-name \[aq]*.md\[aq] \-exec tpnote \-a \-b {} > /dev/null \[rs]; +TPNOTE_USER=\[dq]John\[dq] find . -type f -name \[aq]*.md\[aq] -exec tpnote -a -b {} > /dev/null \[rs]; .EE .PP The direction of the synchronization depends on whether the @@ -594,32 +594,32 @@ The direction of the synchronization depends on whether the .IP \[bu] 2 A YAML header is present and valid: the header fields might update the filename (see template `\f[CR]tmpl.sync_filename\f[R]'). -A possible \f[I]sort\-tag\f[R] at the beginning of the filename remains +A possible \f[I]sort-tag\f[R] at the beginning of the filename remains untouched. .IP \[bu] 2 No YAML header: a new header is prepended (see template `\f[CR]from_text_file_content\f[R]') and the filename might change slightly (see template `\f[CR]from_text_file_filename\f[R]'). -A possible \f[I]sort\-tag\f[R] at the beginning of the filename remains +A possible \f[I]sort-tag\f[R] at the beginning of the filename remains untouched. If the filename does not start with a sort tag, the file\[cq]s creation date is prepended. .RE .SH OPTIONS -\f[B]\-a\f[R], \f[B]\-\-add\-header\f[R] +\f[B]-a\f[R], \f[B]--add-header\f[R] .RS .PP Prepends a YAML header in case the text file does not have one. The default template, deduces the `\f[CR]title:\f[R]' and `\f[CR]subtitle:\f[R]' header field from the filename. -It\[cq]s sort\-tag and file extension remain untouched. -In case the filename is lacking a \f[I]sort\-tag\f[R], the file creation +It\[cq]s sort-tag and file extension remain untouched. +In case the filename is lacking a \f[I]sort-tag\f[R], the file creation date in numerical format is prepended. As this option is activated by default, it has no effect unless you set `\f[CR]arg_default.add_header = false\f[R]' in the configuration file. .RE .PP -\f[B]\-b\f[R], \f[B]\-\-batch\f[R] +\f[B]-b\f[R], \f[B]--batch\f[R] .RS .PP Do not launch the external text editor or viewer. @@ -629,29 +629,28 @@ alert windows pop up. .RE .RS .PP -Tp\-Note ignores the clipboard when run in batch mode with -`\f[CR]\-\-batch\f[R]'. +Tp-Note ignores the clipboard when run in batch mode with +`\f[CR]--batch\f[R]'. Instead, if available, it reads the \f[CR]stdin\f[R] stream as if the data came from the clipboard. .RE .PP -\f[B]\-c\f[R] \f[I]FILE\f[R], \f[B]\-\-config\f[R]=\f[I]FILE\f[R] +\f[B]-c\f[R] \f[I]FILE\f[R], \f[B]--config\f[R]=\f[I]FILE\f[R] .RS .PP Loads an additional configuration from the TOML formatted \f[I]FILE\f[R] and merges it into the default configuration. .RE .PP -\f[B]\-C\f[R] \f[I]FILE\f[R], -\f[B]\-\-config\-defaults\f[R]=\f[I]FILE\f[R] +\f[B]-C\f[R] \f[I]FILE\f[R], \f[B]--config-defaults\f[R]=\f[I]FILE\f[R] .RS .PP Dumps the internal default configuration in TOML format into -\f[I]FILE\f[R] or stdout if \f[I]FILE\f[R] equals to `\f[CR]\-\f[R]', -e.g.\ `\f[CR]tpnote \-C \- | less\f[R]'. +\f[I]FILE\f[R] or stdout if \f[I]FILE\f[R] equals to `\f[CR]-\f[R]', +e.g.\ `\f[CR]tpnote -C - | less\f[R]'. .RE .PP -\f[B]\-d\f[R] \f[I]LEVEL\f[R], \f[B]\-\-debug\f[R]=\f[I]LEVEL\f[R] +\f[B]-d\f[R] \f[I]LEVEL\f[R], \f[B]--debug\f[R]=\f[I]LEVEL\f[R] .RS .PP Prints additional log messages. @@ -665,36 +664,35 @@ might be available or work as expected. .RE .RS .PP -Use `\f[CR]\-b \-d trace\f[R]' for debugging templates and -`\f[CR]\-V \-b \-d trace\f[R]' for debugging configuration files. +Use `\f[CR]-b -d trace\f[R]' for debugging templates and +`\f[CR]-V -b -d trace\f[R]' for debugging configuration files. If the HTTP server (viewer) does not work as expected: -`\f[CR]\-n \-d debug\f[R]'. +`\f[CR]-n -d debug\f[R]'. If your text editor does not open as expected: -`\f[CR]\-n \-d info \-\-edit\f[R]'. +`\f[CR]-n -d info --edit\f[R]'. Or, to observe the launch of the web browser: -`\f[CR]\-n \-d info \-\-view\f[R]'. -The option `\f[CR]\-d trace\f[R]' shows all available template -variables, the templates used and the rendered result of the -substitution. +`\f[CR]-n -d info --view\f[R]'. +The option `\f[CR]-d trace\f[R]' shows all available template variables, +the templates used and the rendered result of the substitution. This is particularly useful for debugging new templates. -The option `\f[CR]\-d off\f[R]' silences all error message reporting and -also suppresses the error pop\-up windows. +The option `\f[CR]-d off\f[R]' silences all error message reporting and +also suppresses the error pop-up windows. .RE .RS .PP -Note, under Linux, when \f[CR]\-d trace\f[R] is given, no pop\-up -messages appear. +Note, under Linux, when \f[CR]-d trace\f[R] is given, no pop-up messages +appear. Instead, the logs are dumped to the console from where you started -Tp\-Note. +Tp-Note. .RE .RS .PP All error messages are dumped in the error stream \f[CR]stderr\f[R] and -appear on the console from where Tp\-Note was launched: +appear on the console from where Tp-Note was launched: .RE .IP .EX - tpnote.exe \-\-debug info my_note.md + tpnote.exe --debug info my_note.md .EE .RS .PP @@ -702,7 +700,7 @@ Under Windows the output must be redirected into a file to see it: .RE .IP .EX - tpnote.exe \-\-debug info my_note.md >debug.md 2>&1 + tpnote.exe --debug info my_note.md >debug.md 2>&1 .EE .RS .PP @@ -711,7 +709,7 @@ windows. .RE .IP .EX - tpnote.exe \-\-popup \-\-debug info my_note.md + tpnote.exe --popup --debug info my_note.md .EE .RS .PP @@ -732,29 +730,29 @@ The value for `\f[CR]arg_default.debug\f[R]' must be one out of They have the same meaning as the corresponding command line options. .RE .PP -\f[B]\-e\f[R], \f[B]\-\-edit\f[R] +\f[B]-e\f[R], \f[B]--edit\f[R] .RS .PP Edit only mode: opens the external text editor, but not the file viewer. -This disables Tp\-Note\[cq]s internal file watcher and web server, -unless `\f[CR]\-v\f[R]' is given. +This disables Tp-Note\[cq]s internal file watcher and web server, unless +`\f[CR]-v\f[R]' is given. Alternatively you can set the environment variable `\f[CR]TPNOTE_BROWSER=\[dq]\[dq]\f[R]' to the empty string. Another way to permanently disable the web server is to set the configuration variable `\f[CR]arg_default.edit=true\f[R]'. -When `\f[CR]\-\-edit \-\-view\f[R]' appear together, both the editor and -the viewer will open and the \f[CR]arg_default.edit\f[R] variable is +When `\f[CR]--edit --view\f[R]' appear together, both the editor and the +viewer will open and the \f[CR]arg_default.edit\f[R] variable is ignored. .RE .PP -\f[B]\-l\f[R] \f[I]LANGUAGE_TAG\f[R], -\f[B]\-\-force\-lang\f[R]=\f[I]LANGUAGE_TAG\f[R] +\f[B]-l\f[R] \f[I]LANGUAGE_TAG\f[R], +\f[B]--force-lang\f[R]=\f[I]LANGUAGE_TAG\f[R] .RS .PP Disables the automatic language detection while creating a new note file and use \f[I]LANGUAGE_TAG\f[R] instead. \f[I]LANGUAGE_TAG\f[R] is formatted as IETF BCP 47 language tag, -e.g.\ `\f[CR]en\-US\f[R]'. +e.g.\ `\f[CR]en-US\f[R]'. If \f[I]LANGUAGE_TAG\f[R] equals `\[ga]\f[CR]\[aq], the environment variable \[aq]\f[R]TPNOTE_LANG\[ga]' determines the language instead; or, if the latter is not defined, the @@ -762,7 +760,7 @@ user\[cq]s default language, as reported from the operating system\[cq]s locale setting, is decisive. .RE .PP -\f[B]\-p\f[R] \f[I]PORT\f[R], \f[B]\-\-port\f[R]=\f[I]PORT\f[R] +\f[B]-p\f[R] \f[I]PORT\f[R], \f[B]--port\f[R]=\f[I]PORT\f[R] .RS .PP Sets the server port that the web browser connects to, to the specified @@ -770,20 +768,20 @@ value \f[I]PORT\f[R]. If not given, a random available port is chosen automatically. .RE .PP -\f[B]\-n\f[R], \f[B]\-\-no\-filename\-sync\f[R] +\f[B]-n\f[R], \f[B]--no-filename-sync\f[R] .RS .PP -Whenever Tp\-Note opens a note file, it synchronizes its YAML\-metadata +Whenever Tp-Note opens a note file, it synchronizes its YAML-metadata with its filename. -`\f[CR]\-\-no\-filename\-sync\f[R]' disables this synchronization. +`\f[CR]--no-filename-sync\f[R]' disables this synchronization. In addition, in scripts this flag can be especially useful for -validating the syntax of `\f[CR].md\f[R]'\-files. +validating the syntax of `\f[CR].md\f[R]'-files. See section EXIT STATUS for more details. The section METADATA FILENAME SYNCHRONIZATION shows alternative ways to disable synchronization. .RE .PP -\f[B]\-s\f[R] \f[I]PORT\f[R], \f[B]\-\-scheme\f[R]=\f[I]SCHEME_NAME\f[R] +\f[B]-s\f[R] \f[I]PORT\f[R], \f[B]--scheme\f[R]=\f[I]SCHEME_NAME\f[R] .RS .PP Sets the filename scheme for creating a new note file. @@ -794,79 +792,77 @@ The default configuration ships two schemes with the SCHEME_NAMES `\f[CR]default\f[R]' and `\f[CR]zettel\f[R]' (for Zettelkasten). .RE .PP -\f[B]\-t\f[R], \f[B]\-\-tty\f[R] +\f[B]-t\f[R], \f[B]--tty\f[R] .RS .PP -Tp\-Note tries different heuristics to detect whether a graphic +Tp-Note tries different heuristics to detect whether a graphic environment is available or not. For example, under Linux, the `\f[CR]DISPLAY\f[R]' environment variable is evaluated. -The `\f[CR]\-\-tty\f[R]' flag disables the automatic detection and sets -Tp\-Note into \[lq]console only\[rq] mode: now only the non GUI editor +The `\f[CR]--tty\f[R]' flag disables the automatic detection and sets +Tp-Note into \[lq]console only\[rq] mode: now only the non GUI editor (see configuration variable: `\f[CR]app_args.editor_console\f[R]') and no viewer is launched. .RE .PP -\f[B]\-u\f[R], \f[B]\-\-popup\f[R] +\f[B]-u\f[R], \f[B]--popup\f[R] .RS .PP Redirects log file entries into popup alert windows. -Must be used together with the \f[B]\-\-debug\f[R] option to have an +Must be used together with the \f[B]--debug\f[R] option to have an effect. Note, that debug level `\f[CR]error\f[R]' conditions will always trigger -popup messages, regardless of \f[B]\-\-popup\f[R] and -\f[B]\-\-debug\f[R] (unless `\f[CR]\-\-debug off\f[R]'). -Popup alert windows are queued and will never interrupt Tp\-Note. +popup messages, regardless of \f[B]--popup\f[R] and \f[B]--debug\f[R] +(unless `\f[CR]--debug off\f[R]'). +Popup alert windows are queued and will never interrupt Tp-Note. To better associate a particular action with its log events, read through all upcoming popup alert windows until they fail to appear. .RE .PP -\f[B]\-v\f[R], \f[B]\-\-view\f[R] +\f[B]-v\f[R], \f[B]--view\f[R] .RS .PP View only mode: do not open the external text editor. -This flag instructs Tp\-Note to start an internal file watcher and web +This flag instructs Tp-Note to start an internal file watcher and web server and connect the system\[cq]s default web browser to view the note file and to observe live file modifications. The configuration setting `\f[CR]arg_default.edit=true\f[R]' or the environment variable `\f[CR]TPNOTE_EDITOR=\[dq]\[dq]\f[R]' disables the viewer. -However, with `\f[CR]\-\-view\f[R]' given at the command line, the -viewer appears, regardless of the value of -`\f[CR]arg_default.edit\f[R]'. +However, with `\f[CR]--view\f[R]' given at the command line, the viewer +appears, regardless of the value of `\f[CR]arg_default.edit\f[R]'. .RE .RS .PP -NB: By default, Tp\-Note tries to synchronize every file it opens. -To prevent the viewed filename from changing, `\f[CR]\-\-view\f[R]' can -be used together with `\f[CR]\-\-no\-filename\-sync\f[R]'. +NB: By default, Tp-Note tries to synchronize every file it opens. +To prevent the viewed filename from changing, `\f[CR]--view\f[R]' can be +used together with `\f[CR]--no-filename-sync\f[R]'. .RE .PP -\f[B]\-V\f[R], \f[B]\-\-version\f[R] +\f[B]-V\f[R], \f[B]--version\f[R] .RS .PP -Print Tp\-Note\[cq]s version, its built\-in features and the path to the +Print Tp-Note\[cq]s version, its built-in features and the path to the sourced configuration file. The output is YAML formatted for further automatic processing. -In addition, use `\f[CR]\-V \-b \-d trace\f[R]' for configuration file +In addition, use `\f[CR]-V -b -d trace\f[R]' for configuration file debugging. .RE .PP -\f[B]\-x\f[R] \f[I]DIRECTORY\f[R], -\f[B]\-\-export\f[R]=\f[I]DIRECTORY\f[R] +\f[B]-x\f[R] \f[I]DIRECTORY\f[R], \f[B]--export\f[R]=\f[I]DIRECTORY\f[R] .RS .PP Prints the note as HTML rendition into \f[I]DIRECTORY\f[R]. -`\f[CR]\-x \-\f[R]' prints to \f[I]stdout\f[R]. -The empty string, e.g.\ `\f[CR]\-\-export=\f[R]' or -`\f[CR]\-x \[dq]\[dq]\f[R]', defaults to the directory where the note +`\f[CR]-x -\f[R]' prints to \f[I]stdout\f[R]. +The empty string, e.g.\ `\f[CR]--export=\f[R]' or +`\f[CR]-x \[dq]\[dq]\f[R]', defaults to the directory where the note file resides. No external text editor or viewer is launched. -Can be combined with `\f[CR]\-\-batch\f[R]' to avoid popup error alert +Can be combined with `\f[CR]--batch\f[R]' to avoid popup error alert windows. .RE .PP -\f[B]\-\-export\-link\-rewriting\f[R]=\f[I]MODE\f[R] +\f[B]--export-link-rewriting\f[R]=\f[I]MODE\f[R] .RS .PP Chooses how local links in the exported HTML file are written out: @@ -876,7 +872,7 @@ The \f[I]MODE\f[R] `\f[CR]short\f[R]' rewrites all local relative links to absolute links, whose base is the first parent directory containing the marker file `\f[CR].tpnote.toml\f[R]'. NB, the directory of the marker file defines the base for all absolute -local links in your Tp\-Note file! +local links in your Tp-Note file! The mode `\f[CR]long\f[R]' rewrites \f[I]all\f[R] local links to absolute links whose base is the system\[cq]s root directory `\f[CR]/\f[R]'. @@ -898,11 +894,11 @@ in the document\[cq]s path. If you view the HTML file directly in your web browser, better choose `\f[CR]long\f[R]'. In this case, the present of a marker file will not affect the output. -NB: You can also set this option via Tp\-Note\[cq]s configuration file +NB: You can also set this option via Tp-Note\[cq]s configuration file with the key `\f[CR]arg_default.export_link_rewriting\f[R]'. .RE .SH THE NOTE\[cq]S DOCUMENT STRUCTURE -Tp\-Note considers a text file to be a valid note file, if its: +Tp-Note considers a text file to be a valid note file, if its: .IP \[bu] 2 file extension is listed in one of the configuration file variable `\f[CR]filename.extensions\f[R]'; if its @@ -913,12 +909,12 @@ the YAML header contains a key whose name is defined in the configuration file variable `\f[CR]tmpl.compulsory_header_field\f[R]' (default `\f[CR]title\f[R]'). .PP -A Tp\-Note note file is always UTF\-8 encoded. +A Tp-Note note file is always UTF-8 encoded. As newline, either the Unix standard `\f[CR]\[rs]n\f[R]' or the Windows standard `\f[CR]\[rs]r\[rs]n\f[R]' is accepted. -Tp\-Note writes out newlines according the operating system it runs on. +Tp-Note writes out newlines according the operating system it runs on. .SS The document\[cq]s header and body -Tp\-Note is designed to be compatible with `\f[CR]Pandoc\f[R]\[cq]s +Tp-Note is designed to be compatible with `\f[CR]Pandoc\f[R]\[cq]s and'\f[CR]RMarkdown\f[R]s document structure as shown in the figure below. In this documentation the terms \[lq]YAML header\[rq], \[lq]header\[rq] @@ -926,51 +922,49 @@ and \[lq]front matter\[rq] are used as synonyms to designate to document\[cq]s metadata block at the beginning of the text file: .IP .EX -\-\-\- - -\-\-\- +--- + +--- - + .EE .PP -The YAML front\-matter starts at the beginning of the document with -`\f[CR]\-\-\-\f[R]' and ends with `\f[CR]...\f[R]' or -`\f[CR]\-\-\-\f[R]'. +The YAML front-matter starts at the beginning of the document with +`\f[CR]---\f[R]' and ends with `\f[CR]...\f[R]' or `\f[CR]---\f[R]'. Note that according to the YAML standard, string literals are always encoded as JSON strings. -By convention, a valid Tp\-Note file has at least one YAML field named +By convention, a valid Tp-Note file has at least one YAML field named `\f[CR]title:\f[R]' (the name of this compulsory field is defined by the `\f[CR]tmpl.compulsory_header_field\f[R]' variable in the configuration file and can be changed there). .PP -Note that prepended text, placed before the YAML front\-matter, is +Note that prepended text, placed before the YAML front-matter, is ignored. There are however certain restrictions: If present, the skipped text should not be too long (cf.\ constant `\f[CR]BEFORE_HEADER_MAX_IGNORED_CHARS\f[R]' in the source code of -Tp\-Note) and it must be followed by at least one blank line: +Tp-Note) and it must be followed by at least one blank line: .IP .EX Prepended text is ignored. -\-\-\- - -\-\-\- +--- + +--- - + .EE .PP There is no restriction about the markup language being used in the note\[cq]s text body. However, the default templates assume Markdown and the file extension `\f[CR].md\f[R]'. -Both can be changed easily by adapting Tp\-Note\[cq]s configuration -file. -Besides the requirements concerning its header, a valid Tp\-Note file +Both can be changed easily by adapting Tp-Note\[cq]s configuration file. +Besides the requirements concerning its header, a valid Tp-Note file must have a filename extension that is listed in the configuration file variable: `\f[CR]filename.extensions\f[R]'. The latter also determines which internal markup language render is -called for Tp\-Note\[cq]s internal viewer. +called for Tp-Note\[cq]s internal viewer. .SS Links to resources and other documents .SS Link types The document\[cq]s body often contains (inline) links to resources @@ -979,8 +973,8 @@ This section describes how the automatic path rewriting of local links works. .PP In general, the link syntax depends on the markup language used in the -Tp\-Note file. -The following examples illustrate the different link types Tp\-Note +Tp-Note file. +The following examples illustrate the different link types Tp-Note understands: .PP .TS @@ -1015,12 +1009,12 @@ T} T{ Relative local link T}@T{ -`\f[CR][my doc](<../../notes/31\-my doc.md>)\f[R]' +`\f[CR][my doc](<../../notes/31-my doc.md>)\f[R]' T} T{ Relative local autolink T}@T{ -`\f[CR]\f[R]' +`\f[CR]\f[R]' T} T{ Shorthand link @@ -1035,7 +1029,7 @@ T} T{ Formatted shorthand link T}@T{ -`\f[CR])\f[R]' +`\f[CR])\f[R]' T} .TE .PP @@ -1047,59 +1041,58 @@ If absent, absolute local links refer to the root directory `\f[CR]/\f[R]'. .IP \[bu] 2 \f[I]Shorthand link\f[R]: Instead of writing out the full link -destination, e.g.\ -`\f[CR][my doc](<./docs/20230508\-my note.md>)\f[R]', you can shorten -the link to `\f[CR][my doc]()\f[R]' indicating only the -destination\[cq]s sort\-tag. +destination, e.g.\ `\f[CR][my doc](<./docs/20230508-my note.md>)\f[R]', +you can shorten the link to `\f[CR][my doc]()\f[R]' +indicating only the destination\[cq]s sort-tag. Alternatively, the same shorthand link can be expressed as autolink as well: `\f[CR]\f[R]'. -NB, if more than one document with the same sort\-tag exist in a +NB, if more than one document with the same sort-tag exist in a directory, the viewer only displays the first in alphabetical order. -To set up a different order, you can extend the sort\-tag until it +To set up a different order, you can extend the sort-tag until it becomes unique, e.g.\ by renaming the destination document in the above -example to `\f[CR]./ docs/20230508a\-my note.md\f[R]'. -This way you obtain the unique sort\-tag `\f[CR]20230508a\f[R]'. +example to `\f[CR]./ docs/20230508a-my note.md\f[R]'. +This way you obtain the unique sort-tag `\f[CR]20230508a\f[R]'. .PP -Although Tp\-Note\[cq]s built in viewer follows absolute and relative +Although Tp-Note\[cq]s built in viewer follows absolute and relative local links, usually the latter are preferred. They make moving documents easier, as relative links do not break when the source and the destination documents are moved together. .PP -As mentioned above, the shortest way to refer to other Tp\-Note -documents, is indicating their sort\-tag only, +As mentioned above, the shortest way to refer to other Tp-Note +documents, is indicating their sort-tag only, e.g.\ `\f[CR]\f[R]' and `\f[CR][my file]()\f[R]'. If the other document is located in the same directory, the links are even shorter: `\f[CR]\f[R]' and `\f[CR][my file]()\f[R]'. .SS Local links in HTML export -Tp\-Note\[cq]s exporter function `\f[CR]\-\-export\f[R]' converts a -given Tp\-Note file into HTML and adds `\f[CR].html\f[R]' to the output +Tp-Note\[cq]s exporter function `\f[CR]--export\f[R]' converts a given +Tp-Note file into HTML and adds `\f[CR].html\f[R]' to the output filename. -Links in the documents content to other Tp\-Note files are hereby +Links in the documents content to other Tp-Note files are hereby rewritten by appending `\f[CR].html\f[R]' to their URLs. This way you can convert groups of documents to HTML and later jump from document to document in your web browser. -The option `\f[CR]\-\-export\-link\-rewriting\f[R]' allows you to -fine\-tune how local links are written out. +The option `\f[CR]--export-link-rewriting\f[R]' allows you to fine-tune +how local links are written out. Valid values are: `\f[CR]off\f[R]', `\f[CR]short\f[R]' and `\f[CR]long\f[R]'. .PP In order to achieve this, the user must respect the following convention -concerning absolute paths in local links in Tp\-Note documents: When a +concerning absolute paths in local links in Tp-Note documents: When a document contains a local link with an absolute path, the base of this path is considered to be the directory where the marker file `\f[CR].tpnote.toml\f[R]' resides (or `\f[CR]/\f[R]' in non exists). -The option `\f[CR]\-\-export\-link\- rewriting\f[R]' decides how local -links in the Tp\-Note document are converted when the HTML is generated. +The option `\f[CR]--export-link- rewriting\f[R]' decides how local links +in the Tp-Note document are converted when the HTML is generated. If its value is `\f[CR]short\f[R]', then local links with relative paths are converted to absolute paths. The base of the resulting path is where the `\f[CR].tpnote.toml\f[R]' file resides (or \f[CR]/\f[R] if none exists). Consider the following example -`\f[CR]\-\-export\-link\-rewriting=short\f[R]': +`\f[CR]--export-link-rewriting=short\f[R]': .IP \[bu] 2 -The Tp\-Note file `\f[CR]/my/docs/car/bill.md\f[R]' contains +The Tp-Note file `\f[CR]/my/docs/car/bill.md\f[R]' contains .IP \[bu] 2 an absolute local link: `\f[CR]/car/scan.jpg\f[R]', .IP \[bu] 2 @@ -1113,12 +1106,12 @@ The images in the resulting HTML will appear as .IP \[bu] 2 `\f[CR]/car/photo.jpg\f[R]'. .PP -For `\f[CR]\-\-export\-link\-rewriting=long\f[R]', in addition to the -above, all absolute paths in local links are prepended with the marker +For `\f[CR]--export-link-rewriting=long\f[R]', in addition to the above, +all absolute paths in local links are prepended with the marker file\[cq]s directory. Consider the following example: .IP \[bu] 2 -The Tp\-Note file `\f[CR]/my/docs/car/bill.md\f[R]' contains +The Tp-Note file `\f[CR]/my/docs/car/bill.md\f[R]' contains .IP \[bu] 2 an absolute local link: `\f[CR]/car/scan.jpg\f[R]', .IP \[bu] 2 @@ -1132,16 +1125,16 @@ The images in the resulting HTML will appear as .IP \[bu] 2 `\f[CR]/my/docs/car/photo.jpg\f[R]'. .PP -Summary: The right `\f[CR]\-\-export\-link\-rewriting\f[R]' choice -depends on how you view the resulting HTML: if you publish on a web -server, then `\f[CR]short\f[R]' might be a good choice (do not forget to -place a marker file `\f[CR].tpnote.toml\f[R]' somewhere in the -document\[cq]s path). +Summary: The right `\f[CR]--export-link-rewriting\f[R]' choice depends +on how you view the resulting HTML: if you publish on a web server, then +`\f[CR]short\f[R]' might be a good choice (do not forget to place a +marker file `\f[CR].tpnote.toml\f[R]' somewhere in the document\[cq]s +path). If you view the HTML file directly in your web browser, better choose `\f[CR]long\f[R]'. .SS Local links with format strings -So far, we have seen how Tp\-Note\[cq]s viewer and HTML exporter -converts the \f[I]destination\f[R] of local links +So far, we have seen how Tp-Note\[cq]s viewer and HTML exporter converts +the \f[I]destination\f[R] of local links `\f[CR][text](destination)\f[R]'. Concerning the local link\[cq]s \f[I]text\f[R] property, the situation is simpler as the \f[I]text\f[R] property never changes during the above @@ -1151,7 +1144,7 @@ appending a \f[I]format string\f[R] to the destination: `\f[CR][formatted destination](destination?format string)\f[R]'. .PP All local links in the following tables have the same link destination -`\f[CR]dir/01ac\-Tulips\-\-red, yellow.md\f[R]'. +`\f[CR]dir/01ac-Tulips--red, yellow.md\f[R]'. The examples differ only in the way the link is displayed in the browser. .PP @@ -1165,7 +1158,7 @@ What you see T} _ T{ -`\f[CR][matters]()\f[R]' +`\f[CR][matters]()\f[R]' T}@T{ matters T} @@ -1186,7 +1179,7 @@ What you see T} _ T{ -`\f[CR][whatever]()\f[R]' +`\f[CR][whatever]()\f[R]' T}@T{ Tulips\[en]red, yellow T} @@ -1201,12 +1194,12 @@ T}@T{ Tulips\[en]red T} T{ -`\f[CR][whatever]()\f[R]' +`\f[CR][whatever]()\f[R]' T}@T{ Tulips T} T{ -`\f[CR][whatever]()\f[R]' +`\f[CR][whatever]()\f[R]' T}@T{ red T} @@ -1218,14 +1211,14 @@ T} T{ `\f[CR][whatever]()\f[R]' T}@T{ -01ac\-Tulips\[en]red, yellow.md +01ac-Tulips\[en]red, yellow.md T} .TE .PP Observations: .IP "1." 3 The format operator `\f[CR]?\f[R]' (not followed by a `\f[CR]#\f[R]') -strips the path, the sort\-tag, the copy\-counter and the filename +strips the path, the sort-tag, the copy-counter and the filename extension. In other words, it keeps only the file stem. .IP "2." 3 @@ -1239,7 +1232,7 @@ colon is the \f[I]from pattern\f[R], the string after the colon is the Patterns are always searched from the start of the string, e.g.\ in Latin scripts from the left to the right. .IP "4." 3 -The format operator `\f[CR]?#\f[R]' prints the sort\-tag. +The format operator `\f[CR]?#\f[R]' prints the sort-tag. .IP "5." 3 The format operator `\f[CR]??\f[R]' prints the whole filename. .IP "6." 3 @@ -1255,9 +1248,9 @@ What you see T} _ T{ -`\f[CR]\f[R]' +`\f[CR]\f[R]' T}@T{ -dir/01ac\-Tulips\[en]red,%20yellow.md +dir/01ac-Tulips\[en]red,%20yellow.md T} T{ `\f[CR]\f[R]' @@ -1279,7 +1272,7 @@ What you see T} _ T{ -`\f[CR]\f[R]' +`\f[CR]\f[R]' T}@T{ Tulips\[en]red, yellow T} @@ -1291,56 +1284,56 @@ T} T{ `\f[CR]\f[R]' T}@T{ -01ac\-Tulips\[en]red, yellow.md +01ac-Tulips\[en]red, yellow.md T} T{ `\f[CR]\f[R]' T}@T{ -01ac\-Tulips\[en]red, yellow +01ac-Tulips\[en]red, yellow T} T{ `\f[CR]\f[R]' T}@T{ -01ac\-Tulips\[en]red, yellow +01ac-Tulips\[en]red, yellow T} T{ -`\f[CR]\f[R]' +`\f[CR]\f[R]' T}@T{ Tulips\[en]red T} T{ -`\f[CR]\f[R]' +`\f[CR]\f[R]' T}@T{ red T} .TE .SH METADATA FILENAME SYNCHRONIZATION -Consider the following Tp\-Note filename generated with the +Consider the following Tp-Note filename generated with the \f[I]default\f[R] filename scheme (cf section \[lq]Filename synchronization schemes\[rq] for other schemes): .IP .EX -20151208\-Make this world a better place\-\-Suggestions.md +20151208-Make this world a better place--Suggestions.md .EE .PP The filename has 4 parts: .IP .EX -{{ fm_sort_tag }}\-{{ fm_title }}\-\-{{ fm_subtitle }}.{{ fm_file_ext }} +{{ fm_sort_tag }}-{{ fm_title }}--{{ fm_subtitle }}.{{ fm_file_ext }} .EE .PP -The `\f[CR]\-\f[R]' between `\f[CR]{{ fm_sort_tag }}\f[R]' and -`\f[CR]{{ fm_title }}\f[R]' is hereafter referred to as \f[I]sort\-tag +The `\f[CR]-\f[R]' between `\f[CR]{{ fm_sort_tag }}\f[R]' and +`\f[CR]{{ fm_title }}\f[R]' is hereafter referred to as \f[I]sort-tag separator\f[R] (cf.\ `\f[CR]filename.sort_tag.separator\f[R]'). .PP -A so\-called \f[I]sort tag\f[R] is an alphanumerical prefix at the +A so-called \f[I]sort tag\f[R] is an alphanumerical prefix at the beginning of the filename. It is used to order files and notes in the file system. Besides numerical digits and lowercase letters, a \f[I]sort tag\f[R] may -contain any combination of `\f[CR]_\f[R]', `\f[CR]\-\f[R]', +contain any combination of `\f[CR]_\f[R]', `\f[CR]-\f[R]', `\f[CR]=\f[R]' and `\f[CR].\f[R]' (cf.\ `\f[CR]filename.sort_tag.extra_chars\f[R]'). -If a sort\-tag contains lowercase letters, only 2 in a row are allowed +If a sort-tag contains lowercase letters, only 2 in a row are allowed (cf.\ `\f[CR]filename.sort_tag.letters_in_succession_max\f[R]'). Examples: .IP \[bu] 2 @@ -1348,31 +1341,31 @@ Examples: .RS 2 .IP .EX - 20140211\-Reminder.doc - 20151208\-Manual.pdf - 2015\-12\-08\-Manual.pdf + 20140211-Reminder.doc + 20151208-Manual.pdf + 2015-12-08-Manual.pdf .EE .PP -NB: All chronological sort\-tags must have at least one counter with 4 +NB: All chronological sort-tags must have at least one counter with 4 digits or more, e.g.\ `\f[CR]2015\f[R]'. -The character `\f[CR]\-\f[R]' between the counters is optional. +The character `\f[CR]-\f[R]' between the counters is optional. .PP -Tip: Always include the year with 4 digits in chronological sort\-tags. +Tip: Always include the year with 4 digits in chronological sort-tags. .RE .IP \[bu] 2 \f[I]Sequence number sort tag\f[R] .RS 2 .IP .EX - 02\-Invoices/ - 08\-Tax documents/ - 09_2_144\-Manual.pdf - 09.9.1\-Notes.md + 02-Invoices/ + 08-Tax documents/ + 09_2_144-Manual.pdf + 09.9.1-Notes.md .EE .PP NB: None of the counters exceeds 3 digits (cf.\ `\f[CR]filename.sort_tag.sequential.digits_in_succession_max\f[R]') -which is the criterium to recognize a sequence number sort\-tag. +which is the criterium to recognize a sequence number sort-tag. The largest counter in these examples is `\f[CR]144\f[R]', so all sort_tags are sequence numbers. .RE @@ -1381,10 +1374,10 @@ sort_tags are sequence numbers. .RS 2 .IP .EX - 02\-Invoices/ - 08\-Tax documents/ - 09b144\-Manual.pdf - 09i1\-Notes.md + 02-Invoices/ + 08-Tax documents/ + 09b144-Manual.pdf + 09i1-Notes.md .EE .PP NB: the example is equivalent to the previous one. @@ -1394,7 +1387,7 @@ alternation of digits and letters. .PP \f[B]Summary:\f[R] .IP "1." 3 -A \f[I]sort\-tag\f[R] is composed of a number of counters, which can be +A \f[I]sort-tag\f[R] is composed of a number of counters, which can be numerical, e.g.\ `\f[CR]123.28\f[R]' or combined numerical/letter based, e.g.\ `\f[CR]123ab\f[R]'. .IP "2." 3 @@ -1405,23 +1398,21 @@ A letter based counter can be maximal 2 letters wide. Its maximum is `\f[CR]zz\f[R]' (cf.\ `\f[CR]filename.sort_tag.letters_in_succession_max\f[R]'). .IP "4." 3 -A \f[I]sequential sort\-tag\f[R] is a sort\-tag that whose counters are -at most 3 digits wide +A \f[I]sequential sort-tag\f[R] is a sort-tag that whose counters are at +most 3 digits wide (cf.\ `\f[CR]sort_tag.sequential.digits_in_succession_max\f[R]'). .IP "5." 3 The filter `\f[CR]incr_sort_tag\f[R]' increments only sequential -sort\-tags. +sort-tags. .IP "6." 3 -In order not to confuse sequential and chronological sort\-tags, it is -recommended to always write out the year in chronological sort\-tags -with 4 digits, e.g.\ \[cq]`\f[CR]2013\-08\-10\f[R]' or -`\f[CR]20130810\f[R]'. -.PP -Before Tp\-Note creates a new note file, it searches the current -directory for the latest existing Tp\-Note file. -If that file starts with a sequence number sort\-tag, Tp\-Note -increments that number and uses the result as sort\-tag for the new note -file. +In order not to confuse sequential and chronological sort-tags, it is +recommended to always write out the year in chronological sort-tags with +4 digits, e.g.\ \[cq]`\f[CR]2013-08-10\f[R]' or `\f[CR]20130810\f[R]'. +.PP +Before Tp-Note creates a new note file, it searches the current +directory for the latest existing Tp-Note file. +If that file starts with a sequence number sort-tag, Tp-Note increments +that number and uses the result as sort-tag for the new note file. Otherwise, the new note gets a chronological sort tag of today. .PP A note\[cq]s filename is said to be in sync with its metadata, when the @@ -1430,7 +1421,7 @@ following holds (slightly simplified, see .RS .PP filename on disk without \f[I]sort tag\f[R] == -`\f[CR]{{ fm_title }}\-\-{{ fm_subtitle }}.md\f[R]' +`\f[CR]{{ fm_title }}--{{ fm_subtitle }}.md\f[R]' .RE .PP [1] @@ -1438,137 +1429,136 @@ filename on disk without \f[I]sort tag\f[R] == Example, consider the following document with the filename: .IP .EX -20211031\-My file.md +20211031-My file.md .EE .PP and the content: .IP .EX -\-\-\- +--- title: 1. The Beginning subtitle: Note author: Getreu -date: 2021\-10\-31 -lang: en\-GB +date: 2021-10-31 +lang: en-GB remainder: false -\-\-\- +--- .EE .PP As `\f[CR]My file.md\f[R]' is not equal to -`\f[CR]1. The Beginning\-\-Note.md\f[R]', Tp\-Note will rename the file -to `\f[CR]20211031\-1. The Beginning\-\-Note.md\f[R]'. -If the filename had been `\f[CR]05_02\-My file.md\f[R]', it would rename -it to `\f[CR]05_02\-1. The Beginning\-\-Note.md\f[R]'. +`\f[CR]1. The Beginning--Note.md\f[R]', Tp-Note will rename the file to +`\f[CR]20211031-1. The Beginning--Note.md\f[R]'. +If the filename had been `\f[CR]05_02-My file.md\f[R]', it would rename +it to `\f[CR]05_02-1. The Beginning--Note.md\f[R]'. .PP -Note: When the YAML front\-matter does not contain the optional -`\f[CR]sort_tag\f[R]' variable, Tp\-Note will never change a sort tag. +Note: When the YAML front-matter does not contain the optional +`\f[CR]sort_tag\f[R]' variable, Tp-Note will never change a sort tag. Nevertheless, it might change the rest of the filename! .PP -The reason why by default Tp\-Note does not change sort tags is, that +The reason why by default Tp-Note does not change sort tags is, that they define their order in the file listing. In general this order is independent of the notes content. The simplest way to organize the sort tags of your files is by renaming them directly in your file system. Nevertheless, in some cases you might want to have full control over the -whole filename through the note\[cq]s YAML front\-matter. +whole filename through the note\[cq]s YAML front-matter. For example, if \[em] for some reason \[em] you have changed the -document\[cq]s date in the front\-matter and you want to change the +document\[cq]s date in the front-matter and you want to change the chronological sort tag in one go. In order to overwrite the note\[cq]s sort tag on disk, you can add a -`\f[CR]sort_tag\f[R]' string\-variable to its front\-matter: +`\f[CR]sort_tag\f[R]' string-variable to its front-matter: .IP .EX -\-\-\- +--- title: 1. The Beginning -date: 2021\-10\-31 +date: 2021-10-31 sort_tag: \[aq]20211101\[aq] -\-\-\- +--- .EE .PP -Note, the above sort\-tag value \- here a number \- must be enclosed -with quotes in order label it as string type. -When Tp\-Note synchronizes the note\[cq]s metadata with its filename, it +Note, the above sort-tag value - here a number - must be enclosed with +quotes in order label it as string type. +When Tp-Note synchronizes the note\[cq]s metadata with its filename, it will also change the sort tag from `\f[CR]20211031\f[R]' to `\f[CR]20211101\f[R]'. The resulting filename becomes -`\f[CR]20211101\-1. The Beginning\-\-Note.md\f[R]'. +`\f[CR]20211101-1. The Beginning--Note.md\f[R]'. .PP The `\f[CR]sort_tag\f[R]' variable also becomes handy, when you want to create one single note without any sort tag: .IP .EX -\-\-\- +--- title: 1. The Beginning sort_tag: \[aq]\[aq] -\-\-\- +--- .EE .PP In the same way, how it is possible to pin the sort tag of the note from within the note\[cq]s metadata, you can also change the file extension by adding the optional `\f[CR]file_ext\f[R]' variable into the -note\[cq]s front\-matter: +note\[cq]s front-matter: .IP .EX -\-\-\- +--- title: 1. The Beginning file_ext: rst -\-\-\- +--- .EE .PP This will change the file extension from `\f[CR].md\f[R]' to `\f[CR].rst\f[R]'. The resulting filename becomes -`\f[CR]20211101\-1. The Beginning\-\-Note.rst\f[R]'. +`\f[CR]20211101-1. The Beginning--Note.rst\f[R]'. .PP Important: `\f[CR]rst\f[R]' must be one of the registered file extensions listed in the `\f[CR]filename.extensions\f[R]' variable in -Tp\-Note\[cq]s configuration file. +Tp-Note\[cq]s configuration file. If needed you can add more extensions there. If the new filename extension is not listed in one of these variables, -Tp\-Note will not be able to recognize the note file as such and will -not open it in the external text editor and viewer. +Tp-Note will not be able to recognize the note file as such and will not +open it in the external text editor and viewer. .PP Note: When a `\f[CR]sort_tag\f[R]' variable is defined in the note\[cq]s YAML header, you should not change the sort tag string in the note\[cq]s file name manually by renaming the file, as your change will be -overwritten next time you open the note with Tp\-Note. -However, you can switch back to Tp\-Note\[cq]s default behaviour any -time by deleting the `\f[CR]sort_tag\f[R]' line in the note\[cq]s -metadata. +overwritten next time you open the note with Tp-Note. +However, you can switch back to Tp-Note\[cq]s default behaviour any time +by deleting the `\f[CR]sort_tag\f[R]' line in the note\[cq]s metadata. The same applies to the `\f[CR]file_ext\f[R]' variable. .PP The metadata filename synchronization feature can be disabled permanently by setting the configuration file variable `\f[CR]arg_default.no_filename_sync = true\f[R]'. -To disable this feature for one time only, invoke Tp\-Note with -`\f[CR]\-\-no\-filename\-sync\f[R]'. +To disable this feature for one time only, invoke Tp-Note with +`\f[CR]--no-filename-sync\f[R]'. To exclude a particular note from filename synchronization, add the YAML header field `\f[CR]filename_sync: false\f[R]'. .IP .EX -\-\-\- +--- title: 1. The Beginning filename_sync: false -\-\-\- +--- .EE .PP Note, that in the above described examples, the information flow always goes from the YAML note header towards the note\[cq]s filename. -However, when Tp\-Note opens a text file without a YAML header, a new +However, when Tp-Note opens a text file without a YAML header, a new header is added automatically. In this case the information flow goes from the filename towards the header, namely in the opposite direction. Once the new header is prepended to the text file, a regular filename -synchronization \- as described above \- is triggered and executed as +synchronization - as described above - is triggered and executed as described above. .SS Filename synchronization schemes Technically, the rules how the note\[cq]s header relates to its filename -are encoded in customizable so\-called filename templates (cf.\ section +are encoded in customizable so-called filename templates (cf.\ section \f[I]Templates\f[R]). These templates exist in two different variants referred to as \f[I]default scheme\f[R] and \f[I]zettel scheme\f[R]: @@ -1579,10 +1569,10 @@ The \f[CR]\[aq]default\[aq]\f[R] scheme: Example: .IP .EX -\-\-\- +--- title: 1. The Beginning subtitle: Note -\-\-\- +--- Once upon a time... .EE @@ -1591,20 +1581,20 @@ The filename synchronization template from the \f[I]default scheme\f[R] set looks like (simplified): .IP .EX -{{ fm_sort_tag }}\-{{ fm_title }}\-\-{{ fm_subtitle }}.{{ fm_file_ext }} +{{ fm_sort_tag }}-{{ fm_title }}--{{ fm_subtitle }}.{{ fm_file_ext }} .EE .PP It generates from the above example the filename: .IP .EX -20211031\-1. The Beginning\-\-Note.md +20211031-1. The Beginning--Note.md .EE .RE .IP "2." 3 The `\f[CR]zettel\f[R]' scheme: .RS 4 .PP -Although the default scheme covers most of the daily note\-taking, +Although the default scheme covers most of the daily note-taking, Luhmann\[cq]s \f[I]Zettelkasten\f[R] knowledge management system requires slightly different templates, hence the name \f[I]zettel scheme\f[R]. @@ -1613,15 +1603,15 @@ The following example illustrates the header fields of a typical `\f[CR]zettel\f[R]' scheme note file: .IP .EX -\-\-\- +--- title: Lemon keywords: - \- fruit - \- round - \- sour taste + - fruit + - round + - sour taste scheme: zettel sort_tag: 2b3 -\-\-\- +--- The [lemon] belongs to the Rutaceae family. [lemon]: https://en.wikipedia.org/wiki/Lemon @@ -1631,17 +1621,17 @@ The filename synchronization template from the \f[I]zettel scheme\f[R] set looks like (simplified): .IP .EX -{{ fm_sort_tag }}\-\-{{ fm_title }}__{{ fm_keywords }}.{{ fm_file_ext }} +{{ fm_sort_tag }}--{{ fm_title }}__{{ fm_keywords }}.{{ fm_file_ext }} .EE .PP It generates the following filename: .IP .EX -2b3\-\-Lemon__fruit_round_sour taste.md +2b3--Lemon__fruit_round_sour taste.md .EE .RE .SH CUSTOMIZATION -Tp\-Note is shipped with a default internal configuration that can be +Tp-Note is shipped with a default internal configuration that can be customized by merging a series of configuration files from various locations into the default values. This happens in the following order: @@ -1666,29 +1656,29 @@ At startup all parent directories of the note file path `\f[CR].tpnote.toml\f[R]'. If found, the document root moves from `\f[CR]/\f[R]' to the found location. -If present and its content is not empty, Tp\-Note interprets the +If present and its content is not empty, Tp-Note interprets the file\[cq]s content as configuration file. .IP "5." 3 The file indicated by the command line parameter -`\f[CR]\-\-config \f[R]'. +`\f[CR]--config \f[R]'. .PP -When Tp\-Note starts, it first merges all available configuration files +When Tp-Note starts, it first merges all available configuration files into the default configuration. Then the resulting syntax is checked. If not correct, the last sourced configuration file is renamed (thus -disabled) and Tp\-Note starts with its internal default configuration. +disabled) and Tp-Note starts with its internal default configuration. For debugging, you can print out the merged result with -`\f[CR]\-V \-b \-d trace\f[R]'. +`\f[CR]-V -b -d trace\f[R]'. .IP .EX -tpnote \-V \-b \-d trace |less +tpnote -V -b -d trace |less .EE .PP To write a custom configuration file, generate a template with -`\f[CR]\-C\f[R]': +`\f[CR]-C\f[R]': .IP .EX -tpnote \-C \[ti]/.config/tpnote/tpnote.toml +tpnote -C \[ti]/.config/tpnote/tpnote.toml .EE .PP The template shows all variables with their defaults values. @@ -1696,7 +1686,7 @@ When you change a value, do not forget to uncomment the modified line to activate your change. Also make sure to keep the `\f[CR]version\f[R]' variable at the beginning of the file commented out. -As any Tp\-Note upgrade might include a breaking change in the +As any Tp-Note upgrade might include a breaking change in the configuration file structure, try to keep your custom configuration small. .PP @@ -1705,10 +1695,10 @@ Some filename and template related variables are grouped into a The shipped configuration file lists two schemes: `\f[CR]default\f[R]' and `\f[CR]zettel\f[R]'. The scheme used when creating a new note, is selected by the commend -line option `\f[CR]\-\-scheme\f[R]', the environment variable +line option `\f[CR]--scheme\f[R]', the environment variable `\f[CR]TPNOTE_SCHEME\f[R]' or the configuration variable `\f[CR]arg_default.scheme\f[R]'. -The scheme selected when synchronizing a Tp\-Note header with its +The scheme selected when synchronizing a Tp-Note header with its filename depends on the value of the header variable `\f[CR]scheme:\f[R]' which defaults to `\f[CR]default\f[R]' (cf.\ `\f[CR]scheme_sync_default\f[R]'). @@ -1732,14 +1722,14 @@ To add a custom scheme you must provide all variables: .IP .EX [[scheme]] -name=\[dq]my\-custom\-scheme\[dq] +name=\[dq]my-custom-scheme\[dq] [scheme.filename] # Insert all variables here. [scheme.tmpl] # Insert all variables here. .EE .PP -The following example illustrates how non\-top\-level arrays are +The following example illustrates how non-top-level arrays are overwritten by the subsequent configuration file. The default configuration lists about 20 MIME types. After merging the following example, the configuration lists only the @@ -1754,7 +1744,7 @@ served_mime_types = [ ] .EE .SS Register your own text editor -There are two ways to modify the default file editor, Tp\-Note launches +There are two ways to modify the default file editor, Tp-Note launches when it starts: either you can modify the configuration file variables `\f[CR]app_args.*.editor\f[R]' and `\f[CR]app_args.*.editor_console\f[R]', or alternatively, you can set @@ -1764,30 +1754,30 @@ the chapter \f[I]ENVIRONMENT_VARIABLES\f[R] below). The configuration file variables `\f[CR]app_args.unix.editor\f[R]' and `\f[CR]app_args.unix.editor_console\f[R]' define lists of external text editors to be launched for editing. -The lists contain by default well\-known text editor names and their +The lists contain by default well-known text editor names and their command line arguments for Unix like operating systems. For other systems consult: `\f[CR]app_args.windows.editor\f[R]', `\f[CR]app_args.windows.editor_console\f[R]', `\f[CR]app_args.macos.editor\f[R]' and `\f[CR]app_args.macos.editor_console\f[R]'. -Tp\-Note tries to launch every text editor in +Tp-Note tries to launch every text editor in `\f[CR]app_args.*.editor\f[R]' from the beginning of the list until it finds an installed text editor. -When Tp\-Note is started on a Linux console, the list +When Tp-Note is started on a Linux console, the list `\f[CR]app_args.*.editor_console\f[R]' is used instead. Here you can register text editors that do not require a graphical environment, e.g.\ `\f[CR]vim\f[R]' or `\f[CR]nano\f[R]'. In order to use your own text editor, just place it at the top of the list. -To debug your changes invoke Tp\-Note with -`\f[CR]tpnote \-\-debug debug \-\-popup \-\-edit\f[R]'. +To debug your changes invoke Tp-Note with +`\f[CR]tpnote --debug debug --popup --edit\f[R]'. .PP The following example showcases the configuration for the \f[I]Kate\f[R] file editor. The entry `\f[CR]kate\f[R]' launches the binary, while the command line -parameter `\f[CR]\-\-block\f[R]' guarantees, that the launched process +parameter `\f[CR]--block\f[R]' guarantees, that the launched process blocks until the user closes the editor. -Tp\-Note detects the end of the process, checks if the title of the note +Tp-Note detects the end of the process, checks if the title of the note files has changed in its YAML header and renames the note file if necessary. .IP @@ -1796,7 +1786,7 @@ necessary. unix.editor = [ [ \[dq]kate\[dq], - \[dq]\-\-block\[dq] + \[dq]--block\[dq] ] ] .EE @@ -1804,7 +1794,7 @@ unix.editor = [ The equivalent configuration with environment variable: .IP .EX -TPNOTE_EDITOR=\[dq]kate \-\-block\[dq] tpnote +TPNOTE_EDITOR=\[dq]kate --block\[dq] tpnote .EE .PP All items in the above list are subject to limited template expansion @@ -1816,8 +1806,8 @@ Consider the following example: windows.editor = [ [ \[dq]{{get_env(name=\[rs]\[dq]LOCALAPPDATA\[rs]\[dq])}}\[rs]\[rs]Programs\[rs]\[rs]Microsoft VS Code\[rs]\[rs]Code.exe\[dq], - \[dq]\-n\[dq], - \[dq]\-w\[dq], + \[dq]-n\[dq], + \[dq]-w\[dq], ] ] .EE @@ -1832,12 +1822,12 @@ Windows for a user with the username `\f[CR]Joe\f[R]' to windows.editor = [ [ \[dq]C:\[rs]\[rs]User\[rs]\[rs]Joe\[rs]\[rs]AppData\[rs]\[rs]Local\[rs]\[rs]Programs\[rs]\[rs]Microsoft VS Code\[rs]\[rs]Code.exe\[dq], - \[dq]\-\-new\-window\[dq], \[dq]\-\-wait\[dq], + \[dq]--new-window\[dq], \[dq]--wait\[dq], ] ] .EE .PP -In general, when you configure Tp\-Note to work with your text editor, +In general, when you configure Tp-Note to work with your text editor, make sure, that your text editor does not fork! You can check this by launching the text editor from the command line: if the command prompt returns immediately, then the file editor forks @@ -1846,42 +1836,41 @@ On the other hand everything is OK, when the command prompt only reappears at the moment the text editor is closed. Many text editors provide an option to restrain from forking: for example the \f[I]Visual Studio Code\f[R] file editor can be launched -with the `\f[CR]\-\-wait\f[R]' option, \f[I]Vim\f[R] with -`\f[CR]\-\-nofork\f[R]' or \f[I]Kate\f[R] with `\f[CR]\-\-block\f[R]'. +with the `\f[CR]--wait\f[R]' option, \f[I]Vim\f[R] with +`\f[CR]--nofork\f[R]' or \f[I]Kate\f[R] with `\f[CR]--block\f[R]'. .PP -However, Tp\-Note also works with forking text editors. +However, Tp-Note also works with forking text editors. Although this should be avoided, there is a possible workaround. Observe the following example: .IP .EX $ TPNOTE_EDITOR=\[dq]kate\[dq] tpnote -/home/getreu/20230714\-getreu\-\-Note.md +/home/getreu/20230714-getreu--Note.md $ .EE .PP -In the above example Tp\-Note launches the `\f[CR]kate\f[R]' editor in a -forking manner as the command line flag `\f[CR]\-\-block\f[R]' is -missing. +In the above example Tp-Note launches the `\f[CR]kate\f[R]' editor in a +forking manner as the command line flag `\f[CR]--block\f[R]' is missing. Internally the editor process launching returns immediately, leaving -Tp\-Note without any means to detect when exactly the user closes the +Tp-Note without any means to detect when exactly the user closes the editor. -Hence, Tp\-Note is not able to check if the user has changed the +Hence, Tp-Note is not able to check if the user has changed the note\[cq]s header and no filename synchronization can occur afterwards. .PP As a workaround, you can manually trigger the filename synchronization -after editing with `\f[CR]tpnote \-\-batch \[dq]$FILE\[dq]\f[R]': +after editing with `\f[CR]tpnote --batch \[dq]$FILE\[dq]\f[R]': .IP .EX -FILE=$(tpnote \-\-batch) # Create the new note. -tpnote \-\-view \[dq]$FILE\[dq]& # Launch Tp\-Note\[aq]s viewer. +FILE=$(tpnote --batch) # Create the new note. +tpnote --view \[dq]$FILE\[dq]& # Launch Tp-Note\[aq]s viewer. kate \[dq]$FILE\[dq] # Note, the prompt returns immediatly as the editor forks. # After closing the editor when editing is done... -tpnote \-\-batch \[dq]$FILE\[dq] # Synchronize the note\[aq]s filename again. +tpnote --batch \[dq]$FILE\[dq] # Synchronize the note\[aq]s filename again. .EE .PP -Whereby `\f[CR]FILE=$(tpnote \-\-batch)\f[R]' creates the note file, +Whereby `\f[CR]FILE=$(tpnote --batch)\f[R]' creates the note file, `\f[CR]kate \[dq]$FILE\[dq]\f[R]' opens the text editor and -`\f[CR]tpnote \-\-batch \[dq]$FILE\[dq]\f[R]' synchronizes the filename +`\f[CR]tpnote --batch \[dq]$FILE\[dq]\f[R]' synchronizes the filename after editing. .PP NB: Try to avoid forking at all cost. @@ -1889,7 +1878,7 @@ As mentioned above, most text editors have a command line flag to prevent the process from forking: .IP .EX -TPNOTE_EDITOR=\[dq]kate \-\-block\[dq] tpnote +TPNOTE_EDITOR=\[dq]kate --block\[dq] tpnote .EE .PP \f[B]Register a Flatpak Markdown editor\f[R] @@ -1898,10 +1887,10 @@ TPNOTE_EDITOR=\[dq]kate \-\-block\[dq] tpnote .UR https://www.flathub.org/home Flathub for Linux .UE \c -\ is a cross\-platform application repository that works well with -Tp\-Note. -To showcase an example, we will add a Tp\-Note launcher for the -\f[I]Mark Text\f[R] Markdown text editor available as \c +\ is a cross-platform application repository that works well with +Tp-Note. +To showcase an example, we will add a Tp-Note launcher for the \f[I]Mark +Text\f[R] Markdown text editor available as \c .UR https://www.flathub.org/apps/details/com.github.marktext.marktext Flatpak package .UE \c @@ -1923,7 +1912,7 @@ To test, run \f[I]Mark Text\f[R] from the command line: flatpak run com.github.marktext.marktext .EE .PP -Then place a Tp\-Note configuration in its search path (e.g.\ +Then place a Tp-Note configuration in its search path (e.g.\ `\f[CR]\[ti]/.config/tpnote/tpnote.toml\f[R]') with the following content: .IP @@ -1935,31 +1924,30 @@ unix.editor = [ [ \[dq]flatpak\[dq], \[dq]run\[dq], \[dq]com.github.marktext.mar The structure of this variable is a list of lists. Every item in the outer list corresponds to one entire command line launching a different text editor, here \f[I]Marktext\f[R]. -When launching, Tp\-Note searches through this list until it finds an +When launching, Tp-Note searches through this list until it finds an installed text editor on the system. .PP Save the modified configuration file. -Next time you launch Tp\-Note, the \f[I]Mark Text\f[R]\-editor will -open. +Next time you launch Tp-Note, the \f[I]Mark Text\f[R]-editor will open. .PP \f[B]Register a console text editor running in a terminal emulator\f[R] .PP -In this setup Tp\-Note launches the terminal emulator which is -configured to launch the text editor as child process. +In this setup Tp-Note launches the terminal emulator which is configured +to launch the text editor as child process. Neither process should fork when they start (see above). .PP Here, some examples you can adjust to your needs and taste: .IP \[bu] 2 -\f[I]Neovim\f[R] in \f[I]Xfce4\-Terminal\f[R]: +\f[I]Neovim\f[R] in \f[I]Xfce4-Terminal\f[R]: .RS 2 .IP .EX [app_args] unix.editor = [ [ - \[dq]xfce4\-terminal\[dq], - \[dq]\-\-disable\-server\[dq], - \[dq]\-x\[dq], + \[dq]xfce4-terminal\[dq], + \[dq]--disable-server\[dq], + \[dq]-x\[dq], \[dq]nvim\[dq], \[dq]+colorscheme pablo\[dq], \[dq]+set syntax=markdown\[dq], @@ -1968,16 +1956,16 @@ unix.editor = [ .EE .RE .IP \[bu] 2 -\f[I]Helix\-editor\f[R] in \f[I]XFCE4\-Terminal\f[R]: +\f[I]Helix-editor\f[R] in \f[I]XFCE4-Terminal\f[R]: .RS 2 .IP .EX [app_args] unix.editor = [ [ - \[dq]xfce4\-terminal\[dq], - \[dq]\-\-disable\-server\[dq], - \[dq]\-x\[dq], + \[dq]xfce4-terminal\[dq], + \[dq]--disable-server\[dq], + \[dq]-x\[dq], \[dq]hx\[dq], ], ] @@ -1992,8 +1980,8 @@ unix.editor = [ unix.editor = [ [ \[dq]lxterminal\[dq], - \[dq]\-\-no\-remote\[dq], - \[dq]\-e\[dq], + \[dq]--no-remote\[dq], + \[dq]-e\[dq], \[dq]hx\[dq], ], ] @@ -2008,11 +1996,11 @@ unix.editor = [ unix.editor = [ [ \[dq]xterm\[dq], - \[dq]\-fa\[dq], + \[dq]-fa\[dq], \[dq]DejaVu Sans Mono\[dq], - \[dq]\-fs\[dq], + \[dq]-fs\[dq], \[dq]12\[dq], - \[dq]\-e\[dq], + \[dq]-e\[dq], \[dq]hx\[dq], ], ] @@ -2027,7 +2015,7 @@ unix.editor = [ unix.editor = [ [ \[dq]alacritty\[dq], - \[dq]\-e\[dq], + \[dq]-e\[dq], \[dq]hx\[dq], ], ] @@ -2041,7 +2029,7 @@ Flatpack Helix in XFCE4 terminal [app_args] unix.editor = [ [ - \[dq]xfce4\-terminal\[dq], \[dq]\-\-disable\-server\[dq], \[dq]\-x\[dq], + \[dq]xfce4-terminal\[dq], \[dq]--disable-server\[dq], \[dq]-x\[dq], \[dq]flatpak\[dq], \[dq]run\[dq], \[dq]com.helix_editor.Helix\[dq], ], ] @@ -2054,7 +2042,7 @@ unix.editor_console = [ .EE .RE .SS Change the file extension for new note files -Tp\-Note identifies the note\[cq]s markup language by its file extension +Tp-Note identifies the note\[cq]s markup language by its file extension and renders the content accordingly (see `\f[CR]filename.extensions\f[R]' variable). For example: the variable `\f[CR]filename.extensions\f[R]' lists some @@ -2097,7 +2085,7 @@ extension_default = \[dq]markdown\[dq] .EE .PP This modification does not change how the note file\[cq]s content is -interpreted \- in this case as Markdown \- because both file extensions +interpreted - in this case as Markdown - because both file extensions `\f[CR].md\f[R]' and `\f[CR].markdown\f[R]' are rendered as `\f[CR]Markdown\f[R]' according to `\f[CR]filename.extensions\f[R]'. .SS Configure the natural language detection algorithm @@ -2108,11 +2096,11 @@ Depending on the context, the algorithm processes as input: the header field `\f[CR]title:\f[R]' or the first sentence of the text body. The natural language detection algorithm is implemented as a template filter named `\f[CR]get_lang\f[R]', which is used in various Tera -content templates `\f[CR]tmpl.*_content\f[R]' in Tp\-Note\[cq]s +content templates `\f[CR]tmpl.*_content\f[R]' in Tp-Note\[cq]s configuration file. The filter `\f[CR]get_lang\f[R]' is parametrized by the configuration variable `\f[CR]tmpl.filter.get_lang\f[R]' containing a list of ISO -639\-1 encoded languages, the algorithm considers as potential detection +639-1 encoded languages, the algorithm considers as potential detection candidates, e.g.: .IP .EX @@ -2142,13 +2130,13 @@ filter.get_lang = [ \[dq]+all\[dq], ] .PP Once the language is detected with the filter `\f[CR]get_lang\f[R]', it passes another filter called `\f[CR]map_lang\f[R]'. -This filter maps the result of `\f[CR]get_lang\f[R]' \- encoded as ISO -639\-1 code \- to an IETF language tag. -For example, `\f[CR]en\f[R]' is replaced with `\f[CR]en\-US\f[R]' or -`\f[CR]de\f[R]' with `\f[CR]de\-DE\f[R]'. +This filter maps the result of `\f[CR]get_lang\f[R]' - encoded as ISO +639-1 code - to an IETF language tag. +For example, `\f[CR]en\f[R]' is replaced with `\f[CR]en-US\f[R]' or +`\f[CR]de\f[R]' with `\f[CR]de-DE\f[R]'. This additional filtering is useful, because the detection algorithm can -not figure out the region code (e.g.\ \f[CR]\-US\f[R] or -\f[CR]\-DE\f[R]) by itself. +not figure out the region code (e.g.\ \f[CR]-US\f[R] or \f[CR]-DE\f[R]) +by itself. Instead, the region code is appended in a separate processing step. Spell checker or grammar checker like [LTeX] rely on this region information, to work properly. @@ -2161,43 +2149,43 @@ name = \[dq]default\[dq] [scheme.tmpl] filter.get_lang = [ \[dq]en\[dq], \[dq]fr\[dq], \[dq]de\[dq], \[dq]et\[dq] ] filter.map_lang = [ - [ \[dq]en\[dq], \[dq]en\-US\[dq], ], - [ \[dq]de\[dq], \[dq]de\-DE\[dq], ], + [ \[dq]en\[dq], \[dq]en-US\[dq], ], + [ \[dq]de\[dq], \[dq]de-DE\[dq], ], ] .EE .PP -When the user\[cq]s region setting \- as reported from the operating -system\[cq]s locale setting \- does not exist in above list, it is +When the user\[cq]s region setting - as reported from the operating +system\[cq]s locale setting - does not exist in above list, it is automatically appended as additional internal mapping. When the filter \f[CR]map_lang\f[R] encounters a language code for which no mapping is configured, the input language code is forwarded as it is without modification, e.g.\ the input \f[CR]fr\f[R] results in the output \f[CR]fr\f[R]. Subsequent entries that differ only in the region subtag, e.g. -`\f[CR][\[aq]en\[aq], \[aq]en\- GB\[aq]], [\[aq]en\[aq], \[aq]en\-US\[aq]]\f[R]' +`\f[CR][\[aq]en\[aq], \[aq]en- GB\[aq]], [\[aq]en\[aq], \[aq]en-US\[aq]]\f[R]' are ignored. .PP -Note, that the environment variable `\f[CR]TPNOTE_LANG_DETECTION\f[R]' -\- if set \- takes precedence over the `\f[CR]tmpl.filter.get_lang\f[R]' -and `\f[CR]tmpl.filter.map_lang\f[R]' settings. -This allows configuring the language detection feature system\-wide -without touching Tp\-Note\[cq]s configuration file. +Note, that the environment variable `\f[CR]TPNOTE_LANG_DETECTION\f[R]' - +if set - takes precedence over the `\f[CR]tmpl.filter.get_lang\f[R]' and +`\f[CR]tmpl.filter.map_lang\f[R]' settings. +This allows configuring the language detection feature system-wide +without touching Tp-Note\[cq]s configuration file. The following example achieves the equivalent result to the configuration hereinabove: .IP .EX -TPNOTE_LANG_DETECTION=\[dq]en\-US, fr, de\-DE, et\[dq] tpnote +TPNOTE_LANG_DETECTION=\[dq]en-US, fr, de-DE, et\[dq] tpnote .EE .PP If you want to enable all language detection candidates, add the pseudo tag `\f[CR]+all\f[R]' somewhere to the list: .IP .EX -TPNOTE_LANG_DETECTION=\[dq]en\-US, de\-DE, +all\[dq] tpnote +TPNOTE_LANG_DETECTION=\[dq]en-US, de-DE, +all\[dq] tpnote .EE .PP -In the above example the IETF language tags `\f[CR]en\-US\f[R]' and -`\f[CR]de\-DE\f[R]' are retained in order to configure the region codes +In the above example the IETF language tags `\f[CR]en-US\f[R]' and +`\f[CR]de-DE\f[R]' are retained in order to configure the region codes `\f[CR]US\f[R]' and `\f[CR]DE\f[R]' used by the `\f[CR]map_lang\f[R]' template filter. .PP @@ -2205,12 +2193,12 @@ For debugging observe the value of `\f[CR]SETTINGS\f[R]' in the debug log with: .IP .EX -tpnote \-d trace \-b +tpnote -d trace -b .EE .PP -If wished for, you can disable Tp\-Note\[cq]s language detection -feature, by deleting all entries in the -`\f[CR]tmpl.filter.get_lang\f[R]' variable: +If wished for, you can disable Tp-Note\[cq]s language detection feature, +by deleting all entries in the `\f[CR]tmpl.filter.get_lang\f[R]' +variable: .IP .EX [[scheme]] @@ -2272,7 +2260,7 @@ Templates refer to a header variable with an identifier starting with `\f[CR]fm_\f[R]', The identifier corresponds to the first column of the above table. .SS Change the default markup language -Tp\-Note\[cq]s core functionality, the management of note file headers +Tp-Note\[cq]s core functionality, the management of note file headers and filenames, is markup language agnostic. However, there is one content template `\f[CR]tmpl.annotate_file_content\f[R]' that generates a hyperlink. @@ -2282,9 +2270,9 @@ Hence, you should not forget to modify the change the default markup language defined in `\f[CR]filename.extension_default\f[R]'. .PP -Tp\-Note\[cq]s built\-in viewer is not markup language agnostic. +Tp-Note\[cq]s built-in viewer is not markup language agnostic. It comprises three different markup renderers (cf.\ section -\f[I]Customize the built\-in note viewer\f[R]): +\f[I]Customize the built-in note viewer\f[R]): .IP \[bu] 2 \f[I]Markdown\f[R] (file extension \f[CR].md\f[R]) .IP \[bu] 2 @@ -2293,13 +2281,13 @@ It comprises three different markup renderers (cf.\ section \f[I]PlainText\f[R] (Link only renderer, file extension \f[CR].txtnote\f[R]) .SS Change the default markup language to ReStructuredText -Tp\-Note\[cq]s core function is a template system and as such it depends +Tp-Note\[cq]s core function is a template system and as such it depends very little on the used markup language. The default templates are designed in a way that they contain almost no markup specific code. Though there is one little exception in the `\f[CR]annotate_file_content\f[R]' template. -For instance, to instruct Tp\-Note to create \f[CR].rst\f[R] files, +For instance, to instruct Tp-Note to create \f[CR].rst\f[R] files, create a configuration file \f[CR]\[ti]/.config/tpnote/tpnote.toml\f[R] with the following content: .PP @@ -2328,7 +2316,7 @@ COMPLETE HERE .PP In the above replace the string `\f[CR]COMPLETE HERE\f[R]' with the default values for the variables `\f[CR]annotate_file_content\f[R]' you -obtain with `\f[CR]tpnote \-C \- | less\f[R]'. +obtain with `\f[CR]tpnote -C - | less\f[R]'. .PP Then, in \f[CR]annotate_file_content\f[R] replace the line: .IP @@ -2349,36 +2337,36 @@ variable `\f[CR]file_ext:\f[R]' to its YAML header. For example, for ReStructuredText add: .IP .EX -\-\-\- +--- title: some note file_ext: rst -\-\-\- +--- .EE .PP -When Tp\-Note triggers the next filename synchronization, the filename +When Tp-Note triggers the next filename synchronization, the filename extension of the note file will change to `\f[CR].rst\f[R]'. The above modification applies to the current note only. .SS Change the sort tag character set -\f[I]Sort\-tags\f[R] for new notes are generated with the +\f[I]Sort-tags\f[R] for new notes are generated with the `\f[CR]tmpl.*_filename\f[R]' templates. -Before changing the sort\-tag generation scheme in these templates, make -sure to enable the right set of potential sort\-tag characters. +Before changing the sort-tag generation scheme in these templates, make +sure to enable the right set of potential sort-tag characters. .PP -In the default scheme, the digits `\f[CR]0\f[R]'\-`\f[CR]9\f[R]', all -lower case letters and the characters `\f[CR]_\f[R]', `\f[CR]\-\f[R]', +In the default scheme, the digits `\f[CR]0\f[R]'-`\f[CR]9\f[R]', all +lower case letters and the characters `\f[CR]_\f[R]', `\f[CR]-\f[R]', `\f[CR].\f[R]' are recognized as being part of a \f[I]sort tag\f[R] when they appear at the beginning of a filename. This set of characters can be modified with the `\f[CR]filename.sort_tag.extra_chars\f[R]' configuration variable. If defined, the `\f[CR]filename.sort_tag.separator\f[R]' (by default -`\f[CR]\-\f[R]') marks the end of a sort tag without being part of it. +`\f[CR]-\f[R]') marks the end of a sort tag without being part of it. In addition, one special character `\f[CR]filename.sort_tag.extra_separator\f[R]' (by default `\f[CR]\[aq]\f[R]') might be inserted by the filename template directly -after the `\f[CR]\-\f[R]' to avoid ambiguity. +after the `\f[CR]-\f[R]' to avoid ambiguity. .SS Customize the filename synchronization scheme The filename synchronization scheme is fully customizable through -\f[I]Tp\-Note\[cq]s filename templates\f[R]. +\f[I]Tp-Note\[cq]s filename templates\f[R]. To design such a custom scheme, start to set up your synchronization rules in the `\f[CR]tmpl.sync_filename\f[R]' template. Then adjust all `\f[CR]tmpl.*_filename\f[R]' templates to comply with @@ -2390,7 +2378,7 @@ latter should never change the filename initially set up by any `\f[CR]tmpl.*_filename\f[R]' template. .PP Secondly, make sure that in filename templates -`\f[CR]tmpl.*_filename\f[R]', sort\-tags +`\f[CR]tmpl.*_filename\f[R]', sort-tags `\f[CR]{{ path | file_sort_tag }}\f[R]' are never inserted directly. Instead, prepend the \f[I]sort_tag\f[R] with `\f[CR]prepend(with_sort_tag=path|file_sort_tag)\f[R]' to the following @@ -2401,24 +2389,24 @@ expression, e.g.: .EE .PP The filter `\f[CR]prepend(with_sort_tag=<...>)\f[R]' decides whether to -insert the `\f[CR]sort_tag.separator=\[dq]\-\[dq]\f[R]' and/or the +insert the `\f[CR]sort_tag.separator=\[dq]-\[dq]\f[R]' and/or the `\f[CR]sort_tag.extra_separator=\[dq]\[aq]\[dq]\f[R]' characters. -These heuristics enable Tp\-Note to identify unequivocally sort\-tags in +These heuristics enable Tp-Note to identify unequivocally sort-tags in filenames, which avoids potential cyclic filename change. Or, in other words: the `\f[CR]tmpl.sync_filname\f[R]' template must always give the same result, even after repeated application. .PP To debug your `\f[CR]tmpl.sync_filename\f[R]' template, create a test -note file `\f[CR]test.md\f[R]' and invoke Tp\-Note with -`\f[CR]\-\-debug trace\f[R]' and `\f[CR]\-\-batch\f[R]': +note file `\f[CR]test.md\f[R]' and invoke Tp-Note with +`\f[CR]--debug trace\f[R]' and `\f[CR]--batch\f[R]': .IP .EX -tpnote \-\-batch \-\-debug trace test.md +tpnote --batch --debug trace test.md .EE .SS Store new note files by default in a subdirectory When you are annotating an existing file on disk, the new note file is placed in the same directory by default. -To configure Tp\-Note to store the new note file in a subdirectory, +To configure Tp-Note to store the new note file in a subdirectory, let\[cq]s say `\f[CR]Notes/\f[R]', instead, you need to modify the templates `\f[CR]scheme.tmpl.annotate_file_filename\f[R]' and `\f[CR]scheme.tmpl.annotate_file_content\f[R]': @@ -2442,7 +2430,7 @@ COMPLETE HERE .PP In the above replace the string `\f[CR]COMPLETE HERE\f[R]' with the default values for the variables you obtain with -`\f[CR]tpnote \-C \- | less\f[R]'. +`\f[CR]tpnote -C - | less\f[R]'. .PP Then, replace in `\f[CR]annotate_file_filename\f[R]' the string: .IP @@ -2492,21 +2480,19 @@ current directory and annotate that file with: tpnote test.pdf .EE .PP -This should create a new note file -`\f[CR]./Notes/test.pdf\-\-Note.md\f[R] and open your web browser with a -link to'\f[CR]test.pdf\f[R]`. +This should create a new note file `\f[CR]./Notes/test.pdf--Note.md\f[R] +and open your web browser with a link to'\f[CR]test.pdf\f[R]`. Clicking on that link, the PDF page should be shown. The default behaviour, without this customization, is to create the new -note file'\f[CR]./test.pdf\-\-Note.md\f[R]\[cq] in the current -directory. +note file'\f[CR]./test.pdf--Note.md\f[R]\[cq] in the current directory. .PP -To test the `\f[CR]zettel\f[R]' scheme configuration invoke Tp\-Note +To test the `\f[CR]zettel\f[R]' scheme configuration invoke Tp-Note with: .IP .EX -tpnote \-s zettel test.pdf +tpnote -s zettel test.pdf .EE -.SS Customize the built\-in note viewer +.SS Customize the built-in note viewer .SS Change the way how note files are rendered for viewing Currently, three markup renderers are available: `\f[CR]Markdown\f[R]', `\f[CR]ReStructuredText\f[R]' and `\f[CR]PlainText\f[R]'. @@ -2519,8 +2505,8 @@ associating it with the pseudo `\f[CR]RendererDisabled\f[R]' renderer. If you wish to disable the viewer feature overall (for all file extensions), set the variable `\f[CR]arg_default.edit = true\f[R]'. .SS Delay the launch of the web browser -By default, Tp\-Note launches two external programs: some text editor -and a web browser. +By default, Tp-Note launches two external programs: some text editor and +a web browser. If wished for, the configuration variable `\f[CR]viewer.startup_delay\f[R]' allows delaying the launch of the web browser some milliseconds. @@ -2528,7 +2514,7 @@ This way the web browser window will always appear on top of the editor window. A negative value delays the start of the text editor instead. .SS Change the HTML rendition template -After the markup rendition process, Tp\-Note\[cq]s built\-in viewer +After the markup rendition process, Tp-Note\[cq]s built-in viewer generates its final HTML rendition through the customizable HTML templates `\f[CR]tmpl_html.viewer\f[R]', `\f[CR]tmpl_html.viewer_error\f[R]' and `\f[CR]tmpl_html.exporter\f[R]'. @@ -2547,19 +2533,19 @@ variables: .EX [tmpl_html] viewer = \[aq]\[aq]\[aq] -{%\- set ext = fm_file_ext | default(value=extension_default ) \-%} +{%- set ext = fm_file_ext | default(value=extension_default ) -%} - + {{ fm_title }} - 
{{ doc_fm_text }}
+ 
{{ doc_fm_text }}
-
+
{{ doc_body_text | markup_to_html(extension=ext) | safe }}
@@ -2579,23 +2565,23 @@ All content template variables and filters are available. See section \f[I]Template variables\f[R] above. .IP \[bu] 2 `\f[CR]{{ viewer_doc_css_path }}\f[R]' is the CSS stylesheet path -required to format an HTML rendition of a Tp\-Note document. -This path is hard\-wired and it is understood by Tp\-Note\[cq]s internal +required to format an HTML rendition of a Tp-Note document. +This path is hard-wired and it is understood by Tp-Note\[cq]s internal web server. .IP \[bu] 2 `\f[CR]{{ viewer_highlighting_css_path }}\f[R]' is the CSS stylesheet path required to highlight embedded source code. -This path is hard\-wired and it is understood by Tp\-Note\[cq]s internal +This path is hard-wired and it is understood by Tp-Note\[cq]s internal web server. .IP \[bu] 2 -`\f[CR]{{ doc_fm_text }}\f[R]' is the raw UTF\-8 copy of the header. +`\f[CR]{{ doc_fm_text }}\f[R]' is the raw UTF-8 copy of the header. Not to be confounded with the dictionary variable `\f[CR]{{ fm_all }}\f[R]'. .IP \[bu] 2 `\f[CR]{{ doc_body_text | markup_to_html(extension=ext) | safe }}\f[R]' is the note\[cq]s body as HTML rendition. The parameter `\f[CR]extension\f[R]' designates the markup language as -specified in the `\f[CR]filename.extensions\-*\f[R]' variables. +specified in the `\f[CR]filename.extensions-*\f[R]' variables. .IP \[bu] 2 `\f[CR]{{ doc_text | markup_to_html | safe }}\f[R]' is the note\[cq]s raw text as HTML rendition with clickable hyperlinks. @@ -2652,7 +2638,7 @@ The error page template `\f[CR]tmpl_html.viewer_error\f[R]' (see below) does not provide `\f[CR]fm_*\f[R]' variables, because of possible header syntax errors. Instead, the variable `\f[CR]{{ doc_error }}\f[R]' contains the error -message as raw UTF\-8 and the variable +message as raw UTF-8 and the variable `\f[CR]{{ doc_text | markup_to_html | safe }}\f[R]' the HTML rendition of the text source with clickable hyperlinks: .IP @@ -2662,13 +2648,13 @@ viewer_error = \[aq]\[aq]\[aq] - + Syntax error

Syntax error

in note file: 

{{ path }}

-

+
{{ doc_error }}
@@ -2679,21 +2665,21 @@ viewer_error = \[aq]\[aq]\[aq] \[aq]\[aq]\[aq] .EE -.SS Customize the built\-in HTML exporter -Customizing Tp\-Note\[cq]s HTML export function works the same way as -customizing the built\-in viewer. +.SS Customize the built-in HTML exporter +Customizing Tp-Note\[cq]s HTML export function works the same way as +customizing the built-in viewer. There are some slight differences though: The role of the -`\f[CR]tmpl_html.viewer\f[R]' template \- discussed above \- is taken -over by the `\f[CR]tmpl_html.exporter\f[R]' template: +`\f[CR]tmpl_html.viewer\f[R]' template - discussed above - is taken over +by the `\f[CR]tmpl_html.exporter\f[R]' template: .IP .EX [tmpl_html] exporter = \[aq]\[aq]\[aq] -{%\- set ext = fm_file_ext | default(value=extension_default ) \-%} +{%- set ext = fm_file_ext | default(value=extension_default ) -%} - + {{ fm_title }} - 
{{ doc_fm_text }}
+ 
{{ doc_fm_text }}
-
+
{{ doc_body_text| markup_to_html(extension=ext) | safe }}
@@ -2735,10 +2721,10 @@ control over the CCS input coming from the configuration file variables `\f[CR]tmpl_html.exporter_doc_css\f[R]' and `\f[CR]tmpl_html.exporter_highlighting_theme\f[R]'. .SS Choose your favourite web browser as note viewer -Once the note is rendered into HTML, Tp\-Note\[cq]s internal HTTP server +Once the note is rendered into HTML, Tp-Note\[cq]s internal HTTP server connects to a random port at the `\f[CR]localhost\f[R]' interface where the rendition is served to be viewed with a web browser. -Tp\-Note\[cq]s configuration file contains a list +Tp-Note\[cq]s configuration file contains a list `\f[CR]app_args.unix.browser\f[R]' with common web browsers and their usual location on Unix like operating systems. For other systems consult `\f[CR]app_args.windows.browser\f[R]' and @@ -2751,51 +2737,49 @@ your favourite web browser on top. .IP .EX [app_args] -unix.browser = [[ \[dq]chromium\[dq], \[dq]\-\-new\-window\[dq], \[dq]\-\-incognito\[dq]]] +unix.browser = [[ \[dq]chromium\[dq], \[dq]--new-window\[dq], \[dq]--incognito\[dq]]] .EE .PP Alternatively, you can set the `\f[CR]TPNOTE_BROWSER\f[R]' environment variable (cf. examples in the chapter \f[I]ENVIRONMENT_VARIABLES\f[R] below). .PP -In case none of the listed browsers can be found, Tp\-Note switches into +In case none of the listed browsers can be found, Tp-Note switches into a fallback mode with limited functionality, where it tries to open the system\[cq]s default web browser. -A disadvantage is, that in fall back mode Tp\-Note is not able to detect +A disadvantage is, that in fall back mode Tp-Note is not able to detect when the user closes the web browser. -This might lead to situations, where Tp\-Note\[cq]s internal HTTP server +This might lead to situations, where Tp-Note\[cq]s internal HTTP server shuts down to early. -In order to check if Tp\-Note finds the selected web browser as -intended, invoke Tp\-Note with -`\f[CR]tpnote \-\-debug debug \-\-popup \-\-view\f[R]'. +In order to check if Tp-Note finds the selected web browser as intended, +invoke Tp-Note with `\f[CR]tpnote --debug debug --popup --view\f[R]'. .SH TEMPLATES -All \f[I]TP\-Note\f[R]\[cq]s workflows are customizable through its +All \f[I]TP-Note\f[R]\[cq]s workflows are customizable through its templates which are grouped in the `\f[CR][scheme.tmpl]\f[R]' and in the -`\f[CR][scheme.tmpl_html]\f[R]' section of Tp\-Note\[cq]s configuration +`\f[CR][scheme.tmpl_html]\f[R]' section of Tp-Note\[cq]s configuration file. This chapter deals with `\f[CR][scheme.tmpl]\f[R]' templates which are -responsible for generating Tp\-Note files. -`\f[CR][scheme.tmpl_html]\f[R]' templates concern only Tp\-Note\[cq]s -viewer feature and are discussed in the chapters: Customize the -built\-in note viewer_ and \f[I]Choose your favourite web browser as -note viewer\f[R]. -.PP -Tp\-Note captures and stores its environment in \f[I]Tera -variables\f[R]. +responsible for generating Tp-Note files. +`\f[CR][scheme.tmpl_html]\f[R]' templates concern only Tp-Note\[cq]s +viewer feature and are discussed in the chapters: Customize the built-in +note viewer_ and \f[I]Choose your favourite web browser as note +viewer\f[R]. +.PP +Tp-Note captures and stores its environment in \f[I]Tera variables\f[R]. For example, the variable `\f[CR]{{ dir_path }}\f[R]' is initialized with the note\[cq]s target directory. The variable `\f[CR]{{ clipboard }}\f[R]' contains the content of the clipboard. -To learn more about Tera variables, launch Tp\-Note with the -`\f[CR]\-\-debug trace\f[R]' option and observe what information it +To learn more about Tera variables, launch Tp-Note with the +`\f[CR]--debug trace\f[R]' option and observe what information it captures from its environment. .SS Template types -The content of a new note is composed by one of Tp\-Note\[cq]s internal -customizable templates, hence the name Tp\-Note, where \f[I]Tp\f[R] +The content of a new note is composed by one of Tp-Note\[cq]s internal +customizable templates, hence the name Tp-Note, where \f[I]Tp\f[R] stands for \[lq]template\[rq]. Which of the internal templates is applied depends on the context in -which Tp\-Note is invoked: e.g.\ the template for clipboard text input -is called `\f[CR]tmpl.from_clipboard_content\f[R]'. +which Tp-Note is invoked: e.g.\ the template for clipboard text input is +called `\f[CR]tmpl.from_clipboard_content\f[R]'. If the clipboard contains text with a YAML header, the template `\f[CR]tmpl.from_clipboard_yaml_content\f[R]' is used. .PP @@ -2812,12 +2796,12 @@ In total, there are 5 different `\f[CR]tmpl.*_content\f[R]' templates: `\f[CR]tmpl.annotate_file_content\f[R]' .PP In general, the templates are designed in a way, that the text input -stream \- usually originating from the clipboard \- ends up in the body -of the note file, whereas the environment \- such as the username \- -ends up in the header of the note file. +stream - usually originating from the clipboard - ends up in the body of +the note file, whereas the environment - such as the username - ends up +in the header of the note file. .PP Once the content of the new note is set by one of the content templates, -another template type comes into play: the so\-called \f[I]filename +another template type comes into play: the so-called \f[I]filename template\f[R]. Each content template has a corresponding filename template, e.g.: .IP \[bu] 2 @@ -2841,15 +2825,15 @@ filename templates through various `\f[CR]{{ fm_ }}\f[R]' dynamically created template variables. For example the value of the YAML header field `\f[CR]title:\f[R]' can be accessed with `\f[CR]{{ fm_title }}\f[R]'. -Once the filename is set, Tp\-Note writes out the new note on disk. +Once the filename is set, Tp-Note writes out the new note on disk. .PP Most of the above templates are dedicated to the creation of new note files. However, two of them have a special role: \f[I]prepend header to text file\f[R] and \f[I]synchronize filename\f[R]: .IP \[bu] 2 -\f[I]Prepend header to text file\f[R] (new feature in Tp\-Note v1.16.0): -When Tp\-Note opens a regular text file without a YAML header, a new +\f[I]Prepend header to text file\f[R] (new feature in Tp-Note v1.16.0): +When Tp-Note opens a regular text file without a YAML header, a new header is prepended automatically. It\[cq]s data originates mainly form the filename of the text file. The templates applied in this use case are: @@ -2857,12 +2841,12 @@ The templates applied in this use case are: `\f[CR]tmpl.from_text_file_filename\f[R]'. .IP \[bu] 2 \f[I]Synchronize filename\f[R]: This function mode is invoked when -[Tp\-Note] opens an existing note file, after it\[cq]s YAML header is +[Tp-Note] opens an existing note file, after it\[cq]s YAML header is evaluated. The extracted header information is then applied to the `\f[CR]tmpl.sync_filename\f[R]' template and the resulting filename is compared with the actual filename on disk. -If they differ, [Tp\-Note] renames the note file. +If they differ, [Tp-Note] renames the note file. Note, the `\f[CR]tmpl.sync_filename\f[R]' template operates on its own without a corresponding content template. .PP @@ -2883,26 +2867,26 @@ You can disable the \f[I]prepend header\f[R] feature by setting the configuration file variable `\f[CR]arg_default.add_header = false\f[R]'. To disable all filename synchronization, set `\f[CR]arg_default.no_filename_sync = true\f[R]'. -This guarantees, that Tp\-Note will never change neither the filename -nor the YAML header of an existing file. +This guarantees, that Tp-Note will never change neither the filename nor +the YAML header of an existing file. .PP For a more detailed description of templates and their defaults, please -consult the `\f[CR]const\f[R]' definitions in Tp\-Note\[cq]s source code +consult the `\f[CR]const\f[R]' definitions in Tp-Note\[cq]s source code files `\f[CR]config.rs\f[R]' and `\f[CR]note.rs\f[R]' in the directory -`\f[CR]tpnote\-lib/src/\f[R]'. +`\f[CR]tpnote-lib/src/\f[R]'. .SS Template variables All \c .UR https://tera.netlify.com/%20docs/#templates Tera template variables and functions .UE \c -\ can be used within Tp\-Note\[cq]s templates. +\ can be used within Tp-Note\[cq]s templates. For example `\f[CR]{{ get_env(name=\[aq]LANG\[aq]) }}\[aq]\f[R] gives you access to the'\f[CR]LANG\f[R]\[cq] environment variable. .PP -In addition, Tp\-Note defines the following variables: +In addition, Tp-Note defines the following variables: .IP \[bu] 2 `\f[CR]{{ path }}\f[R]' is the canonicalized fully qualified path name -corresponding to Tp\-Note\[cq]s positional command line parameter +corresponding to Tp-Note\[cq]s positional command line parameter `\f[CR]\f[R]'. If none was given on the command line, `\f[CR]{{ path }}\f[R]' contains the current working directory path. @@ -2965,7 +2949,7 @@ Otherwise: empty string. `\f[CR]{{ extension_default }}\f[R]' is the default extension for new notes (can be changed in the configuration file), .IP \[bu] 2 -`\f[CR]{{ username }}\f[R]' is the content of the first non\-empty +`\f[CR]{{ username }}\f[R]' is the content of the first non-empty environment variable: `\f[CR]TPNOTE_USER\f[R]', `\f[CR]LOGNAME\f[R]', `\f[CR]USER\f[R]' or `\f[CR]USERNAME\f[R]'. .IP \[bu] 2 @@ -2989,7 +2973,7 @@ a field named `\f[CR]title:\f[R]' in the content template `\f[CR]fm_title\f[R]' which can then be used in the corresponding `\f[CR]tmpl.from_dir_filename\f[R]' filename template. `\f[CR]{{ fm_* }}\f[R]' variables are generated dynamically. -This means, a YAML front\-matter variable `\f[CR]foo:\f[R]' in a note +This means, a YAML front-matter variable `\f[CR]foo:\f[R]' in a note will generate a `\f[CR]{{ fm_foo }}\f[R]' template variable. On the other hand, a missing `\f[CR]foo:\f[R]' will cause `\f[CR]{{ fm_foo }}\f[R]' to be undefined. @@ -3003,16 +2987,16 @@ available in filename templates and in the `\f[CR]tmpl.from_clipboard_yaml_content\f[R]' content template. .IP \[bu] 2 `\f[CR]{{ fm_title }}\f[R]' is the `\f[CR]title:\f[R]' as indicated in -the YAML front\-matter of the note. +the YAML front-matter of the note. .IP \[bu] 2 `\f[CR]{{ fm_subtitle }}\f[R]' is the `\f[CR]subtitle:\f[R]' as indicated in the YAML front matter of the note. .IP \[bu] 2 `\f[CR]{{ fm_author }}\f[R]' is the `\f[CR]author:\f[R]' as indicated in -the YAML front\-matter of the note. +the YAML front-matter of the note. .IP \[bu] 2 `\f[CR]{{ fm_lang }}\f[R]' is the `\f[CR]lang:\f[R]' as indicated in the -YAML front\-matter of the note. +YAML front-matter of the note. .IP \[bu] 2 `\f[CR]{{ fm_file_ext }}\f[R]' holds the value of the optional YAML header variable `\f[CR]file_ext:\f[R]' @@ -3046,14 +3030,14 @@ The latter are then type checked according configurable rules. The rules are defined in `\f[CR]tmpl.filter.assert_precondition\f[R]' .PP For a more detailed description of the available template variables, -please consult the `\f[CR]const\f[R]' definitions in Tp\-Note\[cq]s +please consult the `\f[CR]const\f[R]' definitions in Tp-Note\[cq]s source code file `\f[CR]note.rs\f[R]'. .SS Template filters In addition to \f[I]Tera\f[R]\[cq]s \c .UR https://tera.netlify.app/docs/#built-in-filters -built\-in filters +built-in filters .UE \c -, Tp\-Note comes with some additional filters, i.e.: +, Tp-Note comes with some additional filters, i.e.: `\f[CR]append(newline=true)\f[R]', `\f[CR]append(with=...)\f[R]', `\f[CR]cut\f[R]', `\f[CR]file_copy_counter\f[R]', `\f[CR]file_ext\f[R]', `\f[CR]file_name\f[R]', `\f[CR]file_sort_tag\f[R]', @@ -3073,16 +3057,16 @@ Here are some examples: `\f[CR]{{ path |\ file_name }}\f[R]' returns the final component of `\f[CR]{{ path }}\f[R]'. If `\f[CR]{{ path }}\f[R]' points to a file, the filter returns the -complete filename including its sort tag, stem, copy\-counter, dot and +complete filename including its sort tag, stem, copy-counter, dot and extension. If the `\f[CR]\f[R]' points to a directory, the filter returns the final directory name. .IP \[bu] 2 `\f[CR]{{ path | file_sort_tag }}\f[R]' is the sort tag (numerical filename prefix) of the final component of `\f[CR]{{ path }}\f[R]', -e.g.\ `\f[CR]01\-23_9\f[R]' or `\f[CR]20191022\f[R]'. +e.g.\ `\f[CR]01-23_9\f[R]' or `\f[CR]20191022\f[R]'. It is similar to `\f[CR]{{ path |\ file_name }}\f[R]' but without -returning its stem, copy\-counter and extension. +returning its stem, copy-counter and extension. .IP \[bu] 2 `\f[CR]{{ path | file_sort_tag | assert_valid_sort_tag }}\f[R]' does not change the above output, but the filter asserts at runtime, that the @@ -3093,7 +3077,7 @@ The additional runtime check simplifies template debugging. .IP \[bu] 2 `\f[CR]{{ path |\ file_stem }}\f[R]' is similar to `\f[CR]{{ path |\ file_name }}\f[R]' but without its sort tag, -copy\-counter and extension. +copy-counter and extension. Only the stem of `\f[CR]{{ path }}\f[R]'\[cq]s last component is returned. .IP \[bu] 2 @@ -3118,13 +3102,13 @@ component), `\f[CR]trim_file_sort_tag\f[R]' trims the sort tag if there is one. .IP \[bu] 2 `\f[CR]{{ dir_path | find_last_created_file | incr_sort_tag(default=\[dq]\[dq]) }}\f[R]' -searches `\f[CR]dir_path\f[R]' for the most recently created Tp\-Note -file, extracts the sort\-tag from this file, increments the sort\-tag -and returns the result. +searches `\f[CR]dir_path\f[R]' for the most recently created Tp-Note +file, extracts the sort-tag from this file, increments the sort-tag and +returns the result. If the incrementation fails, the `\f[CR]default\f[R]' value is returned. -This can happen, when the input sort\-tag contains characters of the set +This can happen, when the input sort-tag contains characters of the set `\f[CR]tmpl.filter.incr_sort_tag.default_if_contains\f[R]'. -Or, if the to be incremented counter (a sequential sort\-tag usually has +Or, if the to be incremented counter (a sequential sort-tag usually has more than one counter) has more than `\f[CR]tmpl.filter.incr_sort_tag.default_if_greater\f[R]' digits. .IP \[bu] 2 @@ -3158,9 +3142,9 @@ Markdown or ReStruncturedText formatted link in the clipboard. .IP \[bu] 2 `\f[CR]{{ username | capitalize | to_yaml(key=\[aq]author\[aq],tab=12) }}\f[R]' is the capitalized YAML encoded username. -As all YAML front\-matter is YAML encoded, the `\f[CR]to_yaml\f[R]' +As all YAML front-matter is YAML encoded, the `\f[CR]to_yaml\f[R]' filter must be appended to any template variable placed in the -front\-matter block. +front-matter block. The `\f[CR]key=\[aq]author\[aq]\f[R]' parameter prepends the key to the capitalized username, e.g.: `\f[CR]autor: John\f[R]'. Note, the first letter of `\f[CR]John\f[R]' starts at the tabulator @@ -3168,16 +3152,16 @@ position `\f[CR]tab=12\f[R]'. .IP \[bu] 2 `\f[CR]{{ fm_subtitle | sanit }}\f[R]' is the note\[cq]s subtitle as defined in its front matter, sanitized in a file system friendly form. -Special characters are omitted or replaced by `\f[CR]\-\f[R]' and +Special characters are omitted or replaced by `\f[CR]-\f[R]' and `\f[CR]_\f[R]'. See the section \f[I]Filename template convention\f[R] for more details about this filter. .IP \[bu] 2 `\f[CR]{{ fm_title | sanit | prepend(with_sort_tag=path|file_sort_tag) }}\f[R]' -is the note\[cq]s title as defined in its front\-matter. +is the note\[cq]s title as defined in its front-matter. Same as above, but the title string is prepended with the note\[cq]s \f[I]sort_tag\f[R] and with a `\f[CR]filename.sort_tag.separator\f[R]' -(by default `\f[CR]\-\f[R]'). +(by default `\f[CR]-\f[R]'). Eventually, a second `\f[CR]filename.sort_tag.extra_separator\f[R]' (by default `\f[CR]\[aq]\[aq]\f[R]') is inserted after the first to guarantee, that one of the separators unequivocally marks the end of the @@ -3211,10 +3195,10 @@ to pass through the HTML formatting of objects and arrays. .IP \[bu] 2 `\f[CR]{{ doc_body_text | get_lang }}\f[R]' determines the natural language of the variable `\f[CR]{{ doc_body_text }}\f[R] and returns the -result as ISO 639\-1 language code. +result as ISO 639-1 language code. The template filter'\f[CR]{{ get_lang }}\f[R]\[cq] can be configured with the configuration file variable `\f[CR]tmpl.filter.get_lang\f[R]'. -The latter defines a list of ISO 639\-1 codes, the detection algorithm +The latter defines a list of ISO 639-1 codes, the detection algorithm considers as possible language candidates. Keep this list as small as possible, because language detection is computationally expensive. @@ -3224,9 +3208,9 @@ If the detection algorithm can not determine the language of returns an empty string. .IP \[bu] 2 `\f[CR]{{ doc_body_text | get_lang | map_lang }}\f[R]' maps the detected -ISO 638\-1 language code to a complete IETF BCP 47 language tag, usually +ISO 638-1 language code to a complete IETF BCP 47 language tag, usually containing the region subtag. -For example the input `\f[CR]en\f[R]' results in `\f[CR]en\-US\f[R]'. +For example the input `\f[CR]en\f[R]' results in `\f[CR]en-US\f[R]'. This additional mapping is useful because the detection algorithm can not determine the region automatically. The mapping can be configured by adjusting the configuration file @@ -3248,8 +3232,8 @@ to. Defaults to the current date in cases `\f[CR]{{ doc_file_date }}\f[R]' is not defined (see \f[I]Template variables\f[R] section). .SS Content template conventions -Tp\-Note distinguishes two template types: content templates are used to -create the note\[cq]s content (front\-matter and body) and the +Tp-Note distinguishes two template types: content templates are used to +create the note\[cq]s content (front-matter and body) and the corresponding filename templates `\f[CR]tmpl.*_filename\f[R]' are used to calculate the note\[cq]s filename. By convention, content templates appear in the configuration file in @@ -3257,8 +3241,8 @@ variables named `\f[CR]tmpl.*_content\f[R]'. .PP Strings in the front matter section of content templates are YAML encoded. -Therefore, all variables used in the front\-matter must pass an -additional `\f[CR]to_yaml()\f[R]'\-filter. +Therefore, all variables used in the front-matter must pass an +additional `\f[CR]to_yaml()\f[R]'-filter. For example, the variable `\f[CR]{{ dir_path | file_stem() }}\f[R]' becomes `\f[CR]{{ dir_path | file_stem() | to_yaml(key=\[aq]title\[aq]) }}\f[R]' @@ -3281,7 +3265,7 @@ has a special role as it synchronizes the filename of existing note files. Besides this, as we are dealing with filenames we must guarantee, that the filename templates produce only file system friendly characters. -For this purpose Tp\-Note provides the additional Tera filter +For this purpose Tp-Note provides the additional Tera filter `\f[CR]sanit\f[R]': .PP The `\f[CR]sanit()\f[R]' filter transforms a string in a file system @@ -3292,7 +3276,7 @@ This filter can be used with any variable, but is most useful with filename templates. For example, in the `\f[CR]tmpl.sync_filename\f[R]' template, we find the expression `\f[CR]{{ subtitle | sanit }}\f[R]'. -Note that the filter recognizes strings that represent a so\-called dot +Note that the filter recognizes strings that represent a so-called dot file name and treats them a little differently by prepending them with an apostrophe: a dot file is a file whose name starts with `\f[CR].\f[R]' and that does not contain whitespace. @@ -3303,26 +3287,26 @@ The `\f[CR]prepend(with_sort_tag=<...>\f[R]' filter is similar to the `\f[CR]prepend(with=<...>\f[R]' filter, with two exceptions: .IP "1." 3 If `\f[CR]filename.sort_tag.separator\f[R]' is defined (by default -`\f[CR]\-\f[R]'), it is automatically inserted between the sort\-tag and +`\f[CR]-\f[R]'), it is automatically inserted between the sort-tag and the input string. .IP "2." 3 In some cases an additional separator `\f[CR]filename.sort_tag.extra_separator\f[R]' (by default `\f[CR]\[aq]\f[R]') may be inserted as well. .PP -Both separators guarantee that the end of a sort\-tag is detected +Both separators guarantee that the end of a sort-tag is detected unequivocally. For example, when the input string starts with a digit -`\f[CR]0123456789\f[R]' or `\f[CR]\-_\f[R]', the string is prepended -with \f[CR]\-\[aq]\f[R], e.g. -`\f[CR]1\-The Show Begins\f[R]' becomes -`\f[CR]\[aq]1\-The Show Begins\f[R]'. +`\f[CR]0123456789\f[R]' or `\f[CR]-_\f[R]', the string is prepended with +\f[CR]-\[aq]\f[R], e.g. +`\f[CR]1-The Show Begins\f[R]' becomes +`\f[CR]\[aq]1-The Show Begins\f[R]'. The `\f[CR]prepend(with_sort_tag=<...>)\f[R]' filter must be applied to the first variable, e.g.\ `\f[CR]{{ fm_title | sanit | prepend(with_separator=path|file_sort_tag )}\f[R]'. -This way, it is always possible to univocally distinguish the sort\-tag +This way, it is always possible to univocally distinguish the sort-tag from the rest of the filename. -Note, the default sort\-tag separators can be changed with the +Note, the default sort-tag separators can be changed with the configuration variables `\f[CR]filename.sort_tag.separator\f[R]' and `\f[CR]filename.sort_tag.extra_separator\f[R]'. For more details please consult the \f[I]Customize the filename @@ -3330,34 +3314,33 @@ synchronization scheme\f[R] chapter. .PP In filename templates most variables must pass the `\f[CR]sanit\f[R]' filter. -Exception to this rule are sort\-tag expressions like +Exception to this rule are sort-tag expressions like `\f[CR]{{ path | file_sort_tag }}\f[R]' and `\f[CR]{{ dir_path | file_sort_tag }}\f[R]'. As the latter are guaranteed to contain only the file system friendly -characters `\f[CR]0123456789 \-_\f[R]', no additional filtering is +characters `\f[CR]0123456789 -_\f[R]', no additional filtering is required. -Please note, that in this case a `\f[CR]sanit\f[R]'\-filter would -needlessly restrict the value range of sort\-tags because they may -contain characters, which the `\f[CR]sanit\f[R]'\-filter screens out -when they appear in leading or trailing position. -For this reason one must not use the `\f[CR]sanit\f[R]'\-filter together +Please note, that in this case a `\f[CR]sanit\f[R]'-filter would +needlessly restrict the value range of sort-tags because they may +contain characters, which the `\f[CR]sanit\f[R]'-filter screens out when +they appear in leading or trailing position. +For this reason one must not use the `\f[CR]sanit\f[R]'-filter together with `\f[CR]{{ path | file_sort_tag }}\f[R]' or `\f[CR]{{ dir_path |file_sort_tag }}\f[R]'. .SH SECURITY AND PRIVACY CONSIDERATIONS -As discussed above, Tp\-Note\[cq]s built\-in viewer sets up an HTTP -server on the `\f[CR]localhost\f[R]' interface with a random port -number. +As discussed above, Tp-Note\[cq]s built-in viewer sets up an HTTP server +on the `\f[CR]localhost\f[R]' interface with a random port number. .PP -For security reasons, Tp\-Note limits the set of files the viewer is -able to publish. +For security reasons, Tp-Note limits the set of files the viewer is able +to publish. To summarize, a file is only served: .IP "1." 3 -When it is referenced in one of the currently viewed Tp\-Note files, +When it is referenced in one of the currently viewed Tp-Note files, .IP "2." 3 when its file extension is registered with the `\f[CR]viewer.served_mime_type\f[R]' list, .IP "3." 3 -if the number of so far viewed Tp\-Note files, +if the number of so far viewed Tp-Note files, `\f[CR]viewer.displayed_tpnote_count_max\f[R]' is not exceeded, .IP "4." 3 when it\[cq]s located under a directory containing a marker file named @@ -3365,32 +3348,32 @@ when it\[cq]s located under a directory containing a marker file named .PP The HTTP server runs as long as the launched web browser window is open. Note, that the server not only exposes the displayed note file, but also -all referenced inline images and other linked TP\-Note files. +all referenced inline images and other linked TP-Note files. Internally, the viewer maintains a list of \f[I]referenced local URLs\f[R]. For security reasons, only listed files are served. To limit data exfiltration in case an attacker gains access to an -account on your machine, the number of served Tp\-Note files is limited +account on your machine, the number of served Tp-Note files is limited by the configurable value `\f[CR]viewer.displayed_tpnote_count_max\f[R]'. .PP -In addition to the above quantitative restriction, Tp\-Note\[cq]s -built\-in viewer serves only files whose file extensions are registered +In addition to the above quantitative restriction, Tp-Note\[cq]s +built-in viewer serves only files whose file extensions are registered with the `\f[CR]viewer.served_mime_type\f[R]' configuration file variable. -The latter allows disabling the \f[I]follow links to other Tp\-Note +The latter allows disabling the \f[I]follow links to other Tp-Note files\f[R] feature by removing all `\f[CR]text/*\f[R]' mime types from that list. .PP Another security feature is the `\f[CR].tpnote.toml\f[R]' marker file. -When Tp\-Note opens a note file, it checks all directories above, one by +When Tp-Note opens a note file, it checks all directories above, one by one, until it finds the marker file `\f[CR].tpnote.toml\f[R]'. -Tp\-Note\[cq]s viewer will never serve a file located outside the root +Tp-Note\[cq]s viewer will never serve a file located outside the root directory and its children. When no `\f[CR].tpnote.toml\f[R]' file is found, the root directory is set to `\f[CR]/\f[R]', which disables this security feature. .PP -As Tp\-Note\[cq]s built\-in viewer binds to the `\f[CR]localhost\f[R]' +As Tp-Note\[cq]s built-in viewer binds to the `\f[CR]localhost\f[R]' interface, the exposed files are in principle accessible to all processes running on the computer. As long as only one user is logged into the computer at a given time, no @@ -3398,54 +3381,53 @@ privacy concern is raised: any potential attacker must be logged in, in order to access the \f[CR]localhost\f[R] HTTP server. .PP This is why on systems where multiple users are logged in at the same -time, it is recommended to disable Tp\-Note\[cq]s internal HTTP server -by setting the configuration file variable +time, it is recommended to disable Tp-Note\[cq]s internal HTTP server by +setting the configuration file variable `\f[CR]arg_default.edit = true\f[R]'. -Alternatively, you can also compile Tp\-Note without the +Alternatively, you can also compile Tp-Note without the `\f[CR]viewer\f[R]' feature. Note, that even if the viewer feature disabled, the -`\f[CR]\-\-export\f[R]' command line option still works: This allows the +`\f[CR]--export\f[R]' command line option still works: This allows the authorized user to render the note to HTML manually. .PP -\f[B]Summary\f[R]: As long as Tp\-Note\[cq]s built\-in note viewer is +\f[B]Summary\f[R]: As long as Tp-Note\[cq]s built-in note viewer is running, the note file and all its referenced (image) files are exposed to all users logged into the computer at that given time. -This concerns only local users, Tp\-Note never exposes any information -to the network or on the Internet. +This concerns only local users, Tp-Note never exposes any information to +the network or on the Internet. .SH ENVIRONMENT VARIABLES LANG .RS .PP -Tp\-Note stores the user\[cq]s locale settings \- originating from the -environment variable `\f[CR]LANG\f[R]' (or the Windows registry) \- in +Tp-Note stores the user\[cq]s locale settings - originating from the +environment variable `\f[CR]LANG\f[R]' (or the Windows registry) - in the template variable `\f[CR]{{ lang }}\f[R]'. When the environment variable `\f[CR]TPNOTE_LANG\f[R]' is set, it overwrites the locale setting stored in `\f[CR]{{ lang }}\f[R]'. `\f[CR]man locale\f[R]' describes the data format of `\f[CR]LANG\f[R]', -a typical value is `\f[CR]en_GB.UTF\-8\f[R]'. +a typical value is `\f[CR]en_GB.UTF-8\f[R]'. .RE .PP TPNOTE_CONFIG .RS .PP When set, the environment variable replaces the default path where -Tp\-Note loads or stores its configuration file. -It has the same effect as the command line option -`\f[CR]\-\-config\f[R]'. +Tp-Note loads or stores its configuration file. +It has the same effect as the command line option `\f[CR]--config\f[R]'. If both are present, that latter takes precedence. .RE .PP TPNOTE_LANG .RS .PP -Tp\-Note stores the user\[cq]s locale settings \- originating from the -environment variable `\f[CR]LANG\f[R]' (or the Windows registry) \- in +Tp-Note stores the user\[cq]s locale settings - originating from the +environment variable `\f[CR]LANG\f[R]' (or the Windows registry) - in the template variable `\f[CR]{{ lang }}\f[R]'. When the environment variable `\f[CR]TPNOTE_LANG\f[R]' is set, it overwrites the locale setting stored in `\f[CR]{{ lang }}\f[R]'. Unlike `\f[CR]LANG\f[R]', the environment variable `\f[CR]TPNOTE_LANG\f[R]' is encoded as IETF BCP 47 language tag, -e.g.\ `\f[CR]en\-US\f[R]'. +e.g.\ `\f[CR]en-US\f[R]'. .RE .PP TPNOTE_LANG_DETECTION @@ -3453,20 +3435,20 @@ TPNOTE_LANG_DETECTION .PP If set, this variable overwrites the configuration file variables `\f[CR]tmpl.filter.get_lang\f[R]' and `\f[CR]tmpl.filter.map_lang\f[R]', -thus selecting potential language candidates for Tp\-Note\[cq]s natural +thus selecting potential language candidates for Tp-Note\[cq]s natural language detection. The string contains a comma and space separated list of ISO 63901 codes, e.g. -`\f[CR]fr\f[R]' or IETF BCP 47 tags, e.g.\ `\f[CR]fr\-FR\f[R]'. +`\f[CR]fr\f[R]' or IETF BCP 47 tags, e.g.\ `\f[CR]fr-FR\f[R]'. Here is an example of a complete string: -`\f[CR]de\-DE, en, fr\-FR, hu\f[R]'. +`\f[CR]de-DE, en, fr-FR, hu\f[R]'. The user\[cq]s default locale `\f[CR]{{ lang }}\f[R]' is automatically added to the list. Note, that the language detection algorithm determines only the language subtag, e.g.\ `\f[CR]en\f[R]'. The region subtag will be added as indicated in your configuration. Subsequent entries that differ only in the region subtag, -e.g.\ `\f[CR]en\-GB, en\-US\f[R]' are ignored. +e.g.\ `\f[CR]en-GB, en-US\f[R]' are ignored. .RE .RS .PP @@ -3486,7 +3468,7 @@ log: .RS .IP .EX -TPNOTE_LANG_DETECTION=\[dq]de\-DE, en, fr\-FR\[dq] tpnote \-d trace \-b +TPNOTE_LANG_DETECTION=\[dq]de-DE, en, fr-FR\[dq] tpnote -d trace -b .EE .RE .PP @@ -3505,14 +3487,14 @@ For example: .RS .IP .EX -TPNOTE_BROWSER=\[dq]chromium \-\-new\-window \-\-incognito\[dq] tpnote +TPNOTE_BROWSER=\[dq]chromium --new-window --incognito\[dq] tpnote .EE .RE .RS .PP -The above instructs Tp\-Note to start the web browser -`\f[CR]chromium\f[R]' with the flags `\f[CR]\-\-new\-window\f[R]' and -`\f[CR]\-\-incognito\f[R]'. +The above instructs Tp-Note to start the web browser +`\f[CR]chromium\f[R]' with the flags `\f[CR]--new-window\f[R]' and +`\f[CR]--incognito\f[R]'. Unlike in a shell, the backslash and quote characters have no special meaning. Instead, all tokens are \f[I]percent encoded\f[R], @@ -3521,7 +3503,7 @@ e.g.\ `\f[CR]my path\f[R]' becomes `\f[CR]my%20path\f[R]'. .RS .PP The empty string disables the launch of the browser the same way as -`\f[CR]\-\-edit\f[R]': +`\f[CR]--edit\f[R]': .RE .RS .IP @@ -3536,7 +3518,7 @@ is equivalent to: .RS .IP .EX -tpnote \-\-edit +tpnote --edit .EE .RE .PP @@ -3556,13 +3538,13 @@ For example: .RS .IP .EX -TPNOTE_EDITOR=\[dq]geany \-sim\[dq] tpnote +TPNOTE_EDITOR=\[dq]geany -sim\[dq] tpnote .EE .RE .RS .PP -The above instructs Tp\-Note to start the editor `\f[CR]geany\f[R]' with -the flags `\f[CR]\-sim\f[R]'. +The above instructs Tp-Note to start the editor `\f[CR]geany\f[R]' with +the flags `\f[CR]-sim\f[R]'. Unlike with shell tokens, the backslash and quote characters have no special meaning. Instead, all tokens are \f[I]percent encoded\f[R]. @@ -3572,13 +3554,13 @@ Consider the following example where the space character is expressed as .RS .IP .EX -TPNOTE_EDITOR=\[dq]geany \-sim \-c \[ti]/my%20config/\[dq] tpnote +TPNOTE_EDITOR=\[dq]geany -sim -c \[ti]/my%20config/\[dq] tpnote .EE .RE .RS .PP The empty string disables the launch of the editor the same way as the -command line option `\f[CR]\-\-view\f[R]' does: +command line option `\f[CR]--view\f[R]' does: .RE .RS .IP @@ -3593,7 +3575,7 @@ is equivalent to: .RS .IP .EX -tpnote \-\-view +tpnote --view .EE .RE .PP @@ -3638,21 +3620,21 @@ TPNOTE_USER, LOGNAME, USER, USERNAME .RS .PP The template variable `\f[CR]{{ username }}\f[R]' is the content of the -first non\-empty environment variable: `\f[CR]TPNOTE_USER\f[R]', +first non-empty environment variable: `\f[CR]TPNOTE_USER\f[R]', `\f[CR]LOGNAME\f[R]', `\f[CR]USER\f[R]' or `\f[CR]USERNAME\f[R]'. .RE .SH EXIT STATUS The exit status is `\f[CR]0\f[R]' when the note file was processed without error or `\f[CR]1\f[R]' otherwise. -If Tp\-Note can not read or write its configuration file, the exit -status is `\f[CR]5\f[R]'. +If Tp-Note can not read or write its configuration file, the exit status +is `\f[CR]5\f[R]'. .PP -When `\f[CR]tpnote \-n \-b \f[R]' returns the code `\f[CR]0\f[R]', +When `\f[CR]tpnote -n -b \f[R]' returns the code `\f[CR]0\f[R]', the note file has a valid YAML header with a `\f[CR]title:\f[R]' field. -In addition, when `\f[CR]tpnote \-n \-b \-x \- \f[R]' returns the -code `\f[CR]0\f[R]', the note\[cq]s body was rendered without error. +In addition, when `\f[CR]tpnote -n -b -x - \f[R]' returns the code +`\f[CR]0\f[R]', the note\[cq]s body was rendered without error. .SH RESOURCES -Tp\-Note it hosted on: +Tp-Note it hosted on: .IP \[bu] 2 Gitlab: \c .UR https://gitlab.com/getreu/tp-note @@ -3664,7 +3646,7 @@ Github (mirror): \c .UE \c \ and on .SH COPYING -Copyright (C) 2016\-2024 Jens Getreu +Copyright (C) 2016-2024 Jens Getreu .PP Licensed under either of .IP \[bu] 2 @@ -3679,9 +3661,9 @@ MIT licence \c at your option. .SS Contribution Unless you explicitly state otherwise, any contribution intentionally -submitted for inclusion in the work by you, as defined in the -Apache\-2.0 licence, shall be dual licensed as above, without any -additional terms or conditions. +submitted for inclusion in the work by you, as defined in the Apache-2.0 +licence, shall be dual licensed as above, without any additional terms +or conditions. Licensed under the Apache Licence, Version 2.0 (the \[lq]Licence\[rq]); you may not use this file except in compliance with the Licence. .SH AUTHORS diff --git a/docs/source/README.md b/docs/source/README.md index b5e8475c..21020d8b 100644 --- a/docs/source/README.md +++ b/docs/source/README.md @@ -306,8 +306,8 @@ compile _Tp-Note_ yourself. _Tp-Note_ into `stderr`: ```sh - cargo install --no-default-features --features \ - html-clipboard,lang-detection,read-clipboard,renderer,viewer \ + cargo install --no-default-features \ + --features lang-detection,read-clipboard,renderer,viewer \ tpnote sudo cp ~/.cargo/bin/tpnote /usr/local/bin ``` diff --git a/docs/source/tpnote--manpage.md b/docs/source/tpnote--manpage.md index a68c922c..232170e0 100644 --- a/docs/source/tpnote--manpage.md +++ b/docs/source/tpnote--manpage.md @@ -1,9 +1,9 @@ --- -title: TP-NOTE(1) Version 1.24.5 | Tp-Note documentation +title: TP-NOTE(1) Version 1.24.6 | Tp-Note documentation subtitle: Unix manpage author: Jens Getreu filename_sync: false -date: 2024-07-04 +date: 2024-07-09 lang: en-GB --- diff --git a/docs/source/tpnote--manual.md b/docs/source/tpnote--manual.md index 8eaa9b01..42350427 100644 --- a/docs/source/tpnote--manual.md +++ b/docs/source/tpnote--manual.md @@ -3,7 +3,7 @@ title: "Tp-Note: markup enhanced granular note-taking" subtitle: Save and edit your clipboard content as a note file author: Jens Getreu date: 2024-07-04 -version: 1.24.5 +version: 1.24.6 filename_sync: false lang: en-GB --- diff --git a/tpnote/Cargo.toml b/tpnote/Cargo.toml index 33b9ada0..1f5a3d22 100644 --- a/tpnote/Cargo.toml +++ b/tpnote/Cargo.toml @@ -94,7 +94,7 @@ time = "0.3.36" tera.workspace = true toml.workspace = true #tpnote-lib = { path = "../tpnote-lib", default-features = false } -tpnote-lib = { version = "0.35.0", default-features = false} +tpnote-lib = { version = "0.35.2", default-features = false} webbrowser = { version = "1.0.1", optional = true }