<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "<application>KDOC</application>">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>        

<book lang="&language;">

<bookinfo>
<title>The <application>KDOC</application> Handbook</title>
<subtitle>Write developer documentation, easily and quickly</subtitle>

<authorgroup>
<author>
<firstname>Sirtaj</firstname>
<othername>Singh</othername>
<surname>Kang</surname>
</author>
</authorgroup>
<address>
<email>taj@kde.org</email>
</address>

<copyright>
<year>1999</year>
<year>2000</year>
<holder>Sirtaj Singh Kang</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>17/11/2000</date>
<releaseinfo>2.0.0</releaseinfo>

<abstract><para><application>KDOC</application> generates documentation in a
variety of formats, directly from C, C++ and IDL interface
definitions. <application>KDOC</application> uses specially formatted comments
in the source to allow customized documentation.</para></abstract>

<keywordset>
<keyword>KDOC</keyword>
<keyword>C++</keyword>
<keyword>C</keyword>
<keyword>KDE Libraries</keyword>
<keyword>Documentation</keyword>
<keyword>API</keyword>
<keyword>Literate Programming</keyword>
</keywordset>

</bookinfo>


<chapter id="introduction">
<title>Introduction</title>

<sect1 id="what-is-kdoc">
<title>What is <application>KDOC</application>?</title>

<para> <application>KDOC</application> generates documentation in a
variety of formats, directly from C, C++ and IDL interface definitions.
<application>KDOC</application> uses specially formatted comments in
the source to allow customized documentation.</para>

<para>It is also very useful as a general class browser for libraries, since the
output is quickly navigable and many index views are presented.</para>

</sect1>

<sect1 id="features">
<title>Features</title>

<itemizedlist>
<listitem><para>Support for C, C++ and <acronym>OMG</acronym>
<acronym>CORBA</acronym> <acronym>IDL</acronym> languages.</para></listitem>
<listitem><para>Output in <acronym>HTML</acronym>,
<application>LaTeX</application>, Manpage, Texinfo and DocBook
<acronym>SGML</acronym> formats. The DocBook format can in turn be converted to
various printable and online formats.</para></listitem>
<listitem><para>Automatically works out many relationships between objects and
their properties, such as hierarchies, overridden virtuals, non-instantiable
(abstract) classes and more.</para></listitem>
<listitem><para>Doc Comments are written in the javadoc style, with many useful
extensions for organizing, documenting and presenting
libraries.</para></listitem>
<listitem><para>Supports a <application>CPP</application> (preprocessor) pass
via an external preprocessor, to expand macros and
<systemitem>#ifdefs</systemitem>.</para></listitem>
<listitem><para>Support for the Qt <acronym>GUI</acronym> Toolkit's signal and
slot specifiers.</para></listitem>
<listitem><para>Cross-reference documentation generated for other
libraries. Links and class hierarchies that reference external libraries are
correctly shown.</para></listitem>
<listitem><para>Includes <application>makekdedoc</application>, an easy
automake-like tool for generating documentation for multiple libraries at
once.</para></listitem>
<listitem><para>Includes <application>qt2kdoc</application>, which allows you to
link your documentation with the Qt <acronym>GUI</acronym> Toolkit's
<acronym>HTML</acronym> documentation as if it had been generated by
<application>KDOC</application> itself. </para></listitem>
<listitem><para>An output mode that allows you to check for errors or omissions
in your documentation.</para></listitem> 
<listitem><para>The application is written entirely in
<application>Perl</application>, and  is therefore quite portable and
extensible.</para></listitem>
</itemizedlist>

</sect1>

<sect1 id="history">
<title>History</title>

<para>Torben Weis <email>weis@kde.org</email> wrote a perl script that
proved how simple it was to parse the KDE Library headers to generate
documentation that looked like the Qt documentation.  </para>

<para>Sirtaj Singh Kang <email>taj@kde.org</email> took it upon himself to
extend this program to turn it into a full-fledged application. He found out the
hard way that while it takes 10% effort to parse 75% of source, the next 10%
takes another 100%.  </para>

<para><application>KDOC</application> 1.0 still used some of Torben's source,
but never really worked properly but was useful enough for a year or so.</para>

<para><application>KDOC</application> 2.0 is a complete rewrite of
<application>KDOC</application>, and is much more extensible and robust, even
though it has scores of new features that were impossible to put into
1.0.</para>

</sect1>

</chapter>

<chapter id="using-kdoc">
<title>Using <application>KDOC</application></title>

<sect1 id="support-and-downloads">
<title>Support and Downloads</title>

<variablelist>
<varlistentry>
<term id="web">Web page</term>
<listitem><para><application>KDOC</application> has a web page at <ulink
url="http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/">http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/</ulink>. It can be downloaded from there.</para></listitem>
</varlistentry>

<varlistentry>
<term id="cvs">Via KDE <acronym>CVS</acronym> or
<application>CVSup</application></term>
<listitem><para>You can checkout <application>KDOC</application> from the KDE
<acronym>CVS</acronym> server in the module <quote>kdoc</quote>. This is the
repository used for <application>KDOC</application> development, so it will
always be up to date.</para></listitem>
</varlistentry>

<varlistentry>
<term id="mlist">Mailing List</term>
<listitem><para>There is a <application>KDOC</application> mailing list hosted
by the KDE project, at  <email>kdoc-list@kde.org</email>. To subscribe, mail
<email>kdoc-list-request@kde.org</email> with <userinput>subscribe</userinput>
in the message body (not the subject).</para></listitem>
</varlistentry>

<varlistentry>
<term id="faqref">The <application>KDOC</application>
<acronym>FAQ</acronym></term>
<listitem><para>The <application>KDOC</application> <acronym>FAQ</acronym> has
answers to common questions and problems with
<application>KDOC</application>.</para></listitem>
</varlistentry>

<varlistentry>
<term id="email">Email: the last resort</term>
<listitem><para>If all else fails, I will respond to decent questions via email,
but I cannot promise prompt replies. Mail the <application>KDOC</application>
<quote>team</quote> at <email>kdoc@kde.org</email>.</para></listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="installation">
<title>Installation</title>

<sect2 id="sys">
<title>Supported Environments</title>

<para><application>KDOC</application> requires <application>Perl
5.004</application> to function. Most environments where this is installed are
supported by <application>KDOC</application>.</para>

<para><application>KDOC</application> has been reported to run to some extent on
&Microsoft; &Windows; (NT/95/98) but you may encounter some problems with
filenames. Also, you will probably have to hack the install scripts and file
locations manually since the  configure script only works on  &UNIX;.</para>

</sect2>

<sect2 id="build">
<title>Building the distribution</title>

<para>The procedure for building <application>KDOC</application> is similar to
most other GPL programs that come with a <application>configure</application>
script.</para>

<procedure>
<step><title>Unpack the distribution</title>
<para>Unpack the distribution into a temporary directory. It will extract
itself into its own directory. If you have downloaded the <literal
role="extension">tar.bz2</literal> version:</para>
<screen><prompt>#</prompt> <userinput><command>bunzip2</command> &lt; <filename>kdoc-2.0a1.tar.bz2</filename> | <command>tar</command> <option>xf</option> -</userinput></screen>

<para>Or if you have downloaded the <literal role="extension">tar.gz</literal>
version:</para>
<screen><prompt>#</prompt> <userinput><command>gunzip</command> &lt; <filename>kdoc-2.0a1.tar.gz</filename> | <command>tar</command> <option>xf</option> -</userinput></screen>
<para>Replace the distribution file name in the above procedure with the one you
have downloaded.</para></step>

<step><title>Build the application</title>
<para>This will configure <application>KDOC</application> to install itself in
<filename class="directory">/usr/local/</filename>:</para>
<screen>
<prompt>#</prompt> <userinput><command>cd</command> <replaceable>kdoc-2.0a1</replaceable></userinput>
<prompt>#</prompt> <userinput><command>./configure</command></userinput>
</screen>
<para>To install it in a different directory, say <filename
class="directory">/opt/kdoc</filename>, add a prefix option to configure like
this:</para>
<screen><prompt>#</prompt> <userinput><command>./configure</command> <option>--prefix=<replaceable>/opt/kdoc</replaceable></option></userinput>
</screen>
</step>
<step><title>Perform the installation</title>
<screen><prompt>#</prompt> <userinput><command>make</command>; <command>make</command> <option>install</option></userinput></screen>
</step>
<step><title>Remove the temporary directory</title>
<screen><prompt>#</prompt> <userinput><command>cd</command> <option>..</option></userinput>
<prompt>#</prompt> <userinput><command>rm</command> <option>-rf</option> <parameter><replaceable>kdoc-2.0a1</replaceable></parameter></userinput>
</screen>
</step>
</procedure>
<para>Now <application>KDOC</application> should be installed on your
system.</para>
</sect2>
</sect1>

<sect1 id="cmdline">
<title><application>KDOC</application> at the command line</title>

<para>The most up-to-date source for command line options is always
the man page that is distributed with the application. This section will provide
a general overview of how to run the program.</para>

</sect1>

</chapter>

<chapter id="writing-kdoc">
<title>Writing Documentation</title>

<sect1 id="commenting-source">
<title>Commenting Source</title>

<para>TODO: Explain doc comments. Explain tags. Examples.</para>

</sect1>

<sect1 id="commenting-style">

<title>Tips on Style</title>

<para>TODO: Various doc suggestions: internal/deprecated, short descriptions,
link to Qt documentation guidelines.</para>

</sect1>

</chapter>

<chapter id="faq">
<title>Frequently Asked Questions</title>

<para>TODO: No questions, no answers.</para>

</chapter>

<chapter id="credits">
<title>Credits and Licenses</title>

<para><application>KDOC</application></para>

<para>Copyright 1999-2000 Sirtaj Singh Khan <email>taj@kde.org</email></para>

<para>Documentation Copyright 1999-2000 Sirtaj Singh Khan
<email>taj@kde.org</email></para>

&underFDL;
&underGPL;

</chapter>

<appendix id="doctagref">
<title>Doc tag reference</title>

<sect1 id="tags-doc-comment">
<title>Doc Comments</title>
<para>TODO</para>

</sect1>

<sect1 id="tags-common">
<title>Common tags</title>

<variablelist>
<varlistentry>
<term><markup>@li &lt;text&gt;</markup></term>
<listitem><para>A list item.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@internal</markup></term>
<listitem><para>Mark member as internal to the library and not for external
use.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@deprecated</markup></term>
<listitem><para>Marks member as obsolete.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@version &lt;string&gt;</markup></term>
<listitem><para>Provide version information about the member. I normally set
this to the <application>RCS</application>/<application>CVS</application>
<acronym>ID</acronym> tag.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@author &lt;string&gt;</markup></term>
<listitem><para>Specify the author.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@since &lt;string&gt;</markup></term>
<listitem><para>Specify the version of the <acronym>API</acronym> in which this
member was added.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@sect &lt;string&gt;</markup></term>
<listitem><para>A section heading, for grouping your doc comment
logically.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>&lt;pre&gt; text &lt;/pre&gt;</markup></term>
<listitem><para>A block of literal (preformatted) text, useful for code
examples.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@image &lt;path&gt;</markup></term>
<listitem><para>Embed an image in the output. This can be set to a
<acronym>URL</acronym>, but it is better to use a path if possible since this
will allow the image to be included in other formats in the
future.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@see &lt;ref&gt;,...</markup></term>
<listitem><para>Links to related information.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@ref &lt;ref&gt;</markup></term>
<listitem><para>Like <markup>@see</markup>, but inline, so it can be used within
a text paragraph. Also, only one member can be referenced at a time, so you will
have to include multiple <markup>@ref</markup> tags for multiple
members.</para></listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="tags-lib-doc">
<title>Tags for Library Documentation</title>

<para>To provide documentation for the entire library, use the
<markup>@libdoc</markup> tag within a doc comment. If this appears in a doc
comment, the comment is associated with the library instead of with the
following syntax member.</para>

<variablelist>
<varlistentry>
<term><markup>@libdoc &lt;string&gt;</markup></term>
<listitem><para>Marks a doc comment as documentation for the library. The string
is used as the title of the library.</para></listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="tags-class">
<title>Tags for Classes</title>

<variablelist>
<varlistentry>
<term><markup>@short &lt;string&gt;</markup></term>
<listitem><para>Short description of the class, one sentence long.</para>
<para>If class documentation is present but no short description is specified,
the first sentence (up to and including the first period) is used instead.
</para></listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="tags-functions">
<title>Tags for Functions</title>

<variablelist>
<varlistentry>
<term><markup>@param &lt;paramname&gt; &lt;text&gt;</markup></term>
<listitem><para>Documentation for a parameter. No check is done whether the
parameter name specified is actually a parameter of the
function.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@return &lt;text&gt;</markup></term>
<listitem><para>Documentation for the value returned by the
function.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@throws &lt;ref&gt;,...</markup></term>
<listitem><para>Define the exceptions that may be thrown from this
function. Synonyms are: <markup>@exception</markup> and
<markup>@raises</markup>.</para></listitem>
</varlistentry>

<varlistentry>
<term><markup>@param &lt;paramname&gt; &lt;text&gt;</markup></term>
<listitem><para>Documentation for a parameter.  No check is done whether the
parameter name specified is actually a parameter of the
function.</para></listitem>
</varlistentry>
</variablelist>

</sect1>

</appendix>

<appendix id="utils">
<title>Utilities</title>

<sect1 id="qt2kdoc">
<title><application>qt2kdoc</application>: Link with &Qt;
<acronym>HTML</acronym> documentation</title>

<para></para>

</sect1>

<sect1 id="makekdedoc">
<title><application>makekdedoc</application>: Generate docs for KDELIBS and
other groups of libraries</title>

<para></para>

</sect1>

</appendix>

<appendix id="appendixc">
<title>Other useful tools</title>

<para></para>

</appendix>

</book>



