c2man: Add xml documentation creation.

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
 

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
 

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
 

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)

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 "<META NAME=\"keywords\" CONTENT=\"Win32,Wine,API,$comment->{COMMENT_NAME}\">\n";
       print OUTPUT "<TITLE>Wine API: $comment->{COMMENT_NAME}</TITLE>\n</HEAD>\n<BODY>\n";
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
       print OUTPUT "<!-- Generated file - DO NOT EDIT! -->\n",
                    "<sect1>\n",
@@ -1373,7 +1386,7 @@ sub output_api_footer($)
                    " Visit <a href=\"http://www.winehq.org\">WineHQ</a> for license details.".
                    " Generated $date.</i></p>\n</body>\n</html>\n";
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
       print OUTPUT "</sect1>\n";
       return;
@@ -1392,7 +1405,7 @@ sub output_api_section_start($$)
   {
     print OUTPUT "\n<h2 class=\"section\">",$section_name,"</h2>\n";
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
     print OUTPUT "<bridgehead>",$section_name,"</bridgehead>\n";
   }
@@ -1427,7 +1440,7 @@ sub output_api_name($)
                  "</b>&nbsp;&nbsp;<i class=\"dll_ord\">",
                  ,$dll_ordinal,"</i></p>\n";
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
     print OUTPUT "<para>\n  <command>",$readable_name,"</command>  <emphasis>",
                  $dll_ordinal,"</emphasis>\n</para>\n";
@@ -1452,7 +1465,7 @@ sub output_api_synopsis($)
     print OUTPUT "<pre class=\"proto\">\n ", $comment->{RETURNS}," ",$comment->{COMMENT_NAME},"\n (\n";
     @fmt = ("", "\n", "<tt class=\"param\">", "</tt>");
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
     print OUTPUT "<screen>\n ",$comment->{RETURNS}," ",$comment->{COMMENT_NAME},"\n (\n";
     @fmt = ("", "\n", "<emphasis>", "</emphasis>");
@@ -1506,7 +1519,7 @@ sub output_api_synopsis($)
   {
     print OUTPUT " )\n</pre>\n";
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
     print OUTPUT " )\n</screen>\n";
   }
@@ -1534,7 +1547,7 @@ sub output_api_comment($)
             "<table class=\"tab\"><colgroup><col><col><col></colgroup><tbody>\n",
             "</tbody></table>\n","<tr><td>","</td></tr>\n","</td>","</td><td>");
   }
-  elsif ($opt_output_format eq "s")
+  elsif ($opt_output_format eq "s" || $opt_output_format eq "x")
   {
     @fmt = ("<para>\n","\n</para>\n","<constant>","</constant>","<emphasis>","</emphasis>",
             "<command>","</command>","<constant>","</constant>","<emphasis>","</emphasis>",
@@ -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/\&/\&amp;/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 "</chapter>\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 "<?xml version='1.0'?>";
+  print OUTPUT "<!-- Generated file - DO NOT EDIT! -->\n";
+  print OUTPUT "<!DOCTYPE book PUBLIC \"-//OASIS//DTD DocBook V5.0/EN\" ";
+  print OUTPUT "               \"http://www.docbook.org/xml/5.0/dtd/docbook.dtd\" [\n\n";
+  print OUTPUT "<!ENTITY blurb SYSTEM \"blurb.xml\">\n";
+
+  # List the entities
+  for (@$dlls)
+  {
+    $_ =~ s/(\..*)?\n//;
+    print OUTPUT "<!ENTITY ",$_," SYSTEM \"",$_,".xml\">\n"
+  }
+
+  print OUTPUT "]>\n\n<book id=\"index\">\n<bookinfo><title>The Wine Api Guide</title></bookinfo>\n\n";
+  print OUTPUT "  &blurb;\n";
+
+  for (@$dlls)
+  {
+    print OUTPUT "  &",$_,";\n"
+  }
+  print OUTPUT "\n\n</book>\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 "<?xml version='1.0' encoding='UTF-8'?>\n<chapter>\n<title>$spec_details->{DLL_NAME}</title>\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 "</chapter>\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; };