[Doc-SIG] An 'apropos' utility for documentations

[John Skaller]

At 23:06 10/12/98 -0500, Tim Peters wrote:

>>         And then I saw the TODO list Ken put up.
>> Which is excellent! So, if there were a way to
>> make an _online_ list of every function, class, and module
>> in the library, with the current docstring, and allow
>> everyone to add docstrings over the Internet, like the TODO list,
>> we'd have more people able to make small contributions.
>
>I have no idea how to implement that (specifically getting the latest
>contributions back into the sources), 

        I agree. This is nasty. But I think it can be done for
_python_ modules fairly easily. For C modules, it will require
manual patching.

        For Python modules, the parser can identify not only
what a docstring is, and which object to plug it into (module, class, function)
but also when there is NO docstring .. and hence a place where one COULD be put.
If the parser was temporarily stuffed with by <wink>ing a lot at it,
it could generate a file of all the docstring insertion points:
be they existing docstrings, or a place docstrings could be put.

        See below for an alternative.

>> [There are some interesting issues here, such as foreign
>> language docstrings. Why English?]
>
>Because only a handful of misfits speak Australian <wink>.

        'viously, notu. ucntevn spell Strine right, mate.
Youse'dseemorecrickt.
--------------------

        I've been thinking <woops!> about internationalisation.
Really, a docstring should be a dictionary, keyed by language.

        There's another way to do this, however, which requires
a bit of internal Python support and provides other advantages.

        Suppose, whenever an interned string literal was about to be used,
it was looked up in a table for an equivalent in the users native
language. If no equivalent is found, the original is used.
But if one is found, it is substituted. For example:

        print "Hello",name

will print

        "Guten morgen John"

if the locale sets the native language to German, and the
following function (or something like it) has been executed:

        set_equivalent_literal("English", "Hello", "German", "Guten morgen")

The general idea is that you can write your program in your native
language, and someone can provide a table of equivalents for one or
more other languages -- not necessarily the author.

        With this idea, it should be possible to have docstrings
in more than one language, even if the author only used 
their native language. It would also support 'internationalising'
programs _without_ having to replace every literal in the program
with a function call.

        This is only an idea! 

        Hmm. Another idea. Just for docstrings. How about
a special __get_docstring__ hook that would do the conversion
for docstrings? In particular, it could lookup docstrings
in places _other_ than the standard place (bound to the object).

-------------------------------------------------------
John Skaller    email: skaller@maxtal.com.au
		http://www.maxtal.com.au/~skaller
		phone: 61-2-96600850
		snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia