From patchwork Tue Oct 18 10:06:28 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 9381805 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 3693260839 for ; Tue, 18 Oct 2016 10:07:36 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 26CEF28B9B for ; Tue, 18 Oct 2016 10:07:36 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 1B44328BA0; Tue, 18 Oct 2016 10:07:36 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 319D128B9B for ; Tue, 18 Oct 2016 10:07:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933629AbcJRKHN (ORCPT ); Tue, 18 Oct 2016 06:07:13 -0400 Received: from bombadil.infradead.org ([198.137.202.9]:36581 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1759591AbcJRKGh (ORCPT ); Tue, 18 Oct 2016 06:06:37 -0400 Received: from 177.43.27.192.dynamic.adsl.gvt.net.br ([177.43.27.192] helo=vento.lan) by bombadil.infradead.org with esmtpsa (Exim 4.85_2 #1 (Red Hat Linux)) id 1bwRI0-0008Jm-5p; Tue, 18 Oct 2016 10:06:32 +0000 Date: Tue, 18 Oct 2016 08:06:28 -0200 From: Mauro Carvalho Chehab To: Markus Heiser Cc: Jonathan Corbet , Jani Nikula , Linux Media Mailing List , linux-doc@vger.kernel.org Subject: Re: [PATCH 1/4] doc-rst: reST-directive kernel-cmd / include contentent from scripts Message-ID: <20161018080628.439a0f40@vento.lan> In-Reply-To: References: <1475738420-8747-1-git-send-email-markus.heiser@darmarit.de> <1475738420-8747-2-git-send-email-markus.heiser@darmarit.de> <20161017144638.139491ad@vento.lan> X-Mailer: Claws Mail 3.14.0 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 X-SRS-Rewrite: SMTP reverse-path rewritten from by bombadil.infradead.org. See http://www.infradead.org/rpr.html Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Sorry, I missed part of your comments on my last reply... Em Tue, 18 Oct 2016 09:03:28 +0200 Markus Heiser escreveu: > +- ``T:`` SCM tree type and location. > + > > + - Type is one of: **git**, **hg**, **quilt**, **stgit**, **topgit** > > + > > Hmm, why is the last line a bullet list, shouldn't it be: > > +- ``T:`` SCM tree type and location > + Type is one of: git, hg, quilt, stgit, topgit IMHO, it is better to output it as: - T: SCM tree type and location. * Type is one of: git, hg, quilt, stgit, topgit Putting the explanation on a separate line, then merging the description of the tag with the details about the valid values. > > > > +- ``S:`` Status, one of the following: > > + > > + - Supported: > > + Someone is actually paid to look after this. > > Sorry, but I will never understand why you using mixed tabs and space > for the same thing ;-) ... what I mean; why is the top-list indented by > a tab after the bullet and the sub-list by two spaces ... > > We had the tab discussion already ... and IMO calling the CodeStyle is not > helpful when using ASCII markup ... lets take the ASCI documentation compact > and forget the tab ;-) Well, my text editor is set to replace 8 spaces by tabs, as this is the Kernel CodingStyle. I suspect other Kernel hackers do the same. Using a different style just for documentation is really odd and will cause problems, and make the maintainers life like hell if they would need to manually check if a documentation hunk is not using tabs. > > > + - Maintained: > > + Someone actually looks after it. > > + - Odd Fixes: > > + It has a maintainer but they don't have time to do > > much other than throw the odd patch in. See below.. > > - Orphan: No current maintainer [but maybe you could take the > > + - Orphan: > > + No current maintainer [but maybe you could take the > > role as you write your new code]. > > - Obsolete: Old code. Something tagged obsolete generally means > > + - Obsolete: > > + Old code. Something tagged obsolete generally means > > it has been replaced by a better system and you > > should be using that. > > Hmm, here its the same with the indent. List, list-items, paragraphs etc. are all > "body elements". > > * http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#body-elements > > A body element is always introduced by a leading empty line. E.g: > > - ``S:`` Status, one of the following: > > - Supported: > > Someone is actually paid to look after this. > > - Maintained: > > Someone actually looks after it. > > or even more compact (which I do prefer), without paragraphs in the list items: > > - ``S:`` Status, one of the following: > > - Supported: Someone is actually paid to look after this. > > - Maintained: Someone actually looks after it. Hmm... we actually use a lot of markups on the media books like: - foo - bar when we want to put the first line in **bold**, as this seems to be the only way to make the first line bold if it contains a verbatim. There's an additional advantage of the above... it requires less typing than: - **foo** - bar :-) > > > - F: Files and directories with wildcard patterns. > > +- ``F:`` Files and directories with wildcard patterns. > > + > > A trailing slash includes all files and subdirectory files. > > - F: drivers/net/ all files in and below drivers/net > > - F: drivers/net/* all files in drivers/net, but not below > > - F: */net/* all files in "any top level directory"/net > > - One pattern per line. Multiple F: lines acceptable. > > - N: Files and directories with regex patterns. > > - N: [^a-z]tegra all files whose path contains the word tegra > > - One pattern per line. Multiple N: lines acceptable. > > - scripts/get_maintainer.pl has different behavior for files that > > - match F: pattern and matches of N: patterns. By default, > > - get_maintainer will not look at git log history when an F: pattern > > - match occurs. When an N: match occurs, git log history is used > > - to also notify the people that have git commit signatures. > > - X: Files and directories that are NOT maintained, same rules as F: > > - Files exclusions are tested before file matches. > > - Can be useful for excluding a specific subdirectory, for instance: > > - F: net/ > > - X: net/ipv6/ > > - matches all files in and below net excluding net/ipv6/ > > - K: Keyword perl extended regex pattern to match content in a > > + > > + ============================== ====================================== > > + ``F:`` ``drivers/net/`` all files in and below > > + ``drivers/net`` > > + ``F:`` ``drivers/net/*`` all files in ``drivers/net``, > > + but not below > > + ``F:`` ``*/net/*`` all files in "any top level > > + directory" ``/net`` > > + ============================== ====================================== > > + > > + One pattern per line. Multiple ``F:`` lines acceptable. > > +- ``N:`` Files and directories with regex patterns. > > Between the last two lines, a empty line is required ... I fond this more times > (will not comment each). Surely we can improve the markups here. Yet, the point is that the html produced via kernel-cmd is completely different than he one produced by calling the perl script directly. When kernel-cmd is used, lots of tags are not parsed. That's said, if I add a logic at the script to expand the tabs before output (patch enclosed), everything looks OK. > > OK, I will stop here, if you are interested in I can prepare a patch for > illustration .... > Thanks, Mauro --- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/sphinx/format_maintainers.pl b/Documentation/sphinx/format_maintainers.pl index fb3af2a30c36..c3174c2b180a 100755 --- a/Documentation/sphinx/format_maintainers.pl +++ b/Documentation/sphinx/format_maintainers.pl @@ -1,4 +1,5 @@ #!/usr/bin/perl +use Text::Tabs; my $is_rst = 1; @@ -15,18 +16,20 @@ my %tags = ( ); while (<>) { + my $s = expand($_); + if ($is_rst) { - if (m/^\s+\-+$/) { + if ($s =~ m/^\s+\-+$/) { $is_rst = 0; next; } - print $_; + print $s; next; } - next if (m/^$/); + next if ($s =~ m/^\s*$/); - if (m/^([A-Z])\:(.*)/) { + if ($s =~ m/^([A-Z])\:(.*)/) { my $tag = $1; my $value = $2; @@ -38,7 +41,7 @@ while (<>) { next; } - print "\n$_"; + print "\n$s"; } print "\n";