From c89c2dd4c59632e3658b980ddbb708e34d6d9d32 Mon Sep 17 00:00:00 2001 From: Stefan Stranz Date: Fri, 5 Jun 2009 20:57:24 -0600 Subject: [PATCH] c2man: Add xml documentation creation. --- Make.rules.in | 6 +- Makefile.in | 5 +- dlls/Makedll.rules.in | 5 +- documentation/Makefile.in | 9 ++- tools/c2man.pl | 132 ++++++++++++++++++++++++++++++++++---- 5 files changed, 136 insertions(+), 21 deletions(-) diff --git a/Make.rules.in b/Make.rules.in index b1ccd7c1040..c01a2b714a4 100644 --- a/Make.rules.in +++ b/Make.rules.in @@ -302,11 +302,15 @@ $(DOCSUBDIRS:%=%/__doc_html__): dummy $(DOCSUBDIRS:%=%/__doc_sgml__): dummy @cd `dirname $@` && $(MAKE) doc-sgml +$(DOCSUBDIRS:%=%/__doc_xml__): dummy + @cd `dirname $@` && $(MAKE) doc-xml + man: $(DOCSUBDIRS:%=%/__man__) doc-html: $(DOCSUBDIRS:%=%/__doc_html__) doc-sgml: $(DOCSUBDIRS:%=%/__doc_sgml__) +doc-xml: $(DOCSUBDIRS:%=%/__doc_xml__) -.PHONY: man doc-html doc-sgml $(DOCSUBDIRS:%=%/__man__) $(DOCSUBDIRS:%=%/__doc_html__) $(DOCSUBDIRS:%=%/__doc_sgml__) +.PHONY: man doc-html doc-sgml doc-xml $(DOCSUBDIRS:%=%/__man__) $(DOCSUBDIRS:%=%/__doc_html__) $(DOCSUBDIRS:%=%/__doc_sgml__) $(DOCSUBDIRS:%=%/__doc_xml__) # Misc. rules diff --git a/Makefile.in b/Makefile.in index 5d9039a3f56..7c1eb50663b 100644 --- a/Makefile.in +++ b/Makefile.in @@ -16,6 +16,7 @@ # manpages: compile manpages for Wine API # htmlpages: compile html pages for Wine API # sgmlpages: compile sgml source for the Wine API Guide +# xmlpages: compile xml source for the Wine API Guide # Directories @@ -132,14 +133,14 @@ tags ctags: $(RM) tags (test -d .git && git ls-files '*.[chly]' '*.idl' || find -L $(TOPSRCDIR) -name '*.[ch]' -print) | xargs ctags -a -manpages htmlpages sgmlpages: dummy +manpages htmlpages sgmlpages xmlpages: dummy @cd documentation && $(MAKE) $@ distclean:: clean $(RM) config.* configure.lineno TAGS tags include/config.h include/stamp-h $(RM) -r autom4te.cache -.PHONY: manpages htmlpages sgmlpages distclean +.PHONY: manpages htmlpages sgmlpages xmlpages distclean # Makefile rules diff --git a/dlls/Makedll.rules.in b/dlls/Makedll.rules.in index 5a77d9e4a17..9c7be290e0b 100644 --- a/dlls/Makedll.rules.in +++ b/dlls/Makedll.rules.in @@ -70,7 +70,10 @@ doc-html: $(C_SRCS) dummy doc-sgml: $(C_SRCS) dummy $(C2MAN) -o $(TOPOBJDIR)/documentation/api-guide -R$(TOPOBJDIR) -C$(SRCDIR) $(INCLUDES) -Ts $(MAINSPEC:%=-w %) $(SPEC_SRCS16:%=-w %) $(C_SRCS) $(C_SRCS16) -.PHONY: man doc-html doc-sgml +doc-xml: $(C_SRCS) dummy + $(C2MAN) -o $(TOPOBJDIR)/documentation/api-guide-xml -R$(TOPOBJDIR) -C$(SRCDIR) $(INCLUDES) -Tx $(MAINSPEC:%=-w %) $(SPEC_SRCS16:%=-w %) $(C_SRCS) $(C_SRCS16) + +.PHONY: man doc-html doc-sgml doc-xml # Rules for installation diff --git a/documentation/Makefile.in b/documentation/Makefile.in index 4723a540731..ece117cd5c0 100644 --- a/documentation/Makefile.in +++ b/documentation/Makefile.in @@ -4,7 +4,7 @@ SRCDIR = @srcdir@ VPATH = @srcdir@ MODULE = none -INSTALLDIRS = man$(api_manext) html api-guide $(DESTDIR)$(mandir)/man$(api_manext) +INSTALLDIRS = man$(api_manext) html api-guide api-guide-xml $(DESTDIR)$(mandir)/man$(api_manext) @MAKE_RULES@ @@ -17,10 +17,13 @@ htmlpages: html dummy sgmlpages: api-guide dummy @cd $(DLLDIR) && $(MAKE) doc-sgml -.PHONY: manpages htmlpages sgmlpages install-man +xmlpages: api-guide-xml dummy + @cd $(DLLDIR) && $(MAKE) doc-xml + +.PHONY: manpages htmlpages sgmlpages xmlpages install-man install-man:: manpages $(DESTDIR)$(mandir)/man$(api_manext) for i in man$(api_manext)/*.$(api_manext); do $(INSTALL_DATA) $$i $(DESTDIR)$(mandir)/$$i; done clean:: - $(RM) -r html api-guide man$(api_manext) + $(RM) -r html api-guide api-guide-xml man$(api_manext) diff --git a/tools/c2man.pl b/tools/c2man.pl index b1fd0222f97..62d7e1759d2 100755 --- a/tools/c2man.pl +++ b/tools/c2man.pl @@ -44,7 +44,7 @@ my $opt_output_directory = "man3w"; # All default options are for nroff (man pag my $opt_manual_section = "3w"; my $opt_source_dir = ""; my $opt_wine_root_dir = ""; -my $opt_output_format = ""; # '' = nroff, 'h' = html, 's' = sgml +my $opt_output_format = ""; # '' = nroff, 'h' = html, 's' = sgml, 'x' = xml my $opt_output_empty = 0; # Non-zero = Create 'empty' comments (for every implemented function) my $opt_fussy = 1; # Non-zero = Create only if we have a RETURNS section my $opt_verbose = 0; # >0 = verbosity. Can be given multiple times (for debugging) @@ -80,7 +80,9 @@ sub output_html_index_files(); sub output_html_stylesheet(); sub output_open_api_file($); sub output_sgml_dll_file($); +sub output_xml_dll_file($); sub output_sgml_master_file($); +sub output_xml_master_file($); sub output_spec($); sub process_comment($); sub process_extra_comment($); @@ -1299,6 +1301,13 @@ sub output_spec($) output_sgml_dll_file($spec_details); return; } + + if ($opt_output_format eq "x") + { + output_xml_dll_file($spec_details); + return; + } + } # @@ -1322,6 +1331,10 @@ sub output_open_api_file($) { $output_name = $output_name.".sgml"; } + elsif ($opt_output_format eq "x") + { + $output_name = $output_name.".xml"; + } else { $output_name = $output_name.".".$opt_manual_section; @@ -1350,7 +1363,7 @@ sub output_api_header($) print OUTPUT "{COMMENT_NAME}\">\n"; print OUTPUT "Wine API: $comment->{COMMENT_NAME}\n\n\n"; } - elsif ($opt_output_format eq "s") + elsif ($opt_output_format eq "s" || $opt_output_format eq "x") { print OUTPUT "\n", "\n", @@ -1373,7 +1386,7 @@ sub output_api_footer($) " Visit WineHQ for license details.". " Generated $date.

\n\n\n"; } - elsif ($opt_output_format eq "s") + elsif ($opt_output_format eq "s" || $opt_output_format eq "x") { print OUTPUT "\n"; return; @@ -1392,7 +1405,7 @@ sub output_api_section_start($$) { print OUTPUT "\n

",$section_name,"

\n"; } - elsif ($opt_output_format eq "s") + elsif ($opt_output_format eq "s" || $opt_output_format eq "x") { print OUTPUT "",$section_name,"\n"; } @@ -1427,7 +1440,7 @@ sub output_api_name($) "  ", ,$dll_ordinal,"

\n"; } - elsif ($opt_output_format eq "s") + elsif ($opt_output_format eq "s" || $opt_output_format eq "x") { print OUTPUT "\n ",$readable_name," ", $dll_ordinal,"\n\n"; @@ -1452,7 +1465,7 @@ sub output_api_synopsis($) print OUTPUT "
\n ", $comment->{RETURNS}," ",$comment->{COMMENT_NAME},"\n (\n";
     @fmt = ("", "\n", "", "");
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
     print OUTPUT "\n ",$comment->{RETURNS}," ",$comment->{COMMENT_NAME},"\n (\n";
     @fmt = ("", "\n", "", "");
@@ -1506,7 +1519,7 @@ sub output_api_synopsis($)
   {
     print OUTPUT " )\n
\n"; } - elsif ($opt_output_format eq "s") + elsif ($opt_output_format eq "s" || $opt_output_format eq "x") { print OUTPUT " )\n\n"; } @@ -1534,7 +1547,7 @@ sub output_api_comment($) "\n", "
\n","","\n","",""); } - elsif ($opt_output_format eq "s") + elsif ($opt_output_format eq "s" || $opt_output_format eq "x") { @fmt = ("\n","\n\n","","","","", "","","","","","", @@ -1561,7 +1574,7 @@ sub output_api_comment($) for (@{$comment->{TEXT}}) { - if ($opt_output_format eq "h" || $opt_output_format eq "s") + if ($opt_output_format eq "h" || $opt_output_format eq "s" || $opt_output_format eq "x") { # Map special characters s/\&/\&/g; @@ -1609,7 +1622,7 @@ sub output_api_comment($) # Leading cases ("xxxx:","-") start new paragraphs & are emphasised # FIXME: Using bullet points for leading '-' would look nicer. - if ($open_paragraph == 1) + if ($open_paragraph == 1 && $param_docs == 0) { s/^(\-)/$fmt[1]$fmt[0]$fmt[4]$1$fmt[5]/; s/^([[A-Za-z\-]+\:)/$fmt[1]$fmt[0]$fmt[4]$1$fmt[5]/; @@ -1671,6 +1684,7 @@ sub output_api_comment($) if ($param_docs == 1) { print OUTPUT $fmt[17],$fmt[15]; + $param_docs = 0; } else { @@ -1687,7 +1701,7 @@ sub output_api_comment($) else { #print OUTPUT $fmt[15]; - $param_docs = 0; + #$param_docs = 0; } } elsif ( /^$/ ) @@ -1752,6 +1766,15 @@ sub output_api_comment($) { print OUTPUT $fmt[13]; } + if ($param_docs == 1 && $open_paragraph == 1) + { + print OUTPUT $fmt[17]; + $open_paragraph = 0; + } + if ($param_docs == 1) + { + print OUTPUT $fmt[15]; + } if ($open_paragraph == 1) { print OUTPUT $fmt[1]; @@ -1792,7 +1815,7 @@ sub output_master_index_files() TEXT => [], }; - if ($opt_output_format eq "s") + if ($opt_output_format eq "s" || $opt_output_format eq "x") { $comment->{COMMENT_NAME} = "Introduction"; $comment->{ALT_NAME} = "Introduction", @@ -1849,7 +1872,7 @@ sub output_master_index_files() } output_open_api_file("index"); } - elsif ($opt_output_format eq "s") + elsif ($opt_output_format eq "s" || $opt_output_format eq "x") { # Just write this as the initial blurb, with a chapter heading output_open_api_file("blurb"); @@ -1860,7 +1883,7 @@ sub output_master_index_files() output_api_header($comment); output_api_comment($comment); output_api_footer($comment); - if ($opt_output_format eq "s") + if ($opt_output_format eq "s" || $opt_output_format eq "x") { print OUTPUT "\n" # finish the chapter } @@ -1871,6 +1894,11 @@ sub output_master_index_files() output_sgml_master_file(\@dlls); return; } + if ($opt_output_format eq "x") + { + output_xml_master_file(\@dlls); + return; + } if ($opt_output_format eq "h") { output_html_index_files(); @@ -1879,6 +1907,37 @@ sub output_master_index_files() } } +# Write the master wine-api.xml, linking it to each dll. +sub output_xml_master_file($) +{ + my $dlls = shift; + + output_open_api_file("wine-api"); + print OUTPUT ""; + print OUTPUT "\n"; + print OUTPUT "\n"; + + # List the entities + for (@$dlls) + { + $_ =~ s/(\..*)?\n//; + print OUTPUT "\n" + } + + print OUTPUT "]>\n\n\nThe Wine Api Guide\n\n"; + print OUTPUT " &blurb;\n"; + + for (@$dlls) + { + print OUTPUT " &",$_,";\n" + } + print OUTPUT "\n\n\n"; + + output_close_api_file(); +} + # Write the master wine-api.sgml, linking it to each dll. sub output_sgml_master_file($) { @@ -1952,6 +2011,50 @@ sub output_sgml_dll_file($) `mv $tmp_name $opt_output_directory/$spec_details->{DLL_NAME}.sgml`; } +# Produce the xml for the dll chapter from the generated files +sub output_xml_dll_file($) +{ + my $spec_details = shift; + + # Make a list of all the documentation files to include + my $exports = $spec_details->{EXPORTS}; + my @source_files = (); + for (@$exports) + { + # @$_ => ordinal, call convention, exported name, implementation name, documented; + if (@$_[1] ne "forward" && @$_[1] ne "extern" && @$_[1] ne "stub" && @$_[1] ne "equate" && + @$_[1] ne "variable" && @$_[1] ne "fake" && @$_[4] & 1) + { + # A documented function + push (@source_files,@$_[3]); + } + } + + push (@source_files,@{$spec_details->{EXTRA_COMMENTS}}); + + @source_files = sort @source_files; + + # create a new chapter for this dll + my $tmp_name = $opt_output_directory."/".$spec_details->{DLL_NAME}.".tmp"; + open(OUTPUT,">$tmp_name") || die "Couldn't create $tmp_name\n"; + print OUTPUT "\n\n$spec_details->{DLL_NAME}\n"; + output_close_api_file(); + + # Add the sorted documentation, cleaning up as we go + `cat $opt_output_directory/$spec_details->{DLL_NAME}.xml >>$tmp_name`; + for (@source_files) + { + `cat $opt_output_directory/$_.xml >>$tmp_name`; + `rm -f $opt_output_directory/$_.xml`; + } + + # close the chapter, and overwite the dll source + open(OUTPUT,">>$tmp_name") || die "Couldn't create $tmp_name\n"; + print OUTPUT "\n"; + close OUTPUT; + `mv $tmp_name $opt_output_directory/$spec_details->{DLL_NAME}.xml`; +} + # Write the html index files containing the function names sub output_html_index_files() { @@ -2156,6 +2259,7 @@ while(defined($_ = shift @ARGV)) s/^S// && do { $opt_manual_section = $_; last; }; /^Th$/ && do { $opt_output_format = "h"; last; }; /^Ts$/ && do { $opt_output_format = "s"; last; }; + /^Tx$/ && do { $opt_output_format = "x"; last; }; /^v$/ && do { $opt_verbose++; last; }; /^e$/ && do { $opt_output_empty = 1; last; }; /^L$/ && do { last; };