Em Fri, 1 Jul 2016 16:07:47 +0200 Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu: > Am 01.07.2016 um 15:09 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > > > On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: > >> In Sphinx, the code-block directive is a literal block, no refs or markup > >> will be interpreted. This is different to what you know from DocBook. > >> I will look for a solution, that matches your requirement. > > > > Parsed literal block solves the problem, but brings other problems like > > requiring escaping for a lot of stuff. And you lose syntax > > highlighting. It would be great to have a middle ground, like a > > "semi-parsed code block" where the references are parsed but nothing > > else. > > > > http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block OK, using parsed literal indeed seems to be a solution. The script below should be doing what's needed to auto-generate the *.h.rst files. It should be replicating the logic that is done at the media Makefile, on a cleaner way. It also allows ignoring some symbols. We do that when we deprecate APIs: they're kept at the header files, but their descriptions are removed/replaced at the media book. This is not yet the final version. I need to do some adjustments, as only the ioctl refs match the ones on media, but it shouldn't be hard to fix. Thanks, Mauro #!/usr/bin/perl use strict; # change to 1 to generate some debug prints my $debug = 1; if (scalar @ARGV < 2 || scalar @ARGV > 3) { die "Usage:\n\t$0 <file in> <file out> [<exceptions file>]\n"; } my ($file_in, $file_out, $file_exceptions) = @ARGV; my $data; my @ioctls; my @defines; my @typedefs; my @enums; my @enum_symbols; my @structs; # # read the file and get identifiers # my $is_enum = 0; open IN, $file_in or die "Can't open $file_in"; while (<IN>) { $data .= $_; if ($is_enum && m/^\s*([^\s\}]+)\s*[\,=]?/) { my $s = $1; push @enum_symbols, $1; $is_enum = 0 if ($is_enum && m/\}/); next; } $is_enum = 0 if ($is_enum && m/\}/); if (m/^\s*#\s*define\s+([A-Z]\S+)\s+_IO/) { push @ioctls, $1; next; } if (m/^\s*#\s*define\s+([A-Z]\S+)\s+/) { push @defines, $1; next } if (m/^\s*typedef\s+.*\s+(\w\S+);/) { push @typedefs, $1; next; } if (m/^\s*enum\s+(\S+)\s+\{/ || m/^\s*enum\s+(\S+)$/) { my $v = $1; push @enums, $v unless grep{$_ eq $v} @enums; $is_enum = $1; next; } if (m/^\s*struct\s+(\S+)\s+\{/ || m/^\s*struct\s+(\S+)$/) { my $v = $1; push @structs, $v unless grep{$_ eq $v} @structs; next; } } close IN; # # Handle multi-line typedefs # my @matches = $data =~ m/typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*(\S+)\s*\;/g; foreach my $m (@matches) { push @typedefs, $m unless grep{$_ eq $m} @typedefs; next; } # # Handle exceptions, if any # if ($file_exceptions) { open IN, $file_exceptions or die "Can't read $file_exceptions"; while (<IN>) { next if (m/^\s*$/ || m/^\s*#/); if (m/^ignore\s+ioctl\s+(\S+)/) { @ioctls = grep { $_ != $1 } @ioctls; next; } if (m/^ignore\s+define\s+(\S+)/) { @defines = grep { $_ != $1 } @defines; next; } if (m/^ignore\s+typedef\s+(\S+)/) { @typedefs = grep { $_ != $1 } @typedefs; next; } if (m/^ignore\s+enum\s+(\S+)/) { @enums = grep { $_ != $1 } @enums; next; } if (m/^ignore\s+struct\s+(\S+)/) { @structs = grep { $_ != $1 } @structs; next; } die "Can't parse $file_exceptions"; } } print "ioctls: @ioctls\n" if ($debug && @ioctls); print "defines: @defines\n" if ($debug && @defines); print "typedefs: @typedefs\n" if ($debug && @typedefs); print "enums: @enums\n" if ($debug && @enums); print "structs: @structs\n" if ($debug && @structs); # # Add escape codes for special characters # $data =~ s,([\_\`\*\<\>\&\\\\:\/]),\\$1,g; # # Align block # $data = " " . $data; $data =~ s/\n/\n /g; $data =~ s/\n\s+$/\n/g; # # Add references # foreach my $r (@ioctls, @defines, @enum_symbols) { my $n = $r; $n =~ tr/A-Z/a-z/; my $s = ":ref:`$r <$n>`"; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; print "$r -> $s\n" if ($debug); $data =~ s/([\s])($r)([\s])/$1$s$3/g; } foreach my $r (@enums) { my $n = $r; $n =~ tr/A-Z_/a-z-/; my $s = ":ref:`enum $r <$n>`"; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; print "$r -> $s\n" if ($debug); $data =~ s/enum\s+($r)([\s])/$s$2/g; } foreach my $r (@structs) { my $n = $r; $n =~ tr/A-Z_/a-z-/; my $s = ":ref:`struct $r <$n>`"; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; print "$r -> $s\n" if ($debug); $data =~ s/struct\s+($r)([\s])/$s$2/g; } ## FIXME foreach my $r (@typedefs) { my $n = $r; $n =~ tr/A-Z_/a-z-/; my $s = ":ref:`$r <$n>`"; $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g; print "$r -> $s\n" if ($debug); $data =~ s/(typedef\s+^\n+\s+)($r)(\s*;)/$1$s$3/g; $data =~ s/(typedef\s+struct\s+\S+\s*\{[^\}]+\}\s*)($r)(\s*;)/$1$s$3/g; } # # Generate output file # my $title = $file_in; $title =~ s,.*/,,; open OUT, "> $file_out" or die "Can't open $file_out"; print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n"; print OUT "$title\n"; print OUT "=" x length($title); print OUT "\n\n.. parsed-literal::\n\n"; print OUT $data; close OUT; -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
