From 0518e8f506412510125eea8628572c13857673d0 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 4 Jun 2021 10:57:44 +0200 Subject: externalize script bin/mkdocs-prep.pl, and (if missing) auto-generate site.mk in build target --- bin/mkdocs-prep.pl | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100755 bin/mkdocs-prep.pl (limited to 'bin/mkdocs-prep.pl') diff --git a/bin/mkdocs-prep.pl b/bin/mkdocs-prep.pl new file mode 100755 index 0000000..e510185 --- /dev/null +++ b/bin/mkdocs-prep.pl @@ -0,0 +1,49 @@ +#!/usr/bin/perl + +use strict; +use warnings; +use autodie; +use List::Util qw(pairs); +use Config::Tiny; +use Path::Tiny; +use Text::Hogan::Compiler; + +=head1 NAME + +mkdocs-prep - mkdocs preprocessor expanding mustache tokens + +=head1 VERSION + +Version 0.01 + +=head1 SYNOPSIS + +=head1 DESCRIPTION + +B prepares a markdown document for B processing. + +The document is treated as a mustache template +and resolved using an external set of single-word tokens. + +Template tokens are gathered from external config file F, +where each line lists a token, an equals sign, and replacement string. + +Each token in the document, +wrapped with double curly brackets {{like_this}}, +is replaced (including brackets) with corresponding string. + +=cut + +my ( $infile, $outfile ) = @ARGV; + +my $config = Config::Tiny->new; +$config = Config::Tiny->read( 'site.mk', 'utf8' ); + +my $content = path($infile)->slurp_utf8; + +my $compiler = Text::Hogan::Compiler->new; +my $template = $compiler->compile($content); + +path($outfile)->spew_utf8( $template->render( $config->{_} ) ); + +1; -- cgit v1.2.3 From 1e8aebe4fee30c4c7e5c051581240f4857a8818f Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard 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(-) (limited to 'bin/mkdocs-prep.pl') 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 prepares a markdown document for B 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, 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 From 22faacd38476f7af50cdafc5584baf8fb971a4bc Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 4 Jun 2021 14:21:24 +0200 Subject: prompt for strings for inline defined tokens not defined in site.mk; thanks to Siri Reiter for the idea --- Makefile | 2 +- bin/mkdocs-prep.pl | 17 +++++++++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) (limited to 'bin/mkdocs-prep.pl') diff --git a/Makefile b/Makefile index 5ea53f1..90ccc60 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# Depends: myrepos git mkdocs w3c-linkchecker libconfig-tiny-perl libpath-tiny-perl libtext-hogan-perl +# Depends: myrepos git mkdocs w3c-linkchecker libconfig-tiny-perl libpath-tiny-perl libtext-hogan-perl libio-prompter-perl -include site.mk diff --git a/bin/mkdocs-prep.pl b/bin/mkdocs-prep.pl index efa71fb..96bba69 100755 --- a/bin/mkdocs-prep.pl +++ b/bin/mkdocs-prep.pl @@ -8,6 +8,7 @@ use List::Util qw(pairs); use Config::Tiny; use Path::Tiny; use Text::Hogan::Compiler; +use IO::Prompter; =head1 NAME @@ -35,6 +36,10 @@ wrapped with double curly brackets. Template tokens are gathered from external config file F, where each line lists a token, an equals sign, and replacement string. +Inline defined tokens not declared in F will be prompted for. +if a value is provided it will be used, and also saved in F. +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. @@ -42,9 +47,11 @@ is replaced (including brackets) with corresponding string. =cut my ( $infile, $outfile ) = @ARGV; +@ARGV = undef; my $config = Config::Tiny->new; $config = Config::Tiny->read( 'site.mk', 'utf8' ); +my $config_has_changed; my $content = path($infile)->slurp_utf8; @@ -55,6 +62,13 @@ while ( $section =~ /^(\w+)\h*:\h*(\w+(?:\h+\w+)*)/mg ) { my $token = $1; my $string = $2; + unless ( exists $config->{_}->{$1} ) { + $_ = prompt "Which string should replace token '$token'?"; + next unless $_; + $config->{_}->{$1} = $_; + $config_has_changed++; + } + $content =~ s/\Q$string\E/{{$token}}/g; }; @@ -64,4 +78,7 @@ my $template = $compiler->compile($content); path($outfile)->spew_utf8( $template->render( $config->{_} ) ); +$config->write( 'site.mk', 'utf8' ) + if $config_has_changed; + 1; -- cgit v1.2.3 From 37cebd9636d909cee6369b9471a9ea8703fbe167 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 4 Jun 2021 14:43:53 +0200 Subject: fix handle missing configfile --- bin/mkdocs-prep.pl | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'bin/mkdocs-prep.pl') diff --git a/bin/mkdocs-prep.pl b/bin/mkdocs-prep.pl index 96bba69..fdb4c30 100755 --- a/bin/mkdocs-prep.pl +++ b/bin/mkdocs-prep.pl @@ -49,8 +49,10 @@ is replaced (including brackets) with corresponding string. my ( $infile, $outfile ) = @ARGV; @ARGV = undef; -my $config = Config::Tiny->new; -$config = Config::Tiny->read( 'site.mk', 'utf8' ); +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; @@ -78,7 +80,8 @@ my $template = $compiler->compile($content); path($outfile)->spew_utf8( $template->render( $config->{_} ) ); -$config->write( 'site.mk', 'utf8' ) +$cfgfile->touch; +$config->write( $cfgfile, 'utf8' ) if $config_has_changed; 1; -- cgit v1.2.3 From 4cab562b2af2e436f9093d14153969639acf7e73 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 4 Jun 2021 16:15:33 +0200 Subject: fix relax inline hint parsing --- bin/mkdocs-prep.pl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'bin/mkdocs-prep.pl') diff --git a/bin/mkdocs-prep.pl b/bin/mkdocs-prep.pl index fdb4c30..e452e0b 100755 --- a/bin/mkdocs-prep.pl +++ b/bin/mkdocs-prep.pl @@ -60,7 +60,7 @@ 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 ) { +while ( $section =~ /^(\w+)\h*:\h*(\w\S*(?:\h+\S+)*)/mg ) { my $token = $1; my $string = $2; -- cgit v1.2.3 From d2679dcda9fcf6fe518d18befd4c7f146e7e5d51 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 4 Jun 2021 16:56:37 +0200 Subject: fix skip update site.mk unless values provided when prompted --- bin/mkdocs-prep.pl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'bin/mkdocs-prep.pl') diff --git a/bin/mkdocs-prep.pl b/bin/mkdocs-prep.pl index e452e0b..7d9b1d3 100755 --- a/bin/mkdocs-prep.pl +++ b/bin/mkdocs-prep.pl @@ -66,7 +66,7 @@ while ( $section =~ /^(\w+)\h*:\h*(\w\S*(?:\h+\S+)*)/mg ) { unless ( exists $config->{_}->{$1} ) { $_ = prompt "Which string should replace token '$token'?"; - next unless $_; + next unless length $_; $config->{_}->{$1} = $_; $config_has_changed++; } -- cgit v1.2.3