manweb: A CGI script to display man pages

This function attempts to send the file specified by manPath to man2html, capture its output, and send it to our standard output.

# - - -   c o n v e r t

def convert ( manPath ):
    """Convert a man page to HTML and display it.

      [ manPath is a string ->
          if manPath specifies a readable, valid man file ->
            sys.stdout  +:=  the output of man2html operating on
                             that file
          else ->
            sys.stdout  +:=  an error message as HTML ]
    """

The first complication is that the man file will be compressed with gzip, and man2html will not uncompress them. We can use zcat to uncompress it. So, the command we execute is a pipe of this form:

zcat file | man2html

    #-- 1 --
    command  =  "zcat %s|man2html" % manPath

The standard Python function os.popen() executes a shell command in a subprocess and returns a readable file handle that we can use to retrieve its output. If the command fails, we don't find out until we close the file; the .close() method returns a Boolean value, True if the operation failed, False if it succeeded.

    #-- 2 --
    # [ pipe  :=  an open file handle for reading the output of
    #             command ]
    pipe  =  os.popen ( command )

We have to retrieve the output before we can close the pipe and find out whether the operation failed. If it failed, it won't send us any data, so in that case this step does nothing.

    #-- 3 --
    # [ sys.stdout  +:=  contents of pipe ]
    sys.stdout.write ( pipe.read() )

    #-- 4 --
    # [ if pipe.close returns a false value ->
    #     I
    #   else ->
    #     sys.stdout  +:=  an error message in HTML ]
    status  =  pipe.close()
    if  status:
        errorPage ( "The man2html conversion step for file '%s' "
                    "failed." % manPath )