"""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
"""