[libvirt] [PATCH v2 2/3] NEWS: Reformat at generation time

[Andrea Bolognani]

On Thu, 2017-01-05 at 14:54 +0000, Daniel P. Berrange wrote:
> > Instead of encoding formatting information inside the
> > corresponding XSLT stylesheet, use a Python script to reformat
> > the text appropriately based on a few simple markers.
> > 
> > Splitting the task between the XSLT stylesheet and the Python
> > script allows us to keep both parts very simple.
> 
> It is easy enough todo the right line wrapping & indent in the
> XSLT straight away avoiding this two pass system. We had this
> exact same need for the template that converts security notices
> from XML to plain text.
> 
> Just copy the "wrap-string" template from this file:
> 
>   http://libvirt.org/git/?p=libvirt-security-notice.git;a=blob;f=templates/lsn2text.xsl;hb=HEAD
> 
> and call it anywhere you need todo wrapping from

AFAICT that doesn't *quite* do the same thing, eg. it
doesn't handle

  - What is a very long summay for this change, which should
    arguably not have been this long in the first place
      But we live in what is ultimately an imperfect word and
      we all make mistakes sometimes

properly: "arguably" would be aligned with "-" rather than
with "What", which is of course not a huge deal but looks
less polished.

Moreover, I'm afraid you're going to have a hard time
convincing me that ~50 lines of tightly packed, undocumented
XSLT are more maintainable than ~110 lines (counting empty
lines, comments and the usual GPL blurb) of Python code :)

> This avoids the need to rely on magic markers being the in
> intermediate text file, which could get mis-interpreted
> depending on what people write in the release notes.

The only case where that would happen would be if someone
started a change description with one of the markers, which
I think you'll agree is very unlikely to actually happen.

But if you think we should prevent it altogether, it's
fairly simple to tweak the script and add a marker in front
of the change description in the XSLT, and strip it later
in the Python code so that it doesn't ultimately show up in
the NEWS file.

-- 
Andrea Bolognani / Red Hat / Virtualization