Hyperlinks to keywords and USENET searches in documentation

[Edward C. Jones]

"""I use GIMP to help me find the colors for my webpages. But
GIMP colors
are in base 10 while HTML uses base 16. I got tired of doing the
conversions
by hand so I wrote a pair of simple Python programs called "2hex"
and
"hex2". While writing this code, I had an experience that I have
had many
times before: trouble finding what I wanted in documentation.
Python
documentation is some of the best around, but these problems
still occur.

Here is the tale."""


#! /usr/bin/python

# It is easy to convert an integer into a string in hex format.
i = 123
print i, hex(i), '%X' % i

# But how do I convert a string in hex format into an integer?
First I try

try:
    i = int('0x3a')
except Exception, x:
    print str(x)

"""Perhaps the built-in function "hex" has an opposite. I go to
Library
Reference / 2.2 Built-in Functions and find nothing. Next I use
the UNIX
utility "grep" to search all the documentation text for the
letters "hex".
Nothing. I remember the C function "atoi". I remember that Python
has this
function in module "string". There I find "(Also note: for a more
flexible
interpretation of numeric literals, use the built-in function
eval().)"
Problem solved. I was in the wrong mental space."""

s = '0x3a'
print eval(s)

"""The only thing of interest in this story is the process. I
know a
collection of facts about some system. I use these facts to try
to uncover
another fact. If I succeed, I either write down a note somewhere
or memorize
a new fact. The more I know about a system, the easier this
process is.
Imagine the pain I went through the first time I installed Linux:
where are
the X configuration files for RedHat 4.2? And I didn't know the
word
"configuration"!

I would be helped by (automatically generated) keyword links.
Click on a
little icon at the documentation for "hex()" and find all other
places in
the documentation where the words "hexadecimal", "literal",
"OverflowError",
etc. occur. In some cases, sets of associated words will need to
be input
into the code that generates the links. For example, "hexadecimal
<--> base".

These sets of associated words can be useful in a broader
context. Suppose I
want to answer the question "How do I write programs that do
things with
images?" by searching the Internet. Once I find the first magic
phrase, say
"image processing", I probably can find others, "computer
vision", "image
understanding", "machine vision", "medical imaging", etc.

Here are some further examples:
   "statistics of records" --> "extreme value theory"
   "quit" --> "^D"
   "variables my program has defined" --> "namespaces", "vars",
"locals"
   "display a file" --> "cat"

I searched DejaNews for articles in comp.lang.python with the
word "newbie"
in the title. The first four articles listed that had answers got
me:
   "file selector dialog box" --> "tkFileDialog.py"
   "loading a graphical image using Tkinter and python" -->
"PhotoImage", "PIL"
   ">>>f=open('C:\Autoexec.bat')" --> "escape \"
   "does Python check white space" --> "indents"
Clearly, documenters should do searches for newbie questions.

Back to "hex()". As I wrote this, I searched comp.lang.python for
"hex OR
literal OR "word size" OR OverflowError" trying to locate
questions about
hex(). The results included:"""

import string
string.atoi(hex(150),0)
eval('0xf')
string.atoi('0xf', 16)

"""and a _lot_ of other stuff. It might be useful to embed canned
news
article searches into the documentation. Is there a better search
string to
use? Is there any software that can help eliminate irrelevent
answers?"""

"""
#=== 2hex.py ==================================================

import sys

if len(sys.argv) < 2:
    raise Exception, 'Must have at least one argument.'

for i in range(1, len(sys.argv)):
    print '%X' % int(sys.argv[i]),

print

#=== hex2.py ==================================================

import sys

if len(sys.argv) < 2:
    raise Exception, 'Must have at least one argument.'

for i in range(1, len(sys.argv)):
    print eval('0x' + sys.argv[i]),

print
"""