Thread: [Plplot-cvs] SF.net SVN: plplot:[11482] trunk/doc/docbook/bin/api2swigdoc.pl

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 11482
          http://plplot.svn.sourceforge.net/plplot/?rev=11482&view=rev
Author:   airwin
Date:     2011-01-11 23:07:30 +0000 (Tue, 11 Jan 2011)

Log Message:
-----------
Initial commit of perl script which parses doc/docbook/src/api.xml to
generate one file in a form that should be parseable by swig to
provide documentation for swig-generated bindings from api.xml.

This perl script uses much of the code in api2text.xml to collect the
information from the xml input.  The essential changes here were to
transform that xml information into a form acceptable by swig, and
output all results into one file rather than a series of files.

Added Paths:
-----------
    trunk/doc/docbook/bin/api2swigdoc.pl

Added: trunk/doc/docbook/bin/api2swigdoc.pl
===================================================================

--- trunk/doc/docbook/bin/api2swigdoc.pl	                        (rev 0)
+++ trunk/doc/docbook/bin/api2swigdoc.pl	2011-01-11 23:07:30 UTC (rev 11482)
@@ -0,0 +1,221 @@
+#!/usr/bin/perl
+# File: api2man.pl
+# Description: Convert the PLplot API chapter (file api.xml of the DocBook
+#              manual) into a swig documentation file.
+# $Id: api2text.pl 11276 2010-10-27 01:39:26Z airwin $
+#
+# Copyright (C) 2000, 2003  Rafael Laboissiere
+# Copyright (C) 2010 Alan W. Irwin
+#
+# This script relies on the present structure of the API chapter (file
+# ../src/api.xml), where each API function is documented in its own
+# section.  Here is the typical structure of a section:
+#
+#   <sect1 id="NAME">
+#     <title><function>NAME</function>: DESCRIPTION</title>
+#
+#     <para>
+#       <funcsynopsis>
+#       <funcprototype>
+# 	<funcdef>
+# 	  <function>NAME</function>
+# 	</funcdef>
+#         <paramdef><parameter>ARG1</parameter></paramdef>
+#         <paramdef><parameter>ARG2</parameter></paramdef>
+#          ...
+#       </funcprototype>
+#       </funcsynopsis>
+#     </para>
+#
+#     <para>
+#       DESCRIPTION
+#     </para>
+#
+#     <variablelist>
+#       <varlistentry>
+# 	<term>
+# 	  <parameter>ARG1</parameter>
+# 	  TYPE
+# 	</term>
+# 	<listitem>
+# 	  <para>
+# 	    ARG1 DESCRIPTION
+# 	  </para>
+# 	</listitem>
+#       </varlistentry>
+#       ...
+#     </variablelist>
+#
+#     <para>
+#       REDACTED FORM
+#     </para>
+#     <para>
+#       EXAMPLES LIST
+#     </para>
+#   </sect1>
+
+#  Call this script by giving the master file (typically
+#  plplotdoc.xml) as the first argument, the API chapter file
+#  (typically api.xml) as the second argument, and output file
+#  (typically swig_documentation.i) as third.
+
+use XML::Parser;
+use XML::DOM;
+use Text::Wrap;
+$Text::Wrap::columns = 75;
+use Text::Tabs;
+$tabstop = 4;
+
+$api = "";
+open (MASTER, "< $ARGV[0]");
+while (<MASTER>) {
+  if (/^(<!DOCTYPE.*)\[/) {
+    $api .= "$1 \"\" [\n";
+  }
+  elsif (/^<\?xml/) {
+    $api .= '<?xml version="1.0" standalone="yes"?>
+';
+  }
+  elsif (/^<!ENTITY pl/) {
+    $api .= $_;
+  }
+}
+$api .= "<!ENTITY amp '#38;#38;'>
+<!ENTITY deg ' degrees'>
+<!ENTITY gt '&#x003E;'>
+<!ENTITY leq '&#38;#60;='>
+<!ENTITY lt '&#38;#60;'>
+<!ENTITY ndash '--'>
+]>\n";
+close MASTER;
+
+open (API, "< $ARGV[1]");
+$/ = undef;
+$api .= <API>;
+close API;
+
+sub process_node {
+  my $ret = "";
+  my $t = shift;
+  my $c = $t->getChildNodes;
+  my $m = $c->getLength;
+  for (my $j = 0; $j < $m; $j++) {
+    my $e = $c->item($j);
+    my $nt = $e->getNodeType;
+    if ($nt == TEXT_NODE) {
+      my $a = $e->getData;
+      $a =~ s/^\s+/ /;
+      $a =~ s/^\s+$//;
+      $a =~ s/\n\s+/ /g;
+      $ret .= $a;
+    }
+    elsif ($nt == ELEMENT_NODE) {
+      my $tag = $e->getTagName;
+    if ($tag eq "parameter") {
+        $ret .= "\n" . process_node ($e);
+      }
+      elsif  ($tag eq "function") {
+        $ret .= process_node ($e);
+      }
+      elsif  ($tag eq "link") {
+        $ret .= process_node ($e) ;
+      }
+      elsif  ($tag eq "funcprototype") {
+        $startproto = 1;
+	my $p = process_node ($e);
+	$p =~ s/ +$//;
+        $ret .= $p . ")";
+      }
+      elsif  ($tag eq "paramdef") {
+	my $p = process_node ($e);
+	$p =~ s/ +$//;
+        $ret .= ($startproto ? "(" : ", ") . $p;
+        $startproto = 0;
+      }
+      elsif  ($tag eq "term") {
+        $ret .= "\n" . process_node ($e) . ":";
+      }
+      elsif  ($tag eq "listitem") {
+        $ret .= "\t" . process_node ($e) . "\n";
+      }
+      elsif  ($tag eq "xref") {
+        $ret .= "the PLplot documentation";
+      }
+      elsif  ($tag eq "varlistentry") {
+        $ret .= "\n" . process_node ($e);
+      }
+      else {
+        $ret .= process_node ($e);
+      }
+    }
+    else {
+      $ret .= process_node ($e);
+    }
+  }
+  $ret =~ s/^\s+//;
+  return $ret;
+}
+
+$p = new XML::DOM::Parser;
+$sects = $p->parse ($api)->getElementsByTagName ("sect1");
+my $ns = $sects->getLength;
+$titles = "";
+
+open (MAN, "> $ARGV[2]");
+print MAN "// This file is generated by doc/docbook/src/api2swigdoc.pl from\n";
+print MAN "// doc/docbook/src/api.xml.  Do not modify by hand since this file\n";
+print MAN "// will be overwritten.  Edit doc/docbook/src/api.xml instead.\n\n";
+for ($i = 0; $i < $ns; $i++) {
+  $fun = $sects->item ($i);
+  $name = $fun->getAttribute ("id");
+  $c = $fun->getChildNodes;
+  $nc = $c->getLength;
+  $desc = "";
+  $varlist = "";
+  $got_synopsis = 0;
+  $indent = '    ';
+  for ($j = 0; $j < $nc; $j++) {
+    $part = $c->item($j);
+    if ($part->getNodeType == ELEMENT_NODE) {
+      $contents = process_node ($part);
+      $node = $part->getTagName;
+      if ($node eq "title") {
+        $title = $contents;
+      }
+      elsif ($node eq "para") {
+        if ($got_synopsis) {
+          $desc .=  wrap ($indent, $indent, split(/\n\s*\n/, $contents)) . "\n\n";
+        }
+        else {
+          $synopsis = $contents;
+          $got_synopsis = 1;
+        }
+      }
+      elsif ($node eq "variablelist") {
+        $varlist = $contents;
+      }
+    }
+  }
+  #$desc = wrap ($indent, $indent, split(/\n\s*\n/, $desc));
+  $varlist = join ("\n", map {
+                           s/\t/    /g;
+                           /(^\s+)/;
+                           $_ = wrap ($indent . $1,
+                                      $indent . $1 . $indent, $_);
+                           s/\t/    /g;
+                           $_;
+                         } split ("\n", $varlist));
+  # Get rid of preceding name identifier followed by ":" that is normally
+  # part of the raw title in api.xml.
+  $title =~s/^.*: //;
+
+  # Escape double quotes in arguments
+  $varlist =~ s/\"/\\"/g;
+  print MAN "%feature( \"docstring\", \"$title\n";
+  print MAN "\nDESCRIPTION:\n\n$desc\n";
+  print MAN "\nSYNOPSIS:\n\n$synopsis\n";
+  print MAN "\nARGUMENTS:\n\n$varlist\n"
+    if not $varlist eq "";
+  print MAN "\") $name\n\n";
+}
+close MAN;


Property changes on: trunk/doc/docbook/bin/api2swigdoc.pl
___________________________________________________________________
Added: svn:executable
   + *
Added: svn:eol-style
   + native


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




Thread: [Plplot-cvs] SF.net SVN: plplot:[11482] trunk/doc/docbook/bin/api2swigdoc.pl

Cross-platform, scientific graphics plotting library

plplot-cvs