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:
-------
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.
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/
--
last-call mailing list
last-call@xxxxxxxx
https://www.ietf.org/mailman/listinfo/last-call
