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 <arunisaac@systemreboot.net>
+;;; Copyright © 2022, 2023 Arun Isaac <arunisaac@systemreboot.net>
 ;;;
 ;;; This file is part of tissue.
 ;;;
@@ -30,6 +30,120 @@ 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.]))
+  (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
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/#"
                                                              identifier)))
                                   (list "chapter-introduction"
+                                        "chapter-tutorial"
                                         "chapter-gemtext-markup"
                                         "section-constructors"
                                         "section-reader-functions"