<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY dhusername  "Doug Hellmann">
  <!ENTITY dhpackage   "happydoc">
]>

<refentry>
  <refentryinfo>
    <address>
      <email>hgebel@home.com</email>
    </address>
    <author>
      <firstname>Harry</firstname>
      <othername>Henry</othername>
      <surname>Gebel</surname>
    </author>
    <copyright>
      <year>2001</year>
      <holder>&dhusername;</holder>
    </copyright>
    <date>March 30, 2001</date>
  </refentryinfo>
  <refmeta>
    <refentrytitle>HAPPYDOC</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>
    
    <refpurpose>Python Documentation Extraction Tool</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg><option>-hoqrv</option></arg>
      <arg><option>-F <replaceable>format</replaceable></option></arg>
      <arg><option>-T <replaceable>docset_type</replaceable></option></arg>
      <arg><option>-d <replaceable>outputDirectory</replaceable></option></arg>
      <arg><option>-i <replaceable>ignoreDirectory</replaceable></option></arg>
      <arg><option>-p <replaceable>packageDescriptionFile</replaceable></option></arg>
      <arg><option>-t <replaceable>title</replaceable></option></arg>
      <arg><option>--help</option></arg>
      <arg><option>--dia</option></arg>
      <arg><option>--no_comments</option></arg>
      <arg><option>--no_private_names</option></arg>
      <arg><option>--author=<replaceable>authorNameAndEmail</replaceable></option></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>
    
    <para>This manual page documents briefly the
      <command>&dhpackage;</command> command.</para>
    
    <para>This manual page was written for the <productname>Debian
	GNU/Linux</productname> distribution because the original program does
      not have a manual page.</para>
    
    <para><command>&dhpackage;</command> is a documentation
      generation/extraction tool which does not depend on being able to
      import modules; it is based on the Demos/parser/example.py module
      distributed with the Python source distribution.</para>
    
  </refsect1>
  <refsect1>
    <title>OPTIONS</title>
    
    <variablelist>
      <varlistentry>
	<term><option>-h</option>
	</term>
	<listitem>
	  <para>Displays abbreviated help message.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-help</option>
	</term>
	<listitem>
	  <para>Displays complete usage information.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-F <replaceable>format</replaceable></option>
	</term>
	<listitem>
	  <para>Specify the output format.</para>
	  <para>Defaults to <symbol>HTMLTable</symbol>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-T <replaceable>docset_type</replaceable></option>
	</term>
	<listitem>
	  <para>Specify the documentation set type.</para>
	  <para>Defaults to <symbol>multifile_docset</symbol>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--author=<replaceable>authorNameAndEmail</replaceable></option>
	</term>
	<listitem>
	  <para>Specify the author identification to be inserted for
	    references.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-d <replaceable>outputDirectory</replaceable></option>
	</term>
	<listitem>
	  <para>Specify an outputDirectory.</para>
	  <para>Defaults to <filename>./doc</filename>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--dia</option></term>
	<listitem>
	  <para>Generate UML diagram in Gnome dia format.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-i <replaceable>ignoreDirectory</replaceable></option>
	</term>
	<listitem>
	  <para>Specify a directory basename to be ignored.</para>
	  <para>Use just the
	    base name of the directory.  For instance, to ignore all
	    directories with the name CVS, specify: -i CVS.</para>
	  <para>Defaults to
	    ignore: <filename>CVS</filename>, <filename>dist</filename>,
	    <filename>build</filename>, <filename>doc</filename>,
	    <filename>docs</filename>.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--no_comments</option>
	</term>
	<listitem>
	  <para>Do not include comment text as though it was
	    a __doc__ string.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>--no_private_names</option>
	</term>
	<listitem>
	  <para>Do not include names beginning with _.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-o</option>
	</term>
	<listitem>
	  <para>Specify that output should go to stdout.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-p <replaceable>packageDescriptionFile</replaceable></option>
	</term>
	<listitem>
	  <para>Specify a file with a description of the package.</para>
	  <para>The default packageDescriptionFile is README.txt.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-q</option>
	</term>
	<listitem>
	  <para>Turn on quiet mode.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-r</option>
	</term>
	<listitem>
	  <para>Disable recursion into subdirectories.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-t <replaceable>title</replaceable></option>
	</term>
	<listitem>
	  <para>Specify a title for the documentation set.</para>
	</listitem>
      </varlistentry>
      
      <varlistentry>
	<term><option>-v</option>
	</term>
	<listitem>
	  <para>Increment the verbose level.  Higher levels are more
	    verbose.  The default is 1.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  
  <refsect1>
    <title>SUPPORTED FORMATS for -F Option</title>
    
    <refsect2>
      <title>FORMATTER TYPE htmltable: Formatter which produces HTML with
	tables.</title>

      <para>The output from this formatter is not generally suitable for
	printing, but works fine for online documentation.  The primary
	concern with printing the output is that the nested tables can cause
	pages to be very wide, especially with a lot of nesting of classes.
	Printable HTML output should be addressed by another
	formatter.</para>
      
      <variablelist>
	<title>Parameters</title>
	<varlistentry>
	  <term>compactHTML</term>
	  <listitem>
	    <para>A boolean switch to cause the formatter to generate more
	      compact HTML.  Extra whitespace is removed in order to make the
	      generated files take up less space and x download more quickly.
	      The default is False to cause output to be more
	      readable.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>filenamePrefix</term>
	  <listitem>
	    <para>A prefix to preprend to the base names of files and
	      directories being created.  This is useful for situations where
	      the names which would be automatically generated might cause a
	      name clash or conflict.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>pageBackgroundColor</term>
	  <listitem>
	    <para>Background color for HTML pages</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>levelOneHeadingBackgroundColor</term>
	  <listitem>
	    <para>Background color for level
	      one heading sections.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>levelOneHeadingForegroundColor</term>
	  <listitem>
	    <para>Foreground color for level
	      one heading sections.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>levelTwoHeadingBackgroundColor</term>
	  <listitem>
	    <para>Background color for level
	      two heading sections.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>levelTwoHeadingForegroundColor</term>
	  <listitem>
	    <para>Foreground color for level
	      two heading sections.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>codeForegroundColor</term>
	  <listitem>
	    <para>Foreground color for code blocks.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>dateStampFiles</term>
	  <listitem>
	    <para>Boolean indicating whether or not to include
	      a date/time stamp in files.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>htmlQuoteText</term>
	  <listitem>
	    <para>Boolean indicating whether or not to assume that
	      docstrings need to be quoted because they might have special
	      HTML characters in them.  Defaults to true so that text is
	      quoted.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>debug</term>
	  <listitem>
	    <para>Enable debugging comments in output.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
      
    </refsect2>
    
    <refsect2>
      <title>FORMATTER TYPE null: None</title>
      <para></para>
    </refsect2>
    <refsect2>
      <title>FORMATTER TYPE sgmldocbook: Formatter which produces simple DocBook SGML.</title>
      <para></para>
    </refsect2>
    <refsect2>
      <title>FORMATTER TYPE text: Formatter which produces plain ASCII
	text.</title>
      <variablelist>
	<varlistentry>
	  <term>filenamePrefix</term>
	  <listitem>
	    <para> A prefix to append to the base names of files and
	      directories being created.  This is useful for situations where
	      the names which would be automatically generated might cause a
	      name clash or conflict.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect2>    
  </refsect1>
  
  <refsect1>
    <title>SUPPORTED DOCSET TYPES for -T Option</title>

    <refsect2>
      <title>Basic DocSet Parameters</title>
      <variablelist>
	<title>Parameters</title>
	<varlistentry>
	  <term>includeComments</term>
	  <listitem>
	    <para>Boolean.  False means to skip the comment parsing step in
	      the parser.  Default is True.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>includePrivateNames</term>
	  <listitem>
	    <para>Boolean.  False means to ignore names beginning with _.
	      Default is True.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>usePackages</term>
	  <listitem>
	    <para>Boolean.  True means to provide special handling for
	      Packages (directories containing __init__.py files) from
	      non-package Modules.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>prewrittenFileBasenames</term>
	  <listitem>
	    <para>Base names (no extensions) of StructuredText files which
	      are to be converted to the output format and included in the
	      docset.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>statusMessageFunc</term>
	  <listitem>
	    <para>function which will print a status
	      message for the user</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>title</term>
	  <listitem>
	    <para>the title of the documentation set</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>useRecursion</term>
	  <listitem>
	    <para>Recurse into subdirectories looking for
	      subdirectories and files within them.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </refsect2>

    <refsect2>
      <title>DOCSET TYPE: multifile_docset: Documentation set written to multiple files.</title>
      <para></para>
    </refsect2>

    <refsect2>
      <title>DOCSET TYPE: singlefile: Documentation which writes output to a single file.</title>
      <para></para>
    </refsect2>

    <refsect2>
      <title>DOCSET TYPE: stdout: Documentation set which writes output to standard output.</title>
      <para>No additional parameters</para>
    </refsect2>

  </refsect1>
  
  <refsect1>
    <title>SEE ALSO</title>
    <para>Full HTML documentation is provided in /usr/share/doc/happydoc-doc
      (contained in the happydoc-doc package).</para>
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>This manual page was converted from happydoc's --help message by
      Harry Henry Gebel <email>hgebel@home.com</email> for
      the <productname>Debian GNU/Linux</productname> system (but may be
      used by others).  HappyDoc amd it's documentations are copyrighted by
      &dhusername; and are distributed under a BSD style license found in
      /usr/share/doc/python-happydoc/copyright.</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->