From 4c9b1ef537d819e0d78cd0c152fd16cab1be6e67 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Tue, 24 Nov 2020 11:16:32 +0100 Subject: improve title --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9eb91a0..5f95f27 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,3 @@ -# System features +# Documentation of system features _(features)_ This is documentation for system features at {{organisation}}. -- cgit v1.2.3 From c5c68e81fa126fbb2dc548148b31d92ba56c6ada Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Sun, 4 Apr 2021 20:24:56 +0200 Subject: handle eventhost --- Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 27aa983..7438af3 100644 --- a/Makefile +++ b/Makefile @@ -3,6 +3,7 @@ -include site.mk domain ?= example.org +eventhost ?= event.$(domain) shellhost ?= shell.$(domain) githost ?= source.$(domain) gitshellhost ?= $(shellhost) @@ -14,7 +15,7 @@ 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)", \ + domain => "$(domain)", eventhost => "$(eventhost)", shellhost => "$(shellhost)", githost => "$(githost)", gitshellhost => "$(gitshellhost)", \ matrixhost => "$(matrixhost)", \ organisation => "$(organisation)", contact_sysadmins => "$(contact_sysadmins)" })' -- cgit v1.2.3 From 7adafdcf74f57254991b07f0fef62d9e36a6a1bc Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 4 Jun 2021 10:28:06 +0200 Subject: git-ignore and distclean file site.mk --- .gitignore | 1 + Makefile | 1 + 2 files changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index ba27d5c..ef63da6 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ docs/ site/ source/ +site.mk diff --git a/Makefile b/Makefile index 7438af3..b20b315 100644 --- a/Makefile +++ b/Makefile @@ -55,5 +55,6 @@ clean: distclean: clean rm -rf source + rm -f site.mk .PHONY: all doc check clean distclean -- cgit v1.2.3 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 --- Makefile | 26 +++++++++++--------------- bin/mkdocs-prep.pl | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 15 deletions(-) create mode 100755 bin/mkdocs-prep.pl diff --git a/Makefile b/Makefile index b20b315..5ea53f1 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# Depends: myrepos git mkdocs w3c-linkchecker libtext-hogan-perl +# Depends: myrepos git mkdocs w3c-linkchecker libconfig-tiny-perl libpath-tiny-perl libtext-hogan-perl -include site.mk @@ -10,14 +10,9 @@ 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)", eventhost => "$(eventhost)", shellhost => "$(shellhost)", githost => "$(githost)", gitshellhost => "$(gitshellhost)", \ - matrixhost => "$(matrixhost)", \ - organisation => "$(organisation)", contact_sysadmins => "$(contact_sysadmins)" })' +MKDOCS_PREP ?= bin/mkdocs-prep.pl all: doc @@ -31,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 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(-) 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(-) 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(-) 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(-) 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 856e400959e26092df3279baf690075647fd75d8 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Fri, 4 Jun 2021 16:16:59 +0200 Subject: fix stop git-ignore site.mk --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index ef63da6..ba27d5c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,3 @@ docs/ site/ source/ -site.mk -- 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(-) 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