]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Add files that were added between 2.a35 and 2.a36.
authorwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Wed, 21 Jun 2000 12:50:34 +0000 (12:50 +0000)
committerwolf <wolf@0785d39b-7218-0410-832d-ea1e28bc413d>
Wed, 21 Jun 2000 12:50:34 +0000 (12:50 +0000)
git-svn-id: https://svn.dealii.org/trunk@3047 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/contrib/kdoc/src/doc/index.docbook [new file with mode: 0644]
deal.II/contrib/kdoc/src/kdoc.spec.in [new file with mode: 0644]

diff --git a/deal.II/contrib/kdoc/src/doc/index.docbook b/deal.II/contrib/kdoc/src/doc/index.docbook
new file mode 100644 (file)
index 0000000..8edc332
--- /dev/null
@@ -0,0 +1,437 @@
+<!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 &lt; 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 &lt; 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 &lt;text&gt;</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 &lt;string&gt;</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 &lt;string&gt;</term>
+               <ListItem><para>Specify the author.</para></ListItem>
+       </VarListEntry>
+       <VarListEntry>
+               <term>@since &lt;string&gt;</term>
+               <ListItem><para>Specify the version of the API in which this
+               member was added.</para></ListItem>
+       </VarListEntry>
+       <VarListEntry>
+               <term>@sect &lt;string&gt;</term>
+               <ListItem><para>A section heading, for grouping your doc
+               comment logically.</para></ListItem>
+       </VarListEntry>
+       <VarListEntry>
+               <term>&lt;pre&gt; text &lt;/pre&gt;</term>
+               <ListItem><para>A block of literal (preformatted) text,
+               useful for code examples.</para></ListItem>
+       </VarListEntry>
+       <VarListEntry>
+               <term>@image &lt;path&gt;</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 &lt;ref&gt;,...</term>
+               <ListItem><para>Links to related information.</para></ListItem>
+       </VarListEntry>
+       <VarListEntry>
+               <term>@ref &lt;ref&gt;</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 &lt;string&gt;</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 &lt;string&gt;</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 &lt;paramname&gt; &lt;text&gt;</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 &lt;text&gt;</term>
+               <ListItem><para>Documentation for the value returned by
+               the function.</para></ListItem>
+       </VarListEntry>
+       <VarListEntry>
+               <term>@throws &lt;ref&gt;,...</term>
+               <ListItem><para>Define the exceptions that may be thrown
+               from this function. Synonyms are: @exception and @raises.
+               </para></ListItem>
+       </VarListEntry>
+       <VarListEntry>
+               <term>@param &lt;paramname&gt; &lt;text&gt;</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>
diff --git a/deal.II/contrib/kdoc/src/kdoc.spec.in b/deal.II/contrib/kdoc/src/kdoc.spec.in
new file mode 100644 (file)
index 0000000..a33bb8d
--- /dev/null
@@ -0,0 +1,62 @@
+# You might want to change the next 2 lines, the rest should be ok
+%define qtdir /usr/lib/qt-2.1.0
+Prefix: /opt/kde2
+
+Name: kdoc
+Icon: kde-icon.xpm
+Summary: Documentation tools for the K Desktop Environment (KDE) 2.0.
+Version: @VERSION@
+Release: 1
+Epoch: 1
+Source: ftp://ftp.kde.org/pub/kde/stable/%{version}/distribution/tar/generic/source/kdoc-%{version}.tar.bz2
+Group: Documentation
+BuildRoot: /var/tmp/%{name}-buildroot
+Copyright: GPL
+BuildArch: noarch
+
+%description
+Documentation tools for the K Desktop Environment 2.0.
+
+%prep
+rm -rf $RPM_BUILD_ROOT
+
+%setup -q -n %{name}
+make -f Makefile.cvs
+
+%build
+export KDEDIR=%{prefix} QTDIR=%{qtdir}
+CXXFLAGS="$RPM_OPT_FLAGS -I%{prefix}/include/kde" ./configure \
+       --prefix=%{prefix}
+make CXXFLAGS="$RPM_OPT_FLAGS -DNO_DEBUG -DNDEBUG"
+
+%install
+make install DESTDIR=$RPM_BUILD_ROOT
+
+cd $RPM_BUILD_ROOT
+find . -type d | sed '1,3d;s,^\.,\%attr(-\,root\,root) \%dir ,' > \
+       $RPM_BUILD_DIR/file.list.%{name}
+perl -pi -e "s|\%attr\(-,root,root\) \%dir %{prefix}/man/man1||" $RPM_BUILD_DIR/file.list.%{name}
+perl -pi -e "s|\%attr\(-,root,root\) \%dir %{prefix}/man||" $RPM_BUILD_DIR/file.list.%{name}
+perl -pi -e "s|\%attr\(-,root,root\) \%dir %{prefix}/bin||" $RPM_BUILD_DIR/file.list.%{name}
+perl -pi -e "s|\%attr\(-,root,root\) \%dir %{prefix}/lib$||" $RPM_BUILD_DIR/file.list.%{name}
+
+find . -type f | sed -e 's,^\.,\%attr(-\,root\,root) ,' \
+       -e '/\/config\//s|^|%config|' >> \
+       $RPM_BUILD_DIR/file.list.%{name}
+
+find . -type l | sed 's,^\.,\%attr(-\,root\,root) ,' >> \
+       $RPM_BUILD_DIR/file.list.%{name}
+
+sed -e "s,%{prefix}/man/.*,&*,g" $RPM_BUILD_DIR/file.list.%{name} >$RPM_BUILD_DIR/file.list.%{name}.new
+mv -f $RPM_BUILD_DIR/file.list.%{name}.new $RPM_BUILD_DIR/file.list.%{name}
+
+echo "%docdir %{prefix}/doc/kde" >> $RPM_BUILD_DIR/file.list.%{name}
+
+%clean
+rm -rf $RPM_BUILD_ROOT $RPM_BUILD_DIR/file.list.%{name}
+
+%files -f ../file.list.%{name}
+
+%changelog
+* Thu May 11 2000 Bernhard Rosenkraenzer <bero@redhat.com>
+- initial

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.