c2man: Add xml documentation creation.
This commit is contained in:
Stefan Stranz
Alexandre Julliard
parent
a76db21978
commit
c89c2dd4c5
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
132
tools/c2man.pl
132
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> <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/\&/\&/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; };
|
||||
|
|
|
|||
Loading…
Reference in New Issue