Subject: [xml2rfc] New xml2rfc release: v2.20.0

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 26 Feb 2019 13:24:03 -0800

Hi,

This is an automatic notification about a new xml2rfc release, 
v2.20.0, generated when running the mkrelease script.

Release notes:

xml2rfc (2.20.0) ietf; urgency=medium

  This release changes the rendering of <xref> elements with text content by
  v3 formatters, and reintroduces <xref format="none"> under v3 in order to
  properly cover the combinatorial space of rendering of <xref> with and
  without text content.  It fixes a number of issues, including a somewhat
  unexpected issue with namespace normalization, and improves the rendering
  output in some edge cases.  More details from the commit log:

  * Removed namespace cleanup and normalisation during the v2v3 conversion, 
    as it can have negative effects for inlined <svg> when the SVG namespace is 
    specified in multiple places.

  * Changed handling of reference//author entries with fullname but without
    initials and surname in order to derive those the same way for references
    as it's done in other places.

  * Dropped support for Py34.  Support is now Py27 (untill end 2019), and
    Python 3.5 - 3.7.

  * Tweaked the CSS for bcp14 keyword elements.

  * Fixed a problem where a temporary valuable name stomped on a 
    method-wide name.

  * Fixed a problem where <xref> "relative" attributes were treated as 
    fragment identifiers instead of as relative URL paths.

  * Improved the placeholder text emitted by the v3 text renderer for 
    artwork without ascii-art.

  * Removed stripping of the now (again) functional <xref> format value "none"
    from the v2v3 converter.

  * Tweaked the rendering of <xref> having both derivedContent (section 
    information, for instance) and text content, to generate hyperlinks to the 
    xref target for both of them.  Simplified the html renderer by eliminating 
    extra code for <relref>, now covered by the generic <xref> code.

  * Fixed a problem with a missing hash character between path and fragment 
    identifiers in derivedLink generation.

  * Added a conversion of <relref> elements to the generic <xref> form to 
    preptool.  Tweaked a debug print statement.

  * Added An SVG diagram of the processing flow for v2 and v3 documents, used
    by xml2rfc3.rst, to doc/

  * Added an rST-formatted Introduction to xml2rfc version 3 to doc/

 -- Henrik Levkowetz <[email-masked]>  26 Feb 2019 13:22:09 -0800

The preferred way to install xml2rfc is by doing 'pip install xml2rfc',
and 'pip install --upgrade xml2rfc' to upgrade.  If there are system-
installed python modules which pip will not upgrade, you may have to
use 'pip install --upgrade --no-deps xml2rfc' and install dependencies
manually.

The new version is also available through SVN checkout, with
  'svn checkout http://svn.tools.ietf.org/svn/tools/xml2rfc/tags/cli/2.20.0'

Regards,

	Henrik
	(via the mkrelease script)

---

From: Julian Reschke <[email-masked]>
Date: Wed, 27 Feb 2019 06:30:47 +0100

On 26.02.2019 22:24, Henrik Levkowetz wrote:
> ...
 > ...

Could you clarify/document what the change is? It sounds like rendering 
now varies between formatters?

> ... >    * Changed handling of reference//author entries with fullname but 
without
> ...

There are heuristics, right? The vocabulary captures initials/give name 
separately because - as far as I understand - there is no reliable way 
to derive those from the full name.

There are two issues here:

- rendering will vary between different implementations
- certain locales are getting a better treatment than others; something 
we wanted to avoid in the vocabulary definition

Could you please document the heuristics that you are using?

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 27 Feb 2019 07:05:50 +0100

> now varies between formatters?

The rendering prescribed by 7991 and 7998 differed substantially from that
of the legacy renderers.  This change brings them closer again, as well as
permitting a richer range of expression.  7998 forced the rendering to
ignore the "format" attribute whenever <xref> held text; this is not the
case any more, and has never been the case for v2.  Additional details are
provided here:

https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation-notes-08#section-4.4.17

but I need to update the draft, as I got the release that would contain
this change wrong when I wrote the draft text.

> to derive those from the full name.

It's algorithmic, and falls back on the fullname only if initials/surname
are absent:

def short_author_name_parts(a):
    initials = a.get('initials')
    surname  = a.get('surname')
    if initials!=None and surname!=None:
        if initials and not initials.endswith('.') and is_script(initials, 'Latin'):
            initials += '.'
        parts = [initials, surname]
    else:
        fullname = a.get('fullname') or ''
        if fullname:
            if len(fullname.split())>1:
                parts = fullname.split()
                initials = ' '.join([ "%s."%n[0].upper() for n in parts[:-1] ])
                surname  = parts[-1]
                parts = [initials, surname ]
            else:
                parts = [ None, fullname ]
        else:
            parts = [None, None]
    return parts

> - rendering will vary between different implementations

The alternative is to omit the name, which results in surprise, since
deriving the initials and surname has been in practice for the front
matter for a long time.

> we wanted to avoid in the vocabulary definition

I don't see that.  Expressly provided initials and surname always takes
precedence; you can see this as a shortcut.

> Could you please document the heuristics that you are using?

It's not heuristics, and the algorithm is provided above.

	Henrik

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 27 Feb 2019 14:50:40 +0100

>                surname  = parts[-1]

Well, that is certainly heuristics (fails, e.g., with Spanish names, where the second-to-last is the usual patrimonial surname).
But I agree that it is sane to perform these heuristics, as opposed to completely leaving out the author as I have seen before.

Grüße, Carsten