Re: document writing/editing tools used by IETF

Behcet Sarikaya <> Mon, 01 March 2021 15:56 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 5F46F3A1E86 for <>; Mon, 1 Mar 2021 07:56:44 -0800 (PST)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -1.847
X-Spam-Status: No, score=-1.847 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_ENVFROM_END_DIGIT=0.25, FREEMAIL_FROM=0.001, HTML_MESSAGE=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: (amavisd-new); dkim=pass (2048-bit key)
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id 4lgyagvY1u4N for <>; Mon, 1 Mar 2021 07:56:42 -0800 (PST)
Received: from ( [IPv6:2607:f8b0:4864:20::b2d]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id 44F6E3A1E68 for <>; Mon, 1 Mar 2021 07:56:42 -0800 (PST)
Received: by with SMTP id m9so17439611ybk.8 for <>; Mon, 01 Mar 2021 07:56:42 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=mime-version:references:in-reply-to:reply-to:from:date:message-id :subject:to:cc; bh=zaoCFqgMAjd7b52vtS9hQs8IkxvYHGTmm6W6bu6PMiY=; b=MlamDQ/t9v9neWtaEHP1rFBjVf1xXP+5p243mFU9Ml035fFhm+a8LmVdNmW+CiMkWW fhWnLbKOWV95mxPLJaJ05gwyCWq80gdbMGMhr39u1Jgsw7rgbmcLZG4CYAzrjMlojYHC WKjdpNqp0QSZz0IyA9hKNtnvd4wfHowFykWJ1mXzfbsBAfDmYZyFkhIH1LrAXOloZ/jL fA4Hyr0Y2DLOEfnc2ltSC7JUanvykJdvVZyEewgK3aqcZ0jOcuJuqBXH0Sd1fpChkP13 CrYcJLmQhmLSI+7asx3MCNKCHD8MQxQHKwsQb/tw4pkQMDYuAd7zcejT9q+j3FbWvK1y zFyg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:reply-to :from:date:message-id:subject:to:cc; bh=zaoCFqgMAjd7b52vtS9hQs8IkxvYHGTmm6W6bu6PMiY=; b=fMPVNdVa9/k1MkR/GZoWDDB9z21l8DL2nJdaF9EPaPsqmyrZN0mz8Egak92mFG8cl6 eukVl0LIo6NvXzZ3iNiNCNqbxU+p4Br+S0n1Ar61JjjGbqEq4bxVCEjH3i/EXaP+pTv9 227By69apU4UznA9lxxkSy9PEEVag43nQyG9sSVOIAHVk9FLaYeQAPojPH4Amu/iMX8p nPVqXSSjJ4cD3giMzcGfqeVfAbz2zLEQhDZ039ilpVRo3umHMIwreVzZj1HQo2HDPTY4 Rt+NrrLF0f9P1SeEREJSViKL0G4/sNoS69HlCC0YK0w0Q+5+CVYi35nntItma/7+Jvbu KNZQ==
X-Gm-Message-State: AOAM530uq3Npvp16jArAy0eZ8GZ3Z3CENJ0NQf1yj947rpQJxIIgnq+b FG4nNGrytFTE3dyROQVU61GLtlFktW6comM4yCY=
X-Google-Smtp-Source: ABdhPJylEQpjfGU3OilT0wt6NYv23FTymjWBEI4Uw6IZqhXuVlmyX6SC8Uu4ypc1cCYiG9Ii9wMl+9DN1O09jgrvFLs=
X-Received: by 2002:a25:ca42:: with SMTP id a63mr24406213ybg.318.1614614199624; Mon, 01 Mar 2021 07:56:39 -0800 (PST)
MIME-Version: 1.0
References: <> <> <> <> <LO2P265MB057322BA95B1B44D4175356BC29E9@LO2P265MB0573.GBRP265.PROD.OUTLOOK.COM> <> <> <001d01d70be3$ff0972d0$fd1c5870$> <> <> <> <>
In-Reply-To: <>
From: Behcet Sarikaya <>
Date: Mon, 1 Mar 2021 09:56:28 -0600
Message-ID: <>
Subject: Re: document writing/editing tools used by IETF
Cc: "" <>
Content-Type: multipart/alternative; boundary="000000000000d1685405bc7ba9bf"
Archived-At: <>
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: IETF-Discussion <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Mon, 01 Mar 2021 15:56:44 -0000

Hi Barbara,

On Fri, Feb 26, 2021 at 1:11 PM STARK, BARBARA H <> wrote:

> As someone who has used just about all of the front-end tools mentioned in
> this thread (with front-end, I'm excluding all the processing tools because
> I've only used a few of those), I'd like to say that I really enjoy
> collaborative editing of markdown in GitHub and find it to be an excellent
> tool that is fully accessible to anyone with an Internet connection and a
> browser. I recently finished a document with a bunch of
> people-who-do-not-write-code -- some of whom didn't even have a GH account
> before this. I provided instructions. The only people who had issues
> contributing were the ones who never tried. Everyone who read the
> instructions and tried had no problem. If I had to provide instructions to
> someone who had never used Word, I suspect it would be a lot harder. Not to
> mention the cost of a Word license. One of the things that became clear in
> this process is that some people think you need to be running git on a
> local machine; that's not true.
> If anyone is curious, these are the instructions I provided:
> ====================
> ## Signing up for a GitHub (GH) account
> Everyone needs a GitHub account to participate. To set up a GH account, go
> to and enter a preferred username, the email address
> you want to associate with the account (personal or work, depending on
> preferences and your corporate policies), and a password.  GH will impose
> username uniqueness and password strength.
> ## Signing in to GH
> The page defaults to "Sign Up". Click "Sign In" at
> the upper right to get the "Sign In" page if you already have an account.
> ## Using the GitHub UI
> In the [repository]( <account>/<repo>), click on the
> file you want to edit, and then click on the pencil icon in the upper right
> of the file. Do your edits. When done, scroll to the bottom of the page,
> **select the checkbox that says "Create a new branch for this commit and
> start a pull request"** (this is really important), and click on the
> "Propose Changes" button. If the button says "Commit Changes" instead of
> "Propose Changes", then you need to click the "Create a new branch for this
> commit and start a pull request" button first. On the next page that
> appears, click "Create pull request". If you think some description of your
> changes might help, feel free to enter something in the "Leave a comment"
> box (either for Propose Changes or the Pull Request).
> If you want to work on the Pull Request (PR) over time or provide
> additional edits to your existing PR, you can do this at any time before
> the PR is merged. To do this, you simply edit files in your newly created
> branch. Select your branch from the pulldown menu (default branch in the
> pulldown is "Main") at the upper left of the [<account>/<repo> Code](
> page. The pulldown menu is
> located right under the `<> Code` tab heading. After your PR is merged,
> that branch will be automatically deleted.
> ## Using Markdown
> ======================
> This last part of the instructions had a link to
> For an IETF draft that is going to be processed using kramdown-rfc2629, I
> would also include a link to
> I haven't used mmark or Phil's tools.
> But I don't think the average author needs (or should need) to know much
> more than headers, paragraphs, lists, and IETF references. The first 3 are
> really, really simple. References aren't hard.
> And that's it. I think if we made GH draft authoring this simple for
> people in IETF, opposition to it would disappear.
> The main thing I think is missing is easy set up of GH workflows to create
> XML and HTML artifacts.
I never used GH like you mentioned above. I know that it is used in Quic WG
and possibly others. If I understand well, it is used to create a draft in
text format not in xml2rfc format,
isn't that a big negative?

I find the "I hate Word" vs "I hate GH" argument to be futile. Just make it
> this easy for everyone to use GH and there'd be no argument.


> Barbara