From 25f1dbdf54947bd6bbce653bc64f6c45b2473792 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Fri, 5 Jul 2019 01:03:36 +0200 Subject: [PATCH] Refactor documentation. In particular, move manpages to the 'doc' directory, and generate HTML documentation with `make html`. --- .gitignore | 4 +- Changelog | 3 + INSTALL | 31 ---------- Makefile | 34 +++++++--- README | 6 +- doc/build.md | 99 ++++++++++++++++++++++++++++++ doc/development.md | 4 +- doc/index.md | 20 ++++++ interimap.md => doc/interimap.1.md | 0 pullimap.md => doc/pullimap.1.md | 0 doc/template.html | 76 +++++++++++++++++++++++ 11 files changed, 232 insertions(+), 45 deletions(-) delete mode 100644 INSTALL create mode 100644 doc/build.md create mode 100644 doc/index.md rename interimap.md => doc/interimap.1.md (100%) rename pullimap.md => doc/pullimap.1.md (100%) create mode 100644 doc/template.html 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 + +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 + +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 similarity index 100% rename from interimap.md rename to doc/interimap.1.md diff --git a/pullimap.md b/doc/pullimap.1.md similarity index 100% rename from pullimap.md rename to 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 @@ + + + + + + +$for(author-meta)$ + +$endfor$ +$if(date-meta)$ + +$endif$ +$if(keywords)$ + +$endif$ + $if(title-prefix)$$title-prefix$ – $endif$$pagetitle$ + +$if(highlighting-css)$ + +$endif$ +$for(css)$ + +$endfor$ + +$if(math)$ + $math$ +$endif$ +$for(header-includes)$ + $header-includes$ +$endfor$ + + + +$for(include-before)$ +$include-before$ +$endfor$ +
+
+$if(title)$ +

$title$

+$endif$ + +$body$ +
+ + +
+ + -- 2.39.2