From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932507AbcGFW6o (ORCPT ); Wed, 6 Jul 2016 18:58:44 -0400 Received: from lists.s-osg.org ([54.187.51.154]:46232 "EHLO lists.s-osg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752102AbcGFW6m (ORCPT ); Wed, 6 Jul 2016 18:58:42 -0400 Date: Wed, 6 Jul 2016 19:58:35 -0300 From: Mauro Carvalho Chehab To: Markus Heiser Cc: Jani Nikula , Jonathan Corbet , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, hverkuil@xs4all.nl, daniel.vetter@ffwll.ch, airlied@gmail.com, grant.likely@secretlab.ca, rdunlap@infradead.org, keithp@keithp.com Subject: Re: [PATCH] doc: flat-table directive Message-ID: <20160706195835.1fdc7e31@recife.lan> In-Reply-To: References: <1467288022-10496-1-git-send-email-markus.heiser@darmarIT.de> <20160630130511.34b732e6@lwn.net> <20160630164420.4e3908de@recife.lan> <20160701063857.674bde86@recife.lan> <87d1mxpkrm.fsf@intel.com> Organization: Samsung X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.30; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Fri, 1 Jul 2016 16:07:47 +0200 Markus Heiser escreveu: > Am 01.07.2016 um 15:09 schrieb Jani Nikula : > > > On Fri, 01 Jul 2016, Markus Heiser 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 []\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 () { $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 () { 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;