diff --git a/doc/manual.org b/doc/manual.org deleted file mode 100644 index 43b7b2d..0000000 --- a/doc/manual.org +++ /dev/null @@ -1,23 +0,0 @@ -#+TITLE: The Chronometrist Manual -#+AUTHOR: contrapunctus - -The structure of this manual was inspired by https://documentation.divio.com/ -* How to... -:PROPERTIES: -:DESCRIPTION: Step-by-step guides to achieve specific tasks -:END: -** How to set up Emacs to contribute -All of these are optional, but recommended for the best experience. -1. Use [[https://github.com/Malabarba/Nameless][nameless-mode]] for easier reading of Emacs Lisp code, and -2. Use [[https://github.com/joostkremers/visual-fill-column][visual-fill-column-mode]] to soft-wrap lines in Org/Markdown files. - =org-indent-mode= (for Org files) and [[https://elpa.gnu.org/packages/adaptive-wrap.html][adaptive-prefix-mode]] (for Markdown and other files) will further enhance the experience. -3. Get the sources from https://github.com/contrapunctus-1/chronometrist and read this manual in the Org format (doc/manual.org), so links to identifiers can take you to their location in the source. -4. Install [[https://github.com/cask/cask][Cask]] to easily byte-compile and test the project. - From the project root, you can now run - 1. =cask= to install the project dependencies in a sandbox - 2. =cask exec buttercup -L . --traceback pretty= to run tests. - -# Local Variables: -# org-link-file-path-type: relative -# eval: (progn (make-local-variable (quote after-save-hook)) (add-hook (quote after-save-hook) (lambda () (org-export-to-file 'texinfo "manual.info")))) -# End: diff --git a/elisp/chronometrist.org b/elisp/chronometrist.org index c25e15b..0cc6058 100644 --- a/elisp/chronometrist.org +++ b/elisp/chronometrist.org @@ -1,11 +1,11 @@ #+TITLE: Chronometrist - an extensible time tracker for Emacs #+SUBTITLE: Developer manual and program source #+TODO: TODO TEST WIP EXTEND CLEANUP FIXME REVIEW | -#+PROPERTY: header-args :tangle yes :load yes +#+PROPERTY: header-args :load yes #+HTML_HEAD: * Introduction -This is a book about Chronometrist, a time tracker for Emacs, written by a humble hobbyist hacker. It coincidentally also happens to contain the full source code, and can be loaded as an Emacs Lisp program using the =literate-elisp= library. +This is a book about Chronometrist, a time tracker for Emacs, written by a humble hobbyist hacker. It also happens to contain the canonical copy of the source code, and can be loaded as an Emacs Lisp program using the =literate-elisp= library. I hope this book—when completed—passes Tim Daly's [[https://www.youtube.com/watch?v=Av0PQDVTP4A&t=8m52s]["Hawaii Test"]], in which a programmer with no knowledge of this program whatsover can read this book end-to-end, and come out as much of an expert in its maintenance as the original author. @@ -162,7 +162,7 @@ The shift from a bunch of Elisp files to a single Org literate program was born At first, I tried tangling. Back when I used =benchmark.el= to test it, =org-babel-tangle= took about 30 seconds to tangle this file. Thus, I wrote a little sed one-liner (in the file-local variables) to do the tangling, which was nearly instant. It emitted anything between lines matching the exact strings ="#+BEGIN_SRC emacs-lisp"= and ="#+END_SRC"= - -#+BEGIN_SRC org +#+BEGIN_SRC org :tangle no # eval: (progn (make-local-variable 'after-save-hook) (add-hook 'after-save-hook (lambda () (start-process-shell-command "chronometrist-sed-tangle" "chronometrist-sed-tangle" "sed -n -e '/#+BEGIN_SRC emacs-lisp$/,/#+END_SRC$/{//!p;};/#+END_SRC/i\\ ' chronometrist.org | sed -E 's/^ +$//' > chronometrist.el")))) #+END_SRC @@ -234,9 +234,18 @@ Further details are stored in properties - * Only returned by =chronometrist-seconds-to-hms=, called by =chronometrist-format-time= * How-to guides for maintainers +** How to set up Emacs to contribute +All of these are optional, but recommended for the best experience. +1. Use [[https://github.com/Malabarba/Nameless][nameless-mode]] for easier reading of Emacs Lisp code, and +2. Use [[https://github.com/joostkremers/visual-fill-column][visual-fill-column-mode]] to soft-wrap lines in Org/Markdown files. + =org-indent-mode= (for Org files) and [[https://elpa.gnu.org/packages/adaptive-wrap.html][adaptive-prefix-mode]] (for Markdown and other files) will further enhance the experience. +3. Get the sources from [[https://tildegit.org/contrapunctus/chronometrist]] and read this manual in the Org format (doc/manual.org), so links to identifiers can take you to their location in the source. +4. Install [[https://github.com/cask/cask][Cask]] to easily byte-compile and test the project. + From the project root, you can now run + 1. =cask= to install the project dependencies in a sandbox + 2. =cask exec buttercup -L . --traceback pretty= to run tests. ** How to tangle this file -[[#explanation-literate-programming][Tangling is not necessary]] when you can use =literate-elisp-load= instead. -But if you must tangle, use =org-babel= 's tangle commands, /not/ =literate-elisp-tangle=. The file emitted by the latter does not contain comments - thus, it does not contain library headers or abide by =checkdoc='s comment conventions. +[[#explanation-literate-programming][Tangling is not necessary]] - use =literate-elisp-load= instead. But if you must tangle, use =org-babel= (=org-babel-tangle= / =org-babel-tangle-file=), /not/ =literate-elisp-tangle=. The file emitted by the latter does not contain comments - thus, it does not contain library headers or abide by =checkdoc='s comment conventions. * The Program ** Library headers and commentary