[groff] 01/01: New groff preprocessor for Perl parts in groff files.

[Bernd Warken]

bwarken pushed a commit to branch master
in repository groff.

commit 51476bee112778bd314d1a4c7a27fcd670434167
Author: Bernd Warken <address@hidden>
Date:   Wed Feb 26 02:33:05 2014 +0100

    New groff preprocessor for Perl parts in groff files.
---
 ChangeLog                  |    4 +
 Makefile.in                |   27 ++--
 contrib/gperl/ChangeLog    |   24 ++++
 contrib/gperl/Makefile.sub |   64 +++++++++
 contrib/gperl/gperl.man    |  310 ++++++++++++++++++++++++++++++++++++++++++++
 contrib/gperl/gperl.pl     |  222 +++++++++++++++++++++++++++++++
 6 files changed, 638 insertions(+), 13 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4f26218..75dc435 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2014-02-25  Bernd Warken  <address@hidden>
+
+       * contrib/gperl: New preprocessor for Perl parts in groff files.
+
 2014-02-15  Ingo Schwarze  <address@hidden>
 
        * tmac/groff_mdoc.man: Improve the manual page template.
diff --git a/Makefile.in b/Makefile.in
index a7f1b64..763516a 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -2,7 +2,7 @@
 #   Free Software Foundation, Inc.
 #      Written by James Clark (address@hidden)
 #
-# Last update: 30 Apr 2013
+# Last update: 25 Feb 2014
 # 
 # This file is part of groff.
 # 
@@ -624,25 +624,26 @@ ALLTTYDEVDIRS=\
 # `doc' must be processed before `contrib/pdfmark',
 # pdf stuff must be processed before `contrib/mom
 OTHERDIRS=\
-  man \
-  tmac \
-  src/utils/afmtodit \
-  src/roff/grog \
-  src/roff/nroff \
-  doc \
-  contrib/groff_filenames \
-  contrib/mm \
   contrib/chem \
-  contrib/pic2graph \
   contrib/eqn2graph \
+  contrib/gdiffmk \
+  contrib/glilypond \
+  contrib/gperl \
   contrib/grap2graph \
+  contrib/groff_filenames \
   contrib/groffer \
-  contrib/glilypond \
   contrib/hdtbl \
+  contrib/mm \
   contrib/pdfmark \
-  font/devpdf \
+  contrib/pic2graph \
   contrib/mom \
-  contrib/gdiffmk
+  doc \
+  font/devpdf \
+  man \
+  src/utils/afmtodit \
+  src/roff/grog \
+  src/roff/nroff \
+  tmac
 
 # OTHERDIRS is handled specially in the `$(TARGETS)' rule to avoid
 # dependency problems with parallel builds.
diff --git a/contrib/gperl/ChangeLog b/contrib/gperl/ChangeLog
new file mode 100644
index 0000000..f2c9c66
--- /dev/null
+++ b/contrib/gperl/ChangeLog
@@ -0,0 +1,24 @@
+2014-02-25  Bernd Warken  <address@hidden>
+
+       * gperl.pl, gperl.man, ChangeLog, Makefile.sub: first version 1.0
+
+2014-02-25  Bernd Warken  <address@hidden>
+________________________________________________________________
+License
+
+Copyright (C) 2014
+       Free Software Foundation, Inc.
+Written by Bernd Warken <address@hidden>.
+
+Copying and distribution of this file, with or without
+modification, are permitted provided the copyright notice and this
+notice are preserved.
+
+This file is part of `gperl', which is part of the `groff'
+project.
+
+####### Emacs settings
+
+Local Variables:
+mode: change-log
+End:
diff --git a/contrib/gperl/Makefile.sub b/contrib/gperl/Makefile.sub
new file mode 100644
index 0000000..02f24f4
--- /dev/null
+++ b/contrib/gperl/Makefile.sub
@@ -0,0 +1,64 @@
+# Makefile.sub for `gperl' (preprocessor for added Perl parts)
+
+# File position: <groff-source>/contrib/gperl/Makefile.sub
+
+# Copyright (C) 2014
+#   Free Software Foundation, Inc.
+# Written by Bernd Warken <address@hidden>.
+
+# Last update: 25 Feb 2014
+
+# This file is part of `gperl' which is part of `groff'.
+
+# `groff' is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+
+# `groff' is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see
+# <http://www.gnu.org/licenses/gpl-2.0.html>.
+
+########################################################################
+
+MAN1=gperl.n
+
+MOSTLYCLEANADD=gperl $(MAN1)
+
+# not all make programs have $(RM) predefined.
+RM=rm -f
+
+all: gperl
+
+gperl: gperl.pl
+       sed -f "$(SH_DEPS_SED_SCRIPT)" \
+            -e "s|@g@|$(g)|g" \
+           -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
+           -e "s|@VERSION@|$(version)$(revision)|g" \
+           -e "$(SH_SCRIPT_SED_CMD)" \
+           $(srcdir)/gperl.pl >$@; \
+       chmod +x $@
+
+.PHONY: install_data
+install_data: gperl
+       -test -d $(DESTDIR)$(bindir) || $(mkinstalldirs) $(DESTDIR)$(bindir)
+       $(RM) $(DESTDIR)$(bindir)/gperl
+       $(INSTALL_SCRIPT) gperl $(DESTDIR)$(bindir)/gperl
+
+.PHONY: uninstall_sub
+uninstall_sub:
+       $(RM) $(DESTDIR)$(bindir)/gperl
+
+
+########################################################################
+# Emacs settings
+########################################################################
+#
+# Local Variables:
+# mode: makefile
+# End:
diff --git a/contrib/gperl/gperl.man b/contrib/gperl/gperl.man
new file mode 100644
index 0000000..52431cc
--- /dev/null
+++ b/contrib/gperl/gperl.man
@@ -0,0 +1,310 @@
+.TH GPERL @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
+gperl \- groff preprocessor for Perl parts in roff files
+.
+.SH "SYNOPSIS"
+.\" The .SH was moved to this place in order to appease `apropos'.
+.
+.\" --------------------------------------------------------------------
+.\" Legalese
+.\" --------------------------------------------------------------------
+.
+.de author
+This file was written by Bernd Warken <address@hidden>.
+..
+.
+.de co
+Copyright (C) 2014 Free Software Foundation, Inc.
+.
+.P
+This file is part of
+.IR \%gperl ,
+which is part of
+.IR \%groff ,
+a free software project.
+.
+You can redistribute it and/or modify it under the terms of the
+.nh
+.B "GNU General Public License"
+.hy
+as published by the
+.nh
+.BR "Free Software Foundation" ,
+.hy
+version\~2.
+.
+.P
+The license text is available in the internet at
+.UR http://www.gnu.org/licenses/gpl-2.0.html
+.UE .
+..
+.
+.\" --------------------------------------------------------------------
+.\" Setup
+.\" --------------------------------------------------------------------
+.
+.ds Ellipsis "\&.\|.\|.\&\"
+.
+.\" --------------------------------------------------------------------
+.\" Macro definitions
+.
+.\" --------------------------------------------------------------------
+.\" .CB  (<text>...)
+.\"
+.\" Print in constant-width bold font.
+.\"
+.de CB
+.  ft CB
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .CI  (<text>...)
+.\"
+.\" Print in constant-width italic font.
+.\"
+.de CI
+.  ft CI
+.  Text \\$*
+.  ft
+..
+.\" --------------------------------------------------------------------
+.\" .CR  (<text>...)
+.\"
+.\" Print in constant-width roman font.
+.\"
+.de CR
+.  ft CR
+.  Text \\$*
+.  ft
+..
+.\" End of macro definitions
+.
+.
+.\" --------------------------------------------------------------------
+.\" SH "SYNOPSIS"
+.\" --------------------------------------------------------------------
+.
+.SY gperl
+.OP option \*[Ellipsis]
+.OP --
+.OP \%filespec \*[Ellipsis]
+.YS
+.
+.SY gperl
+.BR -h | --help
+.YS
+.
+.SY gperl
+.BR -v | --version
+.YS
+.
+.
+.\" --------------------------------------------------------------------
+.SH DESCRIPTION
+.\" --------------------------------------------------------------------
+.
+This is a preprocesor for
+.BR \%groff (@MAN1EXT@).
+.
+It allows to add
+.BR perl (7)
+code into
+.BR groff (7)
+files.
+.
+The result of a
+.I Perl part
+can be stored in
+.I roff
+strings
+.RB ( .ds )
+or numerical registers
+.RB ( .rn ).
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OPTION OVERVIEW"
+.\" --------------------------------------------------------------------
+.
+.TP
+.I breaking options
+.RS
+.P
+.SY
+.OP -h\~\fR|\fB\~--help
+.OP -v\~\fR|\fB\~--version
+.YS
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "OPTION DETAILS"
+.\" --------------------------------------------------------------------
+.
+As soon as one of these options is found on the command line it is
+executed, printed to standard output, and the running
+.B \%gperl
+preprocessor is finished thereafter.
+.
+All other arguments are ignored.
+.
+.
+.TP
+.B -h\~\fR|\fB\~--help
+Print help information with a short explanation of options to
+standard output.
+.
+.
+.TP
+.B -v\~\fR|\fB\~--version
+Print version information to standard output.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "PERL PARTS"
+.\" --------------------------------------------------------------------
+.
+.I Perl
+parts in
+.I groff files
+are created by the new command
+.BR .Perl .
+.
+.
+.P
+A
+.I Perl part
+is started either by the request
+.B .Perl
+wiothout arguments, or by a request that's has the term
+.B start
+as its first argument.
+.
+.
+.P
+All
+.B .Perl
+command lines with other arguments finish a running
+.IR "Perl part" .
+.
+So one can add arbitrary arguments for closing.
+.
+It would be reasonable to add the argument
+.BI stop ;
+that's possible, but not necessary.
+.
+.
+.P
+A useful feature is to store the standard output of a
+.I Perl part
+into a
+.I roff
+string or register.
+.
+Storable data can be reached by
+.I printing to standard output
+with the
+.I Perl
+command
+.BR print .
+.
+.
+.P
+Numerical output can be stored into a
+.IR "roff register" ,
+by adding the following 2 arguments to a
+.B .Perl
+stopping command line; the argument
+.B ds
+or
+.B .ds
+and a suitable variable name.
+.
+.
+.P
+String output can be stored into a
+.IR "roff string" ,
+by adding the following 2 arguments to a
+.B .Perl
+stopping command line; the argument
+.B nr
+or
+.B .nr
+and a suitable variable name.
+.
+.
+.P
+Other arguments in a
+.B .Perl
+command line are just ignored.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "EXAMPLE"
+.\" --------------------------------------------------------------------
+.
+A possible
+.I Perl part
+in a
+.I roff file
+could look like that:
+.RS
+.EX
+before
+.Perl start
+my $result = 'some data';
+print $result . \[rq]\[rs]n\[rq];
+.Perl stop .ds some_string 
+after
+.EE
+.RE
+.
+.
+.P
+This stores the result
+.B \[rq]some data\[rq]
+into the
+.I roff string
+called
+.BR some_string ,
+such that the following line is printed:
+.RS
+.EX
+\&.ds some_string some data
+.EE
+.RE
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SEE ALSO"
+.\" --------------------------------------------------------------------
+.
+.P
+.BR \%groff (@MAN1EXT@),
+.BR \%groff (@MAN7EXT@),
+.BR \%grog (@MAN1EXT@),
+.BR \%groffer (@MAN1EXT@),
+.BR \%perl (@MAN1EXT@),
+.BR \%perl (@MAN7EXT@).
+.
+.
+.\" --------------------------------------------------------------------
+.SH "AUTHOR"
+.\" --------------------------------------------------------------------
+.author
+.
+.
+.\" --------------------------------------------------------------------
+.SH "COPYING"
+.\" --------------------------------------------------------------------
+.co
+.
+.
+.\" --------------------------------------------------------------------
+.\" Emacs settings
+.\" --------------------------------------------------------------------
+.
+.\" Local Variables:
+.\" mode: nroff
+.\" End:
diff --git a/contrib/gperl/gperl.pl b/contrib/gperl/gperl.pl
new file mode 100755
index 0000000..83c6821
--- /dev/null
+++ b/contrib/gperl/gperl.pl
@@ -0,0 +1,222 @@
+#! /usr/bin/env perl
+
+# gperl - add Perl part to groff files, this is the preprocessor for that
+
+# Source file position: <groff-source>/contrib/gperl/gperl.pl
+# Installed position: <prefix>/bin/gperl
+
+# Copyright (C) 2014
+#   Free Software Foundation, Inc.
+
+# Written by Bernd Warken <address@hidden>.
+
+# Last update: 25 Feb 2014
+my $version = '1.0';
+
+# This file is part of `gperl', which is part of `groff'.
+
+# `groff' is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 2 of the License, or
+# (at your option) any later version.
+
+# `groff' is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see
+# <http://www.gnu.org/licenses/gpl-2.0.html>.
+
+########################################################################
+
+use strict;
+use warnings;
+#use diagnostics;
+
+# temporary dir and files
+use File::Temp qw/ tempfile tempdir /;
+
+# needed for temporary dir
+use File::Spec;
+
+# for `copy' and `move'
+use File::Copy;
+
+# for fileparse, dirname and basename
+use File::Basename;
+
+# current working directory
+use Cwd;
+
+# $Bin is the directory where this script is located
+use FindBin;
+
+# for running perl scripts
+use IPC::System::Simple qw(system capture);
+
+
+########################################################################
+# system variables and exported variables
+########################################################################
+
+$\ = "\n";
+
+########################################################################
+# read-only variables with double-@ construct
+########################################################################
+
+our $File_split_env_sh;
+our $File_version_sh;
+our $Groff_Version;
+
+my $before_make;               # script before run of `make'
+{
+  my $at = '@';
+  $before_make = 1 if '@VERSION@' eq "${at}VERSION${at}";
+}
+
+my %at_at;
+my $file_perl_test_pl;
+my $groffer_libdir;
+
+if ($before_make) {
+  my $gperl_source_dir = $FindBin::Bin;
+  $at_at{'BINDIR'} = $gperl_source_dir;
+  $at_at{'G'} = '';
+} else {
+  $at_at{'BINDIR'} = '@BINDIR@';
+  $at_at{'G'} = '@g@';
+}
+
+
+########################################################################
+# options
+#######################################################################
+
+foreach (@ARGV) {
+  if ( /^(-h|--h|--he|--hel|--help)$/ ) {
+    print 'usage:';
+    print 'gperl [-h|--help]';
+    print 'gperl [-v|--version]';
+    exit;
+  } elsif ( /^(-v|--v|--ve|--ver|--vers|--versi|--versio|--version)$/ ) {
+    print 'gperl version ' . $version;
+    exit;
+  }
+}
+
+
+########################################################################
+# stdin
+#######################################################################
+
+my $perl_mode = 0;
+my $out_file = '/tmp/out';
+my %set_cmd;
+
+foreach (<STDIN>) {
+  chomp;
+  if ( /^[.']\s*Perl\s?/ ) { # .Perl ...
+    my $res = &perl_request( $_ );
+
+    if ( $res eq '' ) {
+      print $_;
+      next;
+    }
+
+    if ( $res eq 'start' ) {
+      if ( $perl_mode ) {
+       # `.Perl start' is called twice, ignore
+      } else { # new Perl start
+       $perl_mode = 1;
+       open OUT, '>', $out_file;
+      }
+      next;
+    } elsif ( $res eq 'stop' ) {
+      close OUT;
+      $perl_mode = 0;
+      my $res = capture('perl',  $out_file);
+      print $set_cmd{'command'} . ' ' . $set_cmd{'var'} . ' ' . $res
+       if ( exists $set_cmd{'command'} );
+      %set_cmd = ();
+      next;
+    }
+  }
+
+  if ( $perl_mode ) {
+    print OUT $_;
+    next;
+  }
+
+  print $_;
+}
+
+
+########################################################################
+
+sub perl_request {
+  my $line = shift;
+  my @args = split /\s+/, $line;
+  my $is_ds = 0;
+  my $is_rn = 0;
+
+  # 3 results:
+  # '' : error
+  # 'start'
+  # 'stop'
+
+  # arg must be a command line starting with .Perl
+  return '' if ( $line !~ /^[.']\s*Perl/ );
+
+  # different numbers of arguments
+
+  shift @args; # ignore first argument `.Perl'
+
+  return 'start' if ( @args == 0 ); # `.Perl' without args
+  return 'start' if ( $args[0] eq 'start' );
+
+  # now everything means `stop', but only within Perl mode
+  return '' unless ( $perl_mode );
+
+  if ( $args[0] eq 'stop' ) {
+    shift @args; # remove `stop' arg
+  }
+
+  if ( @args <= 1 ) {
+    # ignore single arg, variable name for possible ds or rn is lacking
+    return 'stop';
+  }
+
+  # now >= 2 args for STDOUT result saving
+  if ( $args[0] =~ /^[.']?ds$/ ) {
+    $is_ds = 1;
+    %set_cmd = (
+          'command' => $args[0],
+          'var' => $args[1],
+         );
+  } elsif ( $args[0] =~ /^[.']?rn$/ ) {
+    $is_rn = 1;
+    %set_cmd = (
+          'command' => $args[0],
+          'var' => $args[1],
+         );
+  } else {
+    # ignore other args
+    return 'stop';
+  }
+
+  $set_cmd{'command'} = '.' . $set_cmd{'command'}
+    if ( $set_cmd{'command'} !~ /^[.']/ );
+
+  return 'stop';
+}
+
+
+1;
+########################################################################
+### Emacs settings
+# Local Variables:
+# mode: CPerl
+# End: