diff options
authorArun Isaac2023-01-27 00:56:39 +0000
committerArun Isaac2023-01-27 00:59:10 +0000
commitabaeb6881438832ccf391de70b6aa2b5d9634a4e (patch)
parent17c3e1261c9aa134816414c9e64584efe6450ddf (diff)
doc: Add Tutorial.
* doc/tissue.skb (Tutorial): New chapter. * tissue.scm (#:indexed-documents): Index it.
2 files changed, 116 insertions, 1 deletions
diff --git a/doc/tissue.skb b/doc/tissue.skb
index 3c46c39..8e16518 100644
--- a/doc/tissue.skb
+++ b/doc/tissue.skb
@@ -1,5 +1,5 @@
;;; tissue --- Text based issue tracker
-;;; Copyright © 2022 Arun Isaac <>
+;;; Copyright © 2022, 2023 Arun Isaac <>
;;; This file is part of tissue.
@@ -30,6 +30,120 @@ through project issues and documentation. The search interface is
built on the ,(ref :url "" :text "Xapian search
engine library"), and is available both as a command-line program and
as a web server.]))
+ (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
+"" :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 "" :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
diff --git a/tissue.scm b/tissue.scm
index 3dc35e7..f697491 100644
--- a/tissue.scm
+++ b/tissue.scm
@@ -19,6 +19,7 @@
(string-append "/manual/dev/en/#"
(list "chapter-introduction"
+ "chapter-tutorial"