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