summaryrefslogtreecommitdiff
path: root/Build/source
diff options
context:
space:
mode:
authorAndreas Scherer <andreas_tex@freenet.de>2023-06-16 01:56:32 +0000
committerAndreas Scherer <andreas_tex@freenet.de>2023-06-16 01:56:32 +0000
commitc273d25a15bfc5d43c31eae6b1cbd90147c05b07 (patch)
treeb9849f5b3ad09b436e0f175660884f7c7acb4c9e /Build/source
parentf1480d0f5fa8840746399afe8e480bb5df6214d9 (diff)
[CWEB] Flesh out 'proofsort' script.
* Rename to 'ctwill-proofsort'. * Support '--version' and '--help' options. * Add information in 'man ctwill'. git-svn-id: svn://tug.org/texlive/trunk@67380 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source')
-rw-r--r--Build/source/texk/web2c/cwebdir/ChangeLog4
-rwxr-xr-xBuild/source/texk/web2c/cwebdir/ctwill-proofsort115
-rwxr-xr-xBuild/source/texk/web2c/cwebdir/proofsort52
-rw-r--r--Build/source/texk/web2c/man/ChangeLog4
-rw-r--r--Build/source/texk/web2c/man/ctwill.man38
5 files changed, 151 insertions, 62 deletions
diff --git a/Build/source/texk/web2c/cwebdir/ChangeLog b/Build/source/texk/web2c/cwebdir/ChangeLog
index 512c97a0813..a54e117956d 100644
--- a/Build/source/texk/web2c/cwebdir/ChangeLog
+++ b/Build/source/texk/web2c/cwebdir/ChangeLog
@@ -1,3 +1,7 @@
+2023-06-16 Andreas Scherer <https://ascherer.github.io>
+
+ * ctwill-proofsort: Rename from 'proofsort'.
+
2023-06-14 Andreas Scherer <https://ascherer.github.io>
* ctproofmac.tex,
diff --git a/Build/source/texk/web2c/cwebdir/ctwill-proofsort b/Build/source/texk/web2c/cwebdir/ctwill-proofsort
new file mode 100755
index 00000000000..3146177f0c2
--- /dev/null
+++ b/Build/source/texk/web2c/cwebdir/ctwill-proofsort
@@ -0,0 +1,115 @@
+#!/usr/bin/env perl
+# Public domain. Originally written by Andreas Scherer, 2023.
+
+use strict;
+use warnings;
+
+use File::Basename;
+use Getopt::Long qw(:config no_ignore_case bundling);
+use Pod::Usage;
+
+# We expect a TeX file as the single command-line parameter.
+my $progname = basename $0;
+die "$progname input_file\n" unless scalar @ARGV;
+
+Getopt::Long::GetOptions(
+ 'help|?' => \&help_handler,
+ 'version' => sub { print version(); exit 0; }
+); # Getopt::Long::Getoptions()
+## help_handler()
+sub help_handler {
+ open(my $pipe, '|-', $ENV{PAGER} || 'less -e') or exit 1;
+ pod2usage(-message => version(), -output => $pipe,
+ -verbose => 99, -sections => "COPYRIGHT|SHORT DESCRIPTION|EXAMPLE");
+ close $pipe;
+ exit 0;
+}
+## version()
+sub version {
+ return "This is $progname (2023).\n";
+}
+
+my $tex = $ARGV[0];
+
+open(TEX, $tex) or die "$0: Could not open input file $tex.\n";
+
+my %mini_index; # storage for index entries of a section
+my $print_index = 0; # do we collect and print a mini-index?
+
+foreach my $line (<TEX>)
+{
+ if ("\\mini\n" eq $line) { # start of mini-index
+ $print_index = 1;
+ %mini_index = (); # reset mini-index
+ } elsif ("}\\FI\n" eq $line) { # end of mini-index
+ foreach my $key (sort {"\L$a" cmp "\L$b"} keys %mini_index) {
+ print $mini_index{$key};
+ }
+ $print_index = 0;
+ } elsif ($print_index) { # mini-index entry
+ my ($location,$key) = split / /, $line; # 2nd column is the key
+ $key =~ s/\\//g; # strip TeX escape(s)
+ $key =~ m/\w*\{(\w+)\}/; # extract plain key
+ $key =~ m/\$(\w+)\$/ unless defined $1; # extract @f TeX key
+ $mini_index{$1} = $line; # store index entry
+ next; # print later
+ }
+
+ print $line;
+}
+
+close(TEX);
+
+exit 0;
+
+=pod
+
+=encoding utf8
+
+=head1 NAME
+
+ctwill-proofsort — Sort mini-indexes alphabetically
+
+=head1 COPYRIGHT
+
+Public domain. Originally written by Andreas Scherer, 2023.
+
+=head1 SHORT DESCRIPTION
+
+This small Perl script 'ctwill-proofsort' sorts the mini-indexes for each
+section in the TeX file created by 'ctwill +P', i.e., prior to
+formatting with the 'ctproofmac.tex' macros.
+
+=over
+
+=item Run CTWILL twice on your CWEB program, creating 'texfile'.tex
+
+=item Invoke "ctwill-proofsort 'texfile'.tex > 'texfile'-sorted.tex"
+
+=item Invoke "mv 'texfile'-sorted.tex 'texfile'.tex"
+
+=item Run TeX on 'texfile'.tex
+
+=back
+
+See also "man ctwill" for more information on how to use the CTWILL system.
+
+=head1 EXAMPLE
+
+Example from MMIX (https://github.com/ascherer/mmix, 'local' branch):
+
+=over
+
+=item $ tie -c mmotype-twill.ch mmotype.{w,ch} mmotype-mini.ch
+
+=item $ ctwill +P -x mmotype mmotype-twill (run this two times)
+
+=item $ ctwill-proofsort mmotype.tex > mmotype-sorted.tex
+
+=item $ mv mmotype-sorted.tex mmotype.tex
+
+=item $ tex mmotype
+
+=back
+
+=cut
diff --git a/Build/source/texk/web2c/cwebdir/proofsort b/Build/source/texk/web2c/cwebdir/proofsort
deleted file mode 100755
index 4c349eece2a..00000000000
--- a/Build/source/texk/web2c/cwebdir/proofsort
+++ /dev/null
@@ -1,52 +0,0 @@
-#!/usr/bin/perl
-# This small Perl script 'proofsort' sorts the mini-indexes for each
-# section in the TeX file created by 'ctwill +P', i.e., prior to
-# formatting with the 'proofmac.tex' macros.
-#
-# Example from MMIX:
-# $ tie -c mmotype-twill.ch mmotype.{w,ch} mmotype-mini.ch
-# $ ctwill +P -x mmotype mmotype-twill (run this two times)
-# $ ./proofsort mmotype.tex > mmotype-sorted.tex
-# $ mv mmotype-sorted.tex mmotype.tex
-# $ tex mmotype
-#
-# Public domain. Originally written by Andreas Scherer, 2023.
-
-use strict;
-use warnings;
-
-# We expect a TeX file as the single command-line parameter.
-die "$0 input_file\n" unless scalar @ARGV;
-
-my $tex=$ARGV[0];
-
-open(TEX, $tex) or die "$0: Could not open input file $tex.\n";
-
-my %mini_index; # storage for index entries of a section
-my $print_index=0; # do we collect and print a mini-index?
-
-foreach my $line (<TEX>)
-{
- if ("\\mini\n" eq $line) { # start of mini-index
- $print_index=1;
- %mini_index=(); # reset mini-index
- } elsif ("}\\FI\n" eq $line) { # end of mini-index
- foreach my $key (sort {"\L$a" cmp "\L$b"} keys %mini_index) {
- print $mini_index{$key};
- }
- $print_index=0;
- } elsif ($print_index) { # mini-index entry
- my ($location,$key) = split / /, $line; # 2nd column is the key
- $key=~s/\\//g; # strip TeX escape(s)
- $key=~m/\w*\{(\w+)\}/; # extract plain key
- $key=~m/\$(\w+)\$/ unless defined $1; # extract @f TeX key
- $mini_index{$1}=$line; # store index entry
- next; # print later
- }
-
- print $line;
-}
-
-close(TEX);
-
-exit 0;
diff --git a/Build/source/texk/web2c/man/ChangeLog b/Build/source/texk/web2c/man/ChangeLog
index 2602ea496dc..84df823ac4b 100644
--- a/Build/source/texk/web2c/man/ChangeLog
+++ b/Build/source/texk/web2c/man/ChangeLog
@@ -1,3 +1,7 @@
+2023-06-16 Andreas Scherer <https://ascherer.github.io>
+
+ * ctwill.man: Add information on 'ctwill-proofsort'.
+
2023-05-15 Andreas Scherer <https://ascherer.github.io>
* ctwill.man: CWEB 4.9 release.
diff --git a/Build/source/texk/web2c/man/ctwill.man b/Build/source/texk/web2c/man/ctwill.man
index 46b710a0f04..5d6a1293c42 100644
--- a/Build/source/texk/web2c/man/ctwill.man
+++ b/Build/source/texk/web2c/man/ctwill.man
@@ -14,11 +14,12 @@
. ftr VB CB
. ftr VBI CBI
.\}
-.TH "CTWILL" "1" "June 5, 2022" "Web2c @VERSION@" "General Commands Manual"
+.TH "CTWILL" "1" "June 16, 2023" "Web2c @VERSION@" "General Commands Manual"
.hy
.SH NAME
.PP
-ctwill, ctwill-refsort, ctwill-twinx - translate CWEB to TeX with mini-indexes
+ctwill, ctwill-proofsort, ctwill-refsort, ctwill-twinx - translate CWEB to TeX with
+mini-indexes
.SH SYNOPSIS
.PP
\f[B]ctwill\f[R] [\f[I]options\f[R]] \f[I]webfile\f[R][.w]
@@ -26,6 +27,10 @@ ctwill, ctwill-refsort, ctwill-twinx - translate CWEB to TeX with mini-indexes
.PD 0
.P
.PD
+\f[B]ctwill-proofsort\f[R] \f[I]texfile\f[R].tex > \f[I]texfile\f[R]-sorted.tex
+.PD 0
+.P
+.PD
\f[B]ctwill-refsort\f[R] < \f[I]indexfile\f[R].ref > \f[I]indexfile\f[R].sref
.PD 0
.P
@@ -110,15 +115,27 @@ in braces), a section number (followed by space), and a TeX\ part.
A special \f[I]proofmode\f[R] is provided so that you can check
\f[B]ctwill\f[R]\[cq]s conclusions about cross-references.
Run \f[B]ctwill\f[R] with the flag \f[B]+P\f[R], and TeX will produce a
-specially formatted document (\f[I]without\f[R] mini-indexes) in which
+specially formatted document with mini-indexes for each section, so that
you can check that your specifications are correct.
.PP
+This \f[I]proofmode\f[R] format is used in conjunction with
+\f[B]pdfctproofmac.tex\f[R] that creates active hyperlinks in PDF and HINT
+output.
+You can use \f[B]ctwill-proofsort\f[R] to get the index entries in alphabetical
+order; just invoke
+.IP \[bu] 2
+\f[B]ctwill-proofsort\f[R] \f[I]texfile\f[R].tex > \f[I]texfile\f[R]-sorted.tex
+.IP \[bu] 2
+\f[B]mv\f[R] \f[I]texfile\f[R]-sorted.tex \f[I]texfile\f[R].tex
+.PP
+after invoking \f[B]ctwill\f[R] (twice), but before invoking TeX (once).
+.PP
More details how to use \f[B]ctwill\f[R] can be found in the first
sections of its source code, respectively the change file
\f[B]cweav-twill.ch\f[R] applicable to the \f[B]cweave.w\f[R] source.
A complete example with all bells and whistles is described in
\f[B]Mini-Indexes for Literate Programs\f[R], pages 225\[en]245 of
-Knuth\[cq]s \f[B]Digital Typography\f[R].
+Knuth\[cq]s \f[B]Digital Typography\f[R] (\f[I]CSLI\f[R], 1999).
.SH DIFFERENCES TO ORIGINAL CTWILL
.PP
The present incarnation of \f[B]ctwill\f[R] and its utilities tries hard
@@ -139,8 +156,8 @@ Option \f[B]+lX\f[R] is accompanied by example wrapper files for
captions for German (\f[B]+ld\f[R]).
.IP \[bu] 2
Option \f[B]+lX\f[R] is also accompanied by an extended
-\f[B]pdfctwimac.tex\f[R] for production of PDF output with active
-hyperlinks (\f[B]+lpdf\f[R]).
+\f[B]pdfctwimac.tex\f[R] for production of PDF and HINT output with
+active hyperlinks (\f[B]+lpdf\f[R]).
.IP \[bu] 2
\f[B]ctwill\f[R] in TeX\ Live operates silently by default; use the
\f[B]--verbose\f[R] option to get the original behavior.
@@ -232,8 +249,9 @@ In both cases you can request some prefix \f[I]X\f[R] with the
dctwimac.tex\f[R] and \f[B]+Pld\f[R] will \f[B]\[rs]input
dctproofmac.tex\f[R].
A special application is the use of option \f[B]+lpdf\f[R] that will
-\f[B]\[rs]input pdfctwimac.tex\f[R] for production of PDF output with
-active hyperlinks.
+\f[B]\[rs]input pdfctwimac.tex\f[R] or \f[B]\[rs]input
+pdfctproofmac.tex\f[R] for production of PDF and HINT output with active
+hyperlinks.
.IP \[bu] 2
\f[I]webfile\f[R]\f[B].bux\f[R]: Reference definitions to resolve from
other modules.
@@ -254,9 +272,9 @@ Silvio Levy (hardcopy version of \f[B]cwebman.tex\f[R] and the source
code listings of \f[B]common.w\f[R], \f[B]ctangle.w\f[R], and
\f[B]cweave.w\f[R]).
.IP \[bu] 2
-Digital Typography: by D.\ E.\ Knuth.
+Digital Typography: by D.\ E.\ Knuth (\f[I]CSLI\f[R], 1999).
.IP \[bu] 2
-Literate Programming: by D.\ E.\ Knuth.
+Literate Programming: by D.\ E.\ Knuth (\f[I]CSLI\f[R], 1992).
.IP \[bu] 2
Weaving a Program: by Wayne Sewell.
.PP