On Sep 20, 2006, Kalle Olavi Niemitalo writes:
>"M. Levinson" writes:
>> The patch includes documentation for Python programmers in doc/python.txt,
>> and the documentation is also available internally from Python code via
>> Python's introspection API.
>
>Both currently seem to contain the same text. Would it be a good
>idea to generate one from the other, to prevent them from diverging?
Absolutely. Attached is an additional Python module to help future
maintainers keep them in sync. This still requires manual intervention
by a maintainer who's updating the code -- I haven't thought of a
simple way to completely automate the process of generating the
documentation. (And I wonder if contrib/python is the right place
for this file -- end-users will never care about it, but I'm not sure
where else to put it. Any thoughts?)
>Should CONFIG_SMALL exclude the documentation strings from the
>elinks binary? I suppose users of CONFIG_SMALL are unlikely to
>link with Python, though.
That does seem like a somewhat unlikely combination, but the suggestion
makes sense in principle. If there's a consensus in favor of it then
I'll rework the patch to make the docstrings conditional.
>It would be nice if the comment said this is indirectly used for
>the Cancel button as well, and that text is NULL in that case.
Okay, I've attached a patch to tweak the comment.
>I've been thinking of changing ELinks to allow Unicode characters
>in keystroke name strings. It would then be important to know
>the encoding of the string. It looks like the cleanest way would
>be to use the "es" format unit and explicitly select the "utf_8"
>encoding, then tell this to whatever function parses the string
>in ELinks.
That sounds right to me at the moment, although I may need to study
the problem more carefully.
>Perhaps it is a bad idea in general to use the event registration
>system for key bindings. There will be only one hook for each
>such event, anyway. Instead, the event member of struct
>keybinding could be replaced with a pointer to a new structure:
>[...]
>/* Called by free_keybinding(). Free this struct
> * scripting_function and any language-specific data to which
> * it may point. If the scripting language module uses the
> * same struct scripting_function for multiple key bindings,
> * then *release might just decrement a reference count. */
>void (*release)(struct scripting_function *);
>[...]
>You wouldn't then need the keybindings dictionary, I think.
Agreed. And getting rid of the keybindings dictionary would certainly
simplify the error-handling in python_bind_key().
>Perhaps the same structure could be used for script-generated
>menus, too; or perhaps there are better solutions.
Yes! And I realize I'm pushing the menu machinery beyond its intended
design goals; thoughts on other approaches would be welcome.
>The hooks.c and hooks.py patches were inconvenient to apply
>because their --- and +++ lines did not have the a/ and b/
>prefixes like the other patches did.
Argh, it looks like my git does the wrong thing for a complete rewrite.
I apologize for not catching that.
Thank you for looking at the code, and for all your feedback.
diff --git a/contrib/python/elinks_maint.py b/contrib/python/elinks_maint.py
new file mode 100644
index 000..0b3fe29
--- /dev/null
+++ b/contrib/python/elinks_maint.py
@@ -0,0 +1,137 @@
+"""Additional Python code for ELinks maintainers.
+
+This module is intended for ELinks maintainers. If you modify or add to
+the Python APIs in src/scripting/python/*.c and/or contrib/python/hooks.py,
+you should update the accompanying docstrings to reflect your changes and
+then generate a new version of the file doc/python.txt (which serves as a
+reference manual for the browser's Python APIs). The embedded interpreter
+can use introspection to regenerate the python.txt document for you; just
+copy this file into your ~/.elinks directory and add something like the
+following to ~/.elinks/hooks.py:
+
+import elinks_maint
+elinks.bind_key('F2', elinks_maint.generate_python_txt)
+
+"""
+
+import inspect
+import tempfile
+import types
+
+preface = """\
+Python programmers can customize the behavior of ELinks by creating a Python
+hooks module. The embedded Python interpreter provides an internal module
+called elinks that can be used by the hooks module to create keystroke
+bindings for Python code, obtain information about the document being
+viewed, display simple dialog boxes and menus, load documents into the
+ELinks cache, or display documents to the user. These two modules are
+described below.
+
+"""
+
+module_template = """
+MODULE
+%s - %s
+
+DESCRIPTION
+%s
+
+FUNCTIONS
+%s
+"""
+
+separator = '-' * 78 + '\n'
+
+def document_modules(*modules):
+"""Format the internal documentation found in one or more Python modules."""
+output = []
+for module in modules:
+name, doc, namespace = module.__name__, module.__doc__, module.__dict__
+
