Changes to manual namings to standardise. Added script from M0AZM to

[spider.git] / sgml / commands2sgml.pl

diff --git a/sgml/commands2sgml.pl b/sgml/commands2sgml.pl
new file mode 100755 (executable)
index 0000000..98eaf3d
--- /dev/null
+++ b/sgml/commands2sgml.pl
@@ -0,0 +1,179 @@
+#!/usr/bin/perl -w
+
+# cat Commands_en.hlp | ./commands2sgml.pl <level> > commands.sgml
+# Level 0 is assumed by default.
+
+# This Perl may not be nice but it seems to work :)
+# This is supposed to take a spider command definition file and
+# convert it to SGML format suitable for inclusion in the spider manual.
+#
+# It is cunningly written with no language in mind, and should work for all
+# command files in whatever language.  
+#
+# I claim no suitability for purpose, and should this script mutate and eat
+# your children I'm afraid I'm not responsible.  Wild herds of rampaging
+# Taiwanese suicide squirrels attacking your rabbit are also not my fault.
+#
+# Ian (M0AZM) 20030210.
+
+print STDERR localtime() ." ($$) $0 Starting\n";
+
+use strict;
+
+# Bewitched, debugged and bewildered?
+my $DEBUG = 0 ;
+
+# SGML headers - use for debugging your SGML output :)
+my $HEADERS = 0 ;
+
+# Definitions of things....
+my $count = 0 ;
+my ($cmd, $line) ;
+my %help ;
+
+# Default output level
+my $level = 0 ;
+
+# Command line parameters
+if(my $var = shift(@ARGV))
+    {
+    $level = $var ;
+    }
+
+# Disable line buffering
+$| = 1 ;
+
+# SGML headers
+if($HEADERS)
+    {
+    print("<!doctype linuxdoc system>\n") ;
+    print("<article>\n") ;
+    print("<sect>\n") ;
+    }
+
+# Loop until EOF
+while(<>) 
+    {
+    # Ignore comments
+    if(m/^#/)
+        {
+        next;
+        }
+    
+    chomp $_;
+    
+    # Is this a command definition line?
+    # if(m/^=== ([\d])\^([\w,\W]*)\^([\w,\W]*)/)
+    if(m/^=== ([\d])\^(.*)\^(.*)/)
+        {
+        $count++ ;
+        
+        if($DEBUG)
+            {
+            print("Level       $1\n") ;
+            print("Command     $2\n") ;
+            print("Description $3\n") ;
+            next;
+            }
+
+        $cmd = $2 ;
+
+        $help{$cmd}{level} = $1 ;
+        $help{$cmd}{command} = $2 ;
+        $help{$cmd}{description} = $3 ;
+        }
+    # Not a command definition line - Carry On Appending(tm)....
+    else
+        {
+        $help{$cmd}{comment} .= $_ . "\n" ;
+        }
+    # print("$_\n") ;
+    }
+
+# Go through all of the records in the hash in order
+foreach $cmd (sort(keys %help))
+    {
+    # Level checking goes here.
+    if($help{$cmd}{level} > $level) { next ; }
+    
+    # Need to change characters that SGML doesn't like at this point.
+    # Perhaps we should use a function for each of these variables?
+    # Deal with < and >
+    $help{$cmd}{command} =~ s/</&lt;/g ;
+    $help{$cmd}{command} =~ s/>/&gt;/g ;
+    # Deal with [ and ]
+    $help{$cmd}{command} =~ s/\[/&lsqb;/g ;
+    $help{$cmd}{command} =~ s/\]/&rsqb;/g ;
+    # Change to lower case
+    $help{$cmd}{command} = lc($help{$cmd}{command}) ;
+
+    # Deal with < and >
+    $help{$cmd}{description} =~ s/</&lt;/g ;
+    $help{$cmd}{description} =~ s/>/&gt;/g ;
+
+    # Deal with < and >
+    if($help{$cmd}{comment})
+        {
+        $help{$cmd}{comment} =~ s/</&lt;/g ;
+        $help{$cmd}{comment} =~ s/>/&gt;/g ;
+        }
+
+    # Output the section details and command summary.
+    print("<sect1>$help{$cmd}{command}") ;
+    if($level > 0) { print(" ($help{$cmd}{level})") ; }
+    print("\n\n") ;
+    print("<P>\n") ;
+    print("<tt>\n") ;
+    print("<bf>$help{$cmd}{command}</bf> $help{$cmd}{description}\n") ;
+    print("</tt>\n") ;
+    print("\n") ;
+
+    # Output the command comments.
+    print("<P>\n") ;
+
+    # Loop through each line of the command comments.
+    # If the first character of the line is whitespace, then use tscreen
+    # Once a tscreen block has started, continue until the next blank line.
+    my $block = 0 ;
+
+    # Is the comment field blank?  Then trying to split will error - lets not.
+    if(!$help{$cmd}{comment})
+        {
+        next;
+        }
+
+    # Work through the comments line by line
+    foreach $line (split('\n', $help{$cmd}{comment}))
+        {
+        # Leading whitespace or not?
+        if($line =~ m/^\s+\S+/)
+            {
+            if(!$block) 
+                {
+                $block = 1 ;
+                print("<tscreen><verb>\n") ; 
+                }
+            }
+        else
+            {
+            if($block)
+                {
+                $block = 0 ;
+                print("</verb></tscreen>\n") ;
+                }
+            }
+        print("$line\n") ;
+        }
+    
+    # We fell out of the command comments still in a block - Ouch....
+    if($block)
+        {
+        print("</verb></tscreen>\n\n") ;
+        }
+    }
+
+print("</article>\n") ;
+
+# Is it 'cos we is dun ?
+print STDERR localtime()." ($$) $0 Exiting ($count read)\n" ;
+