dag

Djmoch's Auto Generator
git clone git://git.danielmoch.com/dag.git
Log | Files | Refs | README | LICENSE

commit 2692d7d79ccb9ec067f50866a035aa8591132b71
parent 8570aa8230cc9f06ac78e5fbb0763d6a76964c12
Author: Daniel Moch <daniel@danielmoch.com>
Date:   Tue, 23 Nov 2021 19:33:22 -0500

manpages and README documentation

Diffstat:
MMakefile | 6++++++
MREADME | 20++++++++++++++------
Mconfig.mk | 7-------
Adag.1 | 67+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Adagfile.5 | 117+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Adagindex.1 | 164+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6 files changed, 368 insertions(+), 13 deletions(-)

diff --git a/Makefile b/Makefile @@ -32,10 +32,16 @@ string_test: string_test.o string.o install: dag dagindex install -Dm755 dag ${DESTDIR}${PREFIX}/bin/dag install -Dm755 dagindex ${DESTDIR}${PREFIX}/bin/dagindex + install -Dm644 dag.1 ${DESTDIR}${MANPATH}/man1/dag.1 + install -Dm644 dagindex.1 ${DESTDIR}${MANPATH}/man1/dagindex.1 + install -Dm644 dagfile.5 ${DESTDIR}${MANPATH}/man5/dagfile.5 uninstall: rm -f ${DESTDIR}${PREFIX}/bin/dag rm -f ${DESTDIR}${PREFIX}/bin/dagindex + rm -f ${DESTDIR}${PREFIX}/man1/dag.1 + rm -f ${DESTDIR}${MANPATH}/man1/dagindex.1 + rm -f ${DESTDIR}${MANPATH}/man5/dagfile.5 clean: rm -f *.o dag dagindex *_test y.tab.* lex.yy.c diff --git a/README b/README @@ -8,18 +8,26 @@ directory. Before reaching their destination, files are filtered according to the rules declared in a file (default: Dagfile) in the working directory. -usage: dagindex -Vh - dagindex -A [-a author] [-c category] [-d description] - [-p date_published] [-s slug] [-t title] [-u date_updated] - dagindex -G -o fmt +uage: %dagindex-Vh\ + dagindex -A -t title -s slug -p date_published [-a author] + [-u date_updated] [-c category] [-d description] + dagindex -G -o fmt [-t title] [-f fqdn] [-d description] + [-r rss_url] [-l language] [-c copyright] Dagindex maintains a database of index entries and refers to the database in order to create index files. Index files can be either -HTML for XML formatted (for a landing page and RSS feed, respectively). -In generate mode (-G), output files are sent to stdout. +HTML for XML formatted (for a landing page and sitemap/RSS feed, +respectively). In generate mode (-G), output files are sent to +stdout. Intent ------ Dag, though perhaps reminiscent of make(1), is designed as a more targeted solution for generating static websites and the like. + +Maturity +-------- + +Dag is very alpha. The design and/or implementation is subject to +major overhaul without notice. diff --git a/config.mk b/config.mk @@ -1,13 +1,6 @@ # See LICENSE file for copyright and license details - -LOWDOWN := /usr/local/bin/lowdown -SASSC := /usr/local/bin/sassc -M4 := /usr/bin/m4 -TBL := /usr/local/bin/tbl - PREFIX := /usr/local MANPATH := ${PREFIX}/share/man -X11BASE := /usr/X11R6 HDRS = dagfile.h string.h y.tab.h DSRC = dag.c dagfile.c string.c y.tab.c lex.yy.c diff --git a/dag.1 b/dag.1 @@ -0,0 +1,67 @@ +.\" See LICENSE file for copyright and license details +.Dd 2021-11-23 +.Dt DAG 1 +.Os +.Sh NAME +.Nm dag +.Nd Djmoch's Auto Generator +.Sh SYNOPSIS +.Nm +.Op Fl Vhv +.Op Fl f Ar file +.Sh DESCRIPTION +.Nm +copies file trees from the input directories to the output +directory. +Before reaching their destination, files are filtered +according to the rules declared in a file (default: Dagfile, see +.Xr dagfile 5 ) +in the working directory. +.Pp +By design, and similar to +.Xr make 1 , +.Nm +does not generate files unless they are out of date with the source +file or any other required files. +(See +.Xr dagfile 5 +for a discussion of source and requirement files.) +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl V +Verbose mode. +Print debug information while running. +.It Fl h +Print usage and exit. +.It Fl v +Print version and exit. +.It Fl f Ar file +Change the name of the rules file from the default, Dagfile. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +Run +.Nm +in the current directory: +.Dl $ dag +.Pp +Run +.Nm +in the current directory, using a rules file named +.Pa rules.dag : +.Dl $ dag -f rules.dag +.Sh SEE ALSO +.Xr dagindex 1 +.Xr make 1 +.Xr dagfile 5 +.Sh HISTORY +.Nm +was conceived after a night spent wondering why everyone created +their own static site generators. +It is still unclear whether the author learned any valuable lessons. +.Sh AUTHORS +.Nm +was written by +.An Daniel Moch Aq Mt daniel@danielmoch.com . diff --git a/dagfile.5 b/dagfile.5 @@ -0,0 +1,117 @@ +.\" See LICENSE file for copyright and license details +.Dd 2021-11-23 +.Dt DAGFILE 5 +.Os +.Sh NAME +.Nm dagfile +.Nd Rules file for Djmoch's Auto Generator +.Sh DESCRIPTION +The +.Nm +is a companion file of +.Xr dag 1 +that specifies filters to execute when encountering a file with a +specified extension within a source directory. +Filters are applied in order, referring to the source file and any +other required files as necessary. +.Pp +A +.Nm +is structured hierarchically starting with a single target containing +one or more sources. +Targets and sources both refer to directories within the working +directory. +A +.Nm +can only contain one source. +.Pp +Within each source is one or more extensions defining file extensions +to search for within the source directory. +If a file within a source directory does not match any defined +extension, it is copied to the target directory and no filters are +applied. +.Pp +Each extension may contain one or more suffixes. +A suffix names what the file extension is converted to in the target +directory after the filters are applied. +.Pp +Each suffix contains a series of "require" and "filter" statements. +Require statements name files required by the extension's filters, +relative to the working directory. +Filters name commands to apply, in order, to convert the source +file to the target file. +.Pp +The target file is defined as the file specified by the suffix +statement. +Its full path is the path of the source file, relative to the source +directory, appended to the target directory, with the extension +converted into the suffix. +.Pp +The source, target, and requirement files can be referred to in a +filter statement by the following symbols. +.Bl -tag -width Ds +.It Ar $< +The source file path and name, relative to the working directory. +.It Ar $> +The target file path and name, relative to the working directory. +.It Ar $n +The requirement file specified by number +.Ar n . +The first "require" statement in the suffix block is referred to by +.Ar $1 , +the second by +.Ar $2 , +and so on. +.Sh EXAMPLES +The following +.Nm +will copy all of the files in directory src to directory target, +converting all files with an .md extension to .html files: +.Bd -literal -offset indent -compact +target "target" { + source "src" { + extension ".md" { + suffix ".html" { + filter "lowdown -sThtml $< >$>" + } + } + } +} +.Ed +.Pp +The same as above, but also place .pdf files alongside .html files +within directory target: +.Bd -literal -offset indent -compact +target "target" { + source "src" { + extension ".md" { + suffix ".html" { + filter "lowdown -sThtml $< >$>" + } + suffix ".pdf" { + filter "lowdown -Tms $< | pdfroff -itk -mspdf >$>" + } + } +} +.Ed +.Pp +The same as the first example, but wrap the generated .html files +with header and footer data provided by requirement files: +.Bd -literal -offset indent -compact +target "target" { + source "src" { + extension ".md" { + suffix ".html" { + require "templates/header.html" + require "templates/footer.html" + filter "cp $1 $>" + filter "lowdown -Thtml $< >>$>" + filter "cat $2 >>$>" + } + } + } +} +.Ed +.Sh SEE ALSO +.Xr dag 1 +.Xr dagfile 5 diff --git a/dagindex.1 b/dagindex.1 @@ -0,0 +1,164 @@ +.\" See LICENSE file for copyright and license details +.Dd 2021-11-23 +.Dt DAGINDEX 1 +.Os +.Sh NAME +.Nm dagindex +.Nd Index utility for Djmoch's Auto Generator +.Sh SYNOPSIS +.Nm +.Fl Vhv +.Nm +.Fl A +.Fl t Ar title +.Fl s Ar slug +.Fl p Ar date_published +.Op Fl a Ar author +.Op Fl u Ar date_updated +.Op Fl c Ar category +.Op Fl d Ar description +.Nm +.Fl G +.Fl o Ar fmt +.Op Fl t Ar title +.Op Fl f Ar fqdn +.Op Fl d Ar description +.Op Fl r Ar rss_url +.Op Fl l Ar language +.Op Fl c Ar copyright +.Sh DESCRIPTION +In append mode, +.Nm +maintains a database of index entries and refers to the database +in order to create index files. +Entries are considered to be unique based on their +.Ar slug . +If an existing entry is found in the database with the same slug +as that provided using the +.Fl s +flag, then the database entry is updated. +.Pp +In generate mode, formatted index files are sent to stdout. +Index files can be either HTML for XML formatted (see discussion +of the +.Fl o +option below). +.Pp +The mode of operation is specified with one of the following options: +.Bl -tag -width Ds +.It Fl A +Append mode. +Add an entry to the index database. +.It Fl G +Generate mode. +Consult the index database to print a formatted index file to stdout. +.El +.Pp +Append mode options: +.Bl -tag -width Ds +.It Fl t Ar title +Use +.Ar title +as the title of the entry to be added to the database. +.It Fl s Ar slug +Use +.Ar slug +as the slug of the entry to be added to the database. +.Nm +considers the slug to be everything that will appear after the +server name in the URL. +.It Fl p Ar date_published +Use +.Ar date_published +as the published date of the entry to be added to the database. +The argument may be specified as either a Unix timestamp or as a +string formatted as YYYY-MM-DD HH:MM:SS UTC[+-]hh:mm. +.It Fl a Ar author +Use +.Ar author +as the author of the entry to be added to the database. +.It Fl u Ar date_updated +Use +.Ar date_updated +as the updated date of the entry to be added to the database. +See the description of the +.Fl p +flag for the format of +.Ar date updated . +.It Fl c Ar category +Use +.Ar category +as the category of the entry to be added to the database. +.It Fl d Ar description +Use +.Ar description +as the description of the entry to be added to the database. +.El +.Pp +Generate mode options: +.Bl -tag -width Ds +.It Fl o Ar fmt +Specify the output mode +.Ar fmt . +This may be one of the following: +.Bl -tag -width Ds +.It Ar term +Print the database to stdout in a human-readable format. +.It Ar html +Print the database to stdout formatted as a series of HTML table +rows suitable for use as a blog index page. +.It Ar sitemapindex +Print the database to stdout formatted as a sitemapindex. +This option is deprecated and should not be used. +.It Ar sitemap +Print the database to stdout formatted as a sitemap. +.It Ar rss +Print the database to stdout formatted as an RSS feed. +.El +.It Fl t Ar title +Used when +.Ar fmt +is rss to specify the title of the channel. +.It Fl f Ar fqdn +Used when +.Ar fmt +is sitemapindex, sitemap, or rss to specify the server name of the +site. +.It Fl d Ar description +Used when +.Ar fmt +is rss to specify the description of the channel. +.It Fl r Ar rss_url +Used when +.Ar fmt +is rss to specify the URL at which the RSS feed may be found. +.It Fl l Ar language +Used when +.Ar fmt +is rss to specify to the language of the channel. +.It Fl c Ar copyright +Used when +.Ar fmt +is rss to specify the copyright information for the channel. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +Add an entry to the database, specifying the published date, +slug, and title: +.Dl $ dagindex -A -p1637706721 -s stuff.html -t Stuff +.Pp +Print a human-readable index to the terminal: +.Dl $ dagindex -G -o term +.Sh SEE ALSO +.Xr dag 1 +.Xr dagfile 5 +.Sh HISTORY +.Nm +was conceived after a night spent wondering why everyone created +their own static site generators. +It is still unclear whether the author learned any valuable lessons. +.Sh AUTHORS +.Nm +was written by +.An Daniel Moch Aq Mt daniel@danielmoch.com .