summary refs log tree commit diff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/skribilo.scm109
-rw-r--r--doc/tissue.skb234
2 files changed, 343 insertions, 0 deletions
diff --git a/doc/skribilo.scm b/doc/skribilo.scm
new file mode 100644
index 0000000..23a1829
--- /dev/null
+++ b/doc/skribilo.scm
@@ -0,0 +1,109 @@
+;;; tissue --- Text based issue tracker
+;;; Copyright © 2022, 2023 Arun Isaac <arunisaac@systemreboot.net>
+;;;
+;;; This file is part of tissue.
+;;;
+;;; tissue is free software: you can redistribute it and/or modify it
+;;; under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation, either version 3 of the License, or
+;;; (at your option) any later version.
+;;;
+;;; tissue is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;;; General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with tissue.  If not, see <https://www.gnu.org/licenses/>.
+
+(define-module (doc skribilo)
+  #:use-module (srfi srfi-1)
+  #:use-module (srfi srfi-9)
+  #:use-module (srfi srfi-26)
+  #:use-module (srfi srfi-171)
+  #:use-module (ice-9 match)
+  #:use-module (texinfo)
+  #:use-module (skribilo package base)
+  #:export (file
+            docstring-function-documentation
+            function-documentation))
+
+;; Aliases
+(define file samp)
+
+(define-record-type <function>
+  (function name arguments docstring)
+  function?
+  (name function-name)
+  (arguments function-arguments)
+  (docstring function-docstring))
+
+(define (find-function-definition file name)
+  "Return a @code{<function>} object describing a function named
+@var{name} in @var{file}."
+  (call-with-input-file file
+    (cut port-transduce
+         (tmap identity)
+         (rany (match-lambda
+                 (((or 'define 'define* 'define-lazy)
+                   ((? (cut eq? name <>)) arguments ...)
+                    docstring
+                    body ...)
+                  (function name arguments docstring))
+                 (_ #f)))
+         read
+         <>)))
+
+(define (stexi->skribe stexi)
+  "Convert @var{stexi}, a stexinfo tree, to a skribe tree."
+  (match stexi
+    (('*fragment* children ...)
+     (map stexi->skribe children))
+    (('para children ...)
+     (cons 'paragraph children))))
+
+(define (quoted-write object port)
+  "Write @var{object} to @var{port} printing quoted expressions using
+the quote character."
+  (match object
+    (('quote child)
+     (display "'" port)
+     (quoted-write child port))
+    ((parent children ...)
+     (display "(" port)
+     (quoted-write parent port)
+     (unless (null? children)
+       (display " " port))
+     (for-each (cut quoted-write <> port)
+               children)
+     (display ")" port))
+    (_ (write object port))))
+
+(define (docstring-function-documentation file name)
+  "Document function of @var{name} from @var{file} using its docstring."
+  (let ((function (or (find-function-definition file name)
+                      (error "Function not found in file:" name file))))
+    (item #:key (code (list "("
+                            (bold (symbol->string name))
+                            (unless (null? (function-arguments function))
+                              " ")
+                            (string-join (map (lambda (element)
+                                                (call-with-output-string
+                                                  (cut quoted-write element <>)))
+                                              (function-arguments function)))
+                            ")"))
+          (map (cut eval <> (current-module))
+               (stexi->skribe
+                (texi-fragment->stexi
+                 (function-docstring function)))))))
+
+(define (function-documentation name arguments . documentation)
+  "Document function of @var{name} with @var{arguments} and
+@var{documentation}."
+  (apply item
+         #:key (code (list "("
+                            (bold (symbol->string name))
+                            " "
+                            arguments
+                            ")"))
+        documentation))
diff --git a/doc/tissue.skb b/doc/tissue.skb
new file mode 100644
index 0000000..61ca112
--- /dev/null
+++ b/doc/tissue.skb
@@ -0,0 +1,234 @@
+;;; tissue --- Text based issue tracker
+;;; Copyright © 2022, 2023 Arun Isaac <arunisaac@systemreboot.net>
+;;;
+;;; This file is part of tissue.
+;;;
+;;; tissue is free software: you can redistribute it and/or modify it
+;;; under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation, either version 3 of the License, or
+;;; (at your option) any later version.
+;;;
+;;; tissue is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;;; General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with tissue.  If not, see <https://www.gnu.org/licenses/>.
+
+(use-modules (doc skribilo))
+
+(document :title [tissue]
+  (toc)
+  (chapter :title [Introduction]
+           :ident "chapter-introduction"
+    (p [tissue is an issue tracker and project information management
+system built on plain text files and git. It is specifically intended
+for small free software projects. It features a static site generator
+to build a project website and a powerful search interface to search
+through project issues and documentation. The search interface is
+built on the ,(ref :url "https://xapian.org/" :text "Xapian search
+engine library"), and is available both as a command-line program and
+as a web server.])
+    (section :title "Why tissue?"
+      (subsection :title "tissue is not discussion-oriented"
+        (p [tissue moves away from the discussion-oriented style of popular
+issue trackers such as the GitHub issue tracker. It separates the
+discussion of an issue from the documentation of it. You discuss
+somewhere else (say, on a mailing list, on IRC, or even
+face-to-face), and then distill the discussion into a coherent issue
+report that reads cleanly from top to bottom. Too often, the problem
+with discussion-oriented issue trackers like GitHub is that new
+readers of the issue have to follow the whole discussion from start to
+finish and put it all together in their head to understand what's
+going on. This is tiring, and sometimes people simply give up on
+reading issues that have long discussions. It's much better to have a clear
+succinct actionable issue report. This way, the issue tracker is a list of
+clear actionable items rather than a mess of unreproducible issues.]))
+      (subsection :title "tissue allows and encourages rewriting of issues"
+        (p [Discussion-oriented issue trackers force an append-only
+style where updates to the issue are only possible as newly appended
+messages to the discussion. tissue, on the other hand, allows and
+encourages rewriting of issues to keep the overall issue easily
+readable to a newcomer.]))))
+  (chapter :title [Tutorial]
+           :ident "chapter-tutorial"
+    (p [In this tutorial, we will learn how to create issues for an
+existing project, and how to publish those issues on the web.])
+    (section :title [Creating issues]
+      (p [We start with a git repository for our project.])
+      (prog :line #f [~/my-project$])
+      (p [The repository presumably has project source code committed
+in it. We now create a directory ,(file "issues") and populate it with
+a few issues.])
+      (prog :line #f [~/my-project$ mkdir issues])
+      (p [Each issue is a ,(ref :url
+"https://gemini.circumlunar.space/docs/cheatsheet.gmi" :text
+"gemtext") file. Let's write our first issue ,(file
+"issues/crash-on-invalid-query.gmi") and commit it.])
+      (prog :line #f [# Search engine crashes on invalid query
+
+* tags: bug
+* assigned: Arun Isaac
+
+When a syntatically invalid search query is entered into the search
+engine, the search engine process crashes. Further queries all return
+a 500 Internal Server Error.])
+      (prog :line #f [~/my-project$ git add issues/crash-on-invalid-query.gmi
+~/my-project$ git commit -m "Add first issue"])
+      (p [Let's add a second issue ,(file
+"issues/add-emacs-interface.gmi") and commit it.])
+      (prog :line #f [# Add Emacs interface
+
+* tags: feature-request
+
+Add Emacs interface to search for issues.])
+      (prog :line #f [~/my-project$ git add issues/add-emacs-interface.gmi
+~/my-project$ git commit -m "Add second issue"])
+      (p [Now that we have a couple of issues, let's tell tissue about
+them. We do this using a configuration file ,(file "tissue.scm").])
+      (prog :line #f [(tissue-configuration
+ #:indexed-documents (map read-gemtext-issue
+                          (gemtext-files-in-directory "issues")))])
+      (prog :line #f [~/my-project$ git add tissue.scm
+~/my-project$ git commit -m "Add tissue configuration"])
+      (p [This tells tissue to index all files in the ,(file "issues")
+directory as issues. The ,(code "gemtext-files-in-directory") function
+returns a list of filenames (strings) in the ,(file "issues")
+directory. The ,(code "read-gemtext-issue") function reads each file
+and returns an ,(code "<issue>") object. Now, we may list all issues
+on the command line using tissue.])
+      (prog :line #f [~/my-project$ tissue
+Add Emacs interface feature-request
+ISSUE issues/add-emacs-interface.gmi
+opened 70 minutes ago by Arun Isaac
+Search engine crashes on invalid query (assigned: Arun Isaac)
+ISSUE issues/crash-on-invalid-query.gmi
+opened 71 minutes ago by Arun Isaac])
+      (p [We could also search through and shortlist. The search
+interface is a powerful full text search engine powered by the
+excellent ,(ref :url "https://xapian.org/" :text "Xapian") library.])
+      (prog :line #f [~/my-project$ tissue search assigned:arun
+Search engine crashes on invalid query (assigned: Arun Isaac)
+ISSUE issues/crash-on-invalid-query.gmi
+opened 76 minutes ago by Arun Isaac
+
+~/my-project$ tissue search emacs
+Add Emacs interface feature-request
+ISSUE issues/add-emacs-interface.gmi
+opened 87 minutes ago by Arun Isaac
+Add Emacs interface
+* tags: feature-request
+Add Emacs interface to search for...
+
+~/my-project$ tissue search tag:bug
+Search engine crashes on invalid query bug (assigned: Arun Isaac)
+ISSUE issues/crash-on-invalid-query.gmi
+opened 88 minutes ago by Arun Isaac]))
+    (section :title [Publishing issues on the web]
+      (p [Now, let's try to get our issue tracker on the web. tissue
+does not treat issue files specially. You will notice that it only
+speaks of ,(emph "indexed documents") and not specifically about
+issues. We need to explicitly tell it to create web pages for each
+issue file and to associate each issue to its respective web page. We
+do this with the following ,(file "tissue.scm") configuration.])
+      (prog :line #f [(tissue-configuration
+ #:indexed-documents (map (lambda (filename)
+                            (slot-set (read-gemtext-issue filename)
+                                      'web-uri
+                                      (string-append "/" (string-remove-suffix ".gmi" filename))))
+                          (gemtext-files-in-directory "issues"))
+ #:web-files (map (lambda (filename)
+                    (file (replace-extension filename "html")
+                          (gemtext-exporter filename)))
+                  (gemtext-files-in-directory "issues")))])
+      (prog :line #f [~/my-project$ git add tissue.scm
+~/my-project$ git commit -m "Add web configuration"])
+      (p [The ,(code "#:indexed-documents") keyword argument is the
+same as earlier, but in addition, we set the ,(code "'web-uri") slot
+of the ,(code "<issue>") object to the HTTP URI at which the issue may
+be found.])
+      (p [In order to actually put web pages for each issue at the
+aforementioned HTTP URIs, we need the ,(code "#:web-files") keyword
+argument. The ,(code "#:web-files") keyword argument takes a list of
+,(code "<file>") objects that describe files on the website. Each file
+object constitutes a file path and something we call a ,(emph "writer
+function"). A writer function is a one-argument function that accepts
+a port and writes the contents of a file to it. Here, we use the
+,(code "gemtext-exporter") function provided by tissue to create a
+writer function for each issue file.])
+      (p [Now, to see this in a web interface, run])
+      (prog :line #f [~/my-project$ tissue web-dev
+Tissue development web server listening at http://localhost:8080])
+      (p [Visiting ,(ref :url "http://localhost:8080/") on your
+browser should get you the web search interface.]))
+    ;; TODO
+    (section :title [Production deployment]
+      (p [TODO])))
+  (chapter :title [Gemtext markup for issues]
+           :ident "chapter-gemtext-markup"
+    (p [Issues must be written in ,(ref
+:url "https://gemini.circumlunar.space/docs/gemtext.gmi"
+:text "gemtext markup") with added extra notation to specify issue
+metadata.])
+    (p [Tag issues.]
+       (prog :line #f
+             [* tags: enhancement, good first issue]))
+    (p [Close issues. Use either of]
+       (prog :line #f
+             [* closed])
+       (prog :line #f
+             [* status: closed]))
+    (p [Assign issues to one or more people.]
+       (prog :line #f
+             [* assigned: mekalai])
+       (prog :line #f
+             [* assigned: muthu, mekalai]))
+    (p [Create task lists with regular gemtext lists starting with
+,(code "[ ]"). Tasks may be marked as completed by putting an
+,(code "x") within the brackets, like so: ,(code "[x]")]
+       (prog :line #f
+             [* \[x\] Do this.
+* \[ \] Then, do this.
+* \[ \] Finally, do this.])))
+  (chapter :title [Reference]
+           :ident "chapter-reference"
+    (section :title [Object and record constructors]
+             :ident "section-constructors"
+      (description
+       (docstring-function-documentation "tissue/tissue.scm" 'tissue-configuration)
+       (function-documentation 'file [filename writer]
+         [Construct a ,(code [<file>]) object that represents an
+output file to be created.]
+         (description
+          (item :key (var [filename])
+                [the name of the file to create as a string])
+          (item :key (var [writer])
+                [a one-argument function that takes a port as an
+argument and writes data destined for ,(var [filename]) into that
+port])))))
+    (section :title [Reader functions]
+             :ident "section-reader-functions"
+      (p [These functions produce ,(code [<document>]) objects (or
+objects of classes inheriting from ,(code [<document>])) by reading
+files or other data sources.])
+      (description
+       (docstring-function-documentation "tissue/issue.scm" 'read-gemtext-issue)
+       (docstring-function-documentation "tissue/file-document.scm" 'read-gemtext-document)
+       (docstring-function-documentation "tissue/commit.scm" 'commits-in-current-repository)))
+    (section :title [Writer functions]
+             :ident "section-writer-functions"
+      [These functions write output files and are meant to be
+specified in a ,(code [<file>]) object.]
+      (description
+       (docstring-function-documentation "tissue/web/static.scm" 'copier)
+       (docstring-function-documentation "tissue/web/static.scm" 'gemtext-exporter)
+       (docstring-function-documentation "tissue/web/static.scm" 'skribe-exporter)))
+    (section :title [Utility functions]
+             :ident "section-utility-functions"
+      [These miscellaneous functions are useful when writing tissue
+configuration files.]
+      (description
+       (docstring-function-documentation "tissue/tissue.scm" 'gemtext-files-in-directory)
+       (docstring-function-documentation "tissue/git.scm" 'git-tracked-files)
+       (docstring-function-documentation "tissue/document.scm" 'slot-set)))))