SUPPORT.md, support matrix: Treat commentary before status as description

Running text in feature sections in the markdown document currently
might be (i) a caveat, qualifying or clarifying the support statement
(ii) a plain description of the feature.

Caveats can be version-specific and deserve the [*] annotation in the
relevant feature matrix cell.  They must link to SUPPORT.html for the
specific version.

Descriptions are not version specific.  In that case the [*]
annotation is visusal noise.  Rather, it is better to make a hyperlink
out of the text which is being expanded on.  The hyperlink can point
to any appropriate version.

There is a question about how to notate this distinction in
SUPPORT.md.  After IRL discussion with George and Lars I propose that
we should put text which helps describe a feature (ie, which expands
on a section heading) after the heading but before the Status
indications; whereas, caveats and supplementary information about
the actual status, should follow the Status block.

This patch implements this distinction in the support matrix
generator.  Only paragraphs containing _only_ italic content count as
descriptive; anything else is treated as a caveat.

In the code:

 * Add a new entry to RealSect, HasDescription

 * When parsing, track whether we are before or after the first Status
   block in a new variable $has_feature.

 * In ri_Para, set HasDescription set to the input document index
   when we encounter text before the first feature.

 * When writing a `heading' (ie, the table cell for a feature name)
   look for HasDescription and make an appropriate hyperlink.

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>

1 files changed, 22 insertions, 2 deletions

diff --git a/docs/parse-support-md b/docs/parse-support-md
index 6953930850..653d216025 100755
--- a/docs/parse-support-md
+++ b/docs/parse-support-md
@@ -35,6 +35,7 @@ our $toplevel_sectlist = new_sectlist();
 # $sectlist->{KEY}{Key} = KEY
 # $sectlist->{KEY}{RealSect} = containing real section in @insections, so
 # $sectlist->{KEY}{RealSect}{HasCaveat}[VI] = trueish iff other in a Para
+# $sectlist->{KEY}{RealSect}{HasDescription} = VI for some Emph in Para
 # $sectlist->{KEY}{RealSect}{Anchor} = value for < id="" > in the pandoc html
 # A $sectnode represents a single section from the original markdown
 # document.  Its subsections are in Children.
@@ -58,8 +59,10 @@ our @insections;
 # these next are only defined for real sections, not Status elements
 # $insections[]{Anchor} = string
 # $insections[]{HasCaveat} = array, $sectlist->{HasCaveat} will refer to this
+# $insections[]{HasDescription} VI, likewise
 
 our $had_unknown;
+our $had_feature;
 # adding new variable ?  it must be reset in r_toplevel
 
 #---------- parsing ----------
@@ -78,13 +81,20 @@ sub ri_Header {
          Anchor => $id,
          Headline => $hl,
          HasCaveat => [],
+         HasDescription => undef,
         };
 #print STDERR Dumper(\@insections);
+    $had_feature = 0;
 }
 
 sub ri_Para {
-    if (@insections) {
-        $insections[$#insections]{HasCaveat}[$version_index] = 1;
+    return unless @insections;
+    my $insection = $insections[$#insections];
+
+    if ($had_feature) {
+        $insection->{HasCaveat}[$version_index] = 1;
+    } else {
+        $insection->{HasDescription} //= $version_index;
     }
 };
 
@@ -92,6 +102,8 @@ sub parse_feature_entry ($) {
     my ($value) = @_;
     die unless @insections;
 
+    $had_feature = 1;
+
     my $sectnode;
     my $realsect;
     foreach my $s (@insections) {
@@ -183,6 +195,7 @@ sub r_toplevel ($) {
 
     @insections = ();
     $had_unknown = undef;
+    $had_feature = undef;
 
     foreach my $e (@$i) {
         next unless ref $e eq 'ARRAY';
@@ -346,7 +359,14 @@ sub write_output_row ($) {
         $span->('col', $maxdepth - $heading->{Depth} + 1)
             if !%{ $heading->{Children} };
         o(' align="left">');
+        my $end_a = '';
+        my $desc_i = $heading->{RealSect}{HasDescription};
+        if (defined $desc_i) {
+            o(docref_a $desc_i, $heading->{RealSect});
+            $end_a= '</a>';
+        }
         o($heading->{Headline});
+        o($end_a);
         o('</th>');
     }
     if (%{ $sectnode->{Children} }) {