Subject: Re: [Ietf-and-github] [Gen-art] Genart last call review of draft-ietf-git-using-github-04

From: Alissa Cooper <[email-masked]>
Date: Tue, 3 Mar 2020 21:06:32 -0500

I put this in an RFC Editor note.
Alissa

> On Feb 24, 2020, at 11:04 AM, Martin Thomson <[email-masked]> wrote:
> 
> Thanks Brian,
> 
> On Sun, Feb 23, 2020, at 17:01, Brian Carpenter via Datatracker wrote:
>> Is this draft intended to become part of BCP25? I think it would be
>> useful for the IESG to clarify this rather than leave it to the RFC Editor.
> 
> This is a good question.  Given the intended status of BCP, I would say that integrating into 25 is better than creating a new number.  I don't know how to best signal this intent though.
> 
> And I fixed the nit in the copy on GitHub.
> 
> _______________________________________________
> Gen-art mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/gen-art

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 4 Mar 2020 15:48:57 +1300

Thanks
   Brian

---

From: Alexandre Petrescu <[email-masked]>
Date: Fri, 6 Mar 2020 17:31:58 +0100

Hi,

I take advantage of this Last Call about github use at IETF to give my 
comments about writing I-Ds on github.

We are writing a draft with a few colleagues at IETF about a 6MAN topic. 
  We initially  thought we'd use the Word template but quickly we moved 
to xml2rfc and github storage.

- the xml2rfc.ietf.org GUI generates a *.txt.pdf file, whereas it should
   generate a *.pdf file.  That makes difficult to talk about a 'txt'
   file (is it the ASCII or the .txt.pdf?).  I have been told I should
   report this to 'tools-discuss' email list, which I will do one day.

- the github folder containing the xml source should be as small as
   possible, and have at least as possible additional clutter files.
   This is not like a project of C files where there are no numerous *.c
   and *.h and *.asm files.  There is just one source: the xml.

- I wrote a README about how to use that xml file.  There are to
   distinct operations: compilation and submission.

- despite my efforts of explaining, people still prefer to exchange the
   files by email.  This feedback is from working with several groups on
   several xml drafts on several gihub repositories.

- this the README that I wrote and put in the github repository of the
   xml file of the Internet Draft we currently write:

-----------------------------------------------------------------------

0. on Windows, use the free Github Desktop tool.  Within it, use
    buttons like 'Commit to master' and others like 'Push origin' in
    order to upload the files that you modify.

1. How to 'compile' the .xml file:

- go to https://xml2rfc.tools.ietf.org
- press the button to select a file
- choose the .xml file
- leave the 'Output format' and 'Options' to their default
- click 'Submit'

That displays the .txt file in the browser, but can also create .txt
and .pdf files, depending on how the Output format is Optioned.

That does not submit the draft to the IETF.

2. In order to submit a draft, upload the .xml at the address
https://datatracker.ietf.org/submit/

3. do not commit the xml file to github before you are sure it
compiles safely on xml2rfc.tools.ietf.org

Alex

Le 24/02/2020 à 02:01, Brian Carpenter via Datatracker a écrit :
> Reviewer: Brian Carpenter
> Review result: Ready with Issues
> 
> Gen-ART Last Call review of draft-ietf-git-using-github-04
> 
> I am the assigned Gen-ART reviewer for this draft. The General Area
> Review Team (Gen-ART) reviews all IETF documents being processed
> by the IESG for the IETF Chair.  Please treat these comments just
> like any other last call comments.
> 
> For more information, please see the FAQ at
> <http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.
> 
> Document: draft-ietf-git-using-github-04.txt
> Reviewer: Brian Carpenter
> Review Date: 2020-02-24
> IETF LC End Date: 2020-03-03
> IESG Telechat date:
> 
> Summary: Ready with issue
> --------
> 
> Comment:
> --------
> 
> I've tracked this document since the -00 version and I think it is clear
> and represents WG consensus.
> 
> Issues:
> -------
> 
> Nit:
> ----
>> 3.4.  Document Formats
>>    In addition to the canonical XML format [RFC7991], document editors
>>    might choose to use a different input form for editing documents,
>>    such as Markdown.  Markdown-based formats are more accessible for new
>>    contributors, though ultimately decisions about format is left to
>>    document editors.
> 
> s/is/are/
> 
>

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 09 Mar 2020 15:08:10 +1100

> comments about writing I-Ds on github.

Hi Alex,

Thanks for sharing your experience. Taking this back to the Working Group list as it doesn't seem to be a comment about the work.

Do you think that anything in this invalidates the advice and procedures in the draft?  Or suggests the need for additions?  I didn't see anything that suggests the need for changes.  Indeed, your process would seem to fit within the pattern described, with the possible exception of missing a notice for contributors about their obligations (usually CONTRIBUTING.md).

> compiles safely on xml2rfc.tools.ietf.org

I personally wouldn't make this recommendation.  Stuff breaks occasionally and asking people to check is unreliable.  Automated validation on check-in is my preferred solution to this problem.

Cheers,
Martin

---

From: Alexandre Petrescu <[email-masked]>
Date: Mon, 9 Mar 2020 10:05:56 +0100

Hi,
Thank you for the message.

Le 09/03/2020 à 05:08, Martin Thomson a écrit :
>> I take advantage of this Last Call about github use at IETF to give
>> my comments about writing I-Ds on github.
> 
> Hi Alex,
> 
> Thanks for sharing your experience. Taking this back to the Working 
> Group list as it doesn't seem to be a comment about the work.

Indeed I didnt read the draft prior to submitting the comments.

> Do you think that anything in this invalidates the advice and 
> procedures in the draft?  Or suggests the need for additions?  I 
> didn't see anything that suggests the need for changes.

I now read the draft.  I have the following comments:

draft-ietf-git-using-github-05:
> The Working Group Chairs are responsible for determining if there is
>  interest in using GitHub and making a consensus call to determine if
>  the proposed policy and use is acceptable.

I agree with the suggestion.

But I would like to mention, for the sake of not missing it, that
in my experience it is not the WG Chairs who request the use of GitHub
for documents, but it is the potential authors that might decide so.
They feel a need to share and contribute to a common document, and
select github as a place to store the intermediary verrsions.

But I agree that it might be that in other WGs where I am not active it 
is the WG Chairs who request it.

> 3.1.  What to Use GitHub For

This section 3.1 is good in general, but does not seem to me to say What
to Use GitHub For.  This is what it should be used for: share Internet
Drafts and share code implementing protocols.

> 4.2.  Pull Requests
> 
> Pull requests are the GitHub feature that allow users to request 
> changes to a repository.

It might be a matter of English usage, but I think Pull Requests allow
users to 'obtain' the most recent changes present in the repository(?)
If I understand github correctly, in order to 'request changes to a
repository' one might rather use 'push' instead of 'pull'(?)

(the button in GUI on Windows that obtains the most recent changes
present in the repository is labelled 'Pull origin'; after pressing it, 
and success, the GUI says 'Last fetched just now').

> 1.2.  GitHub

In this introductory section, I think it makes sense to explain the
behaviour of GitHub with respect to accents in people names.  Is it
working ok or not?

For my part, I suspect gihub to be the origin of errors I am struggling
with the following accents in these names: 	
Ole Trøan, 神明達哉 (TATUYA Jinmei), Jérôme Härri.

They display perfectly fine in my emails on Windows with Thunderbird,
but get messed when putting in an xml file on Windows, gnu emacs,
xml2rfc.tools.ietf.org  and github.  I suspect github to be the problem.

I would like to know whether other people using Windows,
xml2rfc.tools.ietf.org and GitHub can put safely these names in an xml file.

If we find out that github does not mess these accents then it would be
great to tell so in the I-D.

You said:
> Indeed, your process would seem to fit within the pattern described,
> with the possible exception of missing a notice for contributors
> about their obligations (usually CONTRIBUTING.md).

Sounds reasonable.

> I personally wouldn't make this recommendation.  Stuff breaks 
> occasionally and asking people to check is unreliable.  Automated 
> validation on check-in is my preferred solution to this problem.

Makes sense.

How about the other recommendation?
I suggest recommending this: do not keep the .txt nor the .pdf in the 
root folder.

Alex
> Cheers, Martin

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 10 Mar 2020 16:50:29 +1100

> select github as a place to store the intermediary verrsions.

This was always possible and remains so.  This document exists to describe how formal functions, like decision-making, might best use the tool.  More specific text on that is in Section 3.1.

> Drafts and share code implementing protocols.

That is in the Introduction and Document Goals sections, which I think is sufficient.

> repository' one might rather use 'push' instead of 'pull'(?)

"pull request" is the correct term.  It is a request for someone else to "pull" certain changes into their repository.  

It's not a push. That would imply no choice on the part of the target.

And yes, it's weird that you push to a branch in order to create a pull request.  But that's how git works: it makes a degree of sense, but only if your world view is sufficiently distorted to begin with.

> behaviour of GitHub with respect to accents in people names.  Is it

Yes.  The whole charset thing is difficult, but if you use UTF-8 and Unicode you will find that things just work.  In most cases, you don't even have to make an effort to do so because modern software has largely left the baggage of the past behind.  We've recently added the real names of contributors to the QUIC specs and it just worked.

> great to tell so in the I-D.

I would rather leave that pass without comment.  From my perspective, this all works.  That might be cause to celebrate, but we don't need to burden people with the details of solved problems when there are enough unsolved ones left to worry about.  If you are having issues, then that's something to work on.  For instance, it could be a system locale issue.

> I suggest recommending this: do not keep the .txt nor the .pdf in the 

That is a fine suggestion that I fully support.  I find that including build output in the repository contributes to a hostile process for contributors. I have other things that I would rather spend that budget on, like trailing whitespace...

But none of that really needs to be in an RFC.  It's just minutiae.

---

From: Kjetil Torgrim Homme <[email-masked]>
Date: Tue, 10 Mar 2020 07:05:15 +0100

On Fri, 2020-03-06 at 17:31 +0100, Alexandre Petrescu wrote:
> - I wrote a README about how to use that xml file.  There are two
> - this the README that I wrote and put in the github repository of
> the xml file of the Internet Draft we currently write:
> 
> -----------------------------------------------------------------
> 

this should be handled automatically by Github Actions (I am not that
familiar with Github Actions, but it is trivial to set up with Gitlab
CI and I don't think Github is much worse.)  the draft mentions this in
section 8 about Continuous Integration.

> https://datatracker.ietf.org/submit/

this could also be done automatically, possibly restricted to happen
only for merges into specific git branches, if you adopt a "git flow"
work method (the draft hints at using something like that, since it
discourages direct commits to "master")

> compiles safely on xml2rfc.tools.ietf.org

again, this sanity check is best left to computers.

> - despite my efforts of explaining, people still prefer to exchange
> the files by email.  This feedback is from working with several
> groups on several xml drafts on several github repositories.

both Github and Gitlab have good web based editors which can
recommended to Git skeptics (there is no doubt that Git can be
intimidating to get started with, and for some contributors it may not
be worthwhile).  I have not tried them on an XML formatted draft,
however.

the draft stresses that a WG's choice of using a git service should not
exclude participants who will not use the service.  the draft does not
go into reasons for such a rejection, but, e.g., the Github EULA is not
necessarily acceptable to everyone, and this should be respected.

-- 
regards,
Kjetil T.

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 11:24:36 +0100

Le 10/03/2020 à 06:50, Martin Thomson a écrit :
>> in my experience it is not the WG Chairs who request the use of
>> GitHub for documents, but it is the potential authors that might
>> decide so. They feel a need to share and contribute to a common
>> document, and select github as a place to store the intermediary
>> verrsions.
> 
> This was always possible and remains so.  This document exists to
> describe how formal functions, like decision-making, might best use
> the tool.  More specific text on that is in Section 3.1.
> 
>> This section 3.1 is good in general, but does not seem to me to say
>> What to Use GitHub For.  This is what it should be used for: share
>> Internet Drafts and share code implementing protocols.
> 
>> It might be a matter of English usage, but I think Pull Requests
>> allow users to 'obtain' the most recent changes present in the
>> repository(?) If I understand github correctly, in order to
>> 'request changes to a repository' one might rather use 'push'
>> instead of 'pull'(?)
> 
> "pull request" is the correct term.  It is a request for someone else
> to "pull" certain changes into their repository.

In that case, it would be better to say

NEW:
> to obtain the changes made to a repository.

instead of

> Pull requests are the GitHub feature that allow users to request 

This latter sounds as if a user might request to make changes to a 
repository. (not to obtain the changes already present).

> And yes, it's weird that you push to a branch in order to create a
> pull request.  But that's how git works: it makes a degree of sense,
> but only if your world view is sufficiently distorted to begin with.
> 
>> In this introductory section, I think it makes sense to explain
>> the behaviour of GitHub with respect to accents in people names.
>> Is it working ok or not?
> 
> Yes.  The whole charset thing is difficult, but if you use UTF-8 and
> Unicode you will find that things just work. 

I heard this theory.

I try what I said I tried.  It does not work.  I suspsect it is github.

One can isnsit siwht this utf-8 word and I can insist with my is not 
working.

But I will not even try again.  I have already tried in the past at IETF 
with a similar thing: the WiFi access and some WiFi driver.  I was told 
by the majority I was wrong.  I was not wrong.  But it was not me who 
proved it - somehow the software got corrected without me insisting.  It 
was a completely other non-IETF advancement.

> In most cases, you
> don't even have to make an effort to do so because modern software
> has largely left the baggage of the past behind.  We've recently
> added the real names of contributors to the QUIC specs and it just
> worked.

Was it with Windows 10?

Were these the names I said?

> 
>> If we find out that github does not mess these accents then it
>> would be great to tell so in the I-D.
> 
> I would rather leave that pass without comment.  From my perspective,
> this all works.  That might be cause to celebrate, but we don't need
> to burden people with the details of solved problems when there are
> enough unsolved ones left to worry about.  If you are having issues,
> then that's something to work on.  For instance, it could be a system
> locale issue.

I sigh: I expire air loudly, I shake head negatively.  I give up in 
deception.

> 
>> How about the other recommendation? I suggest recommending this: do
>> not keep the .txt nor the .pdf in the root folder.
> 
> That is a fine suggestion that I fully support.  I find that
> including build output in the repository contributes to a hostile
> process for contributors. I have other things that I would rather
> spend that budget on, like trailing whitespace...
> 

minutiæ ?

Alex

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 11:29:28 +0100

Le 10/03/2020 à 07:05, Kjetil Torgrim Homme a écrit :
> recommended to Git skeptics

I heard that skepticism from many people in a hurry.  They dont have 
time to get imposed some rule.

It is difficult to understand some parts of the github behaviours.

Especially by those who do shared document processing by using other 
document sharing tools like github.

This is the gist of it: having a beautiful modern web interface, makes 
one think that GitHub easily supports things like uploading a document. 
It is not the case.  There is no button on the web to Upload a file. 
Not even to Download a file.

Alex

  (there is no doubt that Git can be

---

From: Kjetil Torgrim Homme <[email-masked]>
Date: Tue, 10 Mar 2020 11:47:23 +0100

On Tue, 2020-03-10 at 11:29 +0100, Alexandre Petrescu wrote:
> This is the gist of it: having a beautiful modern web interface,
> makes one think that GitHub easily supports things like uploading a
> document. It is not the case.  There is no button on the web to
> Upload a file.

it is right up there in the file browser in Github,

  [Create new file] [Upload files] [Find File]

in Gitlab there is a generic [+ v] dropdown menu to upload a new file,
create a new branch etc.

there is also the concept of gist (Github) and snippet (Gitlab) which
is for more informal sharing of files, think pastebin on steroids.

>  Not even to Download a file.

well, that is slightly less obvious, I'll grant you that - the button
is called [Raw] in Github, which you may have to Control click to get
the file download dialog.  in Gitlab there is a separate download icon
(an arrow pointing down into a tray).

-- 
regards,
Kjetil T.

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 12:39:03 +0100

[...]
> That is in the Introduction and Document Goals sections[...]

I think that is not the case.

It does say in Introduction and Document Goals that one goal is document 
editing.

It does not say in either section that a goal of using github is to 
write software for protocol developped by that WG.

Were it to say so, I would discuss it further.  In one WG I am active I 
hesitate between recommending github for software writing, or another one.

Alex

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 12:46:56 +0100

>    [Create new file] [Upload files] [Find File]

'Find file' is a term that means to open a file, if expressed in Mac, or 
it means to search and find a file if expressed in Windows.  It is 
misleading.

The particular need is the following: I want to download the file.  I do 
not want to display it first and only then download it.  It is too long.

So, I think my need is the following: I want a big visible button on 
github to quickly download a file, and not to have to go through 
numerous other buttons first.

Then, I want to update a file, not to upload a new one.

The fact that there are is no straight button to update a file leads to 
generation of many files in the same folder.  I upload a file with -AP 
in name, others put theirs, and we end up with too many files.

> (an arrow pointing down into a tray).

Thank you for the explanation.  I did not know that.  I think  I might 
need to put it in my howto.

Alex

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 10 Mar 2020 22:51:03 +1100

> > to obtain the changes made to a repository.

After Barry's review it says:

A pull request is a GitHub feature that allows a user to request a change to a repository.

> > added the real names of contributors to the QUIC specs and it just

Yes.  And Mac and Linux variously.  I just took the names I was given and used copy and paste.

> Were these the names I said?

See
https://quicwg.org/base-drafts/draft-ietf-quic-transport.html#name-contributors
https://github.com/quicwg/base-drafts/pull/3283/files

---

From: Tim Wicinski <[email-masked]>
Date: Tue, 10 Mar 2020 07:54:12 -0400

This document very much stays away from suggesting using github to write
software for protocol development.
I would argue that the decision on which tools to use in a WG project
should be decided by the WG based on
needs, etc.

tim

On Tue, Mar 10, 2020 at 7:39 AM Alexandre Petrescu <
[email-masked]> wrote:

> Ietf-and-github mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/ietf-and-github
>

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 10 Mar 2020 23:06:25 +1100

Thanks Tim, I agree.

The document concentrates on document production.  Though GitHub is probably even better suited to software development, that's not an activity that the IETF needs to have such a strong hand in.  If a working group wanted to develop a reference implementation or a test suite or other code product, then I would definitely recommend GitHub.  But that is rare enough to treat on an ad hoc basis. Many people will use the tool for that purpose and more power to them for doing so, but we don't need supporting documents for that.

On Tue, Mar 10, 2020, at 22:54, Tim Wicinski wrote:
> 
> This document very much stays away from suggesting using github to 
> write software for protocol development.
> On Tue, Mar 10, 2020 at 7:39 AM Alexandre Petrescu 
> <[email-masked]> wrote:
> > 
> >

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 13:14:21 +0100

> Yes.  And Mac and Linux variously.  I just took the names I was given and used copy and paste.

I am surprised.

I just checked with Windows 10, emacs, github and xml2rfc.tools.ietf.org

and it becomes this "Ole Troean".

That name is an error.  We know correct name.

The same might happen with the name Jérôme Härri - I expect the ä to 
become an 'ae' that is an error.

You can check for yourself, if the github maintainer gives you access. 
It is there https://github.com/Kottapalli-Naveen/SLAAC-Prefix-Length

Alex

> https://github.com/quicwg/base-drafts/pull/3283/files

There is no ä ?  I guess it's like ü maybe.

Alex

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 13:18:52 +0100

> There is no ä ?  I guess it's like ü maybe.

Which makes me wonder whether access control to github is discussed?

Alex

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 13:20:28 +0100

Le 10/03/2020 à 13:06, Martin Thomson a écrit :
> Thanks Tim, I agree.
> 
> The document concentrates on document production.  Though GitHub is
> probably even better suited to software development, that's not an
> activity that the IETF needs to have such a strong hand in.  If a
> working group wanted to develop a reference implementation or a test
> suite or other code product, then I would definitely recommend
> GitHub.  But that is rare enough to treat on an ad hoc basis. Many
> people will use the tool for that purpose and more power to them for
> doing so, but we don't need supporting documents for that.

In the WGs where I work often times the implementations are referred to 
github.  Many implementations are there.

But indeed there are more places where the software code is put,more 
than just github.

The question would be whether to recommend one (github?), or a list of them.

Alex

>> write software for protocol development. I would argue that the
>> decision on which tools to use in a WG project should be decided by
>> the WG based on needs, etc.
>> 
>> tim
>> 
>> 
>>> Le 10/03/2020 à 06:50, Martin Thomson a écrit : [...]
>>>>> This section 3.1 is good in general, but does not seem to me
>>>>> to say What to Use GitHub For. This is what it should be used
>>>>> for: share Internet Drafts and share code implementing
>>>>> protocols.
>>>> 
>>> It does say in Introduction and Document Goals that one goal is
>>> document editing.
>>> 
>>> It does not say in either section that a goal of using github is
>>> to write software for protocol developped by that WG.
>>> 
>>> Were it to say so, I would discuss it further. In one WG I am
>>> active I hesitate between recommending github for software
>>> writing, or another one.
>>> 
>>> Alex
>>> 
>>> _______________________________________________ Ietf-and-github
>>> mailing list [email-masked]

---

From: Julian Reschke <[email-masked]>
Date: Tue, 10 Mar 2020 15:36:26 +0100

On 10.03.2020 06:50, Martin Thomson wrote:
 > ...
> ...

Well.

That's a stretch. AFAIU, you used an experimental feature in xml2rfv
("<contact>"), which is not even documented yet, and which might change
in the future.

Things would be easier if xml2rfc did not insist on having non-ASCII
characters only appear within certain markup constructs. In that case it
really would be a case of "it just works".

Best regards, Julian

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 15:47:05 +0100

I need to clarify something about my sensed ubiquiteness and necessity
of github.

Not only I use github for my IETF activities but I also use its access
control for document editing on my projects at work: sharepoint.

The access control of several 'sharepoint' repositories where I connect
is with my github account.

This widely encompassing access control has some drawback in some of
today's browsers: if one logs into one repository (e.g. a github
repository) with one email address then the other repositories of same
access control (e.g. sharepoint) wont work if that's not the same email
address.  A certain browser solves this problem by using 'Private
Browsing' Ctl-Shift-P.  It is the first time I absolutely and
explicitely need privacy.  I am not sure that's the intended goal of
privacy, but that's where I need it.

Alex

Le 10/03/2020 à 13:20, Alexandre Petrescu a écrit :
>> The document concentrates on document production.  Though GitHub
>> is probably even better suited to software development, that's not
>> an activity that the IETF needs to have such a strong hand in.  If
>> a working group wanted to develop a reference implementation or a
>> test suite or other code product, then I would definitely
>> recommend GitHub.  But that is rare enough to treat on an ad hoc
>> basis. Many people will use the tool for that purpose and more
>> power to them for doing so, but we don't need supporting documents
>> for that.
> 
> In the WGs where I work often times the implementations are referred
> to github.  Many implementations are there.
> 
>>> This document very much stays away from suggesting using github
>>> to write software for protocol development. I would argue that
>>> the decision on which tools to use in a WG project should be
>>> decided by the WG based on needs, etc.
>>> 
>>> tim
>>> 
>>> 
>>>>>> This section 3.1 is good in general, but does not seem to
>>>>>> me to say What to Use GitHub For. This is what it should be
>>>>>> used for: share Internet Drafts and share code
>>>>>> implementing protocols.
>>>>> 
>>>> It does say in Introduction and Document Goals that one goal
>>>> is document editing.
>>>> 
>>>> It does not say in either section that a goal of using github
>>>> is to write software for protocol developped by that WG.
>>>> 
>>>> Ietf-and-github mailing list [email-masked]

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 15:50:06 +0100

Le 10/03/2020 à 15:36, Julian Reschke a écrit :
>> ... Yes.  The whole charset thing is difficult, but if you use
>> UTF-8 and Unicode you will find that things just work.  In most
>> cases, you don't even have to make an effort to do so because
>> modern software has largely left the baggage of the past behind.
>> We've recently added the real names of contributors to the QUIC
>> specs and it just worked. ...
> 
> Well.
> 
> ("<contact>"), which is not even documented yet, and which might
> change in the future.

I need perfect accents in the Ack section, not in the list of Authors or
Contributors.  Often Ack'ed people make more significant contrib or similar.

<contact> does not work in the Ack section, I just tried.

> characters only appear within certain markup constructs. In that case
> it really would be a case of "it just works".

Do you mean that me not being able to use ö in Ack section is a mistake
of xml2rfc, and not a mistake of github?

Alex

---

From: Julian Reschke <[email-masked]>
Date: Tue, 10 Mar 2020 16:10:16 +0100

> <contact> does not work in the Ack section, I just tried.

It's supposed to work there. What *exactly* did you try?

> of xml2rfc, and not a mistake of github?

github has nothing to do with that.

The developer of xml2rfc has chosen to restrict non-ASCII characters
further than defined in RFC 7991, essentially allowing them only in
artwork/sourcecode and a few new special constructs. The intent of RFC
7991 was to just allow them everywhere, and let the RFC Production
Center deal with overuse.

Best regards, Julian

---

From: Alexandre Petrescu <[email-masked]>
Date: Tue, 10 Mar 2020 17:32:37 +0100

> It's supposed to work there. What *exactly* did you try?

I have tried to write people's names in the Ack section.  "ä" became 
"ae".  Japanese characters got un-understandable - scrambled in a 
strange way.

Then, from private feedback, I tried to put <contact fullname="Ole Trøan 
(Ole Troan)."/> in the Ack section.

The xml2rfc.tools.ietf.org complains this:
Error: Unable to validate the XML document: INPUT
  <string>: Line 1439: Element contact is not declared in t list of 
possible children
  <string>: Line 1440: No declaration for element contact
  <string>: Line 1440: No declaration for attribute fullname of element 
contact

The xml file is local on my Windows 10 computer but is shared on a 
github repository with an application called "Github Desktop".

> github has nothing to do with that.

I tend to agree with that.

I tried testing xml2rfc with a local file, or with the same file stored 
through github.  The result is the same, independently whether is on 
github or not on github.  The error is the following:

Source:
>       <t>
> 	Ole Trøan, 神明達哉 (TATUYA Jinmei), Jérôme Härri.  It
> 	     would be great if xml2rfc could compile these characters
> 	     ok.  People's names are probably the most important thing
> 	     in an I-D.
>       </t>

Compilation results in:
> 
>    Ole Troean, &#31070;&#26126;&#36948;&#21705; (TATUYA Jinmei), Jerome
>    Haerri.  It would be great if xml2rfc could compile these characters
>    ok.  People's names are probably the most important thing in an I-D.

That is why I think I agree with you.  I was wrong saying github has an 
error in accents.  It might be the problem is xml2rfc, actually.

> Center deal with overuse.

Thank you for the explanation.  I dont really understand it fully, but 
it looks understandable.

For my part, it would be great if accents were ok in the Ack section.

(I have other complaints to xml2rfc, like xml2rfc.tools.ietf.org's 
*.txt.pdf output file names, about which I got suggested to register to 
tools-discuss email list and suggest it there; one day).

Alex

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 10 Mar 2020 18:30:56 +0100

Hi Alexandre,

>   <string>: Line 1440: No declaration for attribute fullname of element 

It looks as if you're running your XML through the v2 parser and formatter.

To use the <contact> element you need to use the v3 parser and formatter,
either by converting your v2 xml explicitly to v3 with 'xml2rfc --v2v3',
or by having it done on the fly by using the v3 switch 'xml2rfc --v3 ...'.

The legacy v2 parser and formatters knows nothing about the new v3 elements.

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 10 Mar 2020 19:06:42 +0100

> The legacy v2 parser and formatters knows nothing about the new v3 elements.

Right.

Also:

   <contact fullname="Ole Trøan (Ole Troan)."/>

would be an abuse of the element. Should be:

   <contact fullname="Ole Trøan" asciiFullname="Ole Troan"/>.

(That said, the ASCII version IMHO is not needed here anyway)

Best regards, Julian

---

From: Alexandre Petrescu <[email-masked]>
Date: Wed, 11 Mar 2020 14:18:03 +0100

Hi Henrik,

Thanks for the reply.

> It looks as if you're running your XML through the v2 parser and formatter.

I run https://xml2rfc.tools.ietf.org.  That is v2 as of today.

Is there a v3 xml2rfc.tools.ietf.org?

> or by having it done on the fly by using the v3 switch 'xml2rfc --v3 ...'.

Aha.

It seems that is a command line.  But here I prefer to use a GUI on the 
web.

Can I achieve conversion of my v2 xml to v3 with a GUI rather than a 
command on CLI?

And then, can I run a v3 xml2rfc on a GUI on the web?

Alex

---

From: Alexandre Petrescu <[email-masked]>
Date: Wed, 11 Mar 2020 14:26:34 +0100

Le 10/03/2020 à 19:06, Julian Reschke a écrit :
>>> I have tried to write people's names in the Ack section.  "ä"
>>> became "ae".  Japanese characters got un-understandable -
>>> scrambled in a strange way.
>>> 
>>> Then, from private feedback, I tried to put <contact
>>> fullname="Ole Trøan (Ole Troan)."/> in the Ack section.
>>> 
>>> The xml2rfc.tools.ietf.org complains this: Error: Unable to
>>> validate the XML document: INPUT <string>: Line 1439: Element
>>> contact is not declared in t list of possible children <string>:
>>> Line 1440: No declaration for element contact <string>: Line
>>> 1440: No declaration for attribute fullname of element contact
>> 
>> To use the <contact> element you need to use the v3 parser and
>> formatter, either by converting your v2 xml explicitly to v3 with
>> 'xml2rfc --v2v3', or by having it done on the fly by using the v3
>> switch 'xml2rfc --v3 ...'.
>> 

Ah excellent, it is a very appropriate element behaviour.

I am patiently waiting to be able to test it.

The fact that asciiFullname is optional is good, because not all
non-roman native name people have decided precisely what to put in their
roman interpretation (ascii), so it is good that is optional.

For example, I just discussed with somebody from Greece who prefers
'Gkemou' for her name instead of earlier 'Gemou', even though the French
who read if would prefer to see it 'Guemou'  (the goal of translating
from the native language spelling to roman spelling is that the readers
of that roman spelling make it sound like the originally pronounced).

Alex