From 25c32afaeec73beee2616b9f8e613efbf95d4404 Mon Sep 17 00:00:00 2001
From: Arun Isaac
Date: Mon, 10 Oct 2022 00:56:55 +0530
Subject: doc: Add documentation.

* doc/skribilo.scm, doc/tissue.skb: New files.
* tissue.scm (#:web-files): Add manual/dev/en/index.html.
---
 doc/tissue.skb | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 doc/tissue.skb

(limited to 'doc/tissue.skb')

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)))))
-- 
cgit v1.2.3