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

• locate(1), grep(1)

• Chapter 9 of Python in a Nutshell