contrapunctus
/
chronometrist
Archived
1
3
Fork 0
Code Issues 1 Pull Requests Projects Releases Wiki Activity

doc: merge manual.org into chronometrist.org (again?)

This commit is contained in:
contrapunctus 2021-06-01 16:18:51 +05:30
parent ca5351cbf5
commit 36d3d18769
2 changed files with 14 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/manual.org
View File

@ -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:

19
elisp/chronometrist.org
View File

@ -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: <link rel="stylesheet" type="text/css" href="../org-doom-molokai.css" />
* 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