When SUPPORT.md uses the syntax
Status, <some thing>: <support status>
the caveats were lost (not footnoted) because they were attached
only to <some thing>.
Caveats occur in running text, so they are necessarily part of a real
section, not an individual status line like that. So attach them to
the RealSectNode, and look there for them.
Reported-by: Lars Kurth <lars.kurth@citrix.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Acked-by: Lars Kurth <Lars.kurth@citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
Each document has its own objects in @insections. Only the first
RealSect encountered ends up in the main $toplevel_sectlist tree.
This means that trying to unify the Caveats information for all
version in the RealSect (the $insection) does not work. The caveats
for all versions that aren't the first one where this section was seen
end up in the @insections array during parsing of that version, but
not recorded in the main tree.
The result was that footnotes would only appear in the output for
versions which were the most recent version where that feature row or
category appeared. The other footnotes would be lost.
Instead, store HasCaveat in the sectnode. That means ri_Para needs to
find the sectnode.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
We are going to want to add a call site for this.
No functional change.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
Non-leaf sections with footnotes must have a row of their own, for
just that section, because footnotes only appear if there is status
information.
In that case, the footnote applies to only the rows for that section
in the markdown document, ie that RealSect.
And of course for a leaf section that is true too.
So for footnoes we always want to use a rowspan of the number of
Status elements in the section. So (i) calculate this in
count_rows_sectlist and (ii) use it, instead of the total number of
rows including all the subsections', when writing out the footnote
ref.
This bug has been present in this script since the beginning.
Also, while we're here, suppress the rowspan if it would be 1.
Reported-by: Lars Kurth <lars.kurth@citrix.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
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>
A section in the SUPPORT.md may mention multiple
Status, something: Supported
and then have some text. The text is linked to from [*] footnotes
in the table. But, this means that each bit of text needs to
apply to multiple rows.
Before this commit this was a separate [*] after each applicable item.
But multiple apparently-different links to the same thing are annoying
for the reader.
So, in this commit we combine them. Formatting the result is not
entirely trivial.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
---
v3: New patch
v3.1: Drop `}' in multi-row [*] notes. I put this in to help work
around firefox bugs eg
https://bugzilla.mozilla.org/show_bug.cgi?id=244135
but I have been convinced it is not generally wanted.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
This utility reads json format pandoc output, from parsing one or more
SUPPORT.md files, and generates an HTML table element containing the
principal version and feature information.
This is rather hairier than I anticipated when I started out; hence
the 400-odd-line Perl script.
Machinery to assemble the appropriate inputs for parse-support-md
will be in the next commit.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
Acked-by: Lars Kurth <lars.kurth@citrix.com>
---
v2: New in this version of the series.
v3: Refactor to introduce RealSect
v3: Add [*] footnote to all applicable entries, not just the last
Ian Jackson