Author: Daniel Moch <firstname.lastname@example.org>
Date: Mon, 7 Sep 2020 05:49:19 -0400
README: A new vision for dag
|M||README|| | ||43||++++++-------------------------------------|
1 file changed, 6 insertions(+), 37 deletions(-)
diff --git a/README b/README
@@ -1,43 +1,12 @@
DAG - Djmoch's Automatic Generator
-The goal of dag(1) is to create a static site generator that's as
-Unixy as possible without feeling hacked together. After compilation,
-configuration happens entirely via the command line, and the intent
-is for the building to be orchestrated with a tool like make(1).
-The utility also outsources hard things to other tools, focusing
-on tools available in any POSIX operating system.
+usage: %s [-hv] [-Dname=value ...] [-m intype:outtype:xform ...]
+ in ... out
-- lowdown(1) is used to convert Markdown into HTML and roff_ms
+Dag copies file trees from the input directories to the output directory. Each -m flag specifies a transform, xform, to apply to files of intype to create files of outtype where both intype and outtype are file extensions. Each -D flag specifies a macro that will be passed into each transform (see Transforms section below).
-- groff(1) is used to convert roff_ms into PDF
-- m4(1) is used to process page headers, footers, and any other
- data built from a template
-The design is intended to make it trivial to swap in different tools,
-provided drivers are available.
-There are methods, documented (more or less), on using the tools
-above to generate a static website. Dag was created because these
-solutions have several drawbacks:
-- Short of dropping a Makefile in every source directory (which is
- honorous), it's not apparent to the author how best to avoid the
- problem of regenerating files unnecessarily. Dag is able to do this
-- Even if the above hurdle were overcome, make(1) would still need a
- helper tool to parse the post metadata at the beginning of each
- Markdown file. Once we've begun to write a tool for this, we may
- as well make our lives easier and avoid recusive make(1) while we're
- at it.
-- Generating indexes without a specialized tool to do so is cumbersome
- at best, and may not even be possible without using GNU extensions
- to m4(1).
- - See, for example, http://p.hagelb.org/Makefile.html. Phil boasts
-that his website is generated using nothing but m4(1) and the linked
-Makefile, although he admits that index generation is tricky (ed: and
-probably relies on GNU extensions)
+Dag was created to overcome some of the shortcomings of make(1).