From 8f474a2431b2d03d9b2cbcf987c226499105de12 Mon Sep 17 00:00:00 2001 From: wolf Date: Wed, 21 Jun 2000 12:50:34 +0000 Subject: [PATCH] Add files that were added between 2.a35 and 2.a36. git-svn-id: https://svn.dealii.org/trunk@3047 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/contrib/kdoc/src/doc/index.docbook | 437 +++++++++++++++++++++ deal.II/contrib/kdoc/src/kdoc.spec.in | 62 +++ 2 files changed, 499 insertions(+) create mode 100644 deal.II/contrib/kdoc/src/doc/index.docbook create mode 100644 deal.II/contrib/kdoc/src/kdoc.spec.in diff --git a/deal.II/contrib/kdoc/src/doc/index.docbook b/deal.II/contrib/kdoc/src/doc/index.docbook new file mode 100644 index 0000000000..8edc33262e --- /dev/null +++ b/deal.II/contrib/kdoc/src/doc/index.docbook @@ -0,0 +1,437 @@ + + + + + +The KDOC Handbook +Write developer documentation, easily and quickly + + + +Sirtaj +Singh +Kang + + +
+taj@kde.org +
+ +10/11/1999 +2.0.0 + + + +0.1 +10/11/1999 +S.S.K + + + + +KDOC generates documentation in a +variety of formats, directly from C, C++ and IDL interface definitions. +KDOC uses specially formatted comments in +the source to allow customized documentation. + + + +KDOC +C++ +C +KDE Libraries +Documentation +API +Literate Programming + + +
+ + + + Introduction + + + What is KDOC? + KDOC generates documentation in a +variety of formats, directly from C, C++ and IDL interface definitions. +KDOC uses specially formatted comments in +the source to allow customized documentation. + +It is also very useful as a general class browser for libraries, +since the output is quickly navigable and many index views are +presented. + +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 COPYING +that comes with the distribution for the full text version of the +license. + + + + Features + + Support for C, C++ and OMG CORBA IDL languages. + + + Output in HTML, LaTeX, Manpage, Texinfo and + DocBook SGML formats. The DocBook format can in turn be + converted to various printable and online formats. + + + Automatically works out many relationships + between objects and their properties, such as hierarchies, + overridden virtuals, non-instantiable (abstract) classes and more. + + + Doc Comments are written in the javadoc style, + with many useful extensions for organizing, documenting + and presenting libraries. + + + Supports a CPP (preprocessor) pass + via an external preprocessor, to expand macros and + #ifdefs. + + Support for the Qt GUI Toolkit's signal and + slot specifiers. + + Cross-reference documentation generated for other + libraries. Links and class hierarchies that reference external + libraries are correctly shown. + + Includes makekdedoc, + an easy automake-like tool for generating documentation for + multiple libraries at once. + + Includes qt2kdoc, + which allows you to link your documentation with the Qt GUI + Toolkit's HTML documentation as if it had been generated by + KDOC itself. + + + An output mode that allows you to check for + errors or omissions in your documentation. + The application is written entirely in Perl, and + is therefore quite portable and extensible. + + + + + + History +Torben Weis weis@kde.org 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. + +Sirtaj Singh Kang taj@kde.org 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%. + +KDOC 1.0 still used some of Torben's source, but never really +worked properly but was useful enough for a year or so. + +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. + + + + + + + + Using KDOC + + + Support and Downloads + + + + +Web page +KDOC has a web page at +http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/. +It can be downloaded from there. + + + + +Via KDE CVS or CVSUp +You can checkout KDOC from the KDE CVS server in the module +kdoc. This is the repository used for KDOC development, +so it will always be up to date. + + + + +Mailing List +There is a KDOC mailing list hosted by the KDE project, at +kdoc-list@kde.org. To subscribe, mail +kdoc-list-request@kde.org +with subscribe in the message body (not the subject). + + + +The KDOC FAQ + +The KDOC FAQ has answers to common questions and problems with KDOC. + + + + +E-mail: The Last Resort +If all else fails, I will respond to decent questions via +email, but I cannot promise prompt replies. Mail the KDOC "team" at +kdoc@kde.org. + + + + + + + Installation + +Supported Environments +KDOC requires Perl 5.004 to function. +Most environments where this is installed are supported by KDOC. + +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. + + + + Building the distribution + +The procedure for building KDOC is similar to most other GPL programs that +come with a configure script. + + + +Unpack the distribution +Unpack the distribution into a temporary directory. It will extract +itself into its own directory. If you have downloaded the tar.bz2 version: + +# bunzip2 < kdoc-2.0a1.tar.bz2 | tar xf - + + +Or if you have downloaded the tar.gz version: + +# gunzip < kdoc-2.0a1.tar.gz | tar xf - + + +Replace the distribution file name in the above procedure with the one +you have downloaded. + + +Build the application +This will configure KDOC to install itself in +/usr/local/: + +# cd kdoc-2.0a1 +# ./configure + + +To install it in a different directory, +say /opt/kdoc, add a prefix option to configure like this: + +# ./configure --prefix=/opt/kdoc + + + + +Perform the installation + +# make; make install + + + +Remove the temporary directory + +# cd .. +# rm -rf kdoc-2.0a1 + + + +Now kdoc should be installed on your system. + + + + + KDOC at the command line + +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. + + + + + + + + Writing Documentation +Commenting Source +TODO: Explain doc comments. Explain tags. Examples. + + + Tips on Style +TODO: Various doc suggestions: internal/deprecated, short +descriptions, link to Qt documentation guidelines. + + + + + Frequently Asked Questions +TODO: No questions, no answers. + + + + Appendix A: Doc tag reference + + Doc Comments + TODO + + + Common tags + + + @li <text> + A list item. + + + @internal + Mark member as internal to the + library and not for external use. + + + @deprecated + Marks member as obsolete. + + + @version <string> + Provide version information about the + member. I normally set this to the RCS/CVS Id tag. + + + + @author <string> + Specify the author. + + + @since <string> + Specify the version of the API in which this + member was added. + + + @sect <string> + A section heading, for grouping your doc + comment logically. + + + <pre> text </pre> + A block of literal (preformatted) text, + useful for code examples. + + + @image <path> + 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. + + + @see <ref>,... + Links to related information. + + + @ref <ref> + 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. + + + + + + Tags for Library Documentation + 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. + + + + @libdoc <string> + Marks a doc comment as documentation for + the library. The string is used as the title of the + library. + + + + + + Tags for Classes + + + + @short <string> + Short description of the class, one + sentence long. + If class documentation is present but no short + description is specified, the first sentence (up to and + including the first period) is used instead. + + + + + + + Tags for Functions + + + @param <paramname> <text> + Documentation for a parameter. + No check is done whether the parameter name specified + is actually a parameter of the function. + + + + @return <text> + Documentation for the value returned by + the function. + + + @throws <ref>,... + Define the exceptions that may be thrown + from this function. Synonyms are: @exception and @raises. + + + + @param <paramname> <text> + Documentation for a parameter. + No check is done whether the parameter name specified + is actually a parameter of the function. + + + + + + +Appendix B: Utilities +qt2kdoc: Link with Qt HTML documentation + +makekdedoc: Generate docs for KDELIBS and other groups of libraries + + + +Appendix B: Other useful tools + +
diff --git a/deal.II/contrib/kdoc/src/kdoc.spec.in b/deal.II/contrib/kdoc/src/kdoc.spec.in new file mode 100644 index 0000000000..a33bb8dd42 --- /dev/null +++ b/deal.II/contrib/kdoc/src/kdoc.spec.in @@ -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 +- initial -- 2.39.5