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

Ian Campbell
Tue, 29 Nov 2011 15:25:44 -0000

On Tue, 2011-11-29 at 15:01 +0000, Ian Jackson wrote:
> Generate an "index.html" containing various useful links.
>
> Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>

Acked-by: Ian Campbell <ian.campbell@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