[Xen-changelog] [xen master] SUPPORT.md, support matrix: Treat commentary before status as description

[patchbot@xxxxxxx]

commit 12891402f5b4cf12a5e3edad07e7cb691f80e92a
Author:     Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
AuthorDate: Thu Apr 12 17:57:58 2018 +0100
Commit:     Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
CommitDate: Mon Apr 23 13:58:42 2018 +0100

    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@xxxxxxxxxxxxx>
    Release-acked-by: Juergen Gross <jgross@xxxxxxxx>
---
 docs/parse-support-md | 24 ++++++++++++++++++++++--
 1 file 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} }) {
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/xen-changelog