* doc/gramps-manual/C/cmdplug.xml: Add new section documenting

plugin options (Reports and Tools).
* src/build_cmdplug: Add script to refresh the new doc section.
* doc/gramps-manual/C/Makefile.am: Ship new file.
* doc/gramps-manual/C/gramps-manual.xml: Define new entity.
* doc/gramps-manual/C/cmdline.xml: Include new section.
* src/Makefile.am: Define new make target (cmdplug).
* src/PluginMgr.py: Include human-readable names in CLI plugins
registration.
* src/Report.py: Allow instantiation of command-line report
without adding item-specific options.
* src/Tool.py: Allow instantiation of command-line tool
without adding item-specific options.
* src/plugins/CmdRef.py: Add options for inclusion into the manual
and the target filename; Use human-readable names for titles; Add
section with common options; Add name option.


svn: r5288

gramps2/ChangeLog

@@ -1,3 +1,21 @@
+2005-10-07  Alex Roitman  <shura@gramps-project.org>
+	* doc/gramps-manual/C/cmdplug.xml: Add new section documenting
+	plugin options (Reports and Tools).
+	* src/build_cmdplug: Add script to refresh the new doc section.
+	* doc/gramps-manual/C/Makefile.am: Ship new file.
+	* doc/gramps-manual/C/gramps-manual.xml: Define new entity.
+	* doc/gramps-manual/C/cmdline.xml: Include new section.
+	* src/Makefile.am: Define new make target (cmdplug).
+	* src/PluginMgr.py: Include human-readable names in CLI plugins
+	registration.
+	* src/Report.py: Allow instantiation of command-line report
+	without adding item-specific options.
+	* src/Tool.py: Allow instantiation of command-line tool
+	without adding item-specific options.
+	* src/plugins/CmdRef.py: Add options for inclusion into the manual
+	and the target filename; Use human-readable names for titles; Add
+	section with common options; Add name option.
+
 2005-10-06  Don Allingham  <don@gramps-project.org>
 	* src/plugins/DetAncestralReport.py: fix margin on note paragraph
 	* src/DateEdit.py: try using standard icons

gramps2/doc/gramps-manual/C/Makefile.am

@@ -12,6 +12,7 @@ entities = legal.xml\
 	keybind.xml\
 	filtref.xml\
 	cmdline.xml\
+	cmdplug.xml\
 	bugs.xml\
 	authors.xml
 include $(top_srcdir)/doc/xmldocs.make

gramps2/doc/gramps-manual/C/cmdline.xml

@@ -319,6 +319,7 @@
 
       </sect1>
 
+      &cmdplug;
 
       <sect1 id="cmdline-operation">
       <title>Operation</title>

gramps2/doc/gramps-manual/C/gramps-manual.xml

@@ -50,6 +50,7 @@
   <!ENTITY keybind SYSTEM "keybind.xml">
   <!ENTITY filtref SYSTEM "filtref.xml">
   <!ENTITY cmdline SYSTEM "cmdline.xml">
+  <!ENTITY cmdplug SYSTEM "cmdplug.xml">
   <!ENTITY bugs SYSTEM "bugs.xml">
   <!ENTITY authors SYSTEM "authors.xml">
 ]>

gramps2/src/ArgHandler.py

@@ -614,7 +614,8 @@ class ArgHandler:
                                       category,options_str_dict)
                     else:
                         Report.cl_report(self.parent.db,name,category,
-                                report_class,options_class,options_str_dict)
+                                         report_class,options_class,
+                                         options_str_dict)
                     return
 
             print "Unknown report name. Available names are:"

gramps2/src/Makefile.am

@@ -176,3 +176,6 @@ pycheck:
 docs:
 	epydoc -o doc --url http://gramps.sourceforge.net --name GRAMPS --html $(docfiles)
 	epydoc --pdf $(docfiles)
+
+cmdplug:
+	./build_cmdplug

gramps2/src/PluginMgr.py

@@ -190,7 +190,8 @@ def register_tool(
 
     (junk,cli_task) = divmod(modes-gui_task,2**Tool.MODE_CLI)
     if cli_task:
-        _register_cli_tool(name,category,tool_class,options_class)
+        _register_cli_tool(name,category,tool_class,options_class,
+                           translated_name)
 
 def _register_gui_tool(tool_class,options_class,translated_name,
                        name,category,
@@ -209,11 +210,13 @@ def _register_gui_tool(tool_class,options_class,translated_name,
                       category,name,description,status,
                       author_name,author_email))
 
-def _register_cli_tool(name,category,tool_class,options_class):
+def _register_cli_tool(name,category,tool_class,options_class,
+                       translated_name):
     for n in cli_tool_list:
         if n[0] == name:
             return
-    cli_tool_list.append((name,category,tool_class,options_class))
+    cli_tool_list.append((name,category,tool_class,options_class,
+                          translated_name))
 
 #-------------------------------------------------------------------------
 #
@@ -257,7 +260,8 @@ def register_report(
     (junk,command_line_task) = divmod(modes-standalone_task-book_item_task,
                                         2**Report.MODE_CLI)
     if command_line_task:
-        _register_cl_report(name,category,report_class,options_class)
+        _register_cl_report(name,category,report_class,options_class,
+                            translated_name)
 
 def _register_standalone(report_class, options_class, translated_name, 
                     name, category,
@@ -290,11 +294,13 @@ def register_book_item(translated_name, category, report_class,
     bkitems_list.append((translated_name, category, report_class,
                          option_class, name))
 
-def _register_cl_report(name,category,report_class,options_class):
+def _register_cl_report(name,category,report_class,options_class,
+                        translated_name):
     for n in cl_list:
         if n[0] == name:
             return
-    cl_list.append((name,category,report_class,options_class))
+    cl_list.append((name,category,report_class,options_class,
+                    translated_name))
 
 #-------------------------------------------------------------------------
 #

gramps2/src/Report.py

@@ -1584,17 +1584,18 @@ class CommandLineReport:
     
     """
 
-    def __init__(self,database,name,category,option_class,options_str_dict):
+    def __init__(self,database,name,category,option_class,options_str_dict,
+                 noopt=False):
         self.database = database
         self.category = category
         self.option_class = option_class(name)
         self.show = options_str_dict.pop('show',None)
         self.options_str_dict = options_str_dict
-        self.init_options()
+        self.init_options(noopt)
         self.parse_option_str()
         self.show_options()
 
-    def init_options(self):
+    def init_options(self,noopt):
         self.options_dict = {
             'of'        : self.option_class.handler.module_name,
             'off'       : self.option_class.handler.get_format_name(),
@@ -1619,6 +1620,9 @@ class CommandLineReport:
             'dispf'     : ["=str","Display format for the outputbox."],
             }
 
+        if noopt:
+            return
+
         # Add report-specific options
         for key in self.option_class.handler.options_dict.keys():
             if key not in self.options_dict.keys():

gramps2/src/Tool.py

@@ -105,26 +105,30 @@ class CommandLineTool:
     
     """
 
-    def __init__(self,database,name,category,option_class,options_str_dict):
+    def __init__(self,database,name,category,option_class,options_str_dict,
+                 noopt=False):
         self.database = database
         self.category = category
         self.option_class = option_class(name)
         self.show = options_str_dict.pop('show',None)
         self.options_str_dict = options_str_dict
-        self.init_options()
+        self.init_options(noopt)
         self.parse_option_str()
         self.show_options()
 
-    def init_options(self):
+    def init_options(self,noopt):
         self.options_dict = {
             'id'        : ''
             }
 
         self.options_help = {
-            'id'        : ["=ID","Gramps ID of a central person. MANDATORY"],
+            'id'        : ["=ID","Gramps ID of a central person."],
             'filter'    : ["=num","Filter number."],
             }
 
+        if noopt:
+            return
+
         # Add tool-specific options
         for key in self.option_class.handler.options_dict.keys():
             if key not in self.options_dict.keys():

gramps2/src/build_cmdplug

@@ -0,0 +1,10 @@
+#! /bin/sh
+
+TARGET=../doc/gramps-manual/C/cmdplug.xml
+
+touch ./junk.grdb
+python gramps.py -O ./junk.grdb -a tool -p name=cmdref,include=1,target=$TARGET
+chmod +r $TARGET
+rm ./junk.grdb
+
+exit 0

gramps2/src/plugins/CmdRef.py

@@ -44,56 +44,118 @@ import Report
 
 #-------------------------------------------------------------------------
 #
-# runTool
+# Constants
+#
+#-------------------------------------------------------------------------
+_tags = [
+    'article',
+    'sect1',
+    'sect2',
+    'sect3'
+    ]
+
+#-------------------------------------------------------------------------
+#
+# 
 #
 #-------------------------------------------------------------------------
 class CmdRef(Tool.Tool):
     def __init__(self,db,person,options_class,name,callback=None,parent=None):
         Tool.Tool.__init__(self,db,person,options_class,name)
 
+        # retrieve options
+        include = self.options.handler.options_dict['include']
+        target  = self.options.handler.options_dict['target']
+
+        if include:
+            level = 1
+        else:
+            level = 0
+
         cli = int(parent == None)
 
         f = tempfile.NamedTemporaryFile()
         fname = f.name
-        f.write('<?xml version="1.0" encoding="UTF-8"?>\n')
+        id_counter = 0
-        f.write('<?yelp:chunk-depth 2?>\n')
+
-        f.write('<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" ')
+        if not include:
-        f.write('   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">\n')
+            f.write('<?xml version="1.0" encoding="UTF-8"?>\n')
-        f.write('<article id="index" lang="en">\n')
+            f.write('<?yelp:chunk-depth 2?>\n')
-        f.write('  <title>Reports and Tools parameter reference</title>\n')
+            f.write('<!DOCTYPE book PUBLIC ')
-        f.write('  <sect1 id="reps">\n')
+            f.write('"-//OASIS//DTD DocBook XML V4.1.2//EN" ')
+            f.write('   "http://www.oasis-open.org/docbook/'
+                    'xml/4.1.2/docbookx.dtd">\n')
+            
+        # Top section and title
+        f.write('<%s id="cmdplug-id%d">\n' % (_tags[level],id_counter) )
+        id_counter = id_counter + 1
+        f.write('  <title>Detailed plugin option reference</title>\n')
+
+        # Reports
+        f.write('  <%s id="cmdplug-reps">\n' % _tags[level+1])
         f.write('    <title>Reports</title>\n')
-        counter=0
+
+        # Common report options
+        item = PluginMgr.cl_list[0]
+        clr = Report.CommandLineReport(db,item[0],item[1],item[3],{},True)
+        self.write_ref(f,clr,level+2,id_counter,True)
+        id_counter = id_counter + 1
+
         for item in PluginMgr.cl_list:
             category = item[1]
             if category in (Report.CATEGORY_BOOK,
                             Report.CATEGORY_CODE,
                             Report.CATEGORY_WEB):
-                self.write_ref(f,item,counter,category)
+                self.write_ref(f,item,level+2,id_counter,category)
             else:
-                self.write_ref( f, item, counter, None)
+                self.write_ref(f,item,level+2,id_counter,None)
-            counter = counter + 1
+            id_counter = id_counter + 1
-        f.write('  </sect1>\n')
+        f.write('  </%s>\n' % _tags[level+1] )
-        f.write('  <sect1 id="tools">\n')
+
+        # Tools
+        f.write('  <%s id="cmdplug-tools">\n ' % _tags[level+1] )
         f.write('    <title>Tools</title>\n')
+
+        # Common tool options
+        item = PluginMgr.cli_tool_list[0]
+        clr = Tool.CommandLineTool(db,item[0],item[1],item[3],{},True)
+        self.write_ref(f,clr,level+2,id_counter,True)
+        id_counter = id_counter + 1
+
         for item in PluginMgr.cli_tool_list:
-            self.write_ref( f, item, counter)
+            self.write_ref(f,item,level+2,id_counter)
-            counter = counter + 1
+            id_counter = id_counter + 1
-        f.write('  </sect1>\n')
+        f.write('  </%s>\n' % _tags[level+1] )
         f.write('  \n')
-        f.write('  \n')
+        f.write('</%s>\n' %_tags[level])
-        f.write('  \n')
-        f.write('</article>\n')
         f.flush()
-        os.spawnlp( os.P_WAIT, "yelp", "yelp", fname)
+        if include:
+            os.spawnlp( os.P_WAIT, "cp", "cp", fname, target)
+        else:
+            os.spawnlp( os.P_WAIT, "yelp", "yelp", fname)
         f.close()
 
-    def write_ref( self, f, item,counter,category=None):
+    def write_ref(self,f,item,level,id_counter,category=None):
-        f.write('<sect2 id="sect2id%d">\n' % counter)
+        # Section and title
-        f.write('  <title>%s</title>\n' % item[0])
+        f.write('<%s id="cmdplug-id%d">\n' % (_tags[level],id_counter) )
-        f.write('  <simplesect>\n')
+        if category == True:
-        f.write('    <title>Options</title>\n')
+            title = 'Common Options'
+        else:
+            title = item[4]
+        f.write('  <title>%s</title>\n' % title)
+        
+        # Show command-line name
         f.write('    <variablelist>\n')
+
+        if category != True:
+            f.write('        <varlistentry>\n')
+            f.write('          <term><command>name</command>:</term>\n')
+            f.write('          <listitem>\n')
+            f.write('            <para>%s</para>\n' % item[0])
+            f.write('          </listitem>\n')
+            f.write('        </varlistentry>\n')
+
+        # Instantiate options class
         if category == None:
             oclass = item[3]( item[0])
         elif category == Report.CATEGORY_BOOK:
@@ -109,39 +171,71 @@ class CmdRef(Tool.Tool):
             elif item[0] == "navwebpage":
                 import NavWebPage
                 oclass = NavWebPage.WebReportOptions(item[0])
+        elif category == True:
+            # This is the common options case
+            # so class is already instantiated
+            oclass = item
                 
+        # Spit out all options
         for arg in oclass.options_help.keys():
-            f.write('      <variablelist>\n')
             f.write('        <varlistentry>\n')
             f.write('          <term><command>%s</command>: %s</term>\n'
                     % (escape(arg), escape(oclass.options_help[arg][0])))
             f.write('          <listitem>\n')
             f.write('            <para>%s</para>\n'
                     % escape(oclass.options_help[arg][1]))
-            if type(oclass.options_help[arg][2]) in [list,tuple]:
+
-                if oclass.options_help[arg][3]:
+            if len(oclass.options_help[arg])>2:
-                    f.write('          <orderedlist>\n')
+                if type(oclass.options_help[arg][2]) in [list,tuple]:
-                    for val in oclass.options_help[arg][2]:
+                    if oclass.options_help[arg][3]:
-                        f.write( "      <listitem>%s</listitem>\n"
+                        f.write('          <orderedlist>\n')
-                                 % escape(val))
+                        for val in oclass.options_help[arg][2]:
-                    f.write('          </orderedlist>\n')
+                            f.write( "      <listitem>%s</listitem>\n"
+                                     % escape(val))
+                        f.write('          </orderedlist>\n')
+                    else:
+                        f.write('          <itemizedlist>\n')
+                        for val in oclass.options_help[arg][2]:
+                            f.write( "      <listitem>%s</listitem>\n"
+                                     % escape(val))
+                        f.write('          </itemizedlist>\n')
                 else:
-                    f.write('          <itemizedlist>\n')
+                    f.write('            '
-                    for val in oclass.options_help[arg][2]:
+                            '<para>Value: <userinput>%s</userinput></para>\n'
-                        f.write( "      <listitem>%s</listitem>\n"
+                            % escape(oclass.options_help[arg][2]))
-                                 % escape(val))
-                    f.write('          </itemizedlist>\n')
-            else:
-                f.write('            <para>Value: <userinput>%s</userinput></para>\n'
-                        % escape(oclass.options_help[arg][2]))
             f.write('          </listitem>\n')
             f.write('        </varlistentry>\n')
-            f.write('      </variablelist>\n')
 
         f.write('    </variablelist>\n')
-        f.write('  </simplesect>\n')
+        f.write('</%s>\n' % _tags[level])
-        f.write('</sect2>\n')
     
+#------------------------------------------------------------------------
+#
+# 
+#
+#------------------------------------------------------------------------
+class CmdRefOptions(Tool.ToolOptions):
+    """
+    Defines options and provides handling interface.
+    """
+
+    def __init__(self,name,person_id=None):
+        Tool.ToolOptions.__init__(self,name,person_id)
+
+    def set_new_options(self):
+        # Options specific for this report
+        self.options_dict = {
+            'include' : 0,
+            'target'  : '../doc/gramps-manual/C/cmdplug.xml',
+        }
+        self.options_help = {
+            'include' : ("=0/1","Whether to include into the manual",
+                         ["Do not include","Include"],
+                         True),
+            'target'  : ("=str","Pathname to the target file",
+                         "Any valid pathname")
+            }
+
 #------------------------------------------------------------------------
 #
 # 
@@ -153,10 +247,9 @@ register_tool(
     name = 'cmdref',
     category = Tool.TOOL_DEBUG,
     tool_class = CmdRef,
-    options_class = Tool.ToolOptions,
+    options_class = CmdRefOptions,
     modes = Tool.MODE_GUI | Tool.MODE_CLI,
-    translated_name = _("Generate Commandline Reference "
+    translated_name = _("Generate Commandline Plugin Reference"),
-                        "for Reports and Tools"),
     author_name = "Martin Hawlisch",
     author_email = "martin@hawlisch.de",
     description=_("Generates a DocBook XML file that contains "