From acfd1faf4ca7134c566211b52d4437086b95660a Mon Sep 17 00:00:00 2001 From: wolf Date: Thu, 11 Feb 1999 09:04:12 +0000 Subject: [PATCH] Move the kdoc script to this directory also. It used to be in the deal.II library, but that does not seem to be the proper place. git-svn-id: https://svn.dealii.org/trunk@780 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/doc/auto/scripts/kdoc/Ast.pm | 93 ++ deal.II/doc/auto/scripts/kdoc/kdoc | 1298 +++++++++++++++++++++ deal.II/doc/auto/scripts/kdoc/kdocHTML.pm | 930 +++++++++++++++ deal.II/doc/auto/scripts/kdoc/kdocMan.pm | 379 ++++++ deal.II/doc/auto/scripts/kdoc/kdocTeX.pm | 291 +++++ 5 files changed, 2991 insertions(+) create mode 100644 deal.II/doc/auto/scripts/kdoc/Ast.pm create mode 100644 deal.II/doc/auto/scripts/kdoc/kdoc create mode 100644 deal.II/doc/auto/scripts/kdoc/kdocHTML.pm create mode 100644 deal.II/doc/auto/scripts/kdoc/kdocMan.pm create mode 100644 deal.II/doc/auto/scripts/kdoc/kdocTeX.pm diff --git a/deal.II/doc/auto/scripts/kdoc/Ast.pm b/deal.II/doc/auto/scripts/kdoc/Ast.pm new file mode 100644 index 0000000000..74d4a15119 --- /dev/null +++ b/deal.II/doc/auto/scripts/kdoc/Ast.pm @@ -0,0 +1,93 @@ +package Ast; + +#----------------------------------------------------------------------------- +# This package is used to create a simple Abstract Syntax tree. Each node +# in the AST is an associative array and supports two kinds of properties - +# scalars and lists of scalars. +# See SchemParser.pm for an example of usage. +# ... Sriram +#----------------------------------------------------------------------------- + +sub BEGIN { + $currLevel = 0; + $indent = " " x 2; +} + +# Constructor +# e.g AST::New ("personnel") +# Stores the argument in a property called astNodeName whose sole purpose +# is to support Print() + +sub New { + my ($this) = {"astNodeName" => $_[0]}; + bless ($this); + return $this; +} + +# Add a property to this object +# $astNode->AddProp("className", "Employee"); + +sub AddProp { + my ($this) = $_[0]; + $this->{$_[1]} = $_[2]; +} + +# Equivalent to AddProp, except the property name is associated +# with a list of values +# $classAstNode->AddProp("attrList", $attrAstNode); + +sub AddPropList { + my ($this) = $_[0]; + if (! exists $this->{$_[1]}) { + $this->{$_[1]} = []; + } + push (@{$this->{$_[1]}}, $_[2]); +} + +# Returns a list of all the property names of this object +sub GetProps { + my ($this) = $_[0]; + return keys %{$this}; +} + +sub Visit { + # Converts each of this AstNode's properties into global variables. + # The global variables are introduced into package "main" + # At the same time, a piece of code is formed to undo this work above - + # $endCode essentially contains the values of these global variables + # before they are mangled. endCode gets pushed into a stack (endCodes), + # which is unwound by UnVisit(). + + local ($this, $pack) = @_; + + + $code = ""; $endCode = ""; + + + + foreach $k (keys %{$this}) { + + $glob = $pack."::".$k; + + if ( defined $$glob ) { + + if ( ${$glob} ne "" ) { + $$glob =~ s/\'/\\\'/g; + } + + $endCode .= '$'.$pack.'::'.$k. " = '".$$glob."';"; + } else { + $endCode .= '$'.$pack . "::". $k . ' = "";'; + } + $code .= '$'.$pack . "::" . $k . "= \$this->{\"$k\"};"; + } + push (@endCodes, $endCode); + eval($code) if $code; +} + +sub UnVisit { + $code = pop(@endCodes); + eval($code) if ($code); +} + +1; diff --git a/deal.II/doc/auto/scripts/kdoc/kdoc b/deal.II/doc/auto/scripts/kdoc/kdoc new file mode 100644 index 0000000000..90eada7bca --- /dev/null +++ b/deal.II/doc/auto/scripts/kdoc/kdoc @@ -0,0 +1,1298 @@ +#!/usr/local/bin/perl + +# Documentation generator. +# Torben Weis (weis@kde.org) and Sirtaj Kang (taj@kde.org) +# $Id$ + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +########################################################### +# +# Global Variables +# +########################################################### + +# system options +require 5.000; + +$PREFIX="/usr/local"; +push( @INC, $PREFIX."/share/kdoc"); + +require Ast; + +# User options + +$dontDoPrivate = 1; +$strictParser = 0; +$documentAll = 1; +$docDeprecated = 1; +$docInternal = 1; +$debug = 0; +$docPath = "."; +$urlBase = ""; +$libPath = "."; +$lib = ""; +$genHTML = 0; +$genTeX = 0; +$genMan = 0; +$quiet = 0; + +# running environment +($version = '$Version$') =~ s/:\s*//g; + +$version =~ s/Version//g; + +$thisHost = `uname -n`; chop $thisHost; +$user = `whoami`; chop $user; + +$generatedByText= 'Documentation generated by '.$user. '@'. + $thisHost.' on '.`date`; + +$libPath = $ENV{'KDOCLIBS'} if $ENV{'KDOCLIBS'} ne ""; + +# globals - for method + +$exceptions = ""; +%paramDesc = (); +$paramName = ""; +$paramText = ""; +$retText = ""; +$see = ""; +$text = ""; +$methInternal = 0; +$methDeprecated = 0; + +# for class +$class = ""; +$classAuthor = ""; +$classDeprecated = 0; +$classInternal = 0; +$classSee = ""; +$classShortText = ""; +$classShortTextSet = 0; +$classText = ""; +$classVersion = ""; +$classInherits = ""; +$classAbstract = 0; +$classTmplArgs = ""; + +%classRef = (); # KDOC reference file +%classSource = (); # tracks headers given a class name +%classNode = (); # tracks nodes given a class name +@headerList = (); # list of processed header files + +$filename = ""; # Current file being processed + +# index of stuff that shouldn't flag referencing errors +# (not currently used) + +%noErr = (); +$noErr{ "void" } = 1; +$noErr{ "int" } = 1; +$noErr{ "uint" } = 1; +$noErr{ "uchar" } = 1; +$noErr{ "short" } = 1; +$noErr{ "ushort" } = 1; +$noErr{ "unsignedint" } = 1; +$noErr{ "unsignedchar" } = 1; +$noErr{ "unsignedshort" } = 1; +$noErr{ "float" } = 1; +$noErr{ "double" } = 1; +$noErr{ "short" } = 1; +$noErr{ "char" } = 1; +$noErr{ "unsigned" } = 1; +$noErr{ "bool" } = 1; +$noErr{ "long" } = 1; +$noErr{ "string" } = 1; + +# for main + +$i = 0; +@myargs = @ARGV; + +%children = (); +%parents = (); + +# "<>" is the root of all classes. +$children{"<>"} = ""; +$parents{"<>"} = "<>"; + +$rootNode = Ast::New("ROOT"); + +#### +# +# Function addClass +# Inserts a class into the hierarchy +#### + +sub addClass +{ + my($parent, $child) = @_; + + $parents{ $child } = $parent; + + $children{ $parent } = $child.";".$children{ $parent }; + + $children{ $child } = "" if !defined $children{ $child }; +} + +########################################################### +# +# Function +# readLibrary +# +########################################################### + +sub readLibrary +{ + my( $libname ) = @_; + my( $prefix ); + my( $libFull ); + + $libFull = $libPath."/".$libname.".kdoc"; + + open( IMP, "$libFull" ) + || die "Could not open ".$libFull." for reading\n"; + + # the first line of a library contains the base url under + # which is was stored (using the -u flag at invokation of + # kdoc) + $prefix = ; + chop $prefix; + + # However, there is one problem: kdoc references other symbols + # relative to the files of the library it is working on and that + # will not be in the present directory but somewhere else. + # Therefore $prefix is relative to the present directory, while + # the files of the present library will go to $docPath; we + # therefore need to modify $prefix for the number of subdirectories + # in $docPath. That scheme will fail, however, if $docPath is an + # absolute path, if $prefix is an absolute path or if $docPath + # contains "../". I (WB) am not proficient enough to invent a + # workaround + + foreach ( split "/", $prefix) + { + $prefix = "../" . $prefix; + } + if ( ! ( $prefix =~ /\/$/) ) + { + $prefix .= "/"; + } + + while ( ) + { + chop; + if ( /^(.*)=(.*)$/ ) + { + $classRef{ $1 } = $prefix . "$2"; + } + if( /^(\w+)=/ ) { + # add classes to external list + $classSource{ $1 } = $libname; + } + } + + close( IMP ); +} + +########################################################### +# +# Function +# processClass +# +########################################################### + +sub processClass +{ + my( $end ); + +# New Ast Node for class + + $classNode = Ast::New( $class ); + +# use first line of text as short text if we have none yet. + if( $classShortText eq "" && $classText ne "" ) { + $_ = $classText; + /((\s|\w|[^.\n])*)\.*/; + $classShortText = $1." "; + $classShortTextSet = 1; + } + + + +# work out ancestors + $_ = $classInherits; + tr/\:\{//d; + s/protected//g; + s/private//g; + s/public//g; + s/virtual//g; + + if ( !( /^\s*$/ ) ) + { + foreach $c ( split /,/, $_ ) + { + $c =~ s/\s//g; + addClass( $c, $class ); + + $inheritNode = Ast::New($c); + $classNode->AddPropList( "Ancestors", $inheritNode ); + } + + } + else { + addClass( "<>", $class ); + } + +# process the rest of the class declaration + + while ( ) + { + next if /^\s*$/g; + +# parse out // comments, except where in a string or + s#//.*$##g unless m#"[^"]+".*//# || m#^\s*///#; + + $line = $_; + + if ( /^\s*\}\s*;\s*(\/\/.*)?$/ ) + { +# end of class declaration +# dump all stored stuff to file + + print "CLASS END: $class\n" if $debug; + + if( ($classInternal == 0 || $docInternal ) + && ( $classDeprecated == 0 || $docDeprecated ) ) { + + # add class to list only if it is expected to be + # documented + + addReference( $classNode->{"astNodeName"}, + $classNode->{"astNodeName"}.".html" ); + + print "Added $class to tree\n" if $debug; + + $rootNode->AddPropList( "classes", $classNode ); + + $filename =~ s/^\s+$//g; + $classAuthor =~ s/^\s+$//g; + $classVersion =~ s/^\s+$//g; + $classText =~ s/^\s+$//g; + $classSee =~ s/^\s+$//g; + + $classNode->AddProp( "Author", $classAuthor ); + $classNode->AddProp( "ClassSee", $classSee ); + $classNode->AddProp( "ClassShort", $classShortText ); + $classNode->AddProp( "Deprecated", $classDeprecated ); + $classNode->AddProp( "Description", $classText ); + $classNode->AddProp( "Header", $filename ); + $classNode->AddProp( "Internal", $classInternal ); + $classNode->AddProp( "TmplArgs", $classTmplArgs ); + $classNode->AddProp( "Version", $classVersion ); + + } + + resetClassDoc(); + + return; + } + elsif ( /^\s*public\s*:\s*$/ && $access ne "public" ) + { + $access = "public"; + } + elsif ( /^\s*protected\s*:\s*$/ && $access ne "protected" ) + { + $access = "protected"; + } + elsif ( /^\s*private\s*:\s*$/ && $access ne "private" ) + { + $access = "private"; + } + elsif ( /^\s*signals\s*:\s*$/ && $access ne "signals" ) + { + $access = "signals"; + } + elsif ( /^\s*protected\s+slots\s*:\s*$/ && $access ne "protected_slots" ) + { + $access = "protected_slots"; + } + elsif ( /^\s*public\s+slots\s*:\s*$/ && $access ne "public_slots" ) + { + $access = "public_slots"; + } + elsif ( /^\s*private\s+slots\s*:\s*$/ && $access ne "private_slots" ) + { + $access = "private_slots"; + } + + #### Preprocessor directive + + elsif( /^\s*#[\w\.-_]+/ ) { + + print "CPP: $_\n" if $debug; + + # skip lines carried on with \ + while( /\\\s*$/ ) { + if( !($_ = ) ) { + die "Bad Finish"; + } + print "CPP: Skipped: $_" if $debug; + } + } + + #### Typedef + + elsif( /^\s*typedef\s+(.*[&\*\s])\s*([\w-:_]+)\s*(\[[^\]]*\])*;\s*$/ ) { + # 1 2 3 4 + # 1: type name, possibly more than one + # 2: name of new type + # 3: possible array declaration(s) + # 4: anything else + print "TYPED: $2: $1\n" if $debug; + + if( ( $methInternal == 0 || $docInternal) + && ($methDeprecated == 0 || $docDeprecated) ) { + + addReference( $class."::".$2, $class.".html#".$2 ); + + $newNode = Ast::New( $2 ); + + $classNode->AddPropList( $access, $newNode ); + + $newNode->AddProp( "Keyword", "typedef" ); + $newNode->AddProp( "Description", $text ); + $newNode->AddProp( "See", $see ); + $newNode->AddProp( "MethInternal", $methInternal ); + $newNode->AddProp( "MethDeprecated", $methDeprecated ); + + $newNode->AddProp( "Type", $1 ); + $newNode->AddProp( "Array", $3 ); + } + + resetMemberDoc(); + } + + #### Enum + + elsif ( /^\s*enum\s+([\w_]*)\s*\{(.*)(\/\/.*)?/ ) + { + $enum = $1; + $tmp = $2; + $args = ""; + + # collect constants till } is found + + while ( !($tmp =~ /\}/) ) + { + $args = $args . $tmp; + $tmp = ; + } + + $_ = $tmp; + /^(.*)\}/; + $args = $args . $1; + + + # update Ast node + + if( ( !$methInternal || $docInternal) + && (!$methDeprecated || $docDeprecated) ) { + + addReference( $class."::".$enum, $class.".html#".$enum ); + + $see =~ s/^\s*$//g; + $text =~ s/^\s*$//g; + $args =~ s/^\s*$//g; + + $newNode = Ast::New( $enum ); + $classNode->AddPropList( $access, $newNode ); + $newNode->AddProp( "Keyword", "enum" ); + $newNode->AddProp( "Description", $text ); + $newNode->AddProp( "See", $see ); + $newNode->AddProp( "Constants", $args ); + $newNode->AddProp( "MethInternal", $methInternal ); + $newNode->AddProp( "MethDeprecated", $methDeprecated ); + } + + resetMemberDoc(); + } + + #### parse out Q_OBJECT macro + elsif ( /^\s*Q_OBJECT[^\w]+(\/\/.*)?/ ) { + # dont do anything + } + + + #### Variables + elsif ( /^[^\(]*$/ && /^[\w_\:\s]+[\&\s*]+[\w_]+\s*(\[[^\]]*\])*\s*;\s*(\/\/.*)?$/ ) + # 1 2 3 4 5 6 + # 1: variable declarations have no () + # 2: data type, possibly several words as in 'unsigned int' + # 3: reference pointer or at least a space before variable name + # 4: variable name + # 5: array declaration + # 6: spaces and or comments + { + $str = $_; + + # split variable declaration: + # $1 = data type + # $2 = reference or pointer (why are there two \s's?) + # $3 = variable name + # $4 = array declaration + $str =~ /^(.+)([\s&\s\*])([\w_]+)\s*((\[[^\]]*\])*)\s*;\s*$/; + $var = $3; + $rest = $1.$2; + $array_declaration = $4; + + + if( ( !$methInternal || $docInternal) + && (!$methDeprecated || $docDeprecated) ) { + + addReference( $class."::".$var, $class.".html#".$var ); + + $rest =~ s/^\s*$//g; + $see =~ s/^\s*$//g; + $text =~ s/^\s*$//g; + + $newNode = Ast::New( $var ); + $classNode->AddPropList( $access, $newNode ); + $newNode->AddProp( "Keyword", "property" ); + $newNode->AddProp( "Type", $rest ); + $newNode->AddProp( "Array", $array_declaration); + $newNode->AddProp( "Description", $text ); + $newNode->AddProp( "See", $see ); + $newNode->AddProp( "MethInternal", $methInternal ); + $newNode->AddProp( "MethDeprecated", $methDeprecated ); + } + + resetMemberDoc(); + } + + + #### Nested class + + elsif ( /^\s*(class|struct)/ ) { + # TODO: Implement nested classes + # Till then, find end of declaration + print "NESTED $_\n" if $debug; + + if( !/;/ ) + { +# probably unterminated as yet + print "\nNESTED begin (for $methodName): $_\n" + if $debug == 1; + $foundMemberEnd = 0; + $lookingFor = ";"; + $depth = 0; + + while( $foundMemberEnd == 0 ) { + + if( /\{/ ) { + $depth += countReg( $_, "\{" ); + $lookingFor = "\}"; + } + + print "NESTED '$lookingFor': $_\n" if $debug == 1; + + if ( /$lookingFor/ ) + { + $depth -= countReg( $_, $lookingFor ); + + $foundMemberEnd = 1 if $depth <= 0; + } + + if ($foundMemberEnd == 0 ) { + $_ = ; + s#//.*$##g; + } + } + } + } + elsif ( m#^\s*///\s*(.*)# && $strictParser == 0 ) { + # DOC++ style "///" single-line member doccer + # will be used only if no other documentation exists. + + resetMemberDoc(); + + $text = $1; + + print "DOCXX-STYLE: $text\n" if $debug != 0; + } + + elsif ( /^\s*\/\// ) + { + # parse out comment + print "C++ comment: $_" if $debug != 0; + } + + elsif ( /^\s*\/\*\*+\s*(.*)\*+\/\s*/ && $strictParser == 0 ) { + # single-line "/**..*/" type doc line + # not allowed by the spec but we'll let it pass + # if we're being lenient. + + resetMemberDoc(); + + $text = $1; + print "ONELINE: $text\n" if $debug == 1; + } + + elsif( /^\s*\/\*[^*]/ ) { + # (multiline) comment + while( !/\*\// ) { + # skip lines till we find its end + $_ = ; + } + } + + elsif ( /^\s*\/\*\*+\s*(.*)/ ) { + # member documentation begins + processMemberDoc(); + } + + #### Member Function + + elsif ( /^\s*([^\(]*)\s+([^\s\(]+)\s*\((.*)(\/\/.*)?$/ ) + { + processMethod( $1, $2, $3 ); + } + + } + +} # processClass + +sub processMethod { + + my( $returnType, $methodName, $rest ) = @_; + + + + +# ensure that everything after the operator keyword goes into the +# member name and not the return type + + if( $returnType =~ /operator/ ) { + $returnType =~ s/(operator.*)//g; + $methodName = $1." ".$methodName; + } + +# special case: if we have operator(), then the operator keyword got +# matched into methodName, the first "(" was thrown away and $rest +# contains ") (argumentlist)..." + if( ($methodName =~ /^operator$/) && ($rest =~ /^\)/) ) { + $methodName .= " ()"; + $rest =~ s/^\)\s*\(//; + } + +# ensure that "*" is part of return type + + if( $methodName =~ /^\s*([\*|\&]+)(.*)$/ ) { + $returnType = $returnType.$1; + $methodName = $2; + } + +## Read the parameters ($3 onward) + + $params = ""; + + # Find end of params + while ( !($rest =~ /^[^)]*\)(.*)(\/\/.*)?$/) ) + { + print "SEARCHING: $rest\n" if $debug == 1; + $params = $params . $rest; + ($rest = ) =~ s#//.*$##g; + } + + $rest =~ s#//.*$##g; + $_ = $rest; + /^([^\)]*)\)(.*)/; + + # include all parameters before ) + $params .= $1; + my($restOfLine) = $2; + + my($constness) = ""; + + if( $restOfLine =~ /^\s*const/ ) { + $constness = "const"; + } + +# need to skip inline function if it is there, or if the +# end of declaration is staggered for some other reason. + + if( ! /\)[\s\w=]*;/ ) + { +# probably unterminated as yet + print "\nINLINE begin (for $methodName): $_\n" if $debug == 1; + + $_ = $rest; + $foundMemberEnd = 0; + $lookingFor = ";"; + $depth = 0; + + while( $foundMemberEnd == 0 ) { + + if( /\{/ ) { + $depth += countReg( $_, "\{" ); + $lookingFor = "\}"; + } + + print "INLINE '$lookingFor': $_\n" if $debug == 1; + + if ( /$lookingFor/ ) + { + $depth -= countReg( $_, $lookingFor ); + + $foundMemberEnd = 1 if $depth <= 0; + } + + if ($foundMemberEnd == 0 ) { + $_ = ; + s#//.*$##g; + } + } + } + + # Register if not internal or deprecated + + if( ( !$methInternal || $docInternal) + && (!$methDeprecated || $docDeprecated) ) { + + $returnType =~ s/^\s*$//g; + $see =~ s/^\s*$//g; + $text =~ s/^\s*$//g; + $retText =~ s/^\s*$//g; + $params =~ s/^\s*$//g; + $constness =~ s/^\s*$//g; + + addReference( $class."::".$methodName, $class.".html#".$methodName ); + + $newNode = Ast::New( $methodName ); + $classNode->AddPropList( $access, $newNode ); + + $newNode->AddProp( "ReturnType", $returnType ); + $newNode->AddProp( "Const", $constness ); + $newNode->AddProp( "Parameters", $params ); + $newNode->AddProp( "Keyword", "method" ); + $newNode->AddProp( "Description", $text ); + $newNode->AddProp( "Returns", $retText ); + $newNode->AddProp( "See", $see ); + $newNode->AddProp( "Exceptions", $exceptions ); + $newNode->AddProp( "MethInternal", $methInternal ); + $newNode->AddProp( "MethDeprecated", $methDeprecated ); + + foreach $param ( keys %paramDesc ) { + $paramNode = Ast::New( $param ); + ($desc = $paramDesc{$param}) =~ s/^\s*$//g; + $paramNode->AddProp("Description", $desc ); + + $newNode->AddPropList( "ParamDoc", $paramNode ); + } + } + + resetMemberDoc(); +} # processMethod + +# +# Processes a doc comment +# + +sub processMemberDoc +{ + my( $endDocBlock ) = 0; + my( $paramFlag ) = 0; + my( $retFlag ) = 0; + + resetMemberDoc(); + + $lastLineBlank = 0; + +# allow documentation on first line only if +# we're being lenient. + + if( $strictParser == 0 ) { + $text = $1; + } + else { + $text = ""; + } + + $endDocBlock = 0; + + while ( $endDocBlock == 0 ) { + $_ = ; + $line = $_; + + if ( $paramFlag == 1 ) { + + if ( /^\s*\**\s*\@/ || /^\s*\**\s*\*\// ) { +#parameter ends. + $paramDesc{ $paramName } = $paramText; + $paramFlag = 0; + } + else { + /^\s*\**(.*)$/; + $paramText .= $1."\n"; + $_ = ""; + } + } + elsif ( $retFlag == 1 ) { + if ( /^\s*\**\s*\@/ || /^\s*\**\s*\*\// ) { + $retFlag = 0; + } + else { + /^\s*\*+(.*)$/; + $retText .= "\n$1"; + $_ = ""; + } + } + + if ( /^\s*(.*)\*+\// ) { +# end of member documentation + $endDocBlock = 1; + } + elsif ( /^(.*)\*+\/\s*$/ && ($strictParser == 0) ) { +# end of member documentation, with extraneous +# space before end tag +# only used if we're being lenient. + + $text = $text . $_ . '\n'; + + $endDocBlock = 1; + + print "BAD MEMBER END: $_\n" if $debug == 1; + } + elsif ( /^\s*\**\s*\@param\s+([^\s]+)\s(.*)$/ ) { +# "@param" + $paramName = $1; + $paramText = $2; + + $paramFlag = 1; + } + elsif ( /^\s*\**\s*\@return\s+(.*)/ ) { +# "@return" + + $retText = $1; + $retFlag = 1; + } + elsif( /^\s*\**\s*\@internal/ ) { +# "@internal" + $methInternal = 1; + } + elsif( /^\s*\**\s*\@deprecated/ ) { +# "@deprecated" + $methDeprecated = 1; + } + elsif ( /^\s*\**\s*\@exception\s+([:#\w_~]+)/ ) { +# "@exception" + $exceptions .= $1; + } + elsif ( /^\s*\**\s*\@see\s+([:#\w_~]+)/ ) { +# "@see" + $see .= ", " if $see ne ""; + + $c = $1; + $see .= $c; + } + elsif( /^\s*\**\s*\@(short|author|version)/ ) { +# ignore tags that cannot exist in +# member doc + } + elsif ( /^\s*\**\s*(.*)$/ ) { +# normal member documentation text, +# " * blah blah" + $text = $text. $1 . "\n"; + } # if + } # while still in doc block +} # processMemberDoc + +########################################################### +# +# Function +# processFile # +########################################################### + +sub processFile +{ + while ( ) + { + $line = $_; + + next if /^\s*$/; + + if( m#^\s*/\*[^*]# ) { +# skip multiline comment started with /* (but only one asterisk!) + while( !/\*\// ) { + $_ = ; + } + } + elsif ( m#^\s*/\*\*+\s*(.*)\*/\s*# && ($strictParser == 0) ) { + # single-line "/**..*/" type doc line + # not allowed by the spec but we'll let it pass + # if we're being lenient. + resetMemberDoc(); + $classText = $1; + $classShortText = $1; + print "ONELINE classdoc: $text\n" if $debug == 1; + } + elsif( /^\s*#[\w\.-_]+/ ) { + #### Preprocessor directive + print "CPP: $_\n" if $debug; + + # skip lines carried on with \ + while( /\\\s*$/ ) { + if( !($_ = ) ) { + die "Bad Finish"; + } + print "CPP: Skipped: $_" if $debug; + } + } + elsif ( /^\s*\/\*\*+\s*(.*)$/ ) + { + # start of class doc comment + $classSee = ""; + $classText = ""; + $classShortText = ""; + $lastLineBlank = 0; + + $classText = $1 if( $strictParser == 0 ); + + $end = 0; + while ( $end == 0 ) + { + $_ = ; + $line = $_; + + if ( /^\s*\*\// ) + { + # end of documentation, assume class + # declaration is next. + $end = 1; + } + elsif ( /^(.*)\*+\/\s*$/ && ($strictParser == 0) ) + { + # end of class documentation, with extraneous + # space before end tag + # only used if we are being lenient. + + $text = $text . $1 . '\n'; + + $end = 1; + + print "BAD CLASSDOC END: $_\n" if $debug == 1; + } + elsif ( /^\s*\**\s*\@see\s+([#\w_~]+)/ ) + { + # @see + if ( $classSee ne "" ) + { + $classSee .= ", "; + } + $c = $1; + $classSee .= $c; + } + elsif ( /^\s*\*?\s*\@author\s+(.*)/ ) + { + # @author + $classAuthor .= $1 . " "; + } + elsif ( /^\s*\**\s*\@version\s+(.*)/ ) + { + # @version + $classVersion .= $1 . " "; + } + elsif ( /^\s*\**\s*\@short\s+(.*)/ ) + { + # @short + $classShortText .= $1 . " "; + } + elsif ( /^\s*\**\s*\@deprecated/ ) + { + # @deprecated + $classDeprecated = 1; + } + elsif ( /^\s*\**\s*\@internal/ ) + { + # @internal + $classInternal = 1; + } + elsif ( /^\s*\**(.*)$/ ) + { + # normal documentation text + $lead = $1; + + # check for asterisk + if ( /^\s*\*+/ ) { + $classText .= $lead. "\n"; + } + else { + # preserve leading space. + $classText .= $_. "\n"; + } + } + } + $_ = ; + $line = $_; + + } # documentation if + + if ( /^(\s*template\s*<(([-\w,_\s]|<([-\w,+\s])+>)+)>)/ ) { + $classTmplArgs = $2; + + ($resetme = $1); + $resetme =~ s/([\W])/\\$1/g; + + s/$resetme//g; + } + + if ( !(/;/) && /^\s*(class|struct)\s+([-\w_]+)(.*)$/ ) + { + +# class declaration begins. + + #TODO: skip class if it doesn't have documentation + #and we aren't documenting NULL classes. + + $class = $2; + ($classInherits = $3) =~ s#//.*##g; + + # handle template-instantiation class + if($classInherits =~ + /^\s*(<([-\w,_\s]|<([-\w,+\s])+>)+>)/) { + $class .= $1; + $class =~ s/\s+//g; + } + + $classInherits =~ s/<([-\w,_\s]|<([-\w,+\s])+>)+>//g; + + print "\n $class " unless $quiet; + +# set default visibility + if( $1 eq "class" ) { + $access = "private"; + } else { + $access = "public"; + } + +# process everything in the class + processClass(); + } + + } # outer file while + + close( IN ); +} + +# +# +# + +sub addReference +{ + my( $target, $pointer) = @_; + + print KDOC $target."=".$pointer."\n"; + $classRef{ $target } = $pointer; +} + +# Reset the documentation variables for a class member. + +sub resetMemberDoc +{ + $exceptions = ""; + %paramDesc = (); + $paramName = ""; + $paramText = ""; + $retText = ""; + $see = ""; + $text = ""; + $methInternal = 0; + $methDeprecated=0; +} + +# +# Reset the documentation variables for a class. +# +sub resetClassDoc +{ + $classAuthor = ""; + $classDeprecated= 0; + $classInternal = 0; + $classSee = ""; + $classShortText = ""; + $classShortTextSet = 0; + $classTmplArgs = ""; + $classAbstract = 0; + $classText = ""; + $classVersion = ""; +} + +# Counts the number of times a regular expression occurs in a string + +sub countReg +{ + my( $str, $regexp ) = @_; + my( $count ) = 0; + + while( $str =~ /$regexp/ ) { + $count++; + + $str =~ s/$regexp//; + } + + return $count; +} + +# +# Display usage and quit with an error code. +# + +sub usage +{ +die<, Sirtaj Kang + +Usage: + kdoc [-a] [-M][-H][-T] [-a][-e][-i][-p][-q] [-L] + [-d] [-u ]
... + [-l ... ] + + -T Generate LaTeX documentation. + -M Generate man pages. + + -H Generate HTML documentation (default). + -d Directory for HTML and LaTeX output. + -u Base path/url by which this library will be accessed. + + -a Document methods/classes without explicit doc comment. + -e Skip deprecated methods and classes (\@deprecated tag) + -i Skip classes marked internal (\@internal tag) + -p Document private members. + -q Proceed quietly (display errors only) + + -L Path to kdoc libraries. Default is current dir, or + \$KDOCLIBS if it is set. + + The name of the kdoc library to create. + C++ headers to process. + + -l Cross reference these libraries. +EOF +} + +sub bumpArg +{ + return $1 if $1 ne ""; + my($real); + + $i = $i + 1; + + $real = $myargs[ $i ]; + $myargs[ $i ] = "-".$myargs[ $i ]; + + + return $real; +} + + +# +# Calls dumpDoc for each format for which output was requested. +# + +sub generateDocs +{ + + if( $genHTML == 0 && $genTeX == 0 && $genMan == 0) + { + $genHTML = 1; + require kdocHTML; + } + + if( $genHTML != 0 ) { + kdocHTML::dumpDoc( $name, $rootNode, $docPath ); + } + + if( $genTeX != 0 ) { + kdocTeX::dumpDoc( $name, $rootNode, $docPath ); + } + + if( $genMan != 0 ) { + kdocMan::dumpDoc( $name, $rootNode, $docPath ); + } + + print "Done.\n" unless $quiet; +} + +########################################################### +# +# Main +# +########################################################### + +if ( $#ARGV == -1 ) +{ + die "kdoc: No arguments. Type 'kdoc -h' for help.\n"; +} + +# +# process switches and args # +# + +$libFoundAt = -1; + +$i = 0; + +while( $i <=$#myargs ) +{ + $filename = $myargs[ $i ]; + if ( $filename =~ /^-d(.*)$/ ) { + + $docPath = bumpArg(); + } + elsif ( $filename =~ /^-u(.*)$/ ) { + $urlBase= bumpArg(); + } + elsif ( $filename =~ /^-L(.*)$/ ) { + $libPath = bumpArg(); + } + elsif ( $filename =~ /^-l(.*)$/ ) { + readLibrary( bumpArg() ); + } + elsif ( $filename =~ /^-a/ ) { + $documentAll = 1; + } + elsif ( $filename =~ /^-M/ ) { + $genMan = 1; + require kdocMan; + } + elsif ( $filename =~ /^-T/ ) { + $genTeX = 1; + require kdocTeX; + } + elsif ( $filename =~ /^-H/ ) { + $genHTML = 1; + require kdocHTML; + } + elsif ( $filename =~ /^-e/ ) { + $docDeprecated = 0; + } + elsif ( $filename =~ /^-D/ ) { + $debug = 1; + } + elsif ( $filename =~ /^-i/ ) { + $docInternal = 0; + } + elsif ( $filename =~ /^-p/ ) { + $dontDoPrivate = 0; + } + elsif ( $filename =~ /^-q/ ) { + $quiet = 1; + } + elsif( $filename =~ /^-v(.*)/ ) { + die "kdoc: $version (c) Torben Weis, Sirtaj S. Kang\n"; + } + elsif( $filename =~ /^-h/ || $filename =~ /^--help/ ) + { + usage(); + } + elsif( $filename =~ /^-(.*)/ ) { + die "kdoc: -$1 is an unsupported option. Type kdoc -h for help.\n"; + } + elsif( $lib eq "" ) { + $lib = $filename; + $libFoundAt = $i; + } + + $i = $i + 1; +} + +$urlBase = $docPath if $urlBase eq ""; + +usage() if $lib eq ""; + +#parse out path name for printed libName +( $name = $lib ) =~ s#.*/##g; + +$lib = $libPath."/".$lib.".kdoc"; + +open( KDOC, ">$lib" ) || die "Could not open $lib for writing\n"; +print KDOC "$urlBase\n"; + + +# check document output path + +if( !(-d $docPath)) +{ + if( system("mkdir $docPath") ) { + close ( KDOC ); + unlink( $lib ); + die "Document path '$docPath' doesn't exist and it couldn't\n". + "be created.\n"; + } +} + +# +# process each file +# + +foreach $i (0..$#myargs) +{ + $filename = $myargs[ $i ]; + if ( $filename =~ /^-(.*)$/ ) + { +#option... don't process + } + elsif( $i != $libFoundAt ) + { + print "Processing $filename:" unless $quiet; + push( @headerList, $filename ); + open( IN, $filename ) || die "Could not open $filename for input\n"; + + processFile(); + + print "\n" unless $quiet; + + close( IN ); + } +} + + +close( KDOC ); + +# reparent all parentless classes to root. + +$rootNode->Visit("main"); + +if( defined $classes ) { + + foreach $class ( @{$classes} ) + { + $className = $class->{"astNodeName"}; + + if ( !defined $parents{ $parents{$className} }) { + addClass( "<>", $parents{$className} ); + } + } +} + +Ast::UnVisit(); + +generateDocs(); + +# file ends diff --git a/deal.II/doc/auto/scripts/kdoc/kdocHTML.pm b/deal.II/doc/auto/scripts/kdoc/kdocHTML.pm new file mode 100644 index 0000000000..ae7c8f9057 --- /dev/null +++ b/deal.II/doc/auto/scripts/kdoc/kdocHTML.pm @@ -0,0 +1,930 @@ +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +package kdocHTML; + +## KDOC HTML output +# +# From main: +# children classRef classSource dontDoPrivate +# generatedByText headerList quiet + +require Ast; + +BEGIN +{ + $lib = ""; + $outputdir = "."; + $linkRef = 0; + $modname = "kdocHTML"; + %classList = (); +} + + +sub dumpDoc +{ + $genText = $main::generatedByText; + + ($lib, $root, $outputdir) = @_; + + print "Generating HTML documentation.\n" unless $main::quiet; + writeList(); + writeHier(); + writeHeaderList(); + + print "Generating HTMLized headers.\n" unless $main::quiet; + foreach $header ( @main::headerList ) { + markupCxxHeader( $header ); + } +} + +sub writeHeaderList +{ + + open(HDRIDX, ">$outputdir/header-list.html") + || die "Couldn't create $outputdir/header-list.html\n"; + + print HDRIDX<$lib Header Index +

$lib Header Index

+

+[Index] [Hierarchy] [Headers] +

+
+
    +EOF + + foreach $header ( sort @main::headerList ) { + $_ = $header; +# convert dashes to double dash, convert path to dash + s/-/--g/g; + s/\/|\./-/g; + + # never let a file name start with a '-' sign, since this makes + # some programs think the file name really was a parameter to the + # program. Filenames starting with '-' usually happen if you let + # kdoc work on files like '../../include/foo/bar.h', given the + # above substitution rules. Therefore: if a filename starts with + # '-', prepend a '_' + s/^-/_-/; + + print HDRIDX "\t
  • $header
  • \n"; + } +print HDRIDX "
\n
\n
$genText", + "
\n\n\n"; +} + +sub escape +{ + my( $str ) = @_; + + $str =~ s/&/\&/g; + $str =~ s//\>/g; + $str =~ s/"/\"/g; + + return $str; +} + +# In file names, we don't want to have the special characters be +# replaced by the rules '>' -> '>' etc., so we revert the +# replacement. The reason is that when giving Netscape the tag +# xyz , it looks for the file +# "abc<2>.html". Strange, eh? We'd like to replace filenames +# back to the original names, which is not a good idea also, since +# filenames containing <>&" are no good. Therefore, we stay with +# the HTML tags, but replace the '&' and ';' by ',' which should +# not be a character which appears in class and file names, but +# which has no special meaning for the shell either. +sub filenameUnescape +{ + my( $str ) = @_; + + $str =~ s/\&/,amp,/g; + $str =~ s/\</,lt,/g; + $str =~ s/\>/,gt,/g; + $str =~ s/\"/,quot,/g; + + return $str; +} + +sub writeList() +{ + + $root->Visit( $modname ); + + foreach $class ( @{$classes} ) + { + $classList{ $class->{'astNodeName'} } = $class; + } + + open ( LIBIDX, ">".$outputdir."/index.html" ) + || die "Couldn't write to ".$outputdir."/index.html" ; + + print LIBIDX<$lib Class Index +

$lib Class Index

+

+[Index] [Hierarchy] [Headers] +

+
+ +EOF + + foreach $className ( sort keys %classList ) { + $class = $classList { $className }; + + $class->Visit( $modname ); + + $className = $astNodeName; + + # escape special characters in class names (e.g. <>&) + # however, we need to unescape them when using the + # class name as a file name + $astNodeName = escape( $astNodeName ); + + print LIBIDX "\n", "\t\n"; + + writeClass(); + + Ast::UnVisit(); + + } + + Ast::UnVisit(); + +print LIBIDX< +
+
", + "", + $astNodeName, "", + makeReferencedText( $ClassShort ), "
+ + + + +
$genText
+Kdoc +
+ +EOF + +} + +########################################################### +# +# Function +# makeReferencedText( text ) +# +########################################################### + +sub makeReferencedText +{ + local( $t ) = @_; + + while ( $t =~ /(\@ref\s+)([\w_\#~\d\:]+\W)/ ) + {## + $pat = $1.$2; + $ref = $2; + chop $ref; + $repl = findClassReference( $ref ) . " "; + $pat =~ s/\(/\\(/g; + $pat =~ s/\)/\\)/g; + $t =~ s/$pat/$repl/; + } + + $t =~ s//>/g; + $t =~ s/<\/p><p>/<\/p>

/g; + $t =~ s/\#([^\#]*)\#/$1<\/CODE>/g; + $t =~ s/\\begin\{verbatim\}/

/g;
+    $t =~ s/\\end\{verbatim\}/<\/pre>/g;
+    $t =~ s/\\begin\{itemize\}/
    /g; + $t =~ s/\\end\{itemize\}/<\/UL>/g; + $t =~ s/\\item/
  • /g; + $t =~ s/\{\\bf([^}]*)}/$1<\/b>/g; + $t =~ s/\\section\{([^}]*)\}/

    $1<\/H3>/g; + $t =~ s/\\subsection\{([^}]*)\}/

    $1<\/H4>/g; + $t =~ s/\\subsubsection\{([^}]*)\}/

    $1<\/H5>/g; + + return $t; +} + +########################################################### +# +# Function +# findClassReference( class ) +# +########################################################### + +sub findClassReference +{ + my( $c ) = @_; + my( $old ); + + + if ( $c eq "" ) { return ""; } + if ( $c eq "#" ) { return "#"; } + + $c =~ s/\#/::/g; + + $old = $c; + + if ( $c =~ /^\s*(\#|::)(.*)$/ ) + { + $c = "$className\:\:$2"; + $pref = $1; + $old =~ s/$pref//; + } + + if ( !defined $main::classRef{ $c } ) + { + if ( !defined $main::noErr{ $c } ) + { +# print main::ERROUT "$filename: '$c' undefined Reference\n\n"; + } + return $c; + } + else + { + if ( $c =~ /\:\:/ ) + { + return "". + escape($old).""; + } + else + { + return "". + escape($c).""; + } + } +} + +############# +# +# writeHier -- Write HTML Class Hierarchy +# +############# + +sub writeHier +{ + +open( HIER, ">".$outputdir."/hier.html" ) + ||die "Cannot write to $outputdir/hier.html"; + +print HIER <$lib Class Hierarchy + +

    $lib Class Hierarchy

    +

    +[Index] [Hierarchy] [Headers] +

    +
    +EOF + +printHierarchy( "<>" ); + +print HIER< + + + + + +
    $genText
    +Kdoc +
    + +EOF + +### here we are!! + # build a list of parents and children for each class + # use it to generate a tree of classes suitable for + # a tree view of the inheritance lattice + + # we may not use the %classList for the children information + # since some classes are parents but not in %classList (those + # classes that are found as base classes but are not documented + # within this module +# my (%kids); +# my (%parents); +# my (%classLevel); +# my ($classNames); +# +# foreach $className (keys %main::children) +# { +# $kids{$className} = $main::children{$className}; +# } +# +# foreach $className (keys %kids) +# { +# foreach $c (split /;/, $main::children{$className}) +# { +# $parents{$c} = $parents{$c} . $className . ";" +# if !($className eq "<>"); +# } +# } +# +# # build a list of all class names, irrespective of whether +# # they are documented or not. +# foreach $class (keys %kids, keys %parents, keys %classList) +# { +# $classNames = $classNames . $class . ";" +# if (! ($classNames =~ /$class;/) && +# ! ($class eq "<>")); +# } +# +# +# # now evaluate the list to get the proper hierarchy level +# # for each class. Loop until all classes are processed, +# # which may take some iterations since a class can only +# # be processed if all of its parents have been processed +# my ($unprocessedClasses); +# my ($classLevel); +# my ($maxParentLevel); +# $unprocessedClasses = 1; +# while ($unprocessedClasses == 1) +# { +# $unprocessedClasses = 0; +# foreach $class (split /;/, $classNames) +# { +# if (! defined $classLevel{$class}) +# { +# # if class has no children or no parents: assign +# # level zero. for classes with no parents, this +# # decision may later be revised +# if ((! $parents{$class}) || +# (! defined $parents{$class})) +# { +# $classLevel{$class} = 0; +# } +# else +# { +# foreach $parent (split /;/, $parents{$class}) +# { +# # find the maximum level any of the +# # children has +# $maxParentLevel = 0; +# +# # if the parent has not been processed, +# # then don't do so for this class also +# if (! defined $classLevel{$parent}) +# { +# $unprocessedClasses = 1; +# last; +# } +# else +# { +# if ($classLevel{$parent} > $maxParentLevel) +# { +# $maxParentLevel = $classLevel{$parent}; +# } +# } +# $classLevel{$class} = $maxParentLevel+1; +# } +# } +# } +# } +# } +# +# +# foreach $class (sort split /;/, $classNames ) +# { +# print "--> ", $class, ": $classLevel{$class} \n"; +# +# } +} + + +###### +# +# Dump the hierarchy for a particular class +# +###### + +sub printHierarchy +{ + my( $className ) = @_; + + print HIER "\t
  • ", findClassReference($className),"\n" + if $className ne "<>"; + + if( defined $main::classSource{ $className } ) { + print HIER " (",$main::classSource{$className},")\n"; + } + + if ( defined $main::children{$className} ) { + + print HIER "\t
      \n"; + + foreach $kid ( sort split /;/, $main::children{$className} ) + { + printHierarchy( $kid ); + } + print HIER "\t
    \n"; + } + + print HIER "\t
  • " if $className ne "<>"; +} + +# ############# +# +# Write out the documentation for a single class. +# +# ############# + +sub writeClass() +{ + open( CLASS, ">" . + $outputdir."/".filenameUnescape($astNodeName) . + ".html" + ) || die "Couldn't write to file " . + $outputdir."/".filenameUnescape($astNodeName).".html"; + + print CLASS<$astNodeName Class +\n +

    $astNodeName Class Reference

    +

    +[$lib Index] [$lib Hierarchy] +[Headers] +

    +
    +EOF + + print CLASS "

    This class is Deprecated.

    \n" if $Deprecated; + print CLASS "

    Internal class - general use not recommended.

    \n" + if $Internal; + + print CLASS "

    ", makeReferencedText( $ClassShort ), + " More...

    \n" + if $ClassShort ne ""; + + $_ = $Header; + s/-/--/g; + s/\/|\./-/g; + + # never let a file name start with a '-' sign, since this makes + # some programs think the file name really was a parameter to the + # program. Filenames starting with '-' usually happen if you let + # kdoc work on files like '../../include/foo/bar.h', given the + # above substitution rules. Therefore: if a filename starts with + # '-', prepend a '_' + s/^-/_-/; + + $escapedpath = $_; + +# include file + + print CLASS< + + #include <$Header> +\n +

    +EOF + + +# Template + + if( $class->{ "TmplArgs" } ne "" ) { + + print CLASS "\n

    Template Form: ", + "template < ", escape( $class->{ "TmplArgs" }), + " > $astNodeName

    \n"; + } + +# Inheritance + my ( $pcount ) = 0; + + if( defined $class->{ "Ancestors" } ) { + print CLASS "\n

    \nInherits: "; + + foreach $foreparent ( @{$Ancestors} ) { + print CLASS ", " if $pcount != 0; + $pcount = 1; + + print CLASS findClassReference( + $foreparent->{"astNodeName"} ); + + if( defined $main::classSource{$foreparent->{ + "astNodeName"}} ) { + print CLASS " (",$main::classSource{ + $foreparent->{"astNodeName"}},")"; + } + } + + print CLASS "\n<\P>"; + } + +# Now list members. + + $linkRef = 0; + + listMethods( "Public Members", $public ); + listMethods( "Public Slots", $public_slots ); + listMethods( "Protected Members", $protected ); + listMethods( "Protected Slots", $protected_slots ); + listMethods( "Signals", $signals ); + + if( $main::dontDoPrivate == 0 ) { + listMethods( "Private Members", $private ); + listMethods( "Private Slots", $private_slots ); + } +print CLASS< +EOF + +# Dump Description. + Ast::UnVisit(); + $class->Visit($modname); + writeClassDescription(); + +# Document members. + + $linkRef = 0; + + writeMemberDoc( "public", $public ); + writeMemberDoc( "public slot", $public_slots ); + writeMemberDoc( "protected", $protected ); + writeMemberDoc( "protected slot", $protected_slots ); + writeMemberDoc( "signal", $signals ); + + if( $main::dontDoPrivate == 0 ) { + writeMemberDoc( "private", $private ); + writeMemberDoc( "private slot", $private_slots ); + } + +# File Generation info + print CLASS "


    \n", + " +
    \n"; + + if( $Author ne "" || $Version ne "" ) { + print CLASS "\n
      "; + + print CLASS "
    • Author: ", escape($Author), "
    • \n" + if $Author ne ""; + + print CLASS "
    • Version: ", escape($Version), "
    • \n" + if $Version ne ""; + print CLASS "
    • $genText
    • \n"; + + print CLASS "
    "; + } else { + print CLASS "
    $genText
    \n"; + } + + print CLASS<
    +Kdoc +
    \n +EOF + +} + +###### +# Lists all methods of a particular visibility. +##### + +sub listMethods() +{ + my( $desc, $members ) = @_; + + return if !defined $members || $#{$members} == -1; + +print CLASS<$desc
    +
      +EOF + + foreach $member ( @{$members} ) { + $member->Visit($modname); + + print CLASS "
    • "; + + if( $Description eq "" && $See eq "" ) { + $link = "name=\""; + } else { + $link = "href=\"\#"; + } + + if( $Keyword eq "property" ) { + print CLASS escape($Type), + "", + escape($astNodeName), "", + escape($Array), + "\n"; + } + elsif( $Keyword eq "method" ) { + print CLASS escape($ReturnType), + " ", + escape($astNodeName), " (", + escape($Parameters), + ") ",$Const,"\n"; + } + elsif( $Keyword eq "enum" ) { + print CLASS "enum ", + escape($astNodeName)," {", + escape($Constants),"}\n"; + } + elsif( $Keyword eq "typedef" ) { + print CLASS "typedef ", escape($Type), " ", escape($astNodeName), + "", escape($Array), ""; + } + + print CLASS "
    • \n"; + + $linkRef += 1; + + Ast::UnVisit(); + } + +print CLASS< +EOF + +} + +sub writeClassDescription +{ + my( $term ) = ""; + my( $once ) = 0; + + if( $Description ne "" ) { + print CLASS "

      Detailed Description", + "

      \n

      \n"; + + $term = "


      \n"; + + $Description =~ s/\n\n+/\n<\/p>

      \n/g; + + print CLASS "\n", makeReferencedText($Description) ,"\n

      "; + } + + if( $ClassSee ne "" ) { + print CLASS "

      See Also: "; + + $once = 0; + $term = "


      " if $term eq ""; + + foreach $item ( split /[\s,]+/, $ClassSee ) { + + if( $once ) { print CLASS ", "; } + else { $once = 1; } + + print CLASS findClassReference( $item ); + } + + print CLASS "

      \n"; + } + + print CLASS $term if $term ne ""; +} + +sub writeMemberDoc +{ + my( $visibility, $node ) = @_; + my( $once ) = 0; + my( $myvis ) = ""; + + return if !defined $node || $#{$node} == -1 ; + + foreach $member ( @{$node} ) { + $member->Visit($modname); + + if( $Description eq "" && $See eq "" ) { + $linkRef++; + Ast::UnVisit(); + next; + } + + if( $Keyword eq "property" ) { + print CLASS "

      ",refString(escape($Type)), + "", + "", + escape($astNodeName), "", + refString(escape($Array)), + " [", $visibility, "]", + "

      \n"; + } + elsif( $Keyword eq "method" ) { + $myvis = $visibility; + + if ( $ReturnType =~ /virtual/ ) { + $myvis .= " virtual"; + $ReturnType =~ s/\s*virtual\s*//g; + } + + if ( $ReturnType =~ /static/ ) { + $myvis .= " static"; + $ReturnType =~ s/\s*static\s*//g; + } + + print CLASS "

      ", + refString(escape($ReturnType)), + " ", + "", + escape($astNodeName), "(", + refString(escape($Parameters)), + ") $Const ", + "[", $myvis, "]

      \n"; + } + elsif( $Keyword eq "enum" ) { + print CLASS "

      enum ", + "", + escape($astNodeName), " (", + $Constants,") ", + "[", $visibility, "]

      \n"; + } + elsif( $Keyword eq "typedef" ) { + print CLASS "

      typedef ",refString(escape($Type)), + " ", + escape($astNodeName), + refString(escape($Array)), + " ", + "[", $visibility, "]

      "; + } + + print CLASS "

      Deprecated member.

      \n" + if $MethDeprecated; + print CLASS "

      For internal use only.

      \n" + if $MethInternal; + + $Description =~ s/\n\n+/\n<\/p>

      \n/g; + + print CLASS "

      ",makeReferencedText($Description),"

      \n"; + + + if( $Keyword eq "method" ) { + + if( $#{$ParamDoc} != -1 ) { + print CLASS "
      Parameters:
      \n", + "\n"; + + foreach $parameter ( @{$ParamDoc} ) { + print CLASS + "\n"; + } + + print CLASS "
      \n", + $parameter->{"astNodeName"}; + + print CLASS + "\n", + makeReferencedText( + $parameter->{"Description"}), + "
      \n
      \n"; + + } + + print CLASS "
      Returns:
      \n", + makeReferencedText( $Returns ), + "
      \n" if $Returns ne ""; + + print CLASS "
      Throws:
      \n", + makeReferencedText( $Exceptions ), + "
      \n" if $Exceptions ne ""; + } + + if( $See ne "" ) { + print CLASS "
      See Also:
      "; + + $once = 0; + + foreach $item ( split /[\s,]+/, $See ) { + + if( $once ) { print CLASS ", "; } + else { $once = 1; } + + print CLASS findClassReference( $item ); + } + + print CLASS "
      \n"; + } + + print CLASS $term if $term ne ""; + + Ast::UnVisit(); + + $linkRef++; + } +} + +# +# Check and markup words that are in the symbol table. +# Use sparingly, since EVERY WORD is looked up in the table. +# + +sub refString +{ + my( $source ) = @_; + + foreach $werd ( split /[^\w><]+/, $source ) { + + $ref = findClassReference( $werd ); + if( $ref ne $werd ) { + $source =~ s/$werd/$ref/g; + } + } + + return $source; +} + +###################################################################### +# markupCxxHeader -- Converts the header into a semi-fancy HTML doc +###################################################################### + +$outputFilename = ""; + +# tokens +#$nonIdentifier="[^\w]+"; +#$keywords="if|union|class|struct|operator|for|while|do|goto|new|delete|friend|typedef|return|switch|const|inline|asm|sizeof|virtual|static"; +#$types="void|int|long|float|double|unsigned|char|bool|short"; + +# styles +#$keywordStyle="strong"; +#$typeStyle="u"; +#$stringStyle="i"; + +# Takes the path to a C++ source file, +# spits out a marked-up and cross-referenced HTML file. + +sub markupCxxHeader +{ + my( $filename ) = @_; + $className = ""; + my( $reference ); + my( @inheritance ); + my( $word ); + + open( HFILE, $filename ) || die "Couldn't open $filename to read.\n"; + + $_ = $filename; + # convert dashes to double dash, convert path to dash + s/-/--g/g; + s/\/|\./-/g; + + # never let a file name start with a '-' sign, since this makes + # some programs think the file name really was a parameter to the + # program. Filenames starting with '-' usually happen if you let + # kdoc work on files like '../../include/foo/bar.h', given the + # above substitution rules. Therefore: if a filename starts with + # '-', prepend a '_' + s/^-/_-/; + + $outputFilename = $_; + $outputFilename = $outputdir."/".$outputFilename; + + open( HTMLFILE, ">$outputFilename.html" ) + || die "Couldn't open $outputFilename to read.\n"; + + print HTMLFILE "\n$outputFilename\n". + "\n
      ";
      +
      +	while(  )
      +	{
      +
      +		s//\>/g;
      +		s/"/\"/g;
      +
      +		if( /^\s*(template.*\s+)?(class|struct)/ ) {
      +			$_ = refString($_);
      +		}
      +
      +		print HTMLFILE;
      +	}
      +
      +	print HTMLFILE "
      \n
      \n
      $genText", + "
      \n\n\n"; +} + +#sub Linkize +#{ +# my( $str ) = @_; +# +# $str =~ s/ /%20/g; +# $str =~ s//%3E/g; +# +# return $str; +#} + +1; + diff --git a/deal.II/doc/auto/scripts/kdoc/kdocMan.pm b/deal.II/doc/auto/scripts/kdoc/kdocMan.pm new file mode 100644 index 0000000000..0a82f75df0 --- /dev/null +++ b/deal.II/doc/auto/scripts/kdoc/kdocMan.pm @@ -0,0 +1,379 @@ +# kdocMan -- man page output for kdoc. +# Copyright(c) 1998, Sirtaj Singh Kang (taj@kde.org). + +# $Id$ + +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software +# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +package kdocMan; + +require Ast; + +BEGIN { + $modname = "kdocMan"; + $outputdir = "."; + $genText = ""; + $className = ""; +} + +sub dumpDoc +{ + ( $lib, $root, $outputdir ) = @_; + + print "Generating man pages.\n" unless $main::quiet; + $genText = $main::generatedByText; + $datestamp = `date +%D`; + chop $datestamp; + + writeIndex(); + writeClasses(); +} + +sub writeIndex() +{ + @classNames = (); + %classNodes = (); + + foreach $class ( @{$root->{'classes'}} ) { + push( @classNames, $class->{'astNodeName'} ); + $classNodes{ $class->{'astNodeName'} } = $class; + } + + @classNames = sort @classNames; + + open( MANPAGE, ">$outputdir/$lib.1$lib" ) + || die "Couldn't write to $outputdir/$lib.1$lib\n"; + +print MANPAGE<"); + +print MANPAGE<{ "ClassShort" }; + + print MANPAGE "\n.TP 4\n.BI \"$class\"\n$short\n.PP\n"; + } + + +print MANPAGE<{'classes'}} ) { + $classNode->Visit( $modname ); + $className=$astNodeName; + writeClass(); + Ast::UnVisit(); + } +} + +sub writeClass +{ + ($fname = $astNodeName) =~ tr/[A-Z]/[a-z]/; + $fname .= ".3$lib"; + + $className = $astNodeName; + $Description = makeReferencedText( $Description ); + $Description =~ s/\n\s+/\n/g; + + open ( CLASSMAN, ">$outputdir/$fname" ) + || die "couldn't open $outputdir/$fname for writing.\n"; + + open( REDIR, ">$outputdir/$astNodeName.3$lib" ) + ||die "couldn't open $outputdir/$astNodeName.3$lib ". + " for writing.\n"; + + print REDIR ".so $fname\n"; + close REDIR; + + +print CLASSMAN< + +EOF + +# Internal or Deprecated + +print ".ti +1c\n.b \"Deprecated Class\"\n" if $Deprecated; +print ".ti +1c\n.b \"Internal use only\"\n" if $Internal; + + +print CLASSMAN<{"astNodeName"}; + + if( defined $main::classSource{ + $foreparent->{"astNodeName"}} ) { + print CLASSMAN " (", + $main::classSource{$foreparent->{"astNodeName"}},")"; + } + } + } + else { + print CLASSMAN "nothing"; + } + +print CLASSMAN<" ) { + print MANPAGE "$node"; + if( defined $main::classSource{ $node } ) { + print MANPAGE " (from ",$main::classSource{$node},")"; + } + print MANPAGE "\n"; + } + +# Recurse for each child class + if ( defined $main::children{$node} ) { + print MANPAGE ".in +1c\n"; + foreach $kid ( sort split /;/, $main::children{$node} ) + { + print MANPAGE ".br\n"; + writeHierarchy( $kid ); + } + + print MANPAGE ".in -1c\n"; + } +} + +sub makeReferencedText +{ + my( $str ) = @_; + + $str =~ s/\@ref(\s+[-:#\w\._]+)/\n.BI "$1"\n/g; + + return $str; +} + +sub listMembers +{ + my( $access, $nodelist ) = @_; + my( $node ); + + return if !defined $nodelist || $#{$nodelist} == -1; + +print CLASSMAN<Visit( $modname ); + + print CLASSMAN ".ti -1c\n"; + + if( $Keyword eq "property" ) { + $Type =~ s/^\s+//g; + $Type =~ s/\s+$//g; + print CLASSMAN ".BI \"$Type $astNodeName\"\n.br\n"; + } + elsif( $Keyword eq "method" ) { + $ReturnType =~ s/^\s+//g; + $ReturnType =~ s/\s+$//g; + $ReturnType .= " " if $ReturnType ne ""; + + print CLASSMAN ".BI \"$ReturnType$astNodeName ", + "($Parameters) $Const\"\n.br\n"; + } + elsif( $Keyword eq "enum" ) { + print CLASSMAN ".BI \"", + "enum $astNodeName {$Constants}\"\n.br\n"; + } + elsif( $Keyword eq "typedef" ) { + print CLASSMAN ".BI \"", + "typedef $astNodeName\"\n.br\n"; + } + Ast::UnVisit(); + } + +print CLASSMAN<Visit( $modname ); + + if( $Description eq "" && $See eq "" ) { + Ast::UnVisit(); + next; + } + + if( $Keyword eq "property" ) { + $Type =~ s/^\s+//g; + print CLASSMAN ".SH \"$Type $className","::", + "$astNodeName\"\n"; + } + elsif( $Keyword eq "method" ) { + $ReturnType =~ s/^\s+//g; + $ReturnType =~ s/\s+$//g; + $ReturnType .= " " if $ReturnType ne ""; + + print CLASSMAN ".SH \"$ReturnType$className", + "::","$astNodeName ","($Parameters) $Const\"\n"; + } + elsif( $Keyword eq "enum" ) { + print CLASSMAN ".SH \"", + "enum $className","::", + "$astNodeName {$Constants}\"\n"; + } + elsif( $Keyword eq "typedef" ) { + print CLASSMAN ".SH \"", "typedef $className", + "::","$astNodeName\"\n"; + } + +# Internal or Deprecated + + print ".ti +1c\n.b \"Deprecated member\"\n" if $MethDeprecated; + print ".ti +1c\n.b \"Internal use only\"\n" if $MethInternal; + +# Description + print CLASSMAN makeReferencedText($Description), + "\n.br\n" if $Description ne ""; + +# Parameters + if( $Keyword eq "method" ) { + if( $#{$ParamDoc} != -1 ) { + print CLASSMAN "\n.br\n.in +1c\n", + "Parameters\n.in +1c\n."; + + foreach $parameter ( @{$ParamDoc} ) { +print CLASSMAN ".br\n.BI \"", $parameter->{"astNodeName"}, + "\"\n.in +1c\n", + $parameter->{"Description"}, "\n.in -1c\n"; + } +print CLASSMAN< $outputdir/$name.tex") + || die "Couldn't create $outputdir/".$name.".tex.\n"; + + print TEX<Visit($modname); + + foreach $class ( @{$classes} ) { + + $class->Visit($modname); + + $inPre = 0; + $doc = ""; + + foreach $line ( split /\n/, $Description ) { + if( $line =~ /<(pre|PRE)>/ ) { + $inPre = 1; + $doc .= "\\begin{verbatim}\n"; + next; + } + if( $line =~ m## ) { + $inPre = 0; + $doc .= "\\end{verbatim}\n"; + next; + } + if( !$inPre ) { + $line =~ s/\@ref(\s*(#|::))?//g; + $line =~ s/([~#\$\\\&%#_\{\}])/\\$1/g; + $line =~ s/<(code|pre)>/\\texttt\{/g; + $line =~ s/<\/(code|pre)>/}/g; + $line =~ s/([<>])/\\texttt\{$1\} /g; + $line =~ s/~/\\texttt{~}\\relax /g; + } + + $doc .= $line."\n"; + } + + $ClassName = escape( $astNodeName ); + $Header = escape( $Header ); + $ClassSee = escape( $ClassSee ); + + print TEX<{ "TmplArgs" } ne "" ) { + print TEX "\\begin{description}\n", + "\\item{template form:}", + "\\texttt{template <", escape( $class->{ "TmplArgs" } ), + "> ", + $ClassName, "}\n"; + + print TEX "\\end{description}\n"; + } + + if( defined $class->{ "Ancestors" } ){ + print TEX "\\begin{description}\n", + "\\item{inherits:}"; + + foreach $ancestor ( @{$Ancestors} ) { + $ancName = $ancestor->{"astNodeName"}; + + $str = " ".$ancName; + + if( defined $main::classSource{ $ancName } ) { + $str .="(".$main::classSource{$ancName}. + ")"; + } + + print TEX escape( $str ),"\n"; + } + + print TEX "\\end{description}\n"; + } + + + if( $Author ne "" || $Version ne "" || $ClassShort ne "" + || $ClassSee ne "" ) { + print TEX "\\begin{description}\n"; + + print TEX "\\item[Description:] ", escape( $ClassShort ),"\n" + if $ClassShort ne ""; + print TEX "\\item[Version:] ", escape( $Version ),"\n" + if $Version ne ""; + + print TEX "\\item[Author:] ", escape( $Author ),"\n" + if $Author ne ""; + + print TEX "\\item[See Also:] ", escape( $ClassSee ),"\n" + if $ClassSee ne ""; + + print TEX "\\end{description}\n"; + } + + print TEX "$doc\n\n" if $Description ne ""; + + dumpMembers( "public members", $public ) + if defined $class->{"public"}; + dumpMembers( "public slots", $public_slots ) + if defined $class->{"public_slots"}; + dumpMembers( "protected members", $protected ) + if defined $class->{"protected"}; + dumpMembers( "protected slots", $protected_slots ) + if defined $class->{"protected_slots"}; + dumpMembers( "signals", $signals ) + if defined $class->{"signals"}; + + if( $main::dontDoPrivate == 0 ) { + dumpMembers( "private members", $private ) + if defined $class->{"private"}; + dumpMembers( "private slots", $private_slots ) + if defined $class->{"private_slots"}; + } + + Ast::UnVisit(); + } + + Ast::UnVisit(); + + print TEX "\\printindex\n\\end{document}\n"; + +} + +sub dumpMembers +{ + my( $access, $nodes ) = @_; + + print TEX "\\subsection{$access}\n"; + + foreach $member ( @{$nodes} ) { + + $member->Visit($modname); + + $inPre = 0; + $doc = ""; + + foreach $line ( split /\n/, $Description ) { + if( $line =~ /<(pre|PRE)>/ ) { + $inPre = 1; + $doc .= "\\begin{verbatim}\n"; + next; + } + if( $line =~ /<\/(pre|PRE)>/ ) { + $inPre = 0; + $doc .= "\\end{verbatim}\n"; + next; + } + if( !$inPre ) { + $line =~ s/\@ref(\s*(#|::))?//g; + $line =~ s/([~#\$\\\&%#_\{\}])/\\$1/g; + $line =~ s/<(code|pre)>/\\texttt\{/g; + $line =~ s/<\/(code|pre)>/}/g; + $line =~ s/([<>])/\\texttt\{$1\} /g; + $line =~ s/~/\\texttt{~}\\relax /g; + } + + $doc .= $line."\n"; + } + + $astNodeName = escape( $astNodeName ); + + + print TEX<]+)/\\texttt\{$1\}/g; + $str =~ s/~/\\mtl /g; + + return $str; +} + +1; -- 2.39.5