<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">
package kdocCxxDocbook;
use Carp;
use File::Path;
use kdocDocIter;
use kdocAstUtil;
use kdocAstSearch;
use Iter;

use strict;
no strict "subs";

use vars qw/ $lib $rootnode $outputdir $opt $paraOpen/;

=head2 kdocCxxDocBook

	TODO:

	Templates
	Fix tables, add index.
	Global docs
	Groups

=cut

sub writeDoc
{
	( $lib, $rootnode, $outputdir, $opt ) = @_;

	makeReferences( $rootnode );

	$lib = "kdoc-out" if $lib eq "";	# if no library name set

	mkpath( $outputdir) unless -f $outputdir;

	open ( DOC, "&gt;$outputdir/$lib.sgml" ) || die "Couldn't write output.";

	my $time = localtime;

print DOC&lt;&lt;EOF;
&lt;?xml version="1.0" ?&gt;
&lt;!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kde.dtd" [
]&gt;
&lt;book id="$lib-lib"&gt;
	&lt;bookinfo&gt;
		&lt;date&gt;$time&lt;/date&gt;
		&lt;title&gt;$lib API Documentation&lt;/title&gt;
	&lt;/bookinfo&gt;
EOF

	printLibDoc();
	printHierarchy();
	printClassIndex();
	printClassDoc();

print DOC&lt;&lt;EOF;
&lt;/book&gt;
EOF

}

sub printLibDoc
{
	return unless kdocAstUtil::hasDoc( $rootnode );
	
	print DOC chapter( "$lib-intro", "Introduction" );
	printDoc( $rootnode-&gt;{DocNode}, *DOC, $rootnode );
	print DOC C( "chapter" );
}


sub printHierarchy
{

	print DOC chapter( "class-hierarchy", "$lib Class Hierarchy" );

	my $first = 0;
	my @firststack = ();

	Iter::Hierarchy( $rootnode,
		sub {	# down
			print DOC "&lt;itemizedlist&gt;\n";
			push @firststack, $first;
			$first = 1;
		},
		sub {	# print
			my $node = shift;
			return if $node == $rootnode;

			if( $first ) {
				$first = 0;
			}
			else {
				print DOC "&lt;/listitem&gt;";
			}

			my $src = defined $node-&gt;{ExtSource} ? " ($node-&gt;{ExtSource})":"";
			print DOC "&lt;listitem&gt;&lt;para&gt;", refName($node), "$src&lt;/para&gt;\n"
		},
		sub {	# up
			$first = pop @firststack;
			if( $first ) {
				print DOC "&lt;/itemizedlist&gt;\n";
			}
			else {
				print DOC "&lt;/listitem&gt;&lt;/itemizedlist&gt;\n";
			}
		}, 		# no kids
		sub { print DOC "&lt;/listitem&gt;"; }
	);
		
	print DOC C( "chapter" ); 
}

sub printClassIndex
{
	my @clist = ();
	kdocAstUtil::makeClassList( $rootnode, \@clist );

	print DOC chapter( "class-index", "$lib Class Index" ),
		O( "table", "tocentry", 0, "pgwide", 1, "colsep", 0 ),
		tblk( "title", $lib,' classes' ),
		O( "tgroup", "cols", 2  ), O( "tbody" );

	foreach my $kid ( @clist ) {

		# Internal, deprecated, abstract
		my $name = refName( $kid );

		if ( $kid-&gt;{Abstract} ) {
			$name = tblk( "emphasis", $name );
		}

		my $extra = "";

		if ( $kid-&gt;{Internal} ) {
			$extra .= " internal";
		}

		if ( $kid-&gt;{Deprecated} ) {
			$extra .= " ".tblk( "emphasis", "deprecated" );
		}

		$extra = " [$extra]" unless $extra eq "";
		
		# print class entry
		print DOC tblk( 'row', tblk( 'entry', $name )
			. tblk( 'entry', deref( $kid-&gt;{DocNode}-&gt;{ClassShort},
				$rootnode).$extra ));
	}

	print DOC C( "tbody", "tgroup", "table", "chapter" );
}

sub printClassDoc
{
	print DOC chapter( "class-doc", "$lib Class Documentation" );

	Iter::LocalCompounds( $rootnode, sub { docChildren( shift ); } );

	print DOC C("chapter"), "\n";
}

sub docChildren
{
	my ( $node ) = @_;

	return if $node == $rootnode;
	
	## document self
	printClassInfo( $node );
	
	if ( kdocAstUtil::hasDoc( $node ) ) {
		printDoc( $node-&gt;{DocNode}, *DOC{IO}, $rootnode, 1 );
	}

	# First a member index by type
	print DOC O( "sect2" ),
		"Interface Synopsis", C( "sect2" );

	Iter::MembersByType( $node,
		sub {	# start
		print DOC O( 'table', 'pgwide', 1, "colsep", 0,
				"rowsep", 0, "tocentry", 0 ),
			tblk( 'title', fullName($node)," ",$_[0] ),
			O( "tgroup", "cols", 1 ), O( "tbody" );
		},
		\&amp;sumListMember, # print
		sub {	# end
			print DOC C( "tbody", "tgroup", "table" ), "\n";
		},
		sub {	# no kids
			print DOC tblk( "para", "(Empty interface)" );
		}
	);

	print DOC O( "sect2" );
	print DOC "Member Documentation", C( "sect2" );

	# Then long docs for each member
	Iter::MembersByType ( $node, undef, \&amp;printMemberDoc, undef,
		sub { print DOC tblk( "para", "(Empty interface)" ); }
	);
	
	print DOC C( "sect1" );

	return;
}

sub printClassInfo
{
	my $node = shift;

	print DOC O( "sect1", "id", $node-&gt;{DbRef},
				"xreflabel", fullName( $node, "::" ) ), "\n",
		tblk( "title", esc($node-&gt;{NodeType})," ",fullName( $node ) );


	if ( defined $node-&gt;{DocNode} &amp;&amp;  $node-&gt;{DocNode}-&gt;{ClassShort} ) {
		printClassInfoField( "Description", 
			deref( $node-&gt;{DocNode}-&gt;{ClassShort}, $rootnode ) );
	}

	printClassInfoField( "Header", tblk( "literal", 
			$node-&gt;{Source}-&gt;{astNodeName} ));

	my ($text, $comma ) = ("", "");

	Iter::Ancestors( $node, $rootnode, undef, undef,
		sub { # print
			my ( $node, $name, $type ) = @_;
			$name = refName( $node ) if defined $node;
			$name .= " (".$node-&gt;{ExtSource}.")" if defined $node-&gt;{ExtSource};
			$text .= $comma.$name;
			$text .= " [$type]" unless $type eq "public";

			$comma = ", ";
		},
		sub { # end
			printClassInfoField( "Inherits", $text );
		}
	);
	
	$text = $comma = "";

	Iter::Descendants( $node, undef, undef,
		sub { # print
			my $desc = shift;
			$text .= $comma.refName( $desc );
			$text .= " (".$desc-&gt;{ExtSource}.")" if defined $desc-&gt;{ExtSource};

			$comma = ", ";
		},
		sub { # end
			printClassInfoField( "Inherited By", $text );
		}
	);

	if ( $node-&gt;{Internal} ) {
		printClassInfoField( "note", "Internal use only." );
	}

	if ( $node-&gt;{Deprecated} ) {
		printClassInfoField( "note", "Deprecated, to be removed." );
	}

	return;
}

sub printClassInfoField
{
	my ( $label, $text ) = @_;

	print DOC tblk( "formalpara", tblk( "title", $label ),
			tblk( "para", " ".$text ) );
}

sub sumListMember
{
	my( $class, $m ) = @_;

	print DOC O( "row"), O( "entry" );


	my $type = $m-&gt;{NodeType};
	my $name = esc( $m-&gt;{astNodeName} );
	my $pname = tblk( "emphasis", $name );

	if( $type eq "var" ) {
		print DOC tblk( "literal", esc($m-&gt;{Type}) ), " $pname\n";
	}
	elsif( $type eq "method" || $type eq "fnptr" ) {
		my $flags = $m-&gt;{Flags};

		if ( !defined $flags ) {
			warn "Method ".$m-&gt;{astNodeName}.
				" has no flags";
		}

		my $extra = "";
		$extra .= "virtual " if $flags =~ "v";
		$extra .= "static " if $flags =~ "s";

		my $params = esc( $m-&gt;{Params} );
		$params =~ s/^\s+//g;
		$params =~ s/\s+$//g;
		$params = " $params " unless $params eq "";
		my $c = $flags =~ /c/ ? " const" : "";
		my $p = $flags =~ /p/ ? " [pure]" : "";

		$pname = "(*$pname)" if $type eq "fnptr";


		print DOC esc($m-&gt;{ReturnType}), "  $pname\($params\)$c$p\n";
	}
	elsif( $type eq "enum" ) {
		my $n = $name eq "" ? "" : $pname." ";

		print DOC tblk("literal","enum"),
			" $n\{ ",tblk("literal",esc($m-&gt;{Params}))," }";
	}
	elsif( $type eq "typedef" ) { 
		print DOC tblk( "literal", "typedef " ), esc($m-&gt;{Type}), 
				tblk( "emphasis", $name );
	}
	else { 
		# unknown type
		print DOC tblk( "literal", esc( $type ) )," $pname\n";
	}

	print DOC C( "entry" ), C( "row" ),"\n";

	return;
}

=head2 printMemberDoc

	params: classnode, membernode

	Prints title and long documentation for one class member.

=cut

sub printMemberDoc
{
	my ( $class, $mem ) = @_;

	return unless kdocAstUtil::hasDoc( $mem );

	print DOC O( "sect3", "id",	$mem-&gt;{DbRef},
			"xreflabel", fullName( $mem, "::" ) );

	# title
	my $type = $mem-&gt;{NodeType};
	my $name = esc( $mem-&gt;{astNodeName} );
	my $pname = tblk( "emphasis", $name );

	if( $type eq "var" ) {
		print DOC tblk( "literal", esc($mem-&gt;{Type}) ), " $pname\n";
	}
	elsif( $type eq "method" || $type eq "fnptr" ) {
		my $flags = $mem-&gt;{Flags};

		if ( !defined $flags ) {
			warn "Method ".$mem-&gt;{astNodeName}.
				" has no flags";
		}

		my $extra = "";
		$extra .= "virtual " if $flags =~ "v";
		$extra .= "static " if $flags =~ "s";

		my $params = $mem-&gt;{Params};
		$params =~ s/^\s+//g;
		$params =~ s/\s+$//g;
		$params = " $params " unless $params eq "";
		my $c = $flags =~ /c/ ? " const" : "";
		my $p = $flags =~ /p/ ? " [pure]" : "";

		$pname = "(*$pname)" if $type eq "fnptr";

		print DOC deref($mem-&gt;{ReturnType}, $rootnode), "  $pname\(".
			deref( $params, $rootnode )."\)$c$p\n";
	}
	elsif( $type eq "enum" ) {
		my $n = $name eq "" ? "" : $pname." ";

		print DOC tblk("literal","enum"),
			" $n\{ ",tblk("literal",esc($mem-&gt;{Params}))," }";
	}
	elsif( $type eq "typedef" ) { 
		print DOC tblk( "literal", "typedef" ), " ", esc($mem-&gt;{Type}), $pname;
	}
		# TODO nested compounds
	else { 
		# unknown type
		print DOC tblk( "literal", esc( $type ) )," $pname\n";
	}

	print DOC C( "sect3" );

	# documentation
	printDoc( $mem-&gt;{DocNode}, *DOC, $rootnode );

	if ( $type eq "method" ) {
		my $ref = kdocAstSearch::findOverride( $rootnode,
				$class, $mem-&gt;{astNodeName} );
		if ( defined $ref ) {
			print DOC tblk( "formalpara",
				tblk( "title", "Reimplemented from" ),
				tblk( "para", fullName( $ref-&gt;{Parent}, "::" )) ), "\n";
		}
	}
}

=head2 printDoc

Parameters: docnode, *filehandle, rootnode, compound

Print a doc node. If compound is specified and non-zero, various
compound node properties are not printed.

=cut

sub printDoc
{
	my $docNode = shift;
	local *CLASS = shift;

        my ( $rootnode, $comp ) = @_;
        my $node;
        my $type;
	my $text;
	my $lasttype = "none";

	$comp = 0 if !defined $comp;

	# Main body
	kdocDocIter::TextIter( $docNode,
		sub { # start
			$paraOpen = 0;
		},
		sub { # end
			print CLASS "", pc();
		},
		sub { # text
			print CLASS "", pc(), po(), deref( $_[1], $rootnode );
		},
		sub { # ref
			my ( $node, $name, $ref ) = @_;
			print CLASS defined $ref ? refName($ref) : $name;
		}, 
		sub { # sect
			print CLASS "",pc(), O(  "sect4" ),
					deref( $_[1], $rootnode ), C( "sect4" ),"\n";
		},
		sub { # pre
			print CLASS "",pc(),tblk( "programlisting", esc( $_[1] ) );
		},
		sub { # img
			print CLASS "", pc(),"&lt;graphic fileref=\"$_[2]\"&gt;&lt;/graphic&gt;";

		},
		undef, #para
		sub { # list start
			print CLASS "", pc(),"&lt;itemizedlist&gt;\n";
		},
		sub { # list end
			print CLASS "", pc(),"&lt;/itemizedlist&gt;\n";
		},
		sub { # item
			print CLASS "", tblk( "listitem",
					tblk("para", deref($_[1], $rootnode )));
		}
	);

	# Params
	kdocDocIter::ParamIter( $docNode,
		sub { # start
			print CLASS "", O( 'table', 'pgwide', 0, "colsep", 0,
				"frame", "none", "tocentry", 0 ),
				tblk( 'title', 'Parameters' ),
				O( "tgroup", "cols", "2" ), O( "tbody" );
		},
		sub { # end
			print CLASS "", C( "tbody", "tgroup", "table" );
		},
		sub { # print
			print CLASS "&lt;row&gt;&lt;entry&gt;", esc( shift ),
				"&lt;/entry&gt;&lt;entry&gt;", deref( shift, $rootnode ),
				"&lt;/entry&gt;&lt;/row&gt;\n";
		}
	);

	# Return
	printTextItem( $docNode, *CLASS, "Returns" );

	# Exceptions
	$text = $docNode-&gt;{Throws};

	if ( defined $text ) {
		my $comma = "&lt;formalpara&gt;&lt;title&gt;Exceptions&lt;/title&gt;&lt;para&gt;";

		foreach my $tosee ( @$text ) {
			print CLASS $comma, esc( $tosee );
			$comma = ", ";
		}
		print CLASS C( "para", "formalpara" );
	}

	# See
	my $comma = "";
	
	kdocDocIter::SeeAlso ( $docNode, undef,
		sub { # start
			print CLASS "", O( "tip" ),tblk( "title", "See Also"),O( "para" );
		},
		sub { # print
			my ( $label, $ref ) = @_;
			$label = defined $ref ? refName( $ref ):esc( $label );

			print CLASS $comma, $label;
			$comma = ", ";
		},
		sub { # end
			print CLASS "", C( "para", "tip" );
		}
	);
	
	printTextItem( $docNode, *CLASS, "Since" );
	printTextItem( $docNode, *CLASS, "Version" );
	printTextItem( $docNode, *CLASS, "Id" );
	printTextItem( $docNode, *CLASS, "Author" );
}

sub makeReferences
{
	my $root = shift;
	my $idcount = 0;

	return Iter::Tree( $root, 1,
		sub {
				my ( $parent, $node ) = @_;
				return if $node-&gt;{ExtSource};

				$idcount++;

				$node-&gt;{DbRef} = "docid-$idcount" ;

#				print fullName( $node ), " = ", $node-&gt;{DbRef},"\n";

				return;
		}
	);
}

sub printTextItem
{
	my $node = shift;
	local *CLASS = shift;
	my ( $prop, $label ) = @_;

	my $text = $node-&gt;{ $prop };
	
	return unless defined $text;
	$label = $prop unless defined $label;
	
	print CLASS "&lt;formalpara&gt;&lt;title&gt;", $label, "&lt;/title&gt;&lt;para&gt; ", 
		deref( $text, $rootnode  ), "&lt;/para&gt;&lt;/formalpara&gt;\n";
}


# utilities


sub refName
{
	my( $node ) = @_;

	return fullName( $node ) if defined $node-&gt;{ExtSource}
		|| !kdocAstUtil::hasDoc( $node );

	return '&lt;xref linkend="'.$node-&gt;{DbRef}.'"/&gt;';
}

sub fullName
{
	my( $node, $sep ) = @_;

	$sep = "::" unless defined $sep;

	my @heritage = kdocAstUtil::heritage( $node );
	foreach my $n ( @heritage ) { $n = esc( $n ); }

	return join( $sep, @heritage );
}

=head2 deref

	Parameters: text, rootnode
	returns text

	dereferences all @refs in the text and returns it.

=cut

sub deref
{
	my ( $str, $rootnode ) = @_;
	confess "rootnode is null" if !defined $rootnode;
	my $out = "";
	my $text;

	foreach $text ( split (/(\@\w+\s+[\w:#]+)/, $str ) ) {
		if ( $text =~ /\@ref\s+([\w:#]+)/ ) {
			my $name = $1;
			$name =~ s/^\s*#//g;
			$out .= wordRef( $name, $rootnode );
		}
		elsif ( $text =~ /\@p\s+([\w:]+)/ ) {
			$out .= tblk( "literal", esc($1) );
		}
		else {
			$out .= esc($text);
		}
	}

	return $out;
}



=head2 wordRef

	Parameters: word

	Prints a hyperlink to the word's reference if found, otherwise
	just prints the word. Good for @refs etc.

=cut

sub wordRef
{
	my ( $str, $rootnode ) = @_;
	confess "rootnode is undef" if !defined $rootnode;

	return "" if $str eq "";

	my $ref = kdocAstSearch::findRef( $rootnode, $str );
	return esc($str) if !defined $ref;

	return refName( $ref );
}


=head2 esc

	Escape special SGML characters for normal text.

=cut

sub esc
{
	my $str = $_[ 0 ];

	return "" if !defined $str || $str eq "";

	$str =~ s/&amp;/&amp;amp;/g;
	$str =~ s/&lt;/&amp;lt;/g;
	$str =~ s/&gt;/&amp;gt;/g;

	return $str;
}


sub chapter
{
	my ( $id, $title ) = @_;

	return "&lt;chapter id=\"$id\"&gt;&lt;title&gt;$title&lt;/title&gt;";
}


=head2 tblk

	Params: tagname, text..

	Inserts text in a block tag of type tagname (ie both
	opening and closing tags)
=cut

sub tblk
{
	my $tag = shift;
	return "&lt;$tag&gt;".join( "", @_ )."&lt;/$tag&gt;";
}


=head2 O

	Params: tagname, list of id and idtext interspersed.

=cut

sub O
{
	my $tag = shift;

	carp "mismatched ids and tags" if ($#_+1) % 2 != 0;

	my $out = "&lt;$tag";

	while ( $#_ &gt;= 0 ) {
		$out .= " ".shift( @_ ).'="'.shift( @_ ).'"';
	}

	$out .= "&gt;";

	return $out;
}

=head2 C

	Params: list of tagnames

	returns a list of close tags in the order specified in the
	params.

=cut

sub C
{
	my $out = "";

	foreach my $tag ( @_ ) {
		$out .= "&lt;/$tag&gt;";
	}

	return $out;
}

sub po
{
	my $text = $paraOpen ? "" : "&lt;para&gt;";
	$paraOpen = 1;

	return $text;
}

sub pc
{
	my $text = $paraOpen ? "&lt;/para&gt;" : "";
	$paraOpen = 0;

	return $text;
}
1;
</pre></body></html>