From 833eed5c6ac230dc559377d3a6cdb87d68e417e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20Ankarstr=C3=B6m?= <john@ankarstrom.se>
Date: Thu, 22 Jul 2021 12:12:33 +0200
Subject: fref.t: Add Perl script for arranging references

---
 example.t |  5 -----
 fref.t    | 34 ++++++++++++++++++++++++++--------
 2 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/example.t b/example.t
index e651a7d..d282c61 100644
--- a/example.t
+++ b/example.t
@@ -1,8 +1,3 @@
-.\" $ export LC_ALL=en_US.UTF-8
-.\" $ ./fref <example.t | troff -ms | dpost | ps2pdf - >example.pdf
-.\" % fref
-.SH
-References
 .XP
 %au	Baudouin de Courtenay, J.
 %da	1972
diff --git a/fref.t b/fref.t
index 15708df..f910a40 100644
--- a/fref.t
+++ b/fref.t
@@ -127,7 +127,7 @@ The language (English by default) is controlled with the \fI-l\fP flag:
 .br
 .ne 2i
 .SH
-Example
+Examples
 .PP
 The reference listed earlier is rendered thus:
 .br
@@ -148,7 +148,8 @@ The reference listed earlier is rendered thus:
 The above reference was generated by processing the document's
 source code with \fIfref\fP before passing it to \fItroff\fP:
 .IP
-$ <fref.t fref | troff | dpost | ps2pdf - >fref.pdf
+.nf
+$ <fref.t fref | troff -ms | dpost | ps2pdf ->fref.pdf
 .PP
 Note that \fIfref\fP leaves the job of
 arranging the references alphabetically
@@ -156,11 +157,11 @@ to the document author.
 The benefit is that the author is free to put arbitrary troff requests
 between references.
 .PP
-It is also possible to the reference in a separate file,
+It is also possible to store references in a separate file,
 similarly to what is done with \fIrefer\fP,
 and process the file separately from the main document:
 .IP
-$ <refs.f fref >refs.t
+$ <refs fref >refs.t
 .PP
 The resulting file refs.t might be included in the main document like so:
 .IP
@@ -169,8 +170,23 @@ The resulting file refs.t might be included in the main document like so:
 References
 \&.so refs.t
 .PP
-If you do this, you may want to consider using the .blm request
-to automatically start a new extended paragraph before every reference:
+The benefit of keeping the references in a separate file is
+that you can automate their alphabetical ordering:
+.IP
+.nf
+#!/usr/bin/perl -n
+$i++ if /^[^%]/ and $e[$i] =~ /^%/m;
+$e[$i] .= $_;
+END { print for sort { f($a) cmp f($b) } @e }
+sub f {
+        return $1 if $_[0] =~ /^%la.(.)/m;
+        return $1 if $_[0] =~ /^%au.(.)/m;
+}
+.PP
+If you keep your references in a separate file,
+you may want to consider using the .blm request
+to automatically start a new extended paragraph
+before every reference:
 .IP
 .nf
 \&.SH
@@ -180,7 +196,9 @@ Reference
 \&.so refs.t
 \&.blm
 .PP
-This way, you can store your references in refs.f separated by a blank space.
+That said, the benefit of storing the references
+in the document source itself
+is that you don't run the risk of losing them.
 .br
 .ne 2i
 .SH
@@ -202,7 +220,7 @@ Used for the book in which an article is published.
 .IP %ci
 \fICity\fP.
 .IP %da
-\fIDate (year)\fP.
+\fIDate (usually the year)\fP.
 .IP %ed
 \fIEditor\fP.
 .IP %hr
-- 
cgit v1.2.3