forked from mirrors/linux
kernel-doc: produce RestructuredText output
If given the -rst flag, output will now be in RestructuredText. Various glitches to be worked out yet. In the end I decided not to use RST section headings within the kerneldoc comments. gpu.tmpl already has headings five levels deep; adding more is not going to bring clarity. This is really just Jani Nikula's asciidoc change with the serial numbers filed off. It's a hack job that doubtless needs a lot of cleaning up. Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Jonathan Corbet
parent
fadc0b31cb
commit
c0d1b6ee78
1 changed files with 233 additions and 0 deletions
|
|
@ -55,6 +55,7 @@ Output format selection (mutually exclusive):
|
||||||
-html5 Output HTML5 format.
|
-html5 Output HTML5 format.
|
||||||
-list Output symbol list format. This is for use by docproc.
|
-list Output symbol list format. This is for use by docproc.
|
||||||
-man Output troff manual page format. This is the default.
|
-man Output troff manual page format. This is the default.
|
||||||
|
-rst Output reStructuredText format.
|
||||||
-text Output plain text format.
|
-text Output plain text format.
|
||||||
|
|
||||||
Output selection (mutually exclusive):
|
Output selection (mutually exclusive):
|
||||||
|
|
@ -203,6 +204,8 @@ my $type_param = '\@(\w+)';
|
||||||
my $type_struct = '\&((struct\s*)*[_\w]+)';
|
my $type_struct = '\&((struct\s*)*[_\w]+)';
|
||||||
my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
|
my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
|
||||||
my $type_env = '(\$\w+)';
|
my $type_env = '(\$\w+)';
|
||||||
|
my $type_enum_full = '\&(enum)\s*([_\w]+)';
|
||||||
|
my $type_struct_full = '\&(struct)\s*([_\w]+)';
|
||||||
|
|
||||||
# Output conversion substitutions.
|
# Output conversion substitutions.
|
||||||
# One for each output format
|
# One for each output format
|
||||||
|
|
@ -268,6 +271,17 @@ my @highlights_text = (
|
||||||
);
|
);
|
||||||
my $blankline_text = "";
|
my $blankline_text = "";
|
||||||
|
|
||||||
|
# rst-mode
|
||||||
|
my @highlights_rst = (
|
||||||
|
[$type_constant, "``\$1``"],
|
||||||
|
[$type_func, "\\:c\\:func\\:`\$1`"],
|
||||||
|
[$type_struct_full, "\\:ref\\:`\$1 \$2`"],
|
||||||
|
[$type_enum_full, "\\:ref\\:`\$1 \$2`"],
|
||||||
|
[$type_struct, "\\:ref\\:`struct \$1`"],
|
||||||
|
[$type_param, "**\$1**"]
|
||||||
|
);
|
||||||
|
my $blankline_rst = "\n";
|
||||||
|
|
||||||
# list mode
|
# list mode
|
||||||
my @highlights_list = (
|
my @highlights_list = (
|
||||||
[$type_constant, "\$1"],
|
[$type_constant, "\$1"],
|
||||||
|
|
@ -404,6 +418,10 @@ while ($ARGV[0] =~ m/^-(.*)/) {
|
||||||
$output_mode = "text";
|
$output_mode = "text";
|
||||||
@highlights = @highlights_text;
|
@highlights = @highlights_text;
|
||||||
$blankline = $blankline_text;
|
$blankline = $blankline_text;
|
||||||
|
} elsif ($cmd eq "-rst") {
|
||||||
|
$output_mode = "rst";
|
||||||
|
@highlights = @highlights_rst;
|
||||||
|
$blankline = $blankline_rst;
|
||||||
} elsif ($cmd eq "-docbook") {
|
} elsif ($cmd eq "-docbook") {
|
||||||
$output_mode = "xml";
|
$output_mode = "xml";
|
||||||
@highlights = @highlights_xml;
|
@highlights = @highlights_xml;
|
||||||
|
|
@ -1704,6 +1722,209 @@ sub output_blockhead_text(%) {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
##
|
||||||
|
# output in restructured text
|
||||||
|
#
|
||||||
|
|
||||||
|
#
|
||||||
|
# This could use some work; it's used to output the DOC: sections, and
|
||||||
|
# starts by putting out the name of the doc section itself, but that tends
|
||||||
|
# to duplicate a header already in the template file.
|
||||||
|
#
|
||||||
|
sub output_blockhead_rst(%) {
|
||||||
|
my %args = %{$_[0]};
|
||||||
|
my ($parameter, $section);
|
||||||
|
|
||||||
|
foreach $section (@{$args{'sectionlist'}}) {
|
||||||
|
print "**$section**\n\n";
|
||||||
|
output_highlight_rst($args{'sections'}{$section});
|
||||||
|
print "\n";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
sub output_highlight_rst {
|
||||||
|
my $contents = join "\n",@_;
|
||||||
|
my $line;
|
||||||
|
|
||||||
|
# undo the evil effects of xml_escape() earlier
|
||||||
|
$contents = xml_unescape($contents);
|
||||||
|
|
||||||
|
eval $dohighlight;
|
||||||
|
die $@ if $@;
|
||||||
|
|
||||||
|
foreach $line (split "\n", $contents) {
|
||||||
|
if ($line eq "") {
|
||||||
|
print $lineprefix, $blankline;
|
||||||
|
} else {
|
||||||
|
$line =~ s/\\\\\\/\&/g;
|
||||||
|
print $lineprefix, $line;
|
||||||
|
}
|
||||||
|
print "\n";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
sub output_function_rst(%) {
|
||||||
|
my %args = %{$_[0]};
|
||||||
|
my ($parameter, $section);
|
||||||
|
my $start;
|
||||||
|
|
||||||
|
print ".. c:function:: ";
|
||||||
|
if ($args{'functiontype'} ne "") {
|
||||||
|
$start = $args{'functiontype'} . " " . $args{'function'} . " (";
|
||||||
|
} else {
|
||||||
|
$start = $args{'function'} . " (";
|
||||||
|
}
|
||||||
|
print $start;
|
||||||
|
|
||||||
|
my $count = 0;
|
||||||
|
foreach my $parameter (@{$args{'parameterlist'}}) {
|
||||||
|
if ($count ne 0) {
|
||||||
|
print ", ";
|
||||||
|
}
|
||||||
|
$count++;
|
||||||
|
$type = $args{'parametertypes'}{$parameter};
|
||||||
|
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
|
||||||
|
# pointer-to-function
|
||||||
|
print $1 . $parameter . ") (" . $2;
|
||||||
|
} else {
|
||||||
|
print $type . " " . $parameter;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
print ")\n\n " . $args{'purpose'} . "\n\n";
|
||||||
|
|
||||||
|
print ":Parameters:\n\n";
|
||||||
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
||||||
|
my $parameter_name = $parameter;
|
||||||
|
#$parameter_name =~ s/\[.*//;
|
||||||
|
$type = $args{'parametertypes'}{$parameter};
|
||||||
|
|
||||||
|
if ($type ne "") {
|
||||||
|
print " ``$type $parameter``\n";
|
||||||
|
} else {
|
||||||
|
print " ``$parameter``\n";
|
||||||
|
}
|
||||||
|
if ($args{'parameterdescs'}{$parameter_name} ne $undescribed) {
|
||||||
|
my $oldprefix = $lineprefix;
|
||||||
|
$lineprefix = " ";
|
||||||
|
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
|
||||||
|
$lineprefix = $oldprefix;
|
||||||
|
} else {
|
||||||
|
print "\n _undescribed_\n";
|
||||||
|
}
|
||||||
|
print "\n";
|
||||||
|
}
|
||||||
|
output_section_rst(@_);
|
||||||
|
}
|
||||||
|
|
||||||
|
sub output_section_rst(%) {
|
||||||
|
my %args = %{$_[0]};
|
||||||
|
my $section;
|
||||||
|
my $oldprefix = $lineprefix;
|
||||||
|
$lineprefix = " ";
|
||||||
|
|
||||||
|
foreach $section (@{$args{'sectionlist'}}) {
|
||||||
|
print ":$section:\n\n";
|
||||||
|
output_highlight_rst($args{'sections'}{$section});
|
||||||
|
print "\n";
|
||||||
|
}
|
||||||
|
print "\n";
|
||||||
|
$lineprefix = $oldprefix;
|
||||||
|
}
|
||||||
|
|
||||||
|
sub output_enum_rst(%) {
|
||||||
|
my %args = %{$_[0]};
|
||||||
|
my ($parameter);
|
||||||
|
my $count;
|
||||||
|
|
||||||
|
my $name = "enum " . $args{'enum'};
|
||||||
|
print ".. _" . $name . ":\n\n";
|
||||||
|
print "**$name**\n\n";
|
||||||
|
print " " . $args{'purpose'} . "\n\n";
|
||||||
|
|
||||||
|
print "..\n\n:Constants:\n\n";
|
||||||
|
my $oldprefix = $lineprefix;
|
||||||
|
$lineprefix = " ";
|
||||||
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
||||||
|
print " `$parameter`\n";
|
||||||
|
if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
|
||||||
|
output_highlight_rst($args{'parameterdescs'}{$parameter});
|
||||||
|
} else {
|
||||||
|
print " undescribed\n";
|
||||||
|
}
|
||||||
|
print "\n";
|
||||||
|
}
|
||||||
|
$lineprefix = $oldprefix;
|
||||||
|
output_section_rst(@_);
|
||||||
|
}
|
||||||
|
|
||||||
|
sub output_typedef_rst(%) {
|
||||||
|
my %args = %{$_[0]};
|
||||||
|
my ($parameter);
|
||||||
|
my $count;
|
||||||
|
my $name = "typedef " . $args{'typedef'};
|
||||||
|
|
||||||
|
print "**$name**\n\n";
|
||||||
|
print $args{'purpose'} . "\n\n";
|
||||||
|
|
||||||
|
output_section_rst(@_);
|
||||||
|
}
|
||||||
|
|
||||||
|
sub output_struct_rst(%) {
|
||||||
|
my %args = %{$_[0]};
|
||||||
|
my ($parameter);
|
||||||
|
my $name = $args{'type'} . " " . $args{'struct'};
|
||||||
|
|
||||||
|
print ".. _" . $name . ":\n\n";
|
||||||
|
print "**$name**\n\n";
|
||||||
|
print " " . $args{'purpose'} . "\n\n";
|
||||||
|
|
||||||
|
print ":Definition:\n\n";
|
||||||
|
print " ::\n\n";
|
||||||
|
print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
|
||||||
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
||||||
|
if ($parameter =~ /^#/) {
|
||||||
|
print " " . "$parameter\n";
|
||||||
|
next;
|
||||||
|
}
|
||||||
|
|
||||||
|
my $parameter_name = $parameter;
|
||||||
|
$parameter_name =~ s/\[.*//;
|
||||||
|
|
||||||
|
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
|
||||||
|
$type = $args{'parametertypes'}{$parameter};
|
||||||
|
if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
|
||||||
|
# pointer-to-function
|
||||||
|
print " $1 $parameter) ($2);\n";
|
||||||
|
} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
|
||||||
|
# bitfield
|
||||||
|
print " $1 $parameter$2;\n";
|
||||||
|
} else {
|
||||||
|
print " " . $type . " " . $parameter . ";\n";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
print " };\n\n";
|
||||||
|
|
||||||
|
print ":Members:\n\n";
|
||||||
|
foreach $parameter (@{$args{'parameterlist'}}) {
|
||||||
|
($parameter =~ /^#/) && next;
|
||||||
|
|
||||||
|
my $parameter_name = $parameter;
|
||||||
|
$parameter_name =~ s/\[.*//;
|
||||||
|
|
||||||
|
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
|
||||||
|
$type = $args{'parametertypes'}{$parameter};
|
||||||
|
print " `$type $parameter`" . "\n";
|
||||||
|
my $oldprefix = $lineprefix;
|
||||||
|
$lineprefix = " ";
|
||||||
|
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
|
||||||
|
$lineprefix = $oldprefix;
|
||||||
|
print "\n";
|
||||||
|
}
|
||||||
|
print "\n";
|
||||||
|
output_section_rst(@_);
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
## list mode output functions
|
## list mode output functions
|
||||||
|
|
||||||
sub output_function_list(%) {
|
sub output_function_list(%) {
|
||||||
|
|
@ -2405,6 +2626,18 @@ sub xml_escape($) {
|
||||||
return $text;
|
return $text;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
# xml_unescape: reverse the effects of xml_escape
|
||||||
|
sub xml_unescape($) {
|
||||||
|
my $text = shift;
|
||||||
|
if (($output_mode eq "text") || ($output_mode eq "man")) {
|
||||||
|
return $text;
|
||||||
|
}
|
||||||
|
$text =~ s/\\\\\\amp;/\&/g;
|
||||||
|
$text =~ s/\\\\\\lt;/</g;
|
||||||
|
$text =~ s/\\\\\\gt;/>/g;
|
||||||
|
return $text;
|
||||||
|
}
|
||||||
|
|
||||||
# convert local escape strings to html
|
# convert local escape strings to html
|
||||||
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
|
# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
|
||||||
sub local_unescape($) {
|
sub local_unescape($) {
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue