Recipe 1.11. Finding All of the Documentation for a Program
1.11.1 Problem
You want to find
all the relevant readmes, changelogs, howtos, guides, examples,
samples, and other documentation that accompanies your installed
programs.
1.11.2 Solution
Use finddoc, that wonderful Python script that
comes to you courtesy of the excellent Akkana Peck.
You can call it anything you like. Remember to make it executable:
$ chmod +x finddoc
Using it requires only the script name and the name of the program
for which you need the documentation. For example:
$ ./finddoc grep
/usr/share/doc/grep
/usr/share/doc/grep-dctrl
/usr/share/doc/grep-dctrl/changelog.gz
...
The output can be filtered through other commands, or redirected to a
file:
$ ./finddoc | grep -i examples | lpr
$ ./finddoc | grep -i faq
$ ./finddoc | grep -i examples > python-examples.txt
1.11.3 Program: finddoc
#!/usr/bin/env python
# Finddoc: A Script For Finding Linux Program Documentation
# When making your own copy of this script, be sure to
# preserve the leading spaces exactly as they are written
# here, because Python needs them.
# Search for documentation related to the given strings;
# case-insensitive, and whole-word only.
# Relies on "locate" and assumes that the locate
# database is current.
#
# Copyright 2003 by Akkana Peck.
# You may use, distribute or modify this program
# under the terms of the GPL.
import sys, os, string, re
# This is the list of document-related filenames
# to search for. You may edit this list as needed.
# Be sure to add only lowercase names.
docfilenames = [
"changelog",
"readme",
"install",
"howto",
"authors",
"news",
"todo",
"config",
"sample",
"samples",
"example",
"examples",
"ref",
"guide",
"manual",
"quickstart",
"thanks",
"notes",
"features",
"faq",
"acknowledgement",
"bugs",
"problems"
]
def system_out (cmdstr) :
retlist = [ ]
fp = os.popen(cmdstr)
while 1:
s = fp.readline( )
if not s : break
retlist.append(s)
fp.close( )
return retlist
# main( )
for arg in sys.argv :
#print string.split(arg, " \t./")
files = system_out("locate " + arg + " | grep -w " + arg);
for path in files :
#print path
# Special case for anything with "man", "doc", or "info" in the path:
if (string.find(path, "/man") >= 0) \
or (string.find(path, "/doc") >= 0) \
or (string.find(path, "/info") >= 0) :
print path,
)
continue
# Now see if it matches any of the docfilenames:
base = os.path.basename(path)
for nam in docfilenames :
if base = = "" : continue
# Non full word search would use this:
:
# Full-word-search:
# Make a regexp to search for nam as full-word only
pat = "^" + nam + "$"
if (re.compile(nam).search(base, 1)) :
print path,
base = ""
continue
1.11.4 See Also
|
