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

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 29 Oct 2018 05:20:17 -0700

Hi,

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

Release notes:

xml2rfc (2.12.1) ietf; urgency=medium

  This release provides some additional polish over release 2.12.0, and also a
  few bugfixes.  The primary focus for this release has been HTML compliance
  based on the W3C validator at https://validator.w3.org/.  Valid HTML 5 is
  now generated for all documents used during testing.  From the commit log:

  * Fixed a number of issues with the v3 html renderer, to improve the 
    generated html.  Many of these were caught by the W3C validator at validator.w3.org:

    - removed the <meta http-equiv="Content-Type" ...> element, as it should
      not appear when there is a <meta charset=...> element

    - removed type="text/javascript" from a <script> element (superfluous)

    - removed a number of extraneous wrapping divs with identical id attributes

    - corrected the generation of <dt><dd> items for xml <ol> entries with
      percentage list types

    - removed some attributes on html entries for xml <ol> lists that had
      incorrectly been transferred from the xml

    - corrected the block element generated for <references> to <section>

    - fixed an issue where <xref> in <name> would generate nested html <a>
      elements

  * Also fixed some other issue:

    - added a newline tail for block elements, to improve readability

    - added missing space between author name and (editor)

    - fixed the renderer for <note> to generate html <section> elements with
      the right class attribute

    - refactored the generation of enclosing divs to hold id="$anchor" to be
      more consistent, with less code

    - modified the rendering of <xref> with text content to more closely match
      the historic rendering

  * Updated python-version specific test masters.  Tox runs for py27, py34,
    py35, and py36 aren now all clean.

  * Changed some invalid <link> rel= values to valid ones in the preptool

  * Tweaked the list of html block-level elements we use to control <div>
    wrapping

  * Disallowed <iref> as a direct child of <table> in the schema, as it
    results in invalid html with the rendering specified in RFC 7992.

 -- Henrik Levkowetz <[email-masked]>  29 Oct 2018 12:07:33 +0000

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.12.1'

Regards,

	Henrik
	(via the mkrelease script)

---

From: Miek Gieben <[email-masked]>
Date: Mon, 29 Oct 2018 20:44:46 +0000

[ Quoting <[email-masked]> in "[Rfc-markdown] New xml2rfc release:..." ]
>xml2rfc (2.12.1) ietf; urgency=medium

I'm trying to make a debian package for easy installing on debian systems, but 
the new dependencies make this difficult.

Current error:
pkg_resources.DistributionNotFound: The 'google-i18n-address>=2.3.2' distribution was not found and is required by xml2rfc

Note, previous version worked (up to 2.10.x as that was the last I tried)

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 29 Oct 2018 21:49:46 +0100

Hi Miek,

The package is available on pypi: https://pypi.org/project/google-i18n-address/
If it's a matter of permitting an earlier version, I think that should be
quite possible.  If it's a matter of working around a complete absence, it's
more tricky.  Could you provide a bit more details on what options we have to
work with?

Best regards,

	Henrik

---

From: Miek Gieben <[email-masked]>
Date: Mon, 29 Oct 2018 21:43:25 +0000

[dropping rfc-markdown]

>more tricky.  Could you provide a bit more details on what options we have to

this creates a deb package: py2dsc-deb xml2rfc-2.12.1.orig.tar.gz, that would 
install before, but now needs the google package.

py2dsc-deb fails for that pypi package (somewhere in testing, go figure).

I don't want hold xml2rfc back by insisting older OSs should be installed 
though. What do I miss when hack the google-i18n stuff out?

/Miek

--
Miek Gieben

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 29 Oct 2018 22:57:36 +0100

> py2dsc-deb fails for that pypi package (somewhere in testing, go figure).

Mph.  Might be worth looking into.

When I was asking for options, I wanted to explore if earlier versions of the
i18n-address package would work; whether it might work to pull it into the
xml2rfc distribution, and other possibilities, if you have suggestions.

> though. What do I miss when hack the google-i18n stuff out?

Country-specific address formatting.  Without it, you'll be stuck with the
fallback, which is very americentric for the text output, somewhat less so
for the html output (but not very refined).  I'd hate to see it go.

	Henrik

---

From: Miek Gieben <[email-masked]>
Date: Mon, 29 Oct 2018 22:05:52 +0000

[ Quoting <[email-masked]> in "Re: [Rfc-markdown] New xml2rfc rele..." ]
>xml2rfc distribution, and other possibilities, if you have suggestions.

I think bundling would help here (although I'm hardly an export the in 
python/debian eco-system)

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 29 Oct 2018 23:44:01 +0100

>>Mph.  Might be worth looking into.

I looked into this a bit.  The test requirements for google-i18n-address
seems to require python package setuptools>=36.4, but doesn't say so (in
setup.py).

Upgrading to setuptools>=36.4 (manually: $ pip install --upgrade setuptools)
lets the tests run successfully.

Does that help?

> python/debian eco-system)

I could do that, but the google-i18n-address package is rather large, so if
possible duplication can be avoided, it would be great.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 30 Oct 2018 05:57:17 +0100

On 2018-10-29 22:57, Henrik Levkowetz wrote:
> ...
> ...

Example? Smells a bit like overkill, given that v3 has simplified 
address formatting (postalLine).

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 30 Oct 2018 07:29:34 +0100

> address formatting (postalLine).

Example: In Norwegian and Swedish address format, the postal code goes
before the city, not after the region code.  This is correct:

  Midtskogveien 18
  2020 Skedsmokorset
  Norway 

The current html specification would instead have produced, depending on
how you work around its problems, one of

  Midtskogveien 18
  Skedsmokorset
  2020
  Norway

or 

  Midtskogveien 18
  Skedsmokorset, 2020
  Norway

which is a slighter degree of mangling than for places like various areas
of Japan, that needs city-region.  Here is a Japanese example.  This is
correct (except that it's also a translation, not just a romanization):

  Japan
  112-0001
  Tokyo-to
  Bunkyo-ku
  4-3-2 Hakusan
  3rd Floor Room B

and the RFC7992 specification would have rendered it as either this,
preserving the semantic labelling of the parts, but loosing the city-region
part:

  3rd Floor Room B
  4-3-2 Hakusan
  Tokyo-to, 112-0001
  Japan

or would loose all semantic labelling through forced use of postalLine for
all entries.

This problem has however been solved to a large degree by modern libraries.
If you can do this *right*, why continue to do it wrong?

postalLine would have been a bit of an improvement, if it hadn't been 
handicapped by throwing out interesting and valid information through
the choice of not permitting any of the existing elements that made sense
for the location's address.  A better choice would have been to add
city-region and postal-box as new address elements, and specify the use
of country-specific formatting.  The latter is something I could do.
I haven't done the former, even if it would have been tempting, given
that it would have given a pretty complete set of labelled address entities
to work with.

Take the statistics that are available here:
  https://datatracker.ietf.org/stats/document/yearly/country/

Forcing the removal of country (and region, and city) labelling if your
address needs a non-US address format makes producing that kind of info
harder; and it also removes the vCard/hCard annotation made possible by
having properly identified address parts.  The current code provides the
correct hCard property labels also for non-US addresses.

I'm *tired* of having software only work right for one country out of
many, and it's not necessary any longer.  Look at all the variations
across the globe, and come and tell me that it is preferred not to do
things as right as you can for most of them:

  https://en.wikipedia.org/wiki/Postal_address

Finally, given an old conversation you had about address formatting, the
rendering of the bottom address here may please you:

https://durif.tools.ietf.org/src/xml2rfc/html/show/elements.html#name-authors-addresses

Regards,

	Henrik

---

From: Miek Gieben <[email-masked]>
Date: Tue, 30 Oct 2018 07:03:42 +0000

>lets the tests run successfully.

for getting a deb from i18n-address? Most likely not, 'cause it uses the 
setuptools from the os (Version: 33.1.1-1).

---

From: Julian Reschke <[email-masked]>
Date: Tue, 30 Oct 2018 08:20:11 +0100

> If you can do this *right*, why continue to do it wrong?

Because it's complex, and now you are relying on a specific 
implementation. Is the algorithm documented?

> the choice of not permitting any of the existing elements that made sense

Well, we can discuss it. <postalLine> is the way it is because the 
design team thought that the level of detail that we had before simply 
was unneeded and just made things too complex. I guess this discussion 
supports this point :-)

>    https://datatracker.ietf.org/stats/document/yearly/country/

Understood. I'm just not sure that the fact these kind of stats exists 
(and apparently are already done with heuristics) justifies the 
complexity of the vocabulary.

> many, and it's not necessary any longer.  Look at all the variations

Yes, that's why we took the complexity out of the vocabulary.

Best regards, Julian

---

From: Martin J. Dürst <[email-masked]>
Date: Tue, 30 Oct 2018 07:24:09 +0000

> correct (except that it's also a translation, not just a romanization):

It is (mostly) correct for the original, which would be something like:

日本
〒 112-0001
東京都文京区白山 4-3-2
3F B室

Note that the hierarchical number (4-3-2) always comes after 白山 
(Hakusan) in the Japanese version. It can come after or before in the 
romanized version. Also note that in Japanese, there isn't really a 
fixed convention for line breaks; in addition, this example has a floor 
and room designation but lacks a building name, which isn't very typical.

>    3rd Floor Room B

This order of address fields would be very strange for an actually 
romanized address, the example below, with some fixes, would be much better.

> preserving the semantic labelling of the parts, but loosing the city-region

Romanized, it should be something like:

3rd Floor Room B
4-3-2 Hakusan, Bunkyo-ku
Tokyo, 112-0001 Japan

More or less linebreaks are okay, there isn't too much of a fixed 
convention. The -to after Tokyo isn't used that much for romanized 
addresses.

Regards,   Martin.

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 30 Oct 2018 09:37:00 +0100

> setuptools from the os (Version: 33.1.1-1).

Aha.  I'll look at bundling options, then.

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 30 Oct 2018 09:37:42 +0100

Hi Julian,

> https://durif.tools.ietf.org/src/xml2rfc/html/show/elements.html#name-authors-addresses

No comments on this?

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 30 Oct 2018 10:47:07 +0100

>> https://durif.tools.ietf.org/src/xml2rfc/html/show/elements.html#name-authors-addresses

Looks good to me, but I'm not sure what conversation you're referring 
to... :-)

(My version: 
https://greenbytes.de/tech/webdav/rfc2629xslt/v3test.html#rfc.authors)

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 30 Oct 2018 11:10:22 +0100

> Looks good to me, but I'm not sure what conversation you're referring 

https://mailarchive.ietf.org/arch/msg/rfc-interest/gmDbrPud8n-m6PKeEpJBEqM6YIg

(regarding alignment of right-to-left scripts).

Regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 30 Oct 2018 13:29:21 +0100

> (regarding alignment of right-to-left scripts).

I see.

Can you share the source code for this example?

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 30 Oct 2018 13:33:48 +0100

> Can you share the source code for this example?

It's in the repository, http://svn.tools.ietf.org/svn/tools/xml2rfc/trunk/cli/,
but it's basically very simple:  When rendering non-latin addresses, set the
directionality attribute dir="auto" on each address line <div>.

Regards,

	Henrik

---

From: Daniel Kahn Gillmor <[email-masked]>
Date: Tue, 30 Oct 2018 13:56:57 -0400

> Aha.  I'll look at bundling options, then.

please do not bundle other source with the xml2rfc source!  at least,
do not do it for debian's sake.  bundled sources are actively frowned
upon within debian, and if you bundle it creates more work for the
debian maintainers.

Thanks for your ongoing labors on xml2rfc, Henrik!

       --dkg

---

From: Daniel Kahn Gillmor <[email-masked]>
Date: Tue, 30 Oct 2018 13:54:58 -0400

> Note, previous version worked (up to 2.10.x as that was the last I tried)

I've already packaged google-i18n-address for debian and uploaded it.

   https://bugs.debian.org/912228

It's in the NEW queue, waiting for ftp-master approval:

   https://ftp-master.debian.org/new.html

I've already uploaded version 2.12.1 to debian unstable -- once
google-i18n-address passes NEW, xml2rfc 2.12.1 should be available in
debian.

        --dkg

---

From: Miek Gieben <[email-masked]>
Date: Tue, 30 Oct 2018 18:28:51 +0000

Ah nice!

On Tue, 30 Oct 2018, 18:23 Daniel Kahn Gillmor, <[email-masked]>
wrote:

> > pkg_resources.DistributionNotFound: The 'google-i18n-address>=2.3.2'
> distribution was not found and is required by xml2rfc
> >

---

From: Robert Sparks <[email-masked]>
Date: Tue, 30 Oct 2018 13:34:09 -0500

Meta-comment/question:

Is this a discussion about the vocabulary that we should be tracking as 
an issue on the vocabulary document (to at least make it easier to find 
later)?

RjS

On 10/30/18 2:20 AM, Julian Reschke wrote:
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 30 Oct 2018 19:40:58 +0100

Hi Robert,

> On 30 Oct 2018, at 19:34, Robert Sparks <[email-masked]> wrote:
> 
> Meta-comment/question:
> 
> Is this a discussion about the vocabulary that we should be tracking as an issue on the vocabulary document (to at least make it easier to find later)?

I've tried to capture the relevant bits in my implementation notes draft in parallel with writing the code.  The next rev will be submitted when submissions open again.

Best regards,

        Henrik

>> Because it's complex, and now you are relying on a specific implementation. Is the algorithm documented?
>> 
>> Well, we can discuss it. <postalLine> is the way it is because the design team thought that the level of detail that we had before simply was unneeded and just made things too complex. I guess this discussion supports this point :-)
>> 
>> Understood. I'm just not sure that the fact these kind of stats exists (and apparently are already done with heuristics) justifies the complexity of the vocabulary.
>>

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 30 Oct 2018 21:40:41 +0100

Hi Daniel,

> upon within debian, and if you bundle it creates more work for the

Ack; understood.  I was already hesitant, but I also want to make it
possible to use the tools.  I'll be even more hesitant in the future,
then ;-)
> Thanks for your ongoing labors on xml2rfc, Henrik!

You're welcome :-)

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 31 Oct 2018 00:29:03 +0100

Hi Martin,

> It is (mostly) correct for the original, which would be something like:

Aha, ok.

> romanized address, the example below, with some fixes, would be much better.

Yes, I also saw this when I put an <author> entry in place and processed
it through the i18n library.

> convention. The -to after Tokyo isn't used that much for romanized 

Ok, noted.  I'll correct my example.

Thanks for the additional input :-)

Best regards,

	Henrik