summaryrefslogtreecommitdiff
path: root/doc/tissue.skb
blob: 3c46c393cf6d547f5904b02e733748bda859bc86 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
;;; 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]
           :ident "chapter-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]
           :ident "chapter-gemtext-markup"
    (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]
           :ident "chapter-reference"
    (section :title [Object and record constructors]
             :ident "section-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]
             :ident "section-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]
             :ident "section-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]
             :ident "section-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)))))