aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2019-07-05 01:03:36 +0200
committerGuilhem Moulin <guilhem@fripost.org>2019-07-05 03:32:01 +0200
commit25f1dbdf54947bd6bbce653bc64f6c45b2473792 (patch)
treeeb5a21d1a528502845da6b987d4431bd04a4a5bd
parentc4abd6128c3ca5471afc84225533a958ce273875 (diff)
Refactor documentation.
In particular, move manpages to the 'doc' directory, and generate HTML documentation with `make html`.
-rw-r--r--.gitignore4
-rw-r--r--Changelog3
-rw-r--r--INSTALL31
-rw-r--r--Makefile34
-rw-r--r--README6
-rw-r--r--doc/build.md99
-rw-r--r--doc/development.md4
-rw-r--r--doc/index.md20
-rw-r--r--doc/interimap.1.md (renamed from interimap.md)0
-rw-r--r--doc/pullimap.1.md (renamed from pullimap.md)0
-rw-r--r--doc/template.html76
11 files changed, 232 insertions, 45 deletions
diff --git a/.gitignore b/.gitignore
index d0e940e..9dae7e6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
*~
-/*.1
+/doc/*.1
+/doc/*.html
+!/doc/template.html
/.pc/
diff --git a/Changelog b/Changelog
index 49f49d9..4cc66ba 100644
--- a/Changelog
+++ b/Changelog
@@ -19,6 +19,9 @@ interimap (0.5) upstream;
synchronization, for instance with the newly provided systemd
template unit file).
* Add a test-suite. (Requires dovecot-imapd, pkill(1) and xxd(1).)
+ * Completely refactor the documentation. In particular, move manpages
+ to a new 'doc' directory, and generate HTML documentation with `make
+ html`.
+ interimap: write which --target to use in --delete command
suggestions.
+ interimap: avoid caching hierarchy delimiters forever in the
diff --git a/INSTALL b/INSTALL
deleted file mode 100644
index 69afb26..0000000
--- a/INSTALL
+++ /dev/null
@@ -1,31 +0,0 @@
-InterIMAP depends on Perl >=5.20 and the following Perl modules:
-
- - Compress::Raw::Zlib (core module)
- - Config::Tiny
- - DBI
- - DBD::SQLite
- - Errno (core module)
- - Getopt::Long (core module)
- - MIME::Base64 (core module) if authentication is required
- - List::Util (core module)
- - Net::SSLeay >=1.73
- - POSIX (core module)
- - Socket (core module)
- - Time::HiRes (core module) if 'logfile' is set
-
-On Debian GNU/Linux systems, these modules can be installed with the
-following command:
-
- apt-get install libconfig-tiny-perl libdbi-perl libdbd-sqlite3-perl libnet-ssleay-perl
-
-However Debian GNU/Linux users can also use gbp(1) from git-buildpackage
-to build their own package:
-
- $ git checkout debian
- $ AUTO_DEBSIGN=no gbp buildpackage
-
-Alternatively, for the development version:
-
- $ git checkout debian
- $ git merge master
- $ AUTO_DEBSIGN=no gbp buildpackage --git-force-create --git-upstream-tree=BRANCH
diff --git a/Makefile b/Makefile
index b0e4d59..fda0fe0 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,11 @@
-all: pullimap.1 interimap.1
+all: manual
+
+MANUALS = $(patsubst %.md,%,$(wildcard ./doc/*.[1-9].md))
+manual: $(MANUALS)
# upper case the headers and remove the links
-%.1: %.md
- @pandoc -f markdown -t json "$<" | \
+$(MANUALS): %: %.md
+ @pandoc -f markdown -t json -- "$<" | \
jq " \
def fixheaders: \
if .t == \"Header\" then \
@@ -29,12 +32,29 @@ all: pullimap.1 interimap.1
}" | \
pandoc -s -f json -t man+smart -o "$@"
-install:
-
test:
@for t in tests/*; do if [ -f "$$t/run" ]; then ./tests/run "$$t" || exit 1; fi; done
+HTML_ROOTDIR ?= ./doc
+CSS ?= /usr/share/javascript/bootstrap/css/bootstrap.min.css
+HTML_TEMPLATE ?= ./doc/template.html
+
+HTML_FILES = $(addprefix $(HTML_ROOTDIR)/,$(patsubst ./doc/%.md,%.html,$(wildcard ./doc/*.md)))
+html: $(HTML_FILES)
+
+## CSS="https://guilhem.org/static/css/bootstrap.min.css" HTML_ROOTDIR="$XDG_RUNTIME_DIR/Downloads" make html
+$(HTML_ROOTDIR)/%.html: ./doc/%.md $(HTML_TEMPLATE)
+ mtime="$$(git --no-pager log -1 --pretty="format:%ct" -- "$<" 2>/dev/null)"; \
+ [ -n "$$mtime" ] || mtime="$$(date +%s -r "$<")"; \
+ pandoc -sp -f markdown -t html+smart --css=$(CSS) --template=$(HTML_TEMPLATE) \
+ --variable=date:"$$(LC_TIME=C date +"Last modified on %a, %d %b %Y at %T %z" -d @"$$mtime")" \
+ --output="$@" -- "$<"
+
+doc: manual html
+
+install:
+
clean:
- rm -f pullimap.1 interimap.1
+ rm -f $(MANUALS) $(HTML_FILES)
-.PHONY: all install clean test
+.PHONY: all manual html doc test install clean
diff --git a/README b/README
index a930512..fbc4ed7 100644
--- a/README
+++ b/README
@@ -1,9 +1,7 @@
InterIMAP is a fast bidirectional synchronization program for QRESYNC-capable
IMAP4rev1 servers. PullIMAP retrieves messages a remote IMAP mailbox and
-deliver them to an SMTP session. Consult the manuals for more information.
-
- https://guilhem.org/man/interimap.1.html
- https://guilhem.org/man/pullimap.1.html
+deliver them to an SMTP session. Visit https://guilhem.org/interimap
+for more information.
_______________________________________________________________________
diff --git a/doc/build.md b/doc/build.md
new file mode 100644
index 0000000..38d1bfb
--- /dev/null
+++ b/doc/build.md
@@ -0,0 +1,99 @@
+% Build instructions
+% Guilhem Moulin <guilhem@fripost.org>
+
+On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)]
+is a single command away:
+
+ $ apt-get install interimap
+
+This document is for those who are running other systems, and/or who
+wish to install from [source](https://git.guilhem.org/interimap).
+
+
+Dependencies
+============
+
+[`interimap`(1)](interimap.1.html) depends on Perl ≥5.20 and the
+following Perl modules:
+
+ * [`Compress::Raw::Zlib`](https://perldoc.perl.org/Compress/Raw/Zlib.html) (*core module*)
+ * [`Config::Tiny`](https://metacpan.org/pod/Config::Tiny)
+ * [`DBI`](https://metacpan.org/pod/DBI)
+ * [`DBD::SQLite`](https://metacpan.org/pod/DBD::SQLite)
+ * [`Errno`](https://perldoc.perl.org/Errno.html) (*core module*)
+ * [`Getopt::Long`](https://perldoc.perl.org/Getopt/Long.html) (*core module*)
+ * [`MIME::Base64`](https://perldoc.perl.org/MIME/Base64.html) (*core module*) — if authentication is required
+ * [`List::Util`](https://perldoc.perl.org/List/Util.html) (*core module*)
+ * [`Net::SSLeay`](https://metacpan.org/pod/Net::SSLeay) ≥1.73
+ * [`POSIX`](https://perldoc.perl.org/POSIX.html) (*core module*)
+ * [`Socket`](https://perldoc.perl.org/Socket.html) (*core module*)
+ * [`Time::HiRes`](https://perldoc.perl.org/Time/HiRes.html) (*core module*) — if `logfile` is set
+
+On Debian GNU/Linux systems, the dependencies can be installed with the
+following command:
+
+ $ apt install libconfig-tiny-perl \
+ libdbi-perl \
+ libdbd-sqlite3-perl \
+ libnet-ssleay-perl
+
+Additional packages are required in order to run the test suite:
+
+ $ apt install dovecot-imapd procps sqlite3 xxd
+<!-- -->
+ $ make test
+
+
+Generate documentation
+======================
+
+Yet another set of packages is needed to generate the documentation:
+
+ $ apt install jq pandoc
+
+Run `` `make manual` `` (or just `` `make` ``) in order to generate the
+manpages. You'll find them at `doc/*.[1-9]`. Use for instance `` `man
+-l doc/interimap.1` `` in order to read your copy of the [`interimap`(1)]
+manpage.
+
+The HTML documentation can be built with `` `make html` ``. HTML files
+are generated alongside their Markdown source by default, but you can
+choose another target directory using the `HTML_ROOTDIR` environment
+variable (the value of which defaults to `./doc`). Moreover the
+[`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap) is
+needed by default for the local CSS file; this can be controlled with
+the `CSS` environment variable (the value of which defaults to
+`/usr/share/javascript/bootstrap/css/bootstrap.min.css`).
+
+For instance, use
+
+ $ CSS="https://guilhem.org/static/css/bootstrap.min.css" \
+ HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \
+ make html
+
+to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap`
+(which needs to exist) using a remote CSS file.
+
+The `doc` target generates all documentation, manpages as well as HTML
+pages.
+
+
+Build custom Debian package
+===========================
+
+Debian GNU/Linux users can also use [`gbp`(1)] from
+[`git-buildpackage`](https://tracker.debian.org/pkg/git-buildpackage) in
+order to build their own package:
+
+ $ git checkout debian
+ $ gbp buildpackage
+
+Alternatively, for the development version:
+
+ $ git checkout debian
+ $ git merge master
+ $ gbp buildpackage --git-force-create --git-upstream-tree=BRANCH
+
+
+[`interimap`(1)]: interimap.1.html
+[`gbp`(1)]: https://manpages.debian.org/git-buildpackage/gbp.1.en.html
diff --git a/doc/development.md b/doc/development.md
index 2cb1367..406207a 100644
--- a/doc/development.md
+++ b/doc/development.md
@@ -202,7 +202,7 @@ recursively remove the directory `$BASEDIR`.
[IMAP4rev1]: https://tools.ietf.org/html/rfc3501
-[`interimap`(1)]: https://guilhem.org/man/interimap.1.html
-[`pullimap`(1)]: https://guilhem.org/man/pullimap.1.html
+[`interimap`(1)]: interimap.1.html
+[`pullimap`(1)]: pullimap.1.html
[`doveadm`(1)]: https://wiki.dovecot.org/Tools/Doveadm
[`%`-variable]: https://wiki.dovecot.org/Variables
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..12de956
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,20 @@
+% [`interimap`(1)] and [`pullimap`(1)] documentation
+% Guilhem Moulin <guilhem@fripost.org>
+
+Manuals (HTML versions)
+-----------------------
+
+ * [`interimap`(1)] — Fast bidirectional synchronization for
+ QRESYNC-capable IMAP servers
+ * [`pullimap`(1)] — Pull mails from an IMAP mailbox and deliver them
+ to an SMTP session
+
+Resources for developers
+------------------------
+
+ * [Source-code repository](https://git.guilhem.org/interimap)
+ * [Build instructions](build.html)
+ * [Test environment setup](development.html)
+
+[`interimap`(1)]: interimap.1.html
+[`pullimap`(1)]: pullimap.1.html
diff --git a/interimap.md b/doc/interimap.1.md
index 387850a..387850a 100644
--- a/interimap.md
+++ b/doc/interimap.1.md
diff --git a/pullimap.md b/doc/pullimap.1.md
index 1b2e509..1b2e509 100644
--- a/pullimap.md
+++ b/doc/pullimap.1.md
diff --git a/doc/template.html b/doc/template.html
new file mode 100644
index 0000000..e17f0e3
--- /dev/null
+++ b/doc/template.html
@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$>
+<head>
+ <meta charset="utf-8" />
+ <meta name="generator" content="pandoc" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+$for(author-meta)$
+ <meta name="author" content="$author-meta$" />
+$endfor$
+$if(date-meta)$
+ <meta name="dcterms.date" content="$date-meta$" />
+$endif$
+$if(keywords)$
+ <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
+$endif$
+ <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
+ <style type="text/css">
+ code{white-space: pre-wrap;}
+ span.smallcaps{font-variant: small-caps;}
+ span.underline{text-decoration: underline;}
+ div.column{display: inline-block; vertical-align: top; width: 50%;}
+$if(quotes)$
+ q { quotes: "“" "”" "‘" "’"; }
+$endif$
+ </style>
+$if(highlighting-css)$
+ <style type="text/css">
+$highlighting-css$
+ </style>
+$endif$
+$for(css)$
+ <link rel="stylesheet" href="$css$" />
+$endfor$
+ <style type="text/css">
+ @media(max-width: 1440px) { .container{ max-width: 1080px; } }
+ @media(max-width: 1280px) { .container{ max-width: 960px; } }
+ @media(max-width: 1024px) { .container{ max-width: 768px; } }
+ </style>
+$if(math)$
+ $math$
+$endif$
+$for(header-includes)$
+ $header-includes$
+$endfor$
+</head>
+
+<body>
+$for(include-before)$
+$include-before$
+$endfor$
+<div class="container text-justify">
+ <div class="content">
+$if(title)$
+ <div class="page-header"><h1>$title$</h1></div>
+$endif$
+
+$body$
+ </div>
+
+ <footer>
+ <hr/>
+ <div class="row">
+ <div class="col-md-8 text-muted">
+$if(author)$
+ <a href="https://git.guilhem.org/interimap/plain/COPYING">&copy;</a>
+ $for(author)$$author$$sep$, $endfor$
+$endif$
+ </div>
+ <div class="col-md-4 text-muted text-right small">
+ $if(date)$$date$$endif$
+ </div>
+ </div>
+ </footer>
+</div>
+</body>
+</html>