From 1e8aebe4fee30c4c7e5c051581240f4857a8818f Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Fri, 4 Jun 2021 13:00:16 +0200
Subject: support inline variable hints in documents, and use it for README

---
 README.md          | 10 +++++++++-
 bin/mkdocs-prep.pl | 24 +++++++++++++++++++++---
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 5f95f27..2cdf9b1 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,11 @@
 # Documentation of system features _(features)_
 
-This is documentation for 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
index e510185..efa71fb 100755
--- a/bin/mkdocs-prep.pl
+++ b/bin/mkdocs-prep.pl
@@ -1,5 +1,6 @@
 #!/usr/bin/perl
 
+use v5.18; # needed for \h (horizontal whitespace) in regexes
 use strict;
 use warnings;
 use autodie;
@@ -10,11 +11,11 @@ use Text::Hogan::Compiler;
 
 =head1 NAME
 
-mkdocs-prep - mkdocs preprocessor expanding mustache tokens
+mkdocs-prep - mkdocs preprocessor expanding inline hints and mustache tokens
 
 =head1 VERSION
 
-Version 0.01
+Version 0.02
 
 =head1 SYNOPSIS
 
@@ -22,9 +23,15 @@ Version 0.01
 
 B<mkdocs-prep> prepares a markdown document for B<mkdocs> processing.
 
-The document is treated as a mustache template
+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.
 
@@ -41,6 +48,17 @@ $config = Config::Tiny->read( 'site.mk', 'utf8' );
 
 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+(?:\h+\w+)*)/mg ) {
+	my $token  = $1;
+	my $string = $2;
+
+	$content =~ s/\Q$string\E/{{$token}}/g;
+};
+
+
 my $compiler = Text::Hogan::Compiler->new;
 my $template = $compiler->compile($content);
 
-- 
cgit v1.2.3