More docs

api/gendocbook.py

@@ -9,6 +9,7 @@ from mpi.docbookwriter import Writer
 op = optparse.OptionParser()
 op.add_option("--python", action="store_true")
 op.add_option("--lua", action="store_true")
+op.add_option("--template", action="store")
 (opts, args) = op.parse_args()
 
 assert len(args) == 1
@@ -19,4 +20,4 @@ elif opts.lua:
     mode = 'lua'
 
 mod = Module.from_xml(args[0])
-Writer(mode, sys.stdout).write(mod)
+Writer(mode, opts.template, sys.stdout).write(mod)

api/mpi/docbookwriter.py

@@ -3,19 +3,6 @@ import StringIO
 from mpi.util import *
 from mpi.module import *
 
-tmpl_file_start = """\
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE article [
-<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
-%medit-defines;
-]>
-<article>
-"""
-
-tmpl_file_end = """\
-</article>
-"""
-
 lua_constants = {
     'NULL': 'nil',
     'TRUE': 'true',
@@ -45,10 +32,12 @@ def name_all_caps(cls):
     return '_'.join([s.upper() for s in split_camel_case_name(cls.name)])
 
 class Writer(object):
-    def __init__(self, mode, out):
+    def __init__(self, mode, template, out):
         super(Writer, self).__init__()
-        self.out = out
+        self.file = out
+        self.out = StringIO.StringIO()
         self.mode = mode
+        self.template = template
         if mode == 'python':
             self.constants = python_constants
         elif mode == 'lua':
@@ -235,8 +224,6 @@ class Writer(object):
     def write(self, module):
         self.module = module
 
-        self.out.write(tmpl_file_start)
-
         for cls in module.get_classes() + module.get_boxed() + module.get_pointers():
             self.__write_class(cls)
 
@@ -250,6 +237,9 @@ class Writer(object):
 
         self.out.write('</sect1>\n')
 
-        self.out.write(tmpl_file_end)
+        content = self.out.getvalue()
+        template = open(self.template).read()
+        self.file.write(template.replace('###GENERATED###', content))
 
+        del self.out
         del self.module

doc/Makefile.am

@@ -12,17 +12,23 @@ gendocbook_files =				\
 	$(top_srcdir)/api/mpi/module.py		\
 	$(top_srcdir)/api/mpi/docbookwriter.py
 
-$(srcdir)/script-python.docbook: $(gendocbook_files) $(top_srcdir)/api/moo.xml
+$(srcdir)/script-python.docbook: $(gendocbook_files) script-python.tmpl.docbook $(top_srcdir)/api/moo.xml
-	$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py --python $(top_srcdir)/api/moo.xml \
+	$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py \
-		> script-python.docbook.tmp && mv script-python.docbook.tmp $(srcdir)/script-python.docbook
+		--python --template $(srcdir)/script-python.tmpl.docbook \
+		$(top_srcdir)/api/moo.xml > script-python.docbook.tmp && \
+		mv script-python.docbook.tmp $(srcdir)/script-python.docbook
 
-$(srcdir)/script-lua.docbook: $(gendocbook_files) $(top_srcdir)/api/moo.xml
+$(srcdir)/script-lua.docbook: $(gendocbook_files) script-lua.tmpl.docbook $(top_srcdir)/api/moo.xml
-	$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py --lua $(top_srcdir)/api/moo.xml \
+	$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py \
-		> script-lua.docbook.tmp && mv script-lua.docbook.tmp $(srcdir)/script-lua.docbook
+		--lua --template $(srcdir)/script-lua.tmpl.docbook \
+		$(top_srcdir)/api/moo.xml > script-lua.docbook.tmp && \
+		mv script-lua.docbook.tmp $(srcdir)/script-lua.docbook
 
-$(srcdir)/script-lua-gtk.docbook: $(gendocbook_files) $(top_srcdir)/api/gtk.xml
+$(srcdir)/script-lua-gtk.docbook: $(gendocbook_files) script-lua-gtk.tmpl.docbook $(top_srcdir)/api/gtk.xml
-	$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py --lua $(top_srcdir)/api/gtk.xml \
+	$(AM_V_GEN)$(PYTHON) $(top_srcdir)/api/gendocbook.py \
-		> script-lua-gtk.docbook.tmp && mv script-lua-gtk.docbook.tmp $(srcdir)/script-lua-gtk.docbook
+		--lua --template $(srcdir)/script-lua-gtk.tmpl.docbook \
+		$(top_srcdir)/api/gtk.xml > script-lua-gtk.docbook.tmp && \
+		mv script-lua-gtk.docbook.tmp $(srcdir)/script-lua-gtk.docbook
 
 $(srcdir)/help/script-python.html: script-python.docbook medit-defines.ent script.xsl
 	$(AM_V_at)$(MKDIR_P) $(srcdir)/help/

doc/medit.css

@@ -87,10 +87,10 @@ hr
 {
   margin-top: 0.0em
 }
-.note p, .warning p
+/*.note p, .warning p
 {
   margin-bottom: 0.0em
-}
+}*/
 
 /* blob links */
 h2 .extralinks, h3 .extralinks

doc/script-lua-gtk.tmpl.docbook

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE article [
+<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
+%medit-defines;
+]>
+<article>
+<title>&medit; Gtk API for Lua scripts</title>
+<sect1>
+<title>Introduction</title>
+<para>Lua scripts running in &medit; have limited access to
+<ulink url="http://www.gtk.org/">Gtk</ulink> functionality
+exposed through <code>gtk</code> package in addition to functions in
+<ulink url="script-lua.html"><code>medit</code> package</ulink>.
+It is not a goal to provide complete Lua bindings for Gtk,
+and it is not a goal to enable creating UI in Lua scripts.
+If there is a demand, &medit; might bind more Gtk functionality,
+but so far Lua in &medit; is supposed to be lean and mean
+scripting language which is always available. Use Python if
+you need more functionality.</para>
+<para>
+Notations used in this manual are described
+<ulink url="script-lua.html#section-notations">here</ulink>.
+</para>
+</sect1>
+###GENERATED###
+</article>

doc/script-lua.tmpl.docbook

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE article [
+<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
+%medit-defines;
+]>
+<article>
+<title>&medit; Lua API</title>
+
+<sect1 id="section-introduction">
+<title>Introduction</title>
+<para>Lua scripts running in &medit; have access to its
+functionality through the <code>medit</code> package.</para>
+<warning>
+Functions which are not documented here may or may not work differently in
+the future and they may disappear without notice. Contact the author if you
+need functions which are not present here.
+</warning>
+</sect1>
+
+<sect1 id="section-object-model">
+<title>&medit; object model</title>
+<para>&medit; uses very simple object model where its objects are
+represented as user data in Lua and methods are provided via metatable
+shared by all objects of all "classes". Method dispatch is dynamic,
+i.e. metatable does not contain functions which correspond to methods,
+and <code>obj:method</code> returns a function object which knows which
+method on which object it is going to call.</para>
+<para>This manual lists and talks about "classes", but it is merely
+to avoid complicated terminology. When we say that an object belongs
+to or is an instance of a class <code>Foo</code>, it just means that
+it has methods listed in manual section for class <code>Foo</code>
+and methods of parent classes, if any.</para>
+<note>
+To call a method, you can use both <code>obj:method(args)</code>
+and <code>obj.method(args)</code>.
+</note>
+</sect1>
+
+<sect1 id="section-notations">
+<title>Notations</title>
+<para>This manual uses the following conventions:</para>
+<variablelist>
+  <varlistentry>
+    <term><code>func()</code> and <code>func(nil)</code> are equivalent.</term>
+    <listitem>There is no distinction between <constant>nil</constant> value
+    of a parameter and missing parameter, unless documentation for given function
+    says otehrwise.
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Optional parameters</term>
+    <listitem>
+    <programlisting>func(arg1=val1, arg2=val, arg3=val3, ...)</programlisting>
+    <code><parameter>arg</parameter>=val</code> means that
+    parameter <parameter>arg</parameter> is optional, and function receives
+    value <code>val</code> if it's missing or <constant>nil</constant>.
+    Not all parameters are necessarily optional. For example,
+    <programlisting>insert_text(text, where=nil)</programlisting>
+    means that <parameter>text</parameter> may not be missing or <constant>nil</constant>
+    (unless documentation says otherwise), and <parameter>where</parameter> is optional.
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Keyword parameters</term>
+    <listitem>
+    <programlisting>func{arg1, arg2=val2}</programlisting>
+    This means that function takes a single table parameter, and
+    table must be a dictionary with keys <parameter>arg1</parameter>,
+    <parameter>arg2</parameter>, etc. Similar to regular parameters,
+    <code><parameter>arg</parameter>=val</code> means that
+    <parameter>arg</parameter> is optional.
+    </listitem>
+  </varlistentry>
+  <varlistentry>
+    <term>Dictionary parameters</term>
+    <listitem>
+      <programlisting>func(arg1, arg2, {arg3, arg4=val})</programlisting>
+      <code>{}</code> denote a parameter which must be a table with given keys,
+      similar to keyword parameters (the difference is that with keyword parameters
+      function takes a single table argument).
+    </listitem>
+  </varlistentry>
+</variablelist>
+
+</sect1>
+###GENERATED###
+</article>

doc/script-python.tmpl.docbook

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE article [
+<!ENTITY % medit-defines SYSTEM "medit-defines.ent">
+%medit-defines;
+]>
+<article>
+<title>&medit; Python API</title>
+<sect1>
+<title>Introduction</title>
+<para>When compiled with Python support, &medit; uses
+<ulink url="http://www.pygtk.org/">PyGtk</ulink>. Its functionality is
+exposed through <code>moo</code> module. You can use built-in Python console
+available from <guimenu>Tools</guimenu> to experiment with &medit; API.</para>
+<note>
+Classes and functions documented here are guaranteed to work as long as you
+follow the rules from their documentation (most often there are no special
+rules, but for some functions you may only use named arguments, etc.)
+</note>
+<warning>
+<code>moo</code> module has more classes and functions than documented here,
+but undocumented classes and functions may or may not work differently in
+the future and they may disappear without notice. Contact the author if you
+need functions which are not present here.
+</warning>
+</sect1>
+###GENERATED###
+</article>