aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Makefile28
-rw-r--r--README.md10
-rwxr-xr-xbin/mkdocs-prep.pl87
3 files changed, 109 insertions, 16 deletions
diff --git a/Makefile b/Makefile
index 27aa983..90ccc60 100644
--- a/Makefile
+++ b/Makefile
@@ -1,22 +1,18 @@
-# Depends: myrepos git mkdocs w3c-linkchecker libtext-hogan-perl
+# Depends: myrepos git mkdocs w3c-linkchecker libconfig-tiny-perl libpath-tiny-perl libtext-hogan-perl libio-prompter-perl
-include site.mk
domain ?= example.org
+eventhost ?= event.$(domain)
shellhost ?= shell.$(domain)
githost ?= source.$(domain)
gitshellhost ?= $(shellhost)
matrixhost ?= matrix.$(domain)
organisation ?= Example orga
contact_sysadmins ?= contact sysadmins
+VARIABLES = domain eventhost shellhost githost gitshellhost matrixhost organisation contact_sysadmins
-MUSTACHE = cat source/source/USE.md | perl -MText::Hogan::Compiler -0777 -nE '\
- my $$compiler = Text::Hogan::Compiler->new;\
- my $$template = $$compiler->compile($$_);\
- say $$template->render({ \
- domain => "$(domain)", shellhost => "$(shellhost)", githost => "$(githost)", gitshellhost => "$(gitshellhost)", \
- matrixhost => "$(matrixhost)", \
- organisation => "$(organisation)", contact_sysadmins => "$(contact_sysadmins)" })'
+MKDOCS_PREP ?= bin/mkdocs-prep.pl
all: doc
@@ -30,23 +26,24 @@ check:
docs:
mkdir -p docs
find docs -type l -delete
- $(MUSTACHE) < README.md > docs/index.md
- $(MUSTACHE) < SETUP.md > docs/setup.md
+ $(MKDOCS_PREP) README.md docs/index.md
+ $(MKDOCS_PREP) SETUP.md docs/setup.md
docs/%: source
mkdir -p docs/$*
- $(MUSTACHE) < source/$(subst /,-,$*)/README.md > docs/$*/index.md
+ $(MKDOCS_PREP) source/$(subst /,-,$*)/README.md docs/$*/index.md
$(if $(wildcard source/$(subst /,-,$*)/USE.md),\
- $(MUSTACHE) < source/$(subst /,-,$*)/USE.md > docs/$*/use.md)
+ $(MKDOCS_PREP) source/$(subst /,-,$*)/USE.md docs/$*/use.md)
$(if $(wildcard source/$(subst /,-,$*)/ADMIN.md),\
- $(MUSTACHE) < source/$(subst /,-,$*)/ADMIN.md > docs/$*/admin.md)
+ $(MKDOCS_PREP) source/$(subst /,-,$*)/ADMIN.md docs/$*/admin.md)
$(if $(wildcard source/$(subst /,-,$*)/SETUP.md),\
- $(MUSTACHE) < source/$(subst /,-,$*)/SETUP.md > docs/$*/setup.md)
+ $(MKDOCS_PREP) source/$(subst /,-,$*)/SETUP.md docs/$*/setup.md)
$(if $(wildcard source/$(subst /,-,$*)/DEVELOP.md),\
- $(MUSTACHE) < source/$(subst /,-,$*)/DEVELOP.md > docs/$*/devel.md)
+ $(MKDOCS_PREP) source/$(subst /,-,$*)/DEVELOP.md docs/$*/devel.md)
init:
mr update
+ $(if $(wildcard site.mk),,$(foreach v,$(VARIABLES),echo $v = $($v) >> site.mk;))
clean:
rm -rf site
@@ -54,5 +51,6 @@ clean:
distclean: clean
rm -rf source
+ rm -f site.mk
.PHONY: all doc check clean distclean
diff --git a/README.md b/README.md
index a4f91df..2cdf9b1 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,11 @@
# Documentation of system features _(features)_
-This is documentation of system features at {{organisation}}.
+This is documentation for system features at Example orga.
+
+
+## Special strings
+
+NB! This documentation uses special strings
+which you may want to adapt for your local setup:
+
+organisation: Example orga
diff --git a/bin/mkdocs-prep.pl b/bin/mkdocs-prep.pl
new file mode 100755
index 0000000..7d9b1d3
--- /dev/null
+++ b/bin/mkdocs-prep.pl
@@ -0,0 +1,87 @@
+#!/usr/bin/perl
+
+use v5.18; # needed for \h (horizontal whitespace) in regexes
+use strict;
+use warnings;
+use autodie;
+use List::Util qw(pairs);
+use Config::Tiny;
+use Path::Tiny;
+use Text::Hogan::Compiler;
+use IO::Prompter;
+
+=head1 NAME
+
+mkdocs-prep - mkdocs preprocessor expanding inline hints and mustache tokens
+
+=head1 VERSION
+
+Version 0.02
+
+=head1 SYNOPSIS
+
+=head1 DESCRIPTION
+
+B<mkdocs-prep> prepares a markdown document for B<mkdocs> processing.
+
+The document is converted using inline hint section to a mustache template
+and resolved using an external set of single-word tokens.
+
+A document section named "Special strings" is parsed for token definitions
+where each line lists a single-word token, a colon, and default string.
+The section is then stripped,
+and all occurences of default strings are replaced with tokens
+wrapped with double curly brackets.
+
+Template tokens are gathered from external config file F<site.mk>,
+where each line lists a token, an equals sign, and replacement string.
+
+Inline defined tokens not declared in F<site.mk> will be prompted for.
+if a value is provided it will be used, and also saved in F<site.mk>.
+If no value is provided then inline default string is used.
+
+Each token in the document,
+wrapped with double curly brackets {{like_this}},
+is replaced (including brackets) with corresponding string.
+
+=cut
+
+my ( $infile, $outfile ) = @ARGV;
+@ARGV = undef;
+
+my $cfgfile = path('site.mk');
+my $config = $cfgfile->exists
+ ? Config::Tiny->read( $cfgfile, 'utf8' )
+ : Config::Tiny->new;
+my $config_has_changed;
+
+my $content = path($infile)->slurp_utf8;
+
+$content =~ s/^#+\s*Special strings\s*\n((?:\n|[^#\n][^\n]*\n)*)//m;
+my $section = $1 || '';
+my %defaults;
+while ( $section =~ /^(\w+)\h*:\h*(\w\S*(?:\h+\S+)*)/mg ) {
+ my $token = $1;
+ my $string = $2;
+
+ unless ( exists $config->{_}->{$1} ) {
+ $_ = prompt "Which string should replace token '$token'?";
+ next unless length $_;
+ $config->{_}->{$1} = $_;
+ $config_has_changed++;
+ }
+
+ $content =~ s/\Q$string\E/{{$token}}/g;
+};
+
+
+my $compiler = Text::Hogan::Compiler->new;
+my $template = $compiler->compile($content);
+
+path($outfile)->spew_utf8( $template->render( $config->{_} ) );
+
+$cfgfile->touch;
+$config->write( $cfgfile, 'utf8' )
+ if $config_has_changed;
+
+1;