The new m4manpages, m4webmanpages targets generate nroff and markdown
man pages via an alternate, excitingly complicated process, involving
shake, hakyll, pandoc *and* m4. Currently just the hledger man page is
processed this way, and the output (hledger/doc/m4-hledger.1,
site/m4-hledger.1.md) is equivalent to that of the non-m4 process.
Pro: selecting and massaging web/man content may be smoother with m4
than with pandoc filters. File inclusion allows documentation to be
broken up into chunks, which may be easier to edit, reorganize and
reuse. Macros could reduce boilerplate and enable more featureful and
attractive docs.
Con: the non-m4 process was simpler, easier to for contributors to
understand and working well enough. YAGNI.
Move to a newer stackage snapshot. This helps ensure a new-enough pandoc
will more be available for doc building without needing extra
compilation. Also we get to use the latest swagger and servant-swagger
for hledger-api, but we have to go to stackage nightly. With luck there
will be a lts 6 before next hledger release.
We now parse account directives, like Ledger's. We don't do anything
with them yet. The default parent account feature must now be spelled
"apply account"/"end apply account".
Since commit 7aab544, "-f -" before the command broke command
detection, causing spurious "no such option" errors (and breaking
about 70 functional tests which neither I nor travis noticed).
Eg drop the flaky github ones, and reduce layout popping by moving them
to the end of lines/sections and specifying image dimensions (requires
pandoc 1.16). The image widths can change, hopefully I've specified the
max width in each case.
- Docs are now collected on a single page
- Lots of copy updates
- The front page is less cluttered
- More whitespace at the sides
- The (still WIP) man pages are now linked
- Describe and link to plaintextaccounting.org
Goal:
Generate man pages and web docs from one source.
Current plan:
The master docs for each package are now the pandoc-style
manpage-markdown files in the package directories -
hledger/hledger.1.md, hledger-lib/hledger_journal.5.md, etc.
Parts of these will be marked as web-only, and parts as man-only, using
divs recognisable by custom pandoc filters.
When generating man pages we strip the web-only parts, and all html
blocks, inline html and hyperlinks.
When generating web docs we strip the man-only parts and apply any other
tweaks needed for easy presentation, perhaps combining them into a
single web page similar to the old user manual.
Shake:
This was hard to do with GNU Make, and so I've introduced Shake, which
is working very well. Both coexist for now but it's probably time to
switch.
