diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/tissue.skb | 116 |
1 files changed, 115 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 |