├── .gitignore ├── LICENSE.md ├── README.md ├── build-ztf.sh ├── screenshot.png ├── zt.el └── ztf.zig /.gitignore: -------------------------------------------------------------------------------- 1 | zig-cache/ 2 | ztf-* 3 | 4 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | ### GNU AFFERO GENERAL PUBLIC LICENSE 2 | 3 | Version 3, 19 November 2007 4 | 5 | Copyright (C) 2007 Free Software Foundation, Inc. 6 | 7 | 8 | Everyone is permitted to copy and distribute verbatim copies of this 9 | license document, but changing it is not allowed. 10 | 11 | ### Preamble 12 | 13 | The GNU Affero General Public License is a free, copyleft license for 14 | software and other kinds of works, specifically designed to ensure 15 | cooperation with the community in the case of network server software. 16 | 17 | The licenses for most software and other practical works are designed 18 | to take away your freedom to share and change the works. By contrast, 19 | our General Public Licenses are intended to guarantee your freedom to 20 | share and change all versions of a program--to make sure it remains 21 | free software for all its users. 22 | 23 | When we speak of free software, we are referring to freedom, not 24 | price. Our General Public Licenses are designed to make sure that you 25 | have the freedom to distribute copies of free software (and charge for 26 | them if you wish), that you receive source code or can get it if you 27 | want it, that you can change the software or use pieces of it in new 28 | free programs, and that you know you can do these things. 29 | 30 | Developers that use our General Public Licenses protect your rights 31 | with two steps: (1) assert copyright on the software, and (2) offer 32 | you this License which gives you legal permission to copy, distribute 33 | and/or modify the software. 34 | 35 | A secondary benefit of defending all users' freedom is that 36 | improvements made in alternate versions of the program, if they 37 | receive widespread use, become available for other developers to 38 | incorporate. Many developers of free software are heartened and 39 | encouraged by the resulting cooperation. However, in the case of 40 | software used on network servers, this result may fail to come about. 41 | The GNU General Public License permits making a modified version and 42 | letting the public access it on a server without ever releasing its 43 | source code to the public. 44 | 45 | The GNU Affero General Public License is designed specifically to 46 | ensure that, in such cases, the modified source code becomes available 47 | to the community. It requires the operator of a network server to 48 | provide the source code of the modified version running there to the 49 | users of that server. Therefore, public use of a modified version, on 50 | a publicly accessible server, gives the public access to the source 51 | code of the modified version. 52 | 53 | An older license, called the Affero General Public License and 54 | published by Affero, was designed to accomplish similar goals. This is 55 | a different license, not a version of the Affero GPL, but Affero has 56 | released a new version of the Affero GPL which permits relicensing 57 | under this license. 58 | 59 | The precise terms and conditions for copying, distribution and 60 | modification follow. 61 | 62 | ### TERMS AND CONDITIONS 63 | 64 | #### 0. Definitions. 65 | 66 | "This License" refers to version 3 of the GNU Affero General Public 67 | License. 68 | 69 | "Copyright" also means copyright-like laws that apply to other kinds 70 | of works, such as semiconductor masks. 71 | 72 | "The Program" refers to any copyrightable work licensed under this 73 | License. Each licensee is addressed as "you". "Licensees" and 74 | "recipients" may be individuals or organizations. 75 | 76 | To "modify" a work means to copy from or adapt all or part of the work 77 | in a fashion requiring copyright permission, other than the making of 78 | an exact copy. The resulting work is called a "modified version" of 79 | the earlier work or a work "based on" the earlier work. 80 | 81 | A "covered work" means either the unmodified Program or a work based 82 | on the Program. 83 | 84 | To "propagate" a work means to do anything with it that, without 85 | permission, would make you directly or secondarily liable for 86 | infringement under applicable copyright law, except executing it on a 87 | computer or modifying a private copy. Propagation includes copying, 88 | distribution (with or without modification), making available to the 89 | public, and in some countries other activities as well. 90 | 91 | To "convey" a work means any kind of propagation that enables other 92 | parties to make or receive copies. Mere interaction with a user 93 | through a computer network, with no transfer of a copy, is not 94 | conveying. 95 | 96 | An interactive user interface displays "Appropriate Legal Notices" to 97 | the extent that it includes a convenient and prominently visible 98 | feature that (1) displays an appropriate copyright notice, and (2) 99 | tells the user that there is no warranty for the work (except to the 100 | extent that warranties are provided), that licensees may convey the 101 | work under this License, and how to view a copy of this License. If 102 | the interface presents a list of user commands or options, such as a 103 | menu, a prominent item in the list meets this criterion. 104 | 105 | #### 1. Source Code. 106 | 107 | The "source code" for a work means the preferred form of the work for 108 | making modifications to it. "Object code" means any non-source form of 109 | a work. 110 | 111 | A "Standard Interface" means an interface that either is an official 112 | standard defined by a recognized standards body, or, in the case of 113 | interfaces specified for a particular programming language, one that 114 | is widely used among developers working in that language. 115 | 116 | The "System Libraries" of an executable work include anything, other 117 | than the work as a whole, that (a) is included in the normal form of 118 | packaging a Major Component, but which is not part of that Major 119 | Component, and (b) serves only to enable use of the work with that 120 | Major Component, or to implement a Standard Interface for which an 121 | implementation is available to the public in source code form. A 122 | "Major Component", in this context, means a major essential component 123 | (kernel, window system, and so on) of the specific operating system 124 | (if any) on which the executable work runs, or a compiler used to 125 | produce the work, or an object code interpreter used to run it. 126 | 127 | The "Corresponding Source" for a work in object code form means all 128 | the source code needed to generate, install, and (for an executable 129 | work) run the object code and to modify the work, including scripts to 130 | control those activities. However, it does not include the work's 131 | System Libraries, or general-purpose tools or generally available free 132 | programs which are used unmodified in performing those activities but 133 | which are not part of the work. For example, Corresponding Source 134 | includes interface definition files associated with source files for 135 | the work, and the source code for shared libraries and dynamically 136 | linked subprograms that the work is specifically designed to require, 137 | such as by intimate data communication or control flow between those 138 | subprograms and other parts of the work. 139 | 140 | The Corresponding Source need not include anything that users can 141 | regenerate automatically from other parts of the Corresponding Source. 142 | 143 | The Corresponding Source for a work in source code form is that same 144 | work. 145 | 146 | #### 2. Basic Permissions. 147 | 148 | All rights granted under this License are granted for the term of 149 | copyright on the Program, and are irrevocable provided the stated 150 | conditions are met. This License explicitly affirms your unlimited 151 | permission to run the unmodified Program. The output from running a 152 | covered work is covered by this License only if the output, given its 153 | content, constitutes a covered work. This License acknowledges your 154 | rights of fair use or other equivalent, as provided by copyright law. 155 | 156 | You may make, run and propagate covered works that you do not convey, 157 | without conditions so long as your license otherwise remains in force. 158 | You may convey covered works to others for the sole purpose of having 159 | them make modifications exclusively for you, or provide you with 160 | facilities for running those works, provided that you comply with the 161 | terms of this License in conveying all material for which you do not 162 | control copyright. Those thus making or running the covered works for 163 | you must do so exclusively on your behalf, under your direction and 164 | control, on terms that prohibit them from making any copies of your 165 | copyrighted material outside their relationship with you. 166 | 167 | Conveying under any other circumstances is permitted solely under the 168 | conditions stated below. Sublicensing is not allowed; section 10 makes 169 | it unnecessary. 170 | 171 | #### 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 172 | 173 | No covered work shall be deemed part of an effective technological 174 | measure under any applicable law fulfilling obligations under article 175 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 176 | similar laws prohibiting or restricting circumvention of such 177 | measures. 178 | 179 | When you convey a covered work, you waive any legal power to forbid 180 | circumvention of technological measures to the extent such 181 | circumvention is effected by exercising rights under this License with 182 | respect to the covered work, and you disclaim any intention to limit 183 | operation or modification of the work as a means of enforcing, against 184 | the work's users, your or third parties' legal rights to forbid 185 | circumvention of technological measures. 186 | 187 | #### 4. Conveying Verbatim Copies. 188 | 189 | You may convey verbatim copies of the Program's source code as you 190 | receive it, in any medium, provided that you conspicuously and 191 | appropriately publish on each copy an appropriate copyright notice; 192 | keep intact all notices stating that this License and any 193 | non-permissive terms added in accord with section 7 apply to the code; 194 | keep intact all notices of the absence of any warranty; and give all 195 | recipients a copy of this License along with the Program. 196 | 197 | You may charge any price or no price for each copy that you convey, 198 | and you may offer support or warranty protection for a fee. 199 | 200 | #### 5. Conveying Modified Source Versions. 201 | 202 | You may convey a work based on the Program, or the modifications to 203 | produce it from the Program, in the form of source code under the 204 | terms of section 4, provided that you also meet all of these 205 | conditions: 206 | 207 | - a) The work must carry prominent notices stating that you modified 208 | it, and giving a relevant date. 209 | - b) The work must carry prominent notices stating that it is 210 | released under this License and any conditions added under 211 | section 7. This requirement modifies the requirement in section 4 212 | to "keep intact all notices". 213 | - c) You must license the entire work, as a whole, under this 214 | License to anyone who comes into possession of a copy. This 215 | License will therefore apply, along with any applicable section 7 216 | additional terms, to the whole of the work, and all its parts, 217 | regardless of how they are packaged. This License gives no 218 | permission to license the work in any other way, but it does not 219 | invalidate such permission if you have separately received it. 220 | - d) If the work has interactive user interfaces, each must display 221 | Appropriate Legal Notices; however, if the Program has interactive 222 | interfaces that do not display Appropriate Legal Notices, your 223 | work need not make them do so. 224 | 225 | A compilation of a covered work with other separate and independent 226 | works, which are not by their nature extensions of the covered work, 227 | and which are not combined with it such as to form a larger program, 228 | in or on a volume of a storage or distribution medium, is called an 229 | "aggregate" if the compilation and its resulting copyright are not 230 | used to limit the access or legal rights of the compilation's users 231 | beyond what the individual works permit. Inclusion of a covered work 232 | in an aggregate does not cause this License to apply to the other 233 | parts of the aggregate. 234 | 235 | #### 6. Conveying Non-Source Forms. 236 | 237 | You may convey a covered work in object code form under the terms of 238 | sections 4 and 5, provided that you also convey the machine-readable 239 | Corresponding Source under the terms of this License, in one of these 240 | ways: 241 | 242 | - a) Convey the object code in, or embodied in, a physical product 243 | (including a physical distribution medium), accompanied by the 244 | Corresponding Source fixed on a durable physical medium 245 | customarily used for software interchange. 246 | - b) Convey the object code in, or embodied in, a physical product 247 | (including a physical distribution medium), accompanied by a 248 | written offer, valid for at least three years and valid for as 249 | long as you offer spare parts or customer support for that product 250 | model, to give anyone who possesses the object code either (1) a 251 | copy of the Corresponding Source for all the software in the 252 | product that is covered by this License, on a durable physical 253 | medium customarily used for software interchange, for a price no 254 | more than your reasonable cost of physically performing this 255 | conveying of source, or (2) access to copy the Corresponding 256 | Source from a network server at no charge. 257 | - c) Convey individual copies of the object code with a copy of the 258 | written offer to provide the Corresponding Source. This 259 | alternative is allowed only occasionally and noncommercially, and 260 | only if you received the object code with such an offer, in accord 261 | with subsection 6b. 262 | - d) Convey the object code by offering access from a designated 263 | place (gratis or for a charge), and offer equivalent access to the 264 | Corresponding Source in the same way through the same place at no 265 | further charge. You need not require recipients to copy the 266 | Corresponding Source along with the object code. If the place to 267 | copy the object code is a network server, the Corresponding Source 268 | may be on a different server (operated by you or a third party) 269 | that supports equivalent copying facilities, provided you maintain 270 | clear directions next to the object code saying where to find the 271 | Corresponding Source. Regardless of what server hosts the 272 | Corresponding Source, you remain obligated to ensure that it is 273 | available for as long as needed to satisfy these requirements. 274 | - e) Convey the object code using peer-to-peer transmission, 275 | provided you inform other peers where the object code and 276 | Corresponding Source of the work are being offered to the general 277 | public at no charge under subsection 6d. 278 | 279 | A separable portion of the object code, whose source code is excluded 280 | from the Corresponding Source as a System Library, need not be 281 | included in conveying the object code work. 282 | 283 | A "User Product" is either (1) a "consumer product", which means any 284 | tangible personal property which is normally used for personal, 285 | family, or household purposes, or (2) anything designed or sold for 286 | incorporation into a dwelling. In determining whether a product is a 287 | consumer product, doubtful cases shall be resolved in favor of 288 | coverage. For a particular product received by a particular user, 289 | "normally used" refers to a typical or common use of that class of 290 | product, regardless of the status of the particular user or of the way 291 | in which the particular user actually uses, or expects or is expected 292 | to use, the product. A product is a consumer product regardless of 293 | whether the product has substantial commercial, industrial or 294 | non-consumer uses, unless such uses represent the only significant 295 | mode of use of the product. 296 | 297 | "Installation Information" for a User Product means any methods, 298 | procedures, authorization keys, or other information required to 299 | install and execute modified versions of a covered work in that User 300 | Product from a modified version of its Corresponding Source. The 301 | information must suffice to ensure that the continued functioning of 302 | the modified object code is in no case prevented or interfered with 303 | solely because modification has been made. 304 | 305 | If you convey an object code work under this section in, or with, or 306 | specifically for use in, a User Product, and the conveying occurs as 307 | part of a transaction in which the right of possession and use of the 308 | User Product is transferred to the recipient in perpetuity or for a 309 | fixed term (regardless of how the transaction is characterized), the 310 | Corresponding Source conveyed under this section must be accompanied 311 | by the Installation Information. But this requirement does not apply 312 | if neither you nor any third party retains the ability to install 313 | modified object code on the User Product (for example, the work has 314 | been installed in ROM). 315 | 316 | The requirement to provide Installation Information does not include a 317 | requirement to continue to provide support service, warranty, or 318 | updates for a work that has been modified or installed by the 319 | recipient, or for the User Product in which it has been modified or 320 | installed. Access to a network may be denied when the modification 321 | itself materially and adversely affects the operation of the network 322 | or violates the rules and protocols for communication across the 323 | network. 324 | 325 | Corresponding Source conveyed, and Installation Information provided, 326 | in accord with this section must be in a format that is publicly 327 | documented (and with an implementation available to the public in 328 | source code form), and must require no special password or key for 329 | unpacking, reading or copying. 330 | 331 | #### 7. Additional Terms. 332 | 333 | "Additional permissions" are terms that supplement the terms of this 334 | License by making exceptions from one or more of its conditions. 335 | Additional permissions that are applicable to the entire Program shall 336 | be treated as though they were included in this License, to the extent 337 | that they are valid under applicable law. If additional permissions 338 | apply only to part of the Program, that part may be used separately 339 | under those permissions, but the entire Program remains governed by 340 | this License without regard to the additional permissions. 341 | 342 | When you convey a copy of a covered work, you may at your option 343 | remove any additional permissions from that copy, or from any part of 344 | it. (Additional permissions may be written to require their own 345 | removal in certain cases when you modify the work.) You may place 346 | additional permissions on material, added by you to a covered work, 347 | for which you have or can give appropriate copyright permission. 348 | 349 | Notwithstanding any other provision of this License, for material you 350 | add to a covered work, you may (if authorized by the copyright holders 351 | of that material) supplement the terms of this License with terms: 352 | 353 | - a) Disclaiming warranty or limiting liability differently from the 354 | terms of sections 15 and 16 of this License; or 355 | - b) Requiring preservation of specified reasonable legal notices or 356 | author attributions in that material or in the Appropriate Legal 357 | Notices displayed by works containing it; or 358 | - c) Prohibiting misrepresentation of the origin of that material, 359 | or requiring that modified versions of such material be marked in 360 | reasonable ways as different from the original version; or 361 | - d) Limiting the use for publicity purposes of names of licensors 362 | or authors of the material; or 363 | - e) Declining to grant rights under trademark law for use of some 364 | trade names, trademarks, or service marks; or 365 | - f) Requiring indemnification of licensors and authors of that 366 | material by anyone who conveys the material (or modified versions 367 | of it) with contractual assumptions of liability to the recipient, 368 | for any liability that these contractual assumptions directly 369 | impose on those licensors and authors. 370 | 371 | All other non-permissive additional terms are considered "further 372 | restrictions" within the meaning of section 10. If the Program as you 373 | received it, or any part of it, contains a notice stating that it is 374 | governed by this License along with a term that is a further 375 | restriction, you may remove that term. If a license document contains 376 | a further restriction but permits relicensing or conveying under this 377 | License, you may add to a covered work material governed by the terms 378 | of that license document, provided that the further restriction does 379 | not survive such relicensing or conveying. 380 | 381 | If you add terms to a covered work in accord with this section, you 382 | must place, in the relevant source files, a statement of the 383 | additional terms that apply to those files, or a notice indicating 384 | where to find the applicable terms. 385 | 386 | Additional terms, permissive or non-permissive, may be stated in the 387 | form of a separately written license, or stated as exceptions; the 388 | above requirements apply either way. 389 | 390 | #### 8. Termination. 391 | 392 | You may not propagate or modify a covered work except as expressly 393 | provided under this License. Any attempt otherwise to propagate or 394 | modify it is void, and will automatically terminate your rights under 395 | this License (including any patent licenses granted under the third 396 | paragraph of section 11). 397 | 398 | However, if you cease all violation of this License, then your license 399 | from a particular copyright holder is reinstated (a) provisionally, 400 | unless and until the copyright holder explicitly and finally 401 | terminates your license, and (b) permanently, if the copyright holder 402 | fails to notify you of the violation by some reasonable means prior to 403 | 60 days after the cessation. 404 | 405 | Moreover, your license from a particular copyright holder is 406 | reinstated permanently if the copyright holder notifies you of the 407 | violation by some reasonable means, this is the first time you have 408 | received notice of violation of this License (for any work) from that 409 | copyright holder, and you cure the violation prior to 30 days after 410 | your receipt of the notice. 411 | 412 | Termination of your rights under this section does not terminate the 413 | licenses of parties who have received copies or rights from you under 414 | this License. If your rights have been terminated and not permanently 415 | reinstated, you do not qualify to receive new licenses for the same 416 | material under section 10. 417 | 418 | #### 9. Acceptance Not Required for Having Copies. 419 | 420 | You are not required to accept this License in order to receive or run 421 | a copy of the Program. Ancillary propagation of a covered work 422 | occurring solely as a consequence of using peer-to-peer transmission 423 | to receive a copy likewise does not require acceptance. However, 424 | nothing other than this License grants you permission to propagate or 425 | modify any covered work. These actions infringe copyright if you do 426 | not accept this License. Therefore, by modifying or propagating a 427 | covered work, you indicate your acceptance of this License to do so. 428 | 429 | #### 10. Automatic Licensing of Downstream Recipients. 430 | 431 | Each time you convey a covered work, the recipient automatically 432 | receives a license from the original licensors, to run, modify and 433 | propagate that work, subject to this License. You are not responsible 434 | for enforcing compliance by third parties with this License. 435 | 436 | An "entity transaction" is a transaction transferring control of an 437 | organization, or substantially all assets of one, or subdividing an 438 | organization, or merging organizations. If propagation of a covered 439 | work results from an entity transaction, each party to that 440 | transaction who receives a copy of the work also receives whatever 441 | licenses to the work the party's predecessor in interest had or could 442 | give under the previous paragraph, plus a right to possession of the 443 | Corresponding Source of the work from the predecessor in interest, if 444 | the predecessor has it or can get it with reasonable efforts. 445 | 446 | You may not impose any further restrictions on the exercise of the 447 | rights granted or affirmed under this License. For example, you may 448 | not impose a license fee, royalty, or other charge for exercise of 449 | rights granted under this License, and you may not initiate litigation 450 | (including a cross-claim or counterclaim in a lawsuit) alleging that 451 | any patent claim is infringed by making, using, selling, offering for 452 | sale, or importing the Program or any portion of it. 453 | 454 | #### 11. Patents. 455 | 456 | A "contributor" is a copyright holder who authorizes use under this 457 | License of the Program or a work on which the Program is based. The 458 | work thus licensed is called the contributor's "contributor version". 459 | 460 | A contributor's "essential patent claims" are all patent claims owned 461 | or controlled by the contributor, whether already acquired or 462 | hereafter acquired, that would be infringed by some manner, permitted 463 | by this License, of making, using, or selling its contributor version, 464 | but do not include claims that would be infringed only as a 465 | consequence of further modification of the contributor version. For 466 | purposes of this definition, "control" includes the right to grant 467 | patent sublicenses in a manner consistent with the requirements of 468 | this License. 469 | 470 | Each contributor grants you a non-exclusive, worldwide, royalty-free 471 | patent license under the contributor's essential patent claims, to 472 | make, use, sell, offer for sale, import and otherwise run, modify and 473 | propagate the contents of its contributor version. 474 | 475 | In the following three paragraphs, a "patent license" is any express 476 | agreement or commitment, however denominated, not to enforce a patent 477 | (such as an express permission to practice a patent or covenant not to 478 | sue for patent infringement). To "grant" such a patent license to a 479 | party means to make such an agreement or commitment not to enforce a 480 | patent against the party. 481 | 482 | If you convey a covered work, knowingly relying on a patent license, 483 | and the Corresponding Source of the work is not available for anyone 484 | to copy, free of charge and under the terms of this License, through a 485 | publicly available network server or other readily accessible means, 486 | then you must either (1) cause the Corresponding Source to be so 487 | available, or (2) arrange to deprive yourself of the benefit of the 488 | patent license for this particular work, or (3) arrange, in a manner 489 | consistent with the requirements of this License, to extend the patent 490 | license to downstream recipients. "Knowingly relying" means you have 491 | actual knowledge that, but for the patent license, your conveying the 492 | covered work in a country, or your recipient's use of the covered work 493 | in a country, would infringe one or more identifiable patents in that 494 | country that you have reason to believe are valid. 495 | 496 | If, pursuant to or in connection with a single transaction or 497 | arrangement, you convey, or propagate by procuring conveyance of, a 498 | covered work, and grant a patent license to some of the parties 499 | receiving the covered work authorizing them to use, propagate, modify 500 | or convey a specific copy of the covered work, then the patent license 501 | you grant is automatically extended to all recipients of the covered 502 | work and works based on it. 503 | 504 | A patent license is "discriminatory" if it does not include within the 505 | scope of its coverage, prohibits the exercise of, or is conditioned on 506 | the non-exercise of one or more of the rights that are specifically 507 | granted under this License. You may not convey a covered work if you 508 | are a party to an arrangement with a third party that is in the 509 | business of distributing software, under which you make payment to the 510 | third party based on the extent of your activity of conveying the 511 | work, and under which the third party grants, to any of the parties 512 | who would receive the covered work from you, a discriminatory patent 513 | license (a) in connection with copies of the covered work conveyed by 514 | you (or copies made from those copies), or (b) primarily for and in 515 | connection with specific products or compilations that contain the 516 | covered work, unless you entered into that arrangement, or that patent 517 | license was granted, prior to 28 March 2007. 518 | 519 | Nothing in this License shall be construed as excluding or limiting 520 | any implied license or other defenses to infringement that may 521 | otherwise be available to you under applicable patent law. 522 | 523 | #### 12. No Surrender of Others' Freedom. 524 | 525 | If conditions are imposed on you (whether by court order, agreement or 526 | otherwise) that contradict the conditions of this License, they do not 527 | excuse you from the conditions of this License. If you cannot convey a 528 | covered work so as to satisfy simultaneously your obligations under 529 | this License and any other pertinent obligations, then as a 530 | consequence you may not convey it at all. For example, if you agree to 531 | terms that obligate you to collect a royalty for further conveying 532 | from those to whom you convey the Program, the only way you could 533 | satisfy both those terms and this License would be to refrain entirely 534 | from conveying the Program. 535 | 536 | #### 13. Remote Network Interaction; Use with the GNU General Public License. 537 | 538 | Notwithstanding any other provision of this License, if you modify the 539 | Program, your modified version must prominently offer all users 540 | interacting with it remotely through a computer network (if your 541 | version supports such interaction) an opportunity to receive the 542 | Corresponding Source of your version by providing access to the 543 | Corresponding Source from a network server at no charge, through some 544 | standard or customary means of facilitating copying of software. This 545 | Corresponding Source shall include the Corresponding Source for any 546 | work covered by version 3 of the GNU General Public License that is 547 | incorporated pursuant to the following paragraph. 548 | 549 | Notwithstanding any other provision of this License, you have 550 | permission to link or combine any covered work with a work licensed 551 | under version 3 of the GNU General Public License into a single 552 | combined work, and to convey the resulting work. The terms of this 553 | License will continue to apply to the part which is the covered work, 554 | but the work with which it is combined will remain governed by version 555 | 3 of the GNU General Public License. 556 | 557 | #### 14. Revised Versions of this License. 558 | 559 | The Free Software Foundation may publish revised and/or new versions 560 | of the GNU Affero General Public License from time to time. Such new 561 | versions will be similar in spirit to the present version, but may 562 | differ in detail to address new problems or concerns. 563 | 564 | Each version is given a distinguishing version number. If the Program 565 | specifies that a certain numbered version of the GNU Affero General 566 | Public License "or any later version" applies to it, you have the 567 | option of following the terms and conditions either of that numbered 568 | version or of any later version published by the Free Software 569 | Foundation. If the Program does not specify a version number of the 570 | GNU Affero General Public License, you may choose any version ever 571 | published by the Free Software Foundation. 572 | 573 | If the Program specifies that a proxy can decide which future versions 574 | of the GNU Affero General Public License can be used, that proxy's 575 | public statement of acceptance of a version permanently authorizes you 576 | to choose that version for the Program. 577 | 578 | Later license versions may give you additional or different 579 | permissions. However, no additional obligations are imposed on any 580 | author or copyright holder as a result of your choosing to follow a 581 | later version. 582 | 583 | #### 15. Disclaimer of Warranty. 584 | 585 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 586 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 587 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT 588 | WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT 589 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 590 | A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND 591 | PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE 592 | DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR 593 | CORRECTION. 594 | 595 | #### 16. Limitation of Liability. 596 | 597 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 598 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR 599 | CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, 600 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES 601 | ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT 602 | NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR 603 | LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM 604 | TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER 605 | PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 606 | 607 | #### 17. Interpretation of Sections 15 and 16. 608 | 609 | If the disclaimer of warranty and limitation of liability provided 610 | above cannot be given local legal effect according to their terms, 611 | reviewing courts shall apply local law that most closely approximates 612 | an absolute waiver of all civil liability in connection with the 613 | Program, unless a warranty or assumption of liability accompanies a 614 | copy of the Program in return for a fee. 615 | 616 | END OF TERMS AND CONDITIONS 617 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # zt 2 | 3 | zt is a simple but highly opinionated Emacs package for building a 4 | [Zettelkasten](https://zettelkasten.de/posts/overview/). To get started, skip 5 | ahead to [Installation](#installation) below. 6 | 7 | #### Table of contents 8 | 9 | * [Motivation](#motivation) 10 | * [Installation](#installation) 11 | * [Non-Linux platforms](#non-linux-platforms-installation-of-ztf-companion) 12 | * [Tutorial](#tutorial) 13 | * [Configure keybindings](#configure-keybindings) 14 | * [Create your first note](#create-your-first-note) 15 | * [Branch off into a follower-note](#branch-off-into-a-follower-note) 16 | * [Add a structure note](#add-a-structure-note) 17 | * [Best practices](#best-practices) 18 | * [Don't use a Zettelkasten to keep track of things](#zettelkasten-isnt-for-organization) 19 | * [Integrate your Zettelkasten with your organizational system](#three-tools) 20 | * [Don't rely on an inbox, comprehensive indexes, or backlinks](#avoid-inbox-indexes-backlinks) 21 | * [Use follower notes to chain notes together](#use-folgezettel) 22 | * [Write structure notes that are focused and interesting, not comprehensive](#structure-notes-best-practices) 23 | * [Comparison to other software](#comparison-to-other-software) 24 | * [License](#license) 25 | 26 | #### Screenshot 27 | 28 | 29 | 30 | ## Motivation 31 | 32 | zt is [yet another](#comparison-to-other-software) Emacs package for building a 33 | Zettelkasten. Why another one? From a mechanistic viewpoint, zt is different 34 | from other solutions on a few parameters: 35 | 36 | 1. zt does not (necessarily) store the title of a file in its filename; by 37 | default files are named like `20220921T182341.txt`. You may optionally add 38 | more stuff after the ID prefix if you want, but the ID prefix is required. 39 | 2. However, zt *does* support "logical titles" when selecting notes 40 | interactively (for example when inserting links). For plain text files, the 41 | title is the first line, for Markdown, it's the first heading (or `title:` 42 | property in the YAML frontmatter), and for Org-mode it's the `#+TITLE:` or 43 | first heading. 44 | 3. Links are just the ID of a note. Delimiters are not required. By default, 45 | commands that insert links also insert the title of the linked file and 46 | optionally a link back to the originating context. In Org-mode, the special 47 | `zt:` link type may be used, e.g. `zt:20220921T182341`. 48 | 49 | The result of this is that a note can be renamed without changing its filename 50 | and without updating existing links to that file. You can also use special 51 | characters in titles without any issues. 52 | 53 | As for *why this actually matters*, well, it's mostly a matter of aesthetics. A 54 | Zettelkasten is supposed to be a simple system for building knowledge out of 55 | small notes in an organic way. The [simplest possible 56 | Zettelkasten](https://zettelkasten.de/posts/introduction-antinet-zettelkasten/) 57 | is implemented in terms of slips of paper which are assigned identifiers for 58 | linking between them. 59 | 60 | In a digital system, the most straight-forward emulation of such a system is 61 | with files whose filenames are unique IDs, and links that are simply the IDs 62 | themselves. Many note-taking applications assume a model that is fundamentally 63 | incompatible with such an approach, usually because they conflate titles with 64 | filenames (as [Denote](https://github.com/protesilaos/denote) and 65 | [zk.el](https://github.com/localauthor/zk) do), or even with IDs, as 66 | [Obsidian](https://obsidian.md/) does! zt, in contrast, takes these simple, 67 | plain-text foundations as its base, and then adds extra digital-only 68 | functionality on top to make it an actually useful system. 69 | 70 | If you have a directory of files named like `20220922T200758.txt` which refer to 71 | each other by their IDs, then your system is already compatible with zt. From 72 | there, zt adds support for following links by clicking on them, easily linking 73 | to existing items by their title, finding backlinks to notes, and more, but at 74 | it's core, it's simply a collection of uniquely named text files. Some software, 75 | notably [The Archive](https://zettelkasten.de/the-archive/) and 76 | [Zettlr](https://www.zettlr.com/) do share this design philosophy. 77 | 78 | ## Installation 79 | 80 | First, install the zt package itself. If you're using 81 | [straight.el](https://github.com/radian-software/straight.el), add this to your 82 | `init.el`: 83 | 84 | ```emacs-lisp 85 | (straight-use-package '(zt :host github :repo "c2d7fa/zt")) 86 | ``` 87 | 88 | Otherwise, install zt manually with: 89 | 90 | ```emacs-lisp 91 | ;; Download files (run once, and again when updating zt) 92 | (make-directory "~/.emacs.d/load" t) 93 | (require 'url) 94 | (url-copy-file "https://raw.githubusercontent.com/c2d7fa/zt/main/zt.el" "~/.emacs.d/load/zt.el" t) 95 | 96 | ;; Load package (add this to init.el) 97 | (add-to-list 'load-path "~/.emacs.d/load") 98 | (require 'zt) 99 | ``` 100 | 101 | If you're using x86-64 Linux, you can skip ahead to the [Tutorial](#tutorial) 102 | now; otherwise, read the next section. 103 | 104 | #### Non-Linux platforms: Installation of `ztf` companion 105 | 106 | Unfortunately, zt also requires a companion program called `ztf`. Since we 107 | insist on not storing meaningful information in file names, we are forced to 108 | actually examine the file contents to find the title of each note. Emacs' native 109 | file operations aren't fast enough to be usable with more than a few hundred 110 | notes. Therefore, we call out to this external program when listing files by 111 | titles and also when finding backlinks. 112 | 113 | If you're running x86-64 Linux, zt will ask to download a prebuilt executable 114 | from the internet the first time it's needed. Otherwise, you must manually 115 | download another executable and install it at `~/.local/share/zt/ztf` or 116 | whatever `zt-ztf-executable-path` is set to; such executables can be downloaded 117 | from the following URLs: 118 | 119 | * [ztf-1-x86_64-macos](https://johv.dk/public/ztf-1-x86_64-macos) 120 | * [ztf-1-x86_64-windows.exe](https://johv.dk/public/ztf-1-x86_64-windows.exe) 121 | * [ztf-1-aarch64-linux](https://johv.dk/public/ztf-1-aarch64-linux) 122 | * [ztf-1-aarch64-macos](https://johv.dk/public/ztf-1-aarch64-macos) 123 | * [ztf-1-aarch64-windows.exe](https://johv.dk/public/ztf-1-aarch64-windows.exe) 124 | 125 | Other platforms are not explicitly supported, but you should be able to build it 126 | yourself; see [build-ztf.sh](./build-ztf.sh) for more information. 127 | 128 | ## Tutorial 129 | 130 | In this section, we'll see how to configure zt, begin a new Zettelkasten, and 131 | use follower and structure notes to start building up a library. 132 | 133 | #### Configure keybindings 134 | 135 | By default, zt exports a keymap `zt-minor-mode-prefix-map`, which is bound 136 | (inside `zt-minor-mode-map`) to the prefix `C-c #`. It's *strongly* recommended 137 | that you change this to something more convenient, and also that you remap some 138 | of the more common commands. For example, this is my configuration with 139 | [use-package](https://github.com/jwiegley/use-package) and 140 | [straight.el](https://github.com/radian-software/straight.el): 141 | 142 | ```emacs-lisp 143 | (use-package zt 144 | :straight (:host github :repo "c2d7fa/zt") 145 | :bind-keymap ("C-z" . zt-minor-mode-prefix-map) 146 | :bind (:map zt-minor-mode-map 147 | ("C-a" . zt-insert-link) 148 | ("M-a" . zt-insert-linking-file) 149 | ("C-f" . zt-find-file) 150 | ("M-f" . zt-find-linking-file) 151 | ("C-o" . zt-insert-new-id) 152 | ("M-o" . zt-open-follower-at-point))) 153 | ``` 154 | 155 | Note that this remaps some built-in keys. In the following, the default mappings 156 | (prefixed with `C-c #`) are given, but you really should change them! You can 157 | use `describe-keymap` with `zt-minor-mode-map` to see the default keybindings. 158 | 159 | #### Create your first note 160 | 161 | Usually, you'll be creating notes from other notes. But to create your first 162 | note, call `zt-create-in-directory`, and enter a directory where you would like 163 | to store all your notes. This will open a new plain text file. 164 | 165 | Try saving it, and notice that it has a filename that looks like 166 | `20220922T200758.txt`. In zt, all files are prefixed with an ID; this is how zt 167 | keeps track of them, and it's necessary for using zt. 168 | 169 | By default, zt creates plain text files. If you want to use, say, Markdown 170 | instead, call `zt-change-file-extension` (`C-c # .`) and enter `md`. You can 171 | also change the default file format by customizing `zt-default-file-extension`, 172 | but this is not recommended! Keep most of your notes in plain text, and mix in 173 | other formats only when you actually need the more advanced features. 174 | 175 | zt treats the first line of the file as its title. Try writing something, saving 176 | the buffer, and then calling `zt-find-file` (`C-c # f`) to see how the title is 177 | extracted from the file automatically, even though the filename is just an 178 | ID. In order to use this functionality, a completion framework such as 179 | [Ivy](https://github.com/abo-abo/swiper) is more or less a requirement! 180 | 181 | #### Branch off into a follower note 182 | 183 | We could continue creating independent notes using this same method, but a 184 | Zettelkasten is all about linking your notes. I recommend using an approach 185 | where you "chain" notes together to build up a kind of tree structure. When you 186 | get a new idea, insert a link to a so-called follower note (*Folgezettel*), and 187 | open the new note and continue from there. 188 | 189 | At the bottom of the note you created in the last step, try calling 190 | `zt-insert-new-id` (`C-c # t`). Then, after the ID, type a title for the new 191 | note that you want to create. At this point, your buffer should look something 192 | like this example (with `|` representing the point (cursor)): 193 | 194 | ``` 195 | File names and titles in zt 196 | 197 | In zt, files are named after their IDs. Notes can have titles, which are 198 | extracted from the file, and which are used when finding files with 199 | `zt-find-file' or linking to them with `zt-insert-link`. 200 | 201 | 20220922T222825 Inserting links and backlinks in zt| 202 | ``` 203 | 204 | Now, with the point at the end of the line, call `zt-open-follower-at-point` 205 | (`C-c # O`), or, equivalently, call `zt-open-at-point` with a prefix argument 206 | (`C-u C-c # o`). This will create a new note with both the follower note's title 207 | as well as a link back to the previous note inserted automatically, like this: 208 | 209 | ``` 210 | Inserting links and backlinks in zt 211 | 212 | 20220922T222648 File names and titles in zt| 213 | ``` 214 | 215 | From here, you can continue writing, and then repeat the process to create more 216 | follower notes. You may choose to insert them at the end of the current 217 | sequence, or you can go back to a previous note and start a new branch from 218 | there. Browsing your notes consists of selecting an arbitrary starting point and 219 | then using the "backward" links at the top of each note and the "forward" links 220 | at the bottom to navigate the tree. You can jump directly to an existing note 221 | with `zt-find-file` (`C-c # f`) 222 | 223 | Once you've built up a little tree of notes like this, move on to the next 224 | section. 225 | 226 | #### Add a structure note 227 | 228 | The sequences that we built up in the last step work well as a staging area for 229 | new ideas. The advantage of such an approach is that you can just start writing 230 | somewhere, and as long as you make sure to add links in both directions, there 231 | is no risk of notes getting "lost". This reduces friction in the system; for 232 | example, there is no need for any kind of inbox with this approach. 233 | 234 | But as your Zettelkasten grows, you'll eventually want to introduce a second 235 | layer: [structure 236 | notes](https://zettelkasten.de/posts/three-layers-structure-zettelkasten/). A 237 | structure note is essentially like a table of contents – it's a view of the 238 | entire Zettelkasten if it were designed to answer a very specific question. 239 | 240 | To create these structure notes in zt, use `zt-insert-link` (`C-c # l`), which 241 | inserts a link to an existing note. By default, this will insert both the ID 242 | and title of the selected note, which is useful when building lists of 243 | notes. Try using this functionality to create an interesting overview of some of 244 | the notes you just wrote. Don't worry about adding every relevant note to the 245 | index – focus on making it useful and interesting by not adding two notes that 246 | are too similar. 247 | 248 | Below is a realistic example of what a useful structure note may actually look 249 | like in practice. I wrote this note to summarize and index a previous sequence 250 | of notes, and then added it to an overarching topic note, to which I inserted a 251 | backlink with `zt-insert-linking-file` (`C-c # L`). 252 | 253 | ``` 254 | Folgezettel vs. index-oriented approaches to Zettelkasten 255 | 256 | 20220918T031544 Zettelkasten 257 | 258 | By forcing yourself to add every note to an index, you risk creating bloated 259 | indexes 20220913T214836, which reduces trust in the system 20220428T185922. The 260 | Folgezettel-oriented approach more effectively induces the "conversation 261 | partner" quality of the Zettelkasten 20220922T113137, and also removes the need 262 | for a dedicated inbox. 263 | 264 | Folgezettel in Luhmann's system 265 | 20220124T000002 Luhmann wrote many linear chains of thought 266 | 20220914T025344 Emulating Antinet numbering system in digital Zettelkasten 267 | 20220914T184826 Using two-way "hard" links for branching 268 | 20220914T024106 Disadvantages of digital Zettelkästen 269 | 270 | Importance of simplicity 271 | 20220920T233524 The different purposes of Zettelkasten and GTD 272 | 20220920T233259 Zettelkasten is the wrong tool for managing collections of reference material 273 | 20220920T003710 Collector's Fallacy 274 | 275 | When and how to use indexes 276 | 20220921T004228 Use structure notes to create "wormholes" between distant clusters 277 | 20220918T163155 Meta-index for integrated Zettelkasten/GTD/journal system in Emacs 278 | 20220921T010536 Don't add multiple notes about the same idea to one index 279 | ``` 280 | 281 | Of course, links aren't only used for writing structure notes. Whenever you 282 | reference an idea from another note, insert a link to that note so you can find 283 | it again in the future. When doing this, you may want to insert only the ID of 284 | the chosen file by calling `zt-insert-link` with a prefix argument (`C-u C-c # l`). 285 | By adding links, it also becomes possible to find releted notes via 286 | `zt-find-linking-file` (`C-c # F`), which shows only those files that link to 287 | the current note. 288 | 289 | That's it for the tutorial. You now know everything you need to use zt. If you 290 | want some extra tips on how to use the Zettelkasten methodology most effectively 291 | (in my opinion), check out the section below. 292 | 293 | ## Best practices 294 | 295 | The following are some of my recommendations for how to get the most out of your 296 | Zettelkasten, based on my own experience. I don't claim that this is *the* 297 | Zettelkasten methodology; these are just some recommendations that make sense to 298 | me. As another resource, I recommend 299 | [zettelkasten.de](https://zettelkasten.de/). 300 | 301 | 302 | #### Don't use a Zettelkasten to keep track of things 303 | 304 | Zettelkasten is designed for research and writing, not as an organizational 305 | system. In fact, I like to think of Zettelkasten as a kind of "tool for 306 | forgetting". You can use the Zettelkasten to think through complex problems in a 307 | structured way, completely forget about everything you just wrote down, and then 308 | wait for the Zettelkasten to bring those ideas up to you again, as though it 309 | were a kind of conversation partner. Later, the individual notes can be 310 | stictched together into a larger publishable piece. 311 | 312 | However, this process isn't magical. It isn't entirely reliable, and it 313 | certainly isn't timely. So if you need a tool for organizing your life, look 314 | elsewhere – Zettelkästen are not the right tool for storing things such as 315 | reminders, calendars, project reference material, todo-lists, or other 316 | information that's actually important for you to remember. 317 | 318 | 319 | #### Integrate your Zettelkasten with your organizational system 320 | 321 | If you *do* need an organizational system, you may consider taking some 322 | inspiration from my approach that uses zt to integrate Zettelkasten with two 323 | other systems. It consists of three different "tools": one for thinking and 324 | writing (Zettelkasten), one for remembering and keeping track of things, and one 325 | for planning out each day (daily log). 326 | 327 | *The Zettelkasten:* When there's something that I want to rediscover later, but 328 | forget about in the meantime, I add it to the Zettelkasten. This includes not 329 | only research notes and snippets of writing, but also ideas for future projects, 330 | interesting bookmarks and articles that I haven't yet read, and anything else 331 | that I want to find again but which isn't in itself critically important. To 332 | increase the chances of finding something again, try distributing it throughout 333 | the Zettelkasten – for example, instead of having a big list of bookmarks about 334 | some topic, sprinkle in a link here and there, where you might end up clicking 335 | on it again in the future when you stumble upon it. 336 | 337 | *The big list:* If Zettelkasten is a [tool for 338 | forgetting](#zettelkasten-isnt-for-organization), then this is my "tool for 339 | remembering". I just have a big list of items, separated into three sections 340 | called *daily*, *weekly* and *monthly*. Each day, week or month respectively, I 341 | look through each list, copy relevant items to my daily log (see below) and 342 | remove items that are no longer relevant. This is how I handle stuff like task 343 | lists and calendar events. To manage larger projects, I add links to sublists 344 | that I follow recursively. This list-based approach is very loosely based on 345 | [GTD](https://gettingthingsdone.com/), although without the focus on *next 346 | actions* and with many other aspects removed. 347 | 348 | *The daily log:* Each day, I pick out relevant items from my *daily* section of 349 | the big list and copy them into my daily log where I list out everything I need 350 | to work on that day. I add new items thoughout the day, so the daily log acts as 351 | a kind of inbox. At the end of the day, I look through all the non-completed 352 | items, and for each item, I either drop it or move it to the big list for 353 | later. This approach is inspired by the daily log in the [Bullet 354 | Journal](https://bulletjournal.com/), although I don't use the other parts. 355 | 356 | 357 | #### Don't rely on an inbox, comprehensive indexes, or backlinks 358 | 359 | When writing notes for your Zettelkasten, it's natural to feel some anxiety 360 | about whether you're just writing into the void, or whether you'll actually 361 | stumble across those notes again in the future. To relieve this anxiety, there 362 | are at least three tempting solutions that seem to make sense on the surface, 363 | but which tend to fall apart in the long term. 364 | 365 | *Inbox:* Whenever you write a new note, just park it in the inbox until you can 366 | add it somewhere it belongs. The problem with this approach is that it adds a 367 | lot of unnecessary overhead to your Zettelkasten. Now every time you write a new 368 | note, you're giving yourself extra work to do later. It's demoralizing, 369 | impractical, and it goes against the spirit of the Zettelkasten, which is to 370 | make it fun and easy to just sit down and start writing. 371 | 372 | *Comprehensive indexes:* Whenever you write a new note, add it to some relevant 373 | index. With this approach, every note can be reached from the top-level index by 374 | following some path of sub-indexes. However, this approach also creates a lot of 375 | unnecessary overhead and makes it harder to add new notes. Even more 376 | problematically, the Zettelkasten is supposed to be all about building knowledge 377 | from the bottom up. If you need to decide in advance what these indexes should 378 | look like, you're robbing yourself of your own creative freedom. Indexes (or 379 | [structure notes](#add-a-structure-note)) should arise naturally as you start to 380 | gain an understanding of the topic you're writing about; they shouldn't be laid 381 | down in advance – and rather than containing every single note about some topic, 382 | they should instead contain just a small, interesting selection of notes that 383 | you actually want to read. The kind of indexes that are created by proactively 384 | adding every note in the system as you write it just aren't interesting to read. 385 | 386 | *Backlinks:* Other tools, such as Obsidian and its descendants, place a great 387 | emphasis on backlinks for exploring your notes. zt does support backlinks (with 388 | `zt-find-linking-file` (`C-c # F`)), but they should not be the primary way of 389 | navigating your Zettelkasten. There is [a good article on zettelkasten.de about 390 | this topic](https://zettelkasten.de/posts/backlinks-are-bad-links/), but in 391 | short, backlinking as an organizational mechanism fails because backlinks lack 392 | context, priority and meaning. 393 | 394 | How then *should* you structure your Zettelkasten to make sure you will actually 395 | discover your notes again in the future? [I suggest relying primarily on 396 | follower notes](#use-folgezettel), together with a [selection of small, focused 397 | structure notes.](#structure-notes-best-practices) 398 | 399 | 400 | #### Use follower notes to chain notes together 401 | 402 | When it works well, browsing a Zettelkasten should feel like having a 403 | conversation with another person, who can bring up ideas and make connections 404 | that you had yourself forgotten about. In my experience, a necessary condition 405 | to achieve this is that every note must be linked to every other note through 406 | some path, however circuitous. 407 | 408 | My recommendation for how to actually do this, is to follow a method that is 409 | closely based on Luhmann's original *Folgezettel* (loosely translated as 410 | "follower notes" here). By assigning each note a numeric ID, Luhmann would place 411 | each new note at some specific location in the sequence of notes. These IDs were 412 | not assigned in sequence, but in an organic way where each new note could be 413 | placed anywhere in the sequence. Luhmann would use this to always place new 414 | notes near old related notes, as a kind of addtional linking mechanism. 415 | 416 | In zt, the analogous method is to create notes only by first inserting a link 417 | and then, from the new note, insert a link back to the originating note, as 418 | described [in the tutorial above](#branch-off-into-a-follower-note). If you 419 | follow this technique rigorously, then there will never be any note in your 420 | Zettelkasten that can't be reached in some way – even if it doesn't have any 421 | backlinks and doesn't appear in any index. Every note is reachable from every 422 | other note, however indirectly. 423 | 424 | Don't worry about finding exactly the right spot to branch off into a new 425 | follower note. Usually the right spot is whatever you were looking at when you 426 | got a new idea – other relevant notes can always be linked to explicitly, or 427 | placed in some shared structure note. If you didn't get the idea while looking 428 | at your Zettelkasten, just find some vaguely related note and start there. It 429 | doesn't have to be the best possible spot, or even be that relevant at all; the 430 | important part is that you pick *some* location for it. 431 | 432 | 433 | #### Make structure notes that are focused and interesting, not comprehensive 434 | 435 | *Structure note* is a loose term that just refers to any normal note that acts 436 | mostly as a sort of collection of other notes, usually grouped by a topic. It 437 | may be tempting to attempt to classify and organize all the notes in your 438 | Zettelkasten into structure notes, [but this impulse should be 439 | supressed](#avoid-inbox-indexes-backlinks). 440 | 441 | On the contrary, you should specifically *avoid* placing multiple very similar 442 | notes in the same structure note! Remember that structure notes should be 443 | designed to be useful, and nobody wants to read the same idea restated in a 444 | dozen slightly different variations. For each idea that you want to include in 445 | the structure note, pick one related note. If you're not sure which note is 446 | "best", either combine the candidates into a newly written note, or just pick 447 | one arbitrarily. Adding too links will make your notes *less* useful, not more, 448 | since it reduces the value of each individual link. 449 | 450 | I like to think of structure notes as a kind of wormhole from one "side" of the 451 | Zettelkasten to the other. If you're using the [follower note 452 | approach](#use-folgezettel), then your notes are already chained together in 453 | some way via the two-way links that are added to each note. So the primary 454 | function of a structure note is to let you jump directly from one chain of notes 455 | to another one that is very far away – there is little point in adding notes 456 | that are already close together in the sequence. 457 | 458 | Creating structure notes should feel like a creative exercise in compiling 459 | seemingly disparate ideas that actually have some hidden connection. Write each 460 | structure note like a table of contents for a small book about some very 461 | specific topic; if it's a book you actually want to read from one end to the 462 | other, then the structure note is successful. If writing the structure note 463 | feels feels like chore, then you're doing something wrong. 464 | 465 | ## Comparison to other software 466 | 467 | [The Archive](https://zettelkasten.de/the-archive/) is a proprietary application 468 | for macOS. It's designed for buliding Zettelkästen and values simple design. Its 469 | authors are the same as those of the excellent 470 | [zettelkasten.de](https://zettelkasten.de/) resource. If you use macOS 471 | exclusively and don't mind using proprietary software, I strongly recommend 472 | this! 473 | 474 | [Zettlr](https://www.zettlr.com/) has a similar design philosophy to The 475 | Archive, but it's free and open-source software and available on multiple 476 | platforms. Zettlr, like zt, does't care about the filenames of notes and 477 | supports finding notes by title, even if the title is different from the 478 | filename. It supports only Markdown. For the average person, this would be my 479 | second recommendation. If you're looking for something that's compatible with 480 | plain text or Org-mode, or just want to use Emacs, keep reading. 481 | 482 | **zt** is an Emacs package designed for Zettelkästen and valuing simple 483 | design. It's compatible with multiple file-formats and handles links to other 484 | files by their IDs, such that renaming a note does not require any updates to 485 | filenames or existing links. It lets you interactively find files by their 486 | "logical" title (in plain text, Markdown and Org), and makes including the title 487 | in the filename optional. The biggest disadvantage is the requirement of an 488 | external program `ztf` that's only officially available on Linux (but can be 489 | built for other platforms). 490 | 491 | [zk.el](https://github.com/localauthor/zk) is another Emacs package with a very 492 | similar design philosophy to zt. It's also inspired by The Archive, is also 493 | designed for plain text Zettelkästen and also values simplicity in its 494 | design. zk stores the titles of files in their filenames for the purpose of 495 | selecting files for linking with completion. If you aren't careful about keeping 496 | filenames and titles in sync, then zk won't be able to help you when inserting 497 | links. However, the links themselves are stored by ID, so it is at least 498 | possible to rename files without needing to update existing links. A major 499 | advantage of zk compared to zt is that it doesn't have any dependencies on 500 | external programs. 501 | 502 | [Denote](https://protesilaos.com/emacs/denote) is another simple note-taking 503 | package for Emacs. Denote expects you to assign tags to your files. Like zk, and 504 | unlike zt, Denote requires you to keep filenames in sync with thier titles for 505 | searching; like both zk and zt, however, you don't need to update existing links 506 | whenever you change the title of a note. If you're trying to build a 507 | Zettelkasten, I recommend using zk or zt over Denote, but Denote may be 508 | well-suited for more general note-taking purposes. Note that zt is designed to 509 | be interoperable with Denote by using the same ID format, so if you're using 510 | Org-mode, transitioning between these two is just a matter of `s/zt:/denote:/g`. 511 | 512 | [Logseq](https://logseq.com/), [Obsidian](https://obsidian.md/), [Roam 513 | Research](https://roamresearch.com/) and others *can* be used to implement a 514 | Zettelkasten system, but they aren't really designed for it. These programs 515 | conflate titles with IDs, so you must manually assign unique titles to all 516 | files. Obsidian has a Zettelkasten plugin which just adds a unique timestamp to 517 | each file, but it still requires you to link to files with verbose links that 518 | include the entire title. Whenever you change the title of a note, you must also 519 | update all links to it (which can be done automatically, of course, but only 520 | from inside Obsidian itself). If you don't mind this – or especially if you want 521 | to build something more like a personal wiki than a strict Zettelkasten – these 522 | are all good solutions. 523 | 524 | [Org-mode](https://orgmode.org/) can be used on its own to build a Zettelkasten 525 | by simply linking between files by their IDs. Although frequently characterized 526 | as "plain text", Org-mode in fact uses a totally proprietary ID-based linking 527 | format that isn't interoperable with any other software to my knowledge. You can 528 | use Org-mode with zt, zk or Denote and get the best of both worlds. 529 | 530 | [Org-roam](https://github.com/org-roam/org-roam) is essentially a port of 531 | Obsidian to Emacs, designed for use with Org-mode. It has the advantages of 532 | plain Org-mode together with the advantages of Obsidian and has quite a few 533 | features. But it also has the disadvantages of both, and for the purpose of 534 | building a Zettelkasten, I found it somewhat clumsy (not least due to its 535 | caching system for storing backlinks), but it may be well-suited if you want 536 | something more like a personal wiki and if you're willing to commit to using 537 | Emacs long-term. 538 | 539 | [emacs-zettelkasten](https://sr.ht/~ymherklotz/emacs-zettelkasten/) seems to 540 | have similar goals both zt and zk, but I haven't tried 541 | it. [Zetteldeft](https://github.com/EFLS/zetteldeft) is the package that zk is 542 | based on, but I haven't tried it either. 543 | 544 | [Hyperbole](https://www.gnu.org/software/hyperbole/) is infamous for being 545 | rather hard to grasp, but it does seem very cool, at least from a distance! It 546 | does a lot more than zt and isn't really designed with Zettelkästen in mind. I 547 | can't give a more useful comparison beyond that. 548 | 549 | ## License 550 | 551 | zt is licensed under the terms of the GNU AGPLv3 or any later version as 552 | described in `LICENSE.md`. 553 | -------------------------------------------------------------------------------- /build-ztf.sh: -------------------------------------------------------------------------------- 1 | zig build-exe -target x86_64-linux -O ReleaseFast --name ztf-2-x86_64-linux ztf.zig 2 | zig build-exe -target aarch64-linux -O ReleaseFast --name ztf-2-aarch64-linux ztf.zig 3 | zig build-exe -target x86_64-macos -O ReleaseFast --name ztf-2-x86_64-macos ztf.zig 4 | zig build-exe -target aarch64-macos -O ReleaseFast --name ztf-2-aarch64-macos ztf.zig 5 | zig build-exe -target x86_64-windows -O ReleaseFast --name ztf-2-x86_64-windows ztf.zig 6 | zig build-exe -target aarch64-windows -O ReleaseFast --name ztf-2-aarch64-windows ztf.zig 7 | 8 | -------------------------------------------------------------------------------- /screenshot.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/c2d7fa/zt/7736fb9725e9192f9017ae9e35ae00104f44a871/screenshot.png -------------------------------------------------------------------------------- /zt.el: -------------------------------------------------------------------------------- 1 | ;;; zt.el --- Simple but opinionated Zettelkasten in Emacs -*- lexical-binding: t; -*- 2 | 3 | ;; Copyright (c) 2022 Jonas Hvid 4 | 5 | ;; Author: Jonas Hvid 6 | ;; URL: https://github.com/c2d7fa/zt 7 | ;; Created: 22 Sep 2022 8 | ;; Version: 1.0.3 9 | ;; Package-Requires: ((emacs "26.0") (s "1.13.1")) 10 | 11 | ;;; Code: 12 | 13 | (require 's) 14 | (require 'url) 15 | 16 | (defcustom zt-ztf-executable-path (concat (getenv "HOME") "/.local/share/zt/ztf") 17 | "The path to the \"ztf\" executable. See the zt package's README 18 | for details on what this is and how to build it." 19 | :type 'file 20 | :group 'zt) 21 | 22 | (defcustom zt-default-file-extension ".txt" 23 | "The default file extension used when creating new files. You can 24 | also change this after files have been created by calling 25 | `zt-change-file-extension'." 26 | :type 'string 27 | :group 'zt) 28 | 29 | (defcustom zt-fontify-plain-text-title t 30 | "When `zt-minor-mode' is enabled in a `text-mode' buffer, add 31 | fontification for the first line." 32 | :type 'boolean 33 | :group 'zt) 34 | 35 | (defface zt-plain-text-title '((t (:weight bold))) 36 | "The face used to highlight titles in plain text files when)))) 37 | `zt-fontify-plain-text-title' is enabled.") 38 | 39 | (defconst zt--required-ztf-version "2") 40 | 41 | (defun zt--system-configuration-has (s) 42 | (s-contains? s system-configuration)) 43 | 44 | (defun zt--platform () 45 | (let* ((cpu (cond ((zt--system-configuration-has "x86_64") "x86_64") 46 | ((zt--system-configuration-has "aarch64") "aarch64") 47 | ((zt--system-configuration-has "arm") "aarch64") 48 | (t nil))) 49 | (os (cond ((zt--system-configuration-has "linux") "linux") 50 | ((zt--system-configuration-has "darwin") "macos") 51 | ((zt--system-configuration-has "apple") "macos") 52 | ((zt--system-configuration-has "mingw") "windows") 53 | ((zt--system-configuration-has "mac") "macos") 54 | ((zt--system-configuration-has "win") "windows") 55 | (t nil)))) 56 | (when (and cpu os) 57 | (concat cpu "-" os)))) 58 | 59 | (defun zt--download-url () 60 | (let ((windows? (s-contains? "windows" (zt--platform)))) 61 | (concat "https://johv.dk/public/ztf-2-" (zt--platform) (if windows? ".exe" "")))) 62 | 63 | (defun zt--expected-sha256 () 64 | (alist-get (zt--platform) 65 | '(("aarch64-linux" . "ce9b0037ede13dea15a08c2d22d3b45f20ac1fe600d5509e5b93c576abbb9383") 66 | ("aarch64-macos" . "cce15815c2f49dfdcd590d44db94c663aa39fe1c3a70f47a260aea521e21b4d5") 67 | ("aarch64-windows" . "b408709e73f50657dd0aa6cfd12614fd2906b00fe64579a250d41d7ddae94602") 68 | ("x86_64-linux" . "d3b612ff8192c38d8d05301abdbb7838bdb377f711c482077307baf550c198d7") 69 | ("x86_64-macos" . "48b02a4198b81833c7cc0998498fe0f5fc7dd053d826fb76b70add562847cdac") 70 | ("x86_64-windows" . "112c4b1d526c5c6e9d4a292fb5a9d5259d05d374c8b62defb06ef56fb34a34ad")) 71 | nil nil 'equal)) 72 | 73 | (defun zt--fontify-first-line (limit) 74 | (if (= (point) 1) 75 | (re-search-forward ".*?\n" limit t) 76 | nil)) 77 | 78 | (defconst zt--id-regexp (rx (= 8 digit) 79 | (? "T") 80 | (= 6 digit))) 81 | 82 | (defvar zt--link-help-echo-cache (cons "" "")) 83 | (defun zt--link-help-echo (window object pos) 84 | (save-excursion 85 | (goto-char pos) 86 | (let ((current-id (zt--id-at-point))) 87 | (if (equal (car zt--link-help-echo-cache) current-id) 88 | (cdr zt--link-help-echo-cache) 89 | (setq zt--link-help-echo-cache (cons current-id (zt--format-link-id current-id))) 90 | (cdr zt--link-help-echo-cache))))) 91 | 92 | (defconst zt--link-face 93 | (let ((link-keymap (make-sparse-keymap))) 94 | (define-key link-keymap (kbd "RET") 'zt--link-enter-key-pressed) 95 | (define-key link-keymap (kbd "") 'zt--link-mouse-pressed) 96 | `(face link 97 | help-echo zt--link-help-echo 98 | keymap ,link-keymap 99 | mouse-face highlight))) 100 | 101 | (defconst zt--keywords `((,zt--id-regexp 0 ',zt--link-face t))) 102 | 103 | (defun zt--generate-id () 104 | (format-time-string "%Y%m%dT%H%M%S")) 105 | 106 | (defun zt--insert-link (link &optional omit-title) 107 | (insert 108 | (if (eq major-mode 'org-mode) "zt:" "") 109 | (if omit-title (zt--find-id link) link))) 110 | 111 | (defun zt--update-buffer-name (&rest args) 112 | (interactive) 113 | (when zt-minor-mode 114 | (rename-buffer (zt--format-link-id (zt--current-id)) t))) 115 | 116 | (defun zt--enable-minor-mode () 117 | (zt--update-buffer-name) 118 | (font-lock-add-keywords nil zt--keywords) 119 | (when (and zt-fontify-plain-text-title (derived-mode-p 'text-mode)) 120 | (font-lock-add-keywords nil '((zt--fontify-first-line 0 'zt-plain-text-title)))) 121 | (setq-local font-lock-extra-managed-props '(help-echo keymap mouse-face)) 122 | (font-lock-fontify-buffer) 123 | (advice-add 'save-buffer :after 'zt--update-buffer-name)) 124 | 125 | (defun zt--disable-minor-mode () 126 | (font-lock-remove-keywords nil zt--keywords) 127 | (font-lock-fontify-buffer)) 128 | 129 | (defun zt--is-id (string) 130 | (string-match zt--id-regexp string)) 131 | 132 | (defun zt--id-at-point () 133 | (if-let ((word (thing-at-point 'word t))) 134 | (when (zt--is-id word) word))) 135 | 136 | (defun zt--formatted-link-at-point () 137 | (let ((line (thing-at-point 'line t))) 138 | (string-match (rx (group (regexp zt--id-regexp) 139 | (opt " " (+? any) line-end))) 140 | line) 141 | (match-string 1 line))) 142 | 143 | ;;;###autoload 144 | (defun zt-insert-new-id () 145 | (interactive) 146 | (zt--insert-link (zt--generate-id))) 147 | 148 | (defun zt--find-id (string) 149 | (string-match zt--id-regexp string) 150 | (match-string 0 string)) 151 | 152 | (defun zt--find-title (formatted-link) 153 | (string-match (rx (+ (or digit "T")) 154 | " " 155 | (group (+? any)) 156 | string-end) 157 | formatted-link) 158 | (match-string 1 formatted-link)) 159 | 160 | (defun zt--search-id (id) 161 | "If a note with the given ID exists in the current directory, 162 | return its full path. If no file exists, or there are multiple 163 | matching files, return `nil'." 164 | (let* ((id-files (directory-files default-directory nil (rx bos (literal id))))) 165 | (when (= (length id-files) 1) 166 | (car id-files)))) 167 | 168 | (defun zt--ztf-command (args) 169 | (s-join " " (cons zt-ztf-executable-path 170 | (mapcar 'shell-quote-argument args)))) 171 | 172 | (defun zt--ztf-needs-update () 173 | (or (not (file-exists-p zt-ztf-executable-path)) 174 | (not (equal zt--required-ztf-version 175 | (s-trim (shell-command-to-string (zt--ztf-command '("--version")))))))) 176 | 177 | (defun zt--interactively-update-ztf () 178 | (if (y-or-n-p (concat "zt: Required companion ztf v. " zt--required-ztf-version 179 | " not available. Automatically download prebuilt executable for " (zt--platform) "?")) 180 | (progn 181 | (make-directory (file-name-directory zt-ztf-executable-path) t) 182 | (url-copy-file (zt--download-url) zt-ztf-executable-path t) 183 | (let ((ztf-executable-buffer (find-file-noselect zt-ztf-executable-path))) 184 | (when (not (equal (zt--expected-sha256) (secure-hash 'sha256 (find-file-noselect zt-ztf-executable-path)))) 185 | (error "zt: sha256 hash didn't match! Refusing to continue.")) 186 | (kill-buffer ztf-executable-buffer)) 187 | (shell-command (concat "chmod +x " (shell-quote-argument zt-ztf-executable-path))) 188 | (when (zt--ztf-needs-update) 189 | (error "zt: Downloading executable didn't work. Make sure you're running the latest version of this package.")) 190 | (message "zt: Sucessfully downloaded prebuilt executable.")) 191 | (error "zt: You must manually install latest 'ztf' executable into 'zt-ztf-executable-path'. See README for more information."))) 192 | 193 | (defun zt--call-ztf (&rest args) 194 | (when (zt--ztf-needs-update) 195 | (zt--interactively-update-ztf)) 196 | (s-trim (shell-command-to-string (zt--ztf-command args)))) 197 | 198 | (defun zt--file-title (file) 199 | "Given the path to a FILE, return it's title as it would be 200 | inserted as a new link." 201 | (zt--call-ztf file)) 202 | 203 | (defun zt--format-link-id (id) 204 | (if-let ((file (zt--search-id id))) 205 | (concat id " " (zt--file-title file)) 206 | id)) 207 | 208 | (defun zt--available-formatted-links () 209 | (s-split "\n" (zt--call-ztf "."))) 210 | 211 | (defun zt--available-linking-files (id) 212 | (s-split "\n" (zt--call-ztf "." id))) 213 | 214 | (defun zt--completing-read (prompt) 215 | (let ((ivy-mode-enabled (and (boundp 'ivy-mode) ivy-mode))) 216 | (if ivy-mode-enabled 217 | (ivy-read prompt (zt--available-formatted-links) :preselect (zt--current-id)) 218 | (completing-read prompt (zt--available-formatted-links))))) 219 | 220 | (defun zt--completing-read-linking-files (prompt id) 221 | (completing-read prompt (zt--available-linking-files id))) 222 | 223 | (defun zt--new-filename-id (id) 224 | (concat id zt-default-file-extension)) 225 | 226 | (defun zt--current-id () 227 | (let ((id (zt--find-id (buffer-name)))) 228 | (when (zt--is-id id) id))) 229 | 230 | ;;;###autoload 231 | (defun zt-change-file-extension (extension) 232 | "Change the file extension of the current file." 233 | (interactive "MFile extension: ") 234 | (save-buffer) 235 | (let* ((old-file-name (buffer-file-name)) 236 | (new-file-name (concat (file-name-directory old-file-name) 237 | (file-name-base old-file-name) 238 | "." extension))) 239 | (write-file new-file-name) 240 | (delete-file old-file-name) 241 | (zt-minor-mode 1))) 242 | 243 | ;;;###autoload 244 | (defun zt-kill-current-id () 245 | "Add the ID of the current file to the kill ring, so that it 246 | can be yanked again with `yank', or, depending on your Emacs 247 | configuration, is copied to the clipboard." 248 | (interactive) 249 | (let ((id (zt--current-id))) 250 | (kill-new id) 251 | (message (format "Added current ID '%s' to kill ring." id)))) 252 | 253 | ;;;###autoload 254 | (defun zt-open (link) 255 | "Given a link to a file, optionally also followed by a title, go 256 | to the associated file if it exists, and otherwise create the 257 | file with the optionally given title. 258 | 259 | Finds or create the associated file: 260 | 261 | (zt-open \"20220912T201109\") 262 | 263 | Find or create the associated file. If and only if it does not 264 | already exist, insert the text \"New file\" on the first line 265 | of the created file: 266 | 267 | (zt-open \"20220912T201109 New file\")" 268 | (let* ((id (zt--find-id link)) 269 | (title (zt--find-title link)) 270 | (file (zt--search-id id))) 271 | (find-file (or file (zt--new-filename-id id))) 272 | (when (and (not file) title) 273 | (insert title)) 274 | (zt-minor-mode 1))) 275 | 276 | ;;;###autoload 277 | (defun zt-open-follower-at-point () 278 | "Open the link at point or before the point, according to the 279 | same rules at `zt-open'. In the newly created file, insert not 280 | only the title but also a list of all linking files (see also 281 | `zt-insert-linking-files'). 282 | 283 | The \"follower\" refers to a Folgezettel-style link where a 284 | backlink from the newly created follower-note is also inserted." 285 | (interactive) 286 | (if-let ((id (or (zt--id-at-point) 287 | (zt--formatted-link-at-point)))) 288 | (progn 289 | (save-buffer) 290 | (zt-open id) 291 | (insert "\n\n") 292 | (zt-insert-linking-files)) 293 | (message "zt: no link at point"))) 294 | 295 | ;;;###autoload 296 | (defun zt-open-at-point (&optional prefix) 297 | "Open the link at point, according to the same rules as 298 | `zt-open'. With a prefix argument, instead do the same as 299 | `zt-open-follower-at-point'." 300 | (interactive "P") 301 | (if prefix 302 | (zt-open-follower-at-point) 303 | (if-let ((id (or (zt--id-at-point) 304 | (zt--formatted-link-at-point)))) 305 | (progn 306 | (zt-open id) 307 | (when prefix 308 | (insert "\n\n") 309 | (zt-insert-linking-files))) 310 | (message "zt: no link at point")))) 311 | 312 | (defun zt--is-point-really-on-link () 313 | (save-excursion 314 | (when (not (= (point) (point-max))) 315 | (forward-char) 316 | (zt--id-at-point)))) 317 | 318 | (defun zt--link-mouse-pressed () 319 | (interactive) 320 | (when (zt--is-point-really-on-link) (zt-open-at-point))) 321 | 322 | (defun zt--link-enter-key-pressed () 323 | (interactive) 324 | (if (zt--is-point-really-on-link) (zt-open-at-point) (newline))) 325 | 326 | ;;;###autoload 327 | (defun zt-insert-link (&optional prefix) 328 | "Interactively select a note, and insert a link to the note at 329 | point. By default, also insert the linked file's title (if it 330 | exists). With prefix argument, insert just the link." 331 | (interactive "P") 332 | (let ((formatted-link (zt--completing-read "Insert link: "))) 333 | (zt--insert-link formatted-link prefix))) 334 | 335 | ;;;###autoload 336 | (defun zt-find-file () 337 | (interactive) 338 | (zt-open (zt--completing-read "Find file: "))) 339 | 340 | ;;;###autoload 341 | (defun zt-find-linking-file () 342 | "Interactively prompt for a file from among those that link to 343 | the current file and open it." 344 | (interactive) 345 | (zt-open (zt--completing-read-linking-files "Find file: " (zt--current-id)))) 346 | 347 | ;;;###autoload 348 | (defun zt-insert-linking-file (&optional prefix) 349 | "Interactively prompt for a file from among those that link to 350 | the current file. Insert a link to the selected file. Prefix 351 | argument has same effect as for `zt-insert-link'." 352 | (interactive "P") 353 | (let ((formatted-link (zt--completing-read-linking-files "Insert link: " (zt--current-id)))) 354 | (zt--insert-link formatted-link prefix))) 355 | 356 | ;;;###autoload 357 | (defun zt-insert-linking-files () 358 | "Insert an index of all files that link to the current file. To 359 | insert only a single link, use `zt-insert-linking-file'. To 360 | insert an index of all files in the system, use 361 | `zt-insert-index'." 362 | (interactive) 363 | (mapc (lambda (link) (insert link "\n")) 364 | (zt--available-linking-files (zt--current-id)))) 365 | 366 | ;;;###autoload 367 | (defun zt-insert-index () 368 | "Insert at point a list of links to each file in the current 369 | directory, including their titles. To include only files that 370 | link to the current file, use `zt-insert-linking-files' instead." 371 | (interactive) 372 | (mapc (lambda (link) (insert link "\n")) 373 | (zt--available-formatted-links))) 374 | 375 | ;;;###autoload 376 | (defun zt-create-in-directory (directory) 377 | "Create a new note in the given directory." 378 | (interactive "DDirectory: ") 379 | (zt-open-in-directory (zt--generate-id) directory)) 380 | 381 | ;;;###autoload 382 | (defun zt-open-in-directory (link directory) 383 | "Open the whose ID corresponds to LINK in DIRECTORY. For example, 384 | if you have an index note with ID \"20220922T193931\", this may 385 | be a useful binding to define: 386 | 387 | (global-set-key (kbd \"C-c z\") 388 | (lambda (interactive) 389 | (zt-open-in-directory \"20220922T193931\" \"~/zt\")))" 390 | (let ((default-directory directory)) 391 | (zt-open link))) 392 | 393 | (defconst zt-minor-mode-prefix-map 394 | (let ((map (make-sparse-keymap))) 395 | (define-key map (kbd "o") 'zt-open-at-point) 396 | (define-key map (kbd "O") 'zt-open-follower-at-point) 397 | (define-key map (kbd "t") 'zt-insert-new-id) 398 | (define-key map (kbd "l") 'zt-insert-link) 399 | (define-key map (kbd "L") 'zt-insert-linking-file) 400 | (define-key map (kbd "M-l") 'zt-insert-linking-files) 401 | (define-key map (kbd "f") 'zt-find-file) 402 | (define-key map (kbd "F") 'zt-find-linking-file) 403 | (define-key map (kbd "M-w") 'zt-kill-current-id) 404 | (define-key map (kbd ".") 'zt-change-file-extension) 405 | map)) 406 | 407 | (defconst zt-minor-mode-map 408 | (let ((map (make-sparse-keymap))) 409 | (define-key map (kbd "C-c #") zt-minor-mode-prefix-map) 410 | map)) 411 | 412 | ;;;###autoload 413 | (define-minor-mode zt-minor-mode 414 | "Toggle zt minor mode. 415 | 416 | Keymap: 417 | \\{zt-minor-mode-map}" 418 | :lighter " zt" 419 | :keymap zt-minor-mode-map 420 | (if zt-minor-mode (zt--enable-minor-mode) (zt--disable-minor-mode))) 421 | 422 | ;; Org-mode links 423 | 424 | (eval-after-load 'org 425 | (progn 426 | (require 'ol) 427 | 428 | (defun zt--org-handler (link) 429 | (zt-open link)) 430 | 431 | (org-link-set-parameters 432 | "zt" 433 | :follow 'zt--org-handler 434 | :help-echo 'zt--link-help-echo))) 435 | 436 | (provide 'zt) 437 | ;;; zt.el ends here 438 | -------------------------------------------------------------------------------- /ztf.zig: -------------------------------------------------------------------------------- 1 | const std = @import("std"); 2 | 3 | fn firstLine(buffer: []const u8) []const u8 { 4 | var i: u64 = 0; 5 | while (i < buffer.len) { 6 | if (buffer[i] == '\n') return buffer[0..i]; 7 | i += 1; 8 | } 9 | return buffer; 10 | } 11 | 12 | fn readTitleFromName(name: []const u8) []const u8 { 13 | var nameEnd: u64 = name.len - 1; 14 | while (nameEnd > 16) { 15 | if (name[nameEnd] == '.') break; 16 | nameEnd -= 1; 17 | } 18 | return name[16..nameEnd]; 19 | } 20 | 21 | fn readTitle(buffer: []const u8, name: []const u8) ![]const u8 { 22 | const isMarkdown = std.mem.endsWith(u8, name, ".md"); 23 | const isOrg = std.mem.endsWith(u8, name, ".org"); 24 | 25 | var textBuffer = buffer; 26 | 27 | if (isMarkdown) { 28 | var i: u64 = 0; 29 | var inFrontmatter = std.mem.startsWith(u8, buffer, "---\n"); 30 | if (inFrontmatter) { i += 4; } 31 | 32 | while (i < buffer.len) { 33 | const line = firstLine(buffer[i..]); 34 | 35 | if (inFrontmatter) { 36 | if (std.mem.startsWith(u8, line, "---")) { 37 | inFrontmatter = false; 38 | textBuffer = buffer[i + line.len..]; 39 | } else if (std.mem.startsWith(u8, line, "title: ")) { 40 | return line[7..]; 41 | } 42 | } else if (std.mem.startsWith(u8, line, "# ")) { 43 | return line[2..]; 44 | } 45 | 46 | i += line.len + 1; 47 | } 48 | } else if (isOrg) { 49 | var i: u64 = 0; 50 | while (i < buffer.len) { 51 | const line = firstLine(buffer[i..]); 52 | 53 | if (std.mem.startsWith(u8, line, "* ")) { 54 | return line[2..]; 55 | } else if (std.mem.startsWith(u8, line, "#+TITLE: ") or std.mem.startsWith(u8, line, "#+title: ")) { 56 | return line[9..]; 57 | } 58 | 59 | i += line.len + 1; 60 | } 61 | } 62 | 63 | const nameTitle = readTitleFromName(name); 64 | if (nameTitle.len > 0) { 65 | return nameTitle; 66 | } 67 | 68 | var i: u64 = 0; 69 | while (i < textBuffer.len and textBuffer[i] == '\n') { i += 1; } 70 | return firstLine(textBuffer[i..]); 71 | } 72 | 73 | fn doesMatch(buffer: []const u8, searchTerm: []const u8) bool { 74 | for (buffer) |char, i| { 75 | if ( 76 | char == searchTerm[0] 77 | and buffer.len >= i + searchTerm.len 78 | and buffer[i+1] == searchTerm[1] 79 | and std.mem.startsWith(u8, buffer[i..], searchTerm) 80 | ) return true; 81 | } 82 | return false; 83 | } 84 | 85 | const InvalidIdError = error { InvalidId }; 86 | 87 | fn parseId(name: []const u8) InvalidIdError![]const u8 { 88 | if (name.len < 17) return InvalidIdError.InvalidId; 89 | if (name[0] != '2' or name[8] != 'T') return InvalidIdError.InvalidId; 90 | return name[0..15]; 91 | } 92 | 93 | fn cmpId(context: void, a: []const u8, b: []const u8) bool { 94 | _ = context; 95 | 96 | if (a.len < 15 or b.len < 15) return false; 97 | 98 | var i: u64 = 0; 99 | while (i < 15) { 100 | if (a[i] > b[i]) { 101 | return true; 102 | } else if (a[i] < b[i]) { 103 | return false; 104 | } 105 | i += 1; 106 | } 107 | 108 | return false; 109 | } 110 | 111 | pub fn main() !void { 112 | var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator); 113 | defer arena.deinit(); 114 | var allocator = arena.allocator(); 115 | 116 | const stdout = std.io.getStdOut().writer(); 117 | 118 | const args = try std.process.argsAlloc(allocator); 119 | const dirPath = args[1]; 120 | 121 | if (std.mem.eql(u8, dirPath, "--version")) { 122 | try stdout.print("{s}\n", .{"2"}); 123 | return; 124 | } 125 | 126 | var fileBuffer: []u8 = try allocator.alloc(u8, 1048576); 127 | 128 | const path = try std.fs.path.resolve(allocator, &.{dirPath}); 129 | var dir = std.fs.openDirAbsolute(path, .{.iterate = true}) catch { 130 | // I couldn't figure out how to actually check the kind of a path, so instead 131 | // we do this to guess if we're dealing with a file. 132 | var file = std.fs.openFileAbsolute(path, .{}) catch { 133 | // Actual error. 134 | try stdout.print("{s}\n", .{dirPath}); 135 | return; 136 | }; 137 | defer file.close(); 138 | 139 | var len = try file.read(fileBuffer); 140 | 141 | const title = try readTitle(fileBuffer[0..len], std.fs.path.basename(path)); 142 | try stdout.print("{s}\n", .{title}); 143 | 144 | return; 145 | }; 146 | defer dir.close(); 147 | 148 | var filenames = try allocator.alloc([]u8, 32768); 149 | var filenamesI: u64 = 0; 150 | 151 | var iterator = dir.iterate(); 152 | while (try iterator.next()) |entry| { 153 | if (filenamesI >= filenames.len) break; 154 | if (entry.kind != std.fs.Dir.Entry.Kind.File) continue; 155 | if (entry.name.len < 15) continue; 156 | filenames[filenamesI] = try allocator.alloc(u8, entry.name.len); 157 | std.mem.copy(u8, filenames[filenamesI], entry.name); 158 | filenamesI += 1; 159 | continue; 160 | } 161 | 162 | std.sort.sort([]const u8, filenames[0..filenamesI], {}, cmpId); 163 | 164 | for (filenames[0..filenamesI]) |filename| { 165 | const id = parseId(filename) catch { continue; }; 166 | 167 | const file = dir.openFile(filename, .{}) catch { continue; }; 168 | defer file.close(); 169 | 170 | const len = file.read(fileBuffer) catch { continue; }; 171 | 172 | if (args.len > 2 and !doesMatch(fileBuffer[0..len], args[2])) { 173 | continue; 174 | } 175 | 176 | const title = readTitle(fileBuffer[0..len], filename) catch { continue; }; 177 | 178 | _ = try stdout.write(id); 179 | _ = try stdout.write(" "); 180 | _ = try stdout.write(title); 181 | _ = try stdout.write("\n"); 182 | } 183 | } 184 | 185 | --------------------------------------------------------------------------------