Simpler code for extraction of manual examples 'units'-wise;

experimental.



git-svn-id: path/gapdoc/trunk@113

Author: GAP

TODO

@@ -1,18 +1,13 @@
 
            Some reminders for the authors
 
-         $Id: TODO,v 1.8 2007-01-31 13:45:09 gap Exp $
+         $Id: TODO,v 1.9 2007-03-05 16:51:11 gap Exp $
 
-- use InfoClass(es) instead of Print's
-
-- MakeDocDoc: only pdf-version from LaTeX
-
-- document SetGapDocLaTeXOptions
+- give record with predefined entities to ParseTreeXML...
+  (and use this for the predefined GAPDoc entities)
 
 - document StringBibAs..., change doc for <Bibliography>
 
-- remove mention of DeclarePackageAutoDocumentation and so on.
-
 - maybe add links to "the" example in the reference section of doc?
   (not so sure, if this is necessary).
 
@@ -29,9 +24,6 @@
 - finalize lib/Examples.g for builtin manual example tester and include and
   document it.
 
-- improve explanations of encodings, maybe add example how to handle a
-  latin-2 special character. How about handling UTF-8?
-
 - allow the distribution of different output documents (html, text, pdf,...)
   into different directories (needs to change the handler for GAPDoc books).
 

init.g

@@ -2,7 +2,7 @@
 ##
 #A  init.g                  GAPDoc              Frank Lübeck / Max Neunhöffer
 ##
-#H  @(#)$Id: init.g,v 1.12 2007-02-20 16:56:27 gap Exp $
+#H  @(#)$Id: init.g,v 1.13 2007-03-05 16:51:11 gap Exp $
 ##
 #Y  Copyright (C)  2000,  Frank Lübeck and Max Neunhöffer,  
 #Y  Lehrstuhl D für Mathematik,  RWTH Aachen
@@ -20,6 +20,7 @@ ReadPackage("GAPDoc", "lib/GAPDoc2LaTeX.gd");
 ReadPackage("GAPDoc", "lib/GAPDoc2Text.gd");
 ReadPackage("GAPDoc", "lib/GAPDoc2HTML.gd");
 ReadPackage("GAPDoc", "lib/Make.g");
+ReadPackage("GAPDoc", "lib/Examples.gd");
 
 # The handler functions for GAP's help system are read now:
 ReadPackage("GAPDoc", "lib/HelpBookHandler.g");

lib/Examples.g

@@ -0,0 +1,19 @@
+#############################################################################
+##
+#W  Examples.gd                  GAPDoc                          Frank Lübeck
+##
+#H  @(#)$Id: Examples.gd,v 1.1 2007-03-05 16:51:11 gap Exp $
+##
+#Y  Copyright (C)  2007,  Frank Lübeck,  Lehrstuhl D für Mathematik,  
+#Y  RWTH Aachen
+##  
+##  The files Examples.g{d,i} contain functions for extracting and checking
+##  GAP examples in GAPDoc manuals.
+##  
+
+DeclareGlobalFunction("GetTextXMLTree");
+DeclareGlobalFunction("XMLElements");
+DeclareGlobalFunction("ManualExamplesXMLTree");
+DeclareGlobalFunction("ManualExamples");
+DeclareGlobalFunction("TestExamplesString");
+

lib/Examples.gd

@@ -0,0 +1,101 @@
+#############################################################################
+##
+#W  Examples.gi                  GAPDoc                          Frank Lübeck
+##
+#H  @(#)$Id: Examples.gi,v 1.1 2007-03-05 16:51:11 gap Exp $
+##
+#Y  Copyright (C)  2007,  Frank Lübeck,  Lehrstuhl D für Mathematik,  
+#Y  RWTH Aachen
+##  
+##  The files Examples.g{d,i} contain functions for extracting and checking
+##  GAP examples in GAPDoc manuals.
+##  
+
+# extract and collect text in elements recursively
+InstallGlobalFunction(GetTextXMLTree, function(r)
+  local res, fun;
+  res := "";
+  fun := function(r)
+    if IsString(r.content) then
+      Append(res, r.content);
+    fi;
+  end;
+  ApplyToNodesParseTree(r, fun);
+  return res;
+end);
+
+# return list of nodes of elements with name in 'eltnames' from XML tree r
+InstallGlobalFunction(XMLElements, function(r, eltnames)
+  local res, fun;
+  res := [];
+  fun := function(r)
+    if r.name in eltnames then
+      Add(res, r);
+    fi;
+  end;
+  ApplyToNodesParseTree(r, fun);
+  return res;
+end);
+
+# Extract examples units-wise from a GAPDoc document as XML tree, 
+# 'units' can either be: "Chapter" or "Section" or "Subsection" or "Single"
+#     then a list of strings is returned
+# For all other values of 'units' one string with all examples is returned.
+# Before each extracted example there is its paragraph number in a comment:
+#  [ chapter, section, subsection, paragraph ]
+
+InstallGlobalFunction(ManualExamplesXMLTree, function( tree, units )
+  local secelts, sec, exelts, res, str, a, ex;
+  if units = "Chapter" then
+    secelts := ["Chapter", "Appendix"];
+  elif units = "Section" then
+    secelts := ["Section"];
+  elif units = "Subsection" then
+    secelts := ["Subsection", "ManSection"];
+  elif units = "Single" then
+    secelts := ["Example"];
+  else
+    secelts := 0;
+  fi;
+  if secelts <> 0 then
+    sec := XMLElements(tree, secelts);
+  else
+    sec := [tree];
+  fi;
+  # want to put section numbers in comments
+  AddParagraphNumbersGapDocTree(tree);
+  exelts := List(sec, a-> XMLElements(a, ["Example"]));
+  res := [];
+  for a in exelts do
+    str := "";
+    for ex in a do
+      Append(str, "# from paragraph ");
+      Append(str, String(ex.count));
+      Append(str, "\n");
+      Append(str, GetTextXMLTree(ex));
+      Append(str, "\n");
+    od;
+    Add(res, str);
+  od;
+  if secelts = 0 then
+    res := res[1];
+  fi;
+  return res;
+end);
+
+# compose and parse document, then extract examples units-wise
+InstallGlobalFunction(ManualExamples, function( path, main, files, units )
+  local str, xmltree;
+  str:= ComposedDocument( "GAPDoc", path, main, files, true );
+  xmltree:= ParseTreeXMLString( str[1], str[2] );
+  return ManualExamplesXMLTree(xmltree, units);
+end);
+
+# test a string with examples 
+InstallGlobalFunction(TestExamplesString, function(str)
+  local file;
+  file := InputTextString(str);
+  ReadTest(file);
+  CloseStream(file);
+end);
+

lib/Examples.gi

@@ -2,7 +2,7 @@
 ##
 #A  read.g                  GAPDoc              Frank Lübeck / Max Neunhöffer
 ##
-#H  @(#)$Id: read.g,v 1.5 2007-02-20 16:56:27 gap Exp $
+#H  @(#)$Id: read.g,v 1.6 2007-03-05 16:51:11 gap Exp $
 ##
 #Y  Copyright (C)  2000,  Frank Lübeck and Max Neunhöffer,  
 #Y  Lehrstuhl D für Mathematik,  RWTH Aachen
@@ -21,4 +21,5 @@ ReadPackage("GAPDoc", "lib/BibXMLextTools.gi");
 ReadPackage("GAPDoc", "lib/GAPDoc2LaTeX.gi");
 ReadPackage("GAPDoc", "lib/GAPDoc2Text.gi");
 ReadPackage("GAPDoc", "lib/GAPDoc2HTML.gi");
+ReadPackage("GAPDoc", "lib/Examples.gi");