lkml.org 
[lkml]   [2016]   [Jul]   [6]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH] doc: flat-table directive
Em Fri, 1 Jul 2016 16:07:47 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 01.07.2016 um 15:09 schrieb Jani Nikula <jani.nikula@intel.com>:
>
> > On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@darmarit.de> 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;

\
 
 \ /
  Last update: 2016-07-07 01:41    [W:0.071 / U:14.036 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site