From cf451c90a160d8764b5e8ff6b0c1c10d038e59a1 Mon Sep 17 00:00:00 2001
Message-Id: <cf451c90a160d8764b5e8ff6b0c1c10d038e59a1.1714965932.git.mdw@distorted.org.uk>
From: Mark Wooding <mdw@chiark.greenend.org.uk>
Date: Mon, 5 May 2008 11:24:21 +0100
Subject: [PATCH] Script to generate -man documentation for expansions from
 comments in source code.
Organization: Straylight/Edgeware

From: Richard Kettlewell <rjk@greenend.org.uk>

---
 scripts/Makefile.am |  2 +-
 scripts/macro-docs  | 51 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100755 scripts/macro-docs

diff --git a/scripts/Makefile.am b/scripts/Makefile.am
index 620c8f4..81574db 100644
--- a/scripts/Makefile.am
+++ b/scripts/Makefile.am
@@ -26,6 +26,6 @@ SEDFILES=setup teardown
 include ${top_srcdir}/scripts/sedfiles.make
 
 EXTRA_DIST=htmlman sedfiles.make text2c oggrename make-unidata \
-	format-gcov-report make-version-string setup.in teardown.in
+	format-gcov-report make-version-string setup.in teardown.in macro-docs
 
 CLEANFILES=$(SEDFILES)
diff --git a/scripts/macro-docs b/scripts/macro-docs
new file mode 100755
index 0000000..46b2a6e
--- /dev/null
+++ b/scripts/macro-docs
@@ -0,0 +1,51 @@
+#! /usr/bin/perl -w
+use strict;
+
+my %macros = ();
+my $name;
+my $docs;
+while(defined($_ = <>)) {
+  chomp;
+  if(!defined $name and m,^/\* (\@([a-z\-]+).*),) {
+    $name = $2;
+    my $heading = $1;
+    $docs = [$heading];
+    $macros{$name} = $docs;
+    next;
+  }
+  if(defined $name) {
+    # Identify and strip trailing */
+    my $last = m,\*/ *$,;
+    s,\*/ *$,,;
+    # Strip trailing spaces
+    s,\s*$,,;
+    # Strip leading comment indicator and spaces
+    s,^ *\* *,,;
+    push(@$docs, $_);
+    undef $name if $last;
+  }
+}
+
+# Generate docs in name order
+for my $m (sort keys %macros) {
+  my @docs = @{$macros{$m}};
+  my $heading = shift @docs;
+  # Strip leading and trailing blanks
+  while(@docs > 0 and $docs[0] eq '') {
+    shift @docs;
+  }
+  while(@docs > 0 and $docs[$#docs] eq '') {
+    pop @docs;
+  }
+  print ".TP\n";
+  print ".B $heading\n";
+  for my $d (@docs) {
+    if($d eq '') {
+      print ".PP\n";
+    } else {
+      # Keep sentence-ending full stops at end of line
+      $d =~ s/\.  /\.\n/g;
+      print "$d\n";
+    }
+  }
+}
-- 
[mdw]