--- /dev/null
+<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+]>
+
+<book lang="EN">
+
+<bookinfo>
+<title>The KDOC 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>
+
+<date>10/11/1999</date>
+<releaseinfo>2.0.0</releaseinfo>
+
+<revhistory>
+<revision>
+<revnumber>0.1</revnumber>
+<date>10/11/1999</date>
+<authorinitials>S.S.K</authorinitials>
+</revision>
+</revhistory>
+
+<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="whatiskdoc">
+ <title>What is KDOC?</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>
+
+<para>KDOC is distributed under the GNU General Public License. In short,
+this allows you to modify and redistribute the package as much as you
+like, but all modifications will automatically also fall under the
+GNU General Public License. See the file <filename>COPYING</filename>
+that comes with the distribution for the full text version of the
+license.</para>
+</Sect1>
+
+<Sect1 id="features">
+ <title>Features</title>
+ <ItemizedList Spacing="Normal">
+ <ListItem><para>Support for C, C++ and OMG CORBA IDL languages.
+ </para></ListItem>
+
+ <ListItem><para>Output in HTML, LaTeX, Manpage, Texinfo and
+ DocBook SGML 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 CPP (preprocessor) pass
+ via an external preprocessor, to expand macros and
+ <SystemItem>#ifdefs</SystemItem>. </para></ListItem>
+
+ <ListItem><para>Support for the Qt GUI 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 GUI
+ Toolkit's HTML 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 Perl, 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>KDOC 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>KDOC 2.0 is a complete rewrite of KDOC, 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="usingkdoc">
+ <title>Using KDOC</title>
+
+<sect1 ID="Support-and-Downloads">
+ <title>Support and Downloads</title>
+
+<ItemizedList Spacing="Normal">
+
+<ListItem id="web">
+<epigraph><para>Web page</para></epigraph>
+<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>
+
+<ListItem id="cvs">
+<epigraph><para>Via KDE CVS or CVSUp</para></epigraph>
+<para>You can checkout KDOC from the KDE CVS server in the module
+<userinput>kdoc</userinput>. This is the repository used for KDOC development,
+so it will always be up to date.
+</para>
+</ListItem>
+
+<ListItem id="mlist">
+<epigraph><para>Mailing List</para></epigraph>
+<para>There is a KDOC 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>
+
+<ListItem id="faqref"><epigraph><para>The KDOC FAQ</para></epigraph>
+<para>
+The KDOC FAQ has answers to common questions and problems with KDOC.
+</para>
+</ListItem>
+
+<ListItem id="email">
+<epigraph><para>E-mail: The Last Resort</para></epigraph>
+<para>If all else fails, I will respond to decent questions via
+email, but I cannot promise prompt replies. Mail the KDOC "team" at
+<email>kdoc@kde.org</email>.</para>
+</ListItem>
+</ItemizedList>
+</sect1>
+
+
+<Sect1 ID="Installation">
+ <title>Installation</title>
+<Sect2 id="sys">
+<title>Supported Environments</title>
+<para>KDOC requires <application>Perl 5.004</application> to function.
+Most environments where this is installed are supported by KDOC.
+</para>
+<para>KDOC has been reported to run to some extent on Win32 (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 KDOC 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 tar.bz2 version:
+<screen>
+<prompt>#</prompt> <userinput>bunzip2 < kdoc-2.0a1.tar.bz2 | tar xf -</userinput>
+</screen>
+</para>
+<para>Or if you have downloaded the tar.gz version:
+<screen>
+<prompt>#</prompt> <userinput>gunzip < kdoc-2.0a1.tar.gz | tar xf -</userinput>
+</screen>
+</para>
+<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 KDOC to install itself in
+<filename>/usr/local/</filename>:
+<screen>
+<prompt>#</prompt> <userinput>cd kdoc-2.0a1</userinput>
+<prompt>#</prompt> <userinput>./configure</userinput>
+</screen>
+</para>
+<para>To install it in a different directory,
+say <filename>/opt/kdoc</filename>, add a prefix option to configure like this:
+<screen>
+<prompt>#</prompt> <userinput>./configure --prefix=/opt/kdoc</userinput>
+</screen>
+</para>
+</step>
+<step>
+<title>Perform the installation</title>
+<screen>
+<prompt>#</prompt> <userinput>make; make install</userinput>
+</screen>
+</step>
+<step>
+<title>Remove the temporary directory</title>
+<screen>
+<prompt>#</prompt> <userinput>cd ..</userinput>
+<prompt>#</prompt> <userinput>rm -rf kdoc-2.0a1</userinput>
+</screen>
+</step>
+</procedure>
+<para>Now kdoc should be installed on your system.</para>
+</Sect2>
+</Sect1>
+
+<Sect1 ID="cmdline">
+ <title>KDOC at the command line</title>
+<abstract>
+<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>
+</abstract>
+</Sect1>
+
+</chapter>
+
+
+<chapter ID="writingkdoc">
+ <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="AppendixA">
+ <title>Appendix A: Doc tag reference</title>
+<Sect1 id="tagsdoccmt">
+ <title>Doc Comments</title>
+ <para>TODO</para>
+</Sect1>
+<Sect1 id="tagscommon">
+ <title>Common tags</title>
+ <VariableList>
+ <VarListEntry>
+ <term>@li <text></term>
+ <ListItem><para>A list item.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@internal</term>
+ <ListItem><para>Mark member as internal to the
+ library and not for external use.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@deprecated</term>
+ <ListItem><para>Marks member as obsolete.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@version <string></term>
+ <ListItem><para>Provide version information about the
+ member. I normally set this to the RCS/CVS Id tag.
+ </para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@author <string></term>
+ <ListItem><para>Specify the author.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@since <string></term>
+ <ListItem><para>Specify the version of the API in which this
+ member was added.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@sect <string></term>
+ <ListItem><para>A section heading, for grouping your doc
+ comment logically.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term><pre> text </pre></term>
+ <ListItem><para>A block of literal (preformatted) text,
+ useful for code examples.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@image <path></term>
+ <ListItem><para>Embed an image in the output. This can be
+ set to a URL, 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>@see <ref>,...</term>
+ <ListItem><para>Links to related information.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@ref <ref></term>
+ <ListItem><para>Like @see, 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
+ @ref tags for multiple members.</para></ListItem>
+ </VarListEntry>
+
+ </VariableList>
+</Sect1>
+<Sect1 id="tagslibdoc">
+ <title>Tags for Library Documentation</title>
+ <para>To provide documentation for the entire library, use the
+ @libdoc 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>@libdoc <string></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="tagsclass">
+ <title>Tags for Classes</title>
+
+ <VariableList>
+ <VarListEntry>
+ <term>@short <string></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>
+ </VariableList>
+
+</Sect1>
+<Sect1 id="tagsfun">
+ <title>Tags for Functions</title>
+ <VariableList>
+ <VarListEntry>
+ <term>@param <paramname> <text></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>@return <text></term>
+ <ListItem><para>Documentation for the value returned by
+ the function.</para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@throws <ref>,...</term>
+ <ListItem><para>Define the exceptions that may be thrown
+ from this function. Synonyms are: @exception and @raises.
+ </para></ListItem>
+ </VarListEntry>
+ <VarListEntry>
+ <term>@param <paramname> <text></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>
+</chapter>
+
+<chapter ID="AppendixB"><title>Appendix B: Utilities</title>
+<Sect1 id="qt2kdoc"><title>qt2kdoc: Link with Qt HTML documentation</title>
+</Sect1>
+<Sect1 id="makekdedoc"><title>makekdedoc: Generate docs for KDELIBS and other groups of libraries</title>
+</Sect1>
+</chapter>
+
+<chapter ID="AppendixC"><title>Appendix B: Other useful tools</title></chapter>
+
+</book>