diff options
| -rw-r--r-- | .gitignore | 4 | ||||
| -rw-r--r-- | Changelog | 3 | ||||
| -rw-r--r-- | INSTALL | 31 | ||||
| -rw-r--r-- | Makefile | 34 | ||||
| -rw-r--r-- | README | 6 | ||||
| -rw-r--r-- | doc/build.md | 99 | ||||
| -rw-r--r-- | doc/development.md | 4 | ||||
| -rw-r--r-- | doc/index.md | 20 | ||||
| -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.html | 76 |
11 files changed, 232 insertions, 45 deletions
@@ -1,3 +1,5 @@ *~ -/*.1 +/doc/*.1 +/doc/*.html +!/doc/template.html /.pc/ @@ -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 @@ -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 @@ -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">©</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> |