Skip to content

W
wine-winehq
Commit c89c2dd4 authored by Stefan Stranz's avatar Stefan Stranz Committed by Alexandre Julliard
Browse files
Options

c2man: Add xml documentation creation.

parent a76db219
Hide whitespace changes
Inline Side-by-side
Showing with 136 additions and 21 deletions
Make.rules.in
View file @ c89c2dd4
......@@ -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
View file @ c89c2dd4
......@@ -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
View file @ c89c2dd4
......@@ -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
View file @ c89c2dd4
......@@ -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
View file @ c89c2dd4
......@@ -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; };
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment