[PATCH 3/4] docs/html/: Generate an "index.html" for hypercall docs

Ian Jackson
Tue, 29 Nov 2011 15:01:32 -0000

Generate an "index.html" containing various useful links.

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
---
 docs/xen-headers         |   59 ++++++++++++++++++++++++++++++++++++++++++++++
 xen/include/public/xen.h |    4 ++-
 2 files changed, 62 insertions(+), 1 deletions(-)

diff --git a/docs/xen-headers b/docs/xen-headers
index e893f91..dcf673e 100755
--- a/docs/xen-headers
+++ b/docs/xen-headers
@@ -17,6 +17,10 @@

 #  definitions must start in LH column
 #  extra syntax:
+#   `incontents <seq> <shortname> <anchor text html>...
+#                              make a table of contents entry; they
+#                              will be sorted by increasing seq, and
+#                              shortname will be used as the anchor target
 #    /* ` <definition>                          } parse as if
<definition>
 #     * ` <definition>                          }  was not commented
 #   enum <name> { // <pattern>* => <func>()     }
cross-reference
@@ -60,6 +64,8 @@ my ($basedir,@indirs) = @ARGV;
 # general globals
 our $pass;
 our %sdef;
+our @incontents;
+our @outfiles;
 # $sdef{$type}{$name} => {
 #     DefLocs => { "$leaf_path:$lineno" => $leaf_opath ,... }
 #     Xrefs => { "$leaf_path,$lineno" => "$xref", ...
}
@@ -187,6 +193,19 @@ sub out_xrefs ($) {
     @pending_xrefs = ();
 }

+sub incontents ($$$) {
+    my ($text, $seq, $anchor) = @_;
+    $anchor = "incontents_$anchor";
+    if ($pass==2) {
+	push @incontents, {
+	    Seq => $seq,
+	    Href => "$leaf_opath#$anchor",
+	    Title => $text,
+	};
+    }
+    return "<a
name=\"$anchor\">$text";
+}
+
 sub write_file ($$) {
     my ($opath, $odata) = @_;
     my $out = new IO::File "$opath.new", ''>'' or
die "$opath $!";
@@ -242,6 +261,8 @@ sub process_file ($$) {
 	    }
 	} elsif (s/^( \s* \#define \s+ ) (\w+) ( \s+\S )
                   / $1.defmacro($2).norm($3) /xe) {
+	} elsif (s/( \`incontents \s+ (\d+) \s+ (\w+) \s+ )(\S .* \S)
+                 / norm($1).incontents($4, $2, $3) /xe) {
 	} else {
 	    if (m/^\s*\}/) {
 		$in_enum = undef;
@@ -261,11 +282,47 @@ sub process_file ($$) {
     warning("pending xrefs at end of file") if @pending_xrefs;

     if ($pass == 2) {
+	push @outfiles, [ $leaf, $leaf_opath ];
$o .= " ";
 	write_file($outfile, $o);
     }
 }

+sub output_index () {
+    my $title = "contents - $xtitle";
+    $o = '''';
+    $o .= <<END;
+ $title
+
+ $title
+ Starting points
+
+END
+    foreach my $ic (sort { $a->{Seq} <=> $b->{Seq} } @incontents) {
+	$o .= " <a
href=\"$ic->{Href}\">$ic->{Title} \n";
+    }
+ $o .= " \n";
+    my $forkind = sub {
+	my ($type,$desc,$pfx,$sfx) = @_;
+	$o .= " $desc \n";
+	foreach my $name (sort keys %{ $sdef{$type} }) {
+	    my $href = refhref($type,$name);
+	    next unless $href =~ m/\S/;
+ $o .= " <a
$href>$pfx$name$sfx \n";
+	}
+	$o .= " \n";
+    };
+
$forkind->(''Func'',''Functions'','''',''()'');
+
$forkind->(''Struct'',''Structs'',''struct
'','''');
+    $forkind->(''Enum'',''Enums and sets of
#defines'','''','''');
+    $forkind->(''EnumVal'',''Enum values and
individual #defines'','''','''');
+ $o .= " \n Files \n";
+    foreach my $of (sort { $a->[0] cmp $b->[0] } @outfiles) {
+	$o .= " <a
href=\"$of->[1]\">$of->[0] \n";
+    }
+ $o .= " \n";
+    write_file("$outdir/index.html", $o);
+}

 foreach $pass (qw(1 2)) {
     find({ wanted =>
@@ -290,3 +347,5 @@ foreach $pass (qw(1 2)) {
 	 },
 	 map { "$basedir/$_" } @indirs);
 }
+
+output_index();
diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index f2c9e6f..a5b6ad8 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -55,7 +55,9 @@ DEFINE_XEN_GUEST_HANDLE(xen_pfn_t);
  * HYPERCALLS
  */

-/* ` enum hypercall_num { // __HYPERVISOR_* => HYPERVISOR_*() */
+/* `incontents 100 hcalls List of hypercalls
+ * ` enum hypercall_num { // __HYPERVISOR_* => HYPERVISOR_*()
+ */

 #define __HYPERVISOR_set_trap_table        0
 #define __HYPERVISOR_mmu_update            1
--
1.7.2.5