doc: Add documentation.

* doc/skribilo.scm, doc/tissue.skb: New files.
* tissue.scm (#:web-files): Add manual/dev/en/index.html.

4 files changed, 200 insertions, 3 deletions

diff --git a/doc/skribilo.scm b/doc/skribilo.scm
new file mode 100644
index 0000000..75ac3a2
--- /dev/null
+++ b/doc/skribilo.scm
@@ -0,0 +1,105 @@
+;;; tissue --- Text based issue tracker
+;;; Copyright © 2022 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 (docstring-function-documentation
+            function-documentation))
+
+(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..41159ae
--- /dev/null
+++ b/doc/tissue.skb
@@ -0,0 +1,92 @@
+;;; tissue --- Text based issue tracker
+;;; Copyright © 2022 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]
+    (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.]))
+  (chapter :title [Gemtext markup for issues]
+    (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]
+    (section :title [Object and record 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]
+      (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]
+      [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]
+      [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)))))
diff --git a/tissue.scm b/tissue.scm
index f069c1e..da88795 100644
--- a/tissue.scm
+++ b/tissue.scm
@@ -16,6 +16,8 @@
                           (skribe-exporter "website/index.skb"))
                     (file "style.css"
                           (copier "website/style.css"))
+                    (file "manual/dev/en/index.html"
+                          (skribe-exporter "doc/tissue.skb"))
                     (append (map (lambda (font-file)
                                    (file (string-append "fonts/" font-file)
                                          (copier (string-append (getenv "GUIX_ENVIRONMENT")
diff --git a/tissue/tissue.scm b/tissue/tissue.scm
index 29f31ac..06fc020 100644
--- a/tissue/tissue.scm
+++ b/tissue/tissue.scm
@@ -115,7 +115,5 @@ document root and must begin with a @code{\"/\"}. If it is @code{#f},
 no stylesheet is used in the generated web pages.
 
 @var{web-files} is a list of @code{<file>} objects representing files to be
-written to the web output.
-
-All arguments to @code{tissue-configuration} are evaluated lazily."
+written to the web output."
    (make-tissue-configuration project aliases indexed-documents web-css web-files))