From 28b2728a3232741ab3e4ccc8ced585d75fffddb1 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 23 Feb 2022 19:54:31 +0100 Subject: Fix/improve doc/build.md. Update instructions/documentation obsolete since a1c089b997ebf705a9023b4f0f97327e5bd2814e and 733ed91162b02cd0fa5d7d1c443c780d3d4405e9. --- Makefile | 1 - doc/build.md | 36 +++++++++++++++--------------------- 2 files changed, 15 insertions(+), 22 deletions(-) diff --git a/Makefile b/Makefile index 0f1d7ea..0c01999 100644 --- a/Makefile +++ b/Makefile @@ -65,7 +65,6 @@ release: -- Changelog interimap pullimap lib/Net/IMAP/InterIMAP.pm && \ git -C $(srcdir) tag -sm "Release version $$VERS" "v$$VERS" -## `make html CSS="https://guilhem.org/static/css/bootstrap.min.css" builddir="$XDG_RUNTIME_DIR/Downloads/interimap"` $(HTML_FILES): $(builddir)/doc/%.html: $(srcdir)/doc/%.md $(HTML_TEMPLATE) @mkdir -vp $(dir $@) mtime="$$(git -C $(srcdir) --no-pager log -1 --pretty="format:%ct" -- "$<" 2>/dev/null)"; \ diff --git a/doc/build.md b/doc/build.md index 142097e..6c812dc 100644 --- a/doc/build.md +++ b/doc/build.md @@ -40,8 +40,8 @@ Additional packages are required in order to run the test suite: $ make check -(The test suite also needs to bind to TCP ports 10024, 10143 and 10993 -on the loopback interface.) +(Note also that the test suite needs to bind to TCP ports 10024, 10143 +and 10993 on the loopback interface.) Generate documentation ====================== @@ -51,29 +51,23 @@ Yet another set of packages is needed to generate the documentation: $ sudo 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. +manuals. You'll find them at `build/doc/*.[1-9]`. Then use for +instance `` `man -l build/doc/interimap.1` `` to read your local copy of +the [`interimap`(1)] manual. -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`). +The HTML documentation can be built with `` `make html` ``. By default +HTML files are generated at `build/doc/*.html`, and a local CSS file is +used — namely `/usr/share/javascript/bootstrap4/css/bootstrap.css`, +shipped the by [`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap) +package. But this is configurable: use for instance -For instance, use + $ make html builddir="$XDG_RUNTIME_DIR/interimap" \ + CSS="https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/css/bootstrap.min.css" - $ env CSS="https://guilhem.org/static/css/bootstrap.min.css" \ - HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \ - make html +to generate the HTML documentation under `$XDG_RUNTIME_DIR/interimap/doc` +using a remote CSS file. -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 +The `doc` target generates all documentation, manuals as well as HTML pages. -- cgit v1.2.3