From: Richard Kettlewell <rjk@greenend.org.uk>
Date: Mon, 5 May 2008 10:24:21 +0000 (+0100)
Subject: Script to generate -man documentation for expansions from comments in
X-Git-Tag: 4.0~76^2~49
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/commitdiff_plain/cf451c90a160d8764b5e8ff6b0c1c10d038e59a1?ds=sidebyside

Script to generate -man documentation for expansions from comments in
source code.
---

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";
+    }
+  }
+}