Re: document writing/editing tools used by IETF

Phillip Hallam-Baker <> Sat, 27 February 2021 18:32 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 59D483A1211 for <>; Sat, 27 Feb 2021 10:32:00 -0800 (PST)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -1.399
X-Spam-Status: No, score=-1.399 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, FREEMAIL_FORGED_FROMDOMAIN=0.249, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.25, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=no autolearn_force=no
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id jUUdH_aT0QVV for <>; Sat, 27 Feb 2021 10:31:58 -0800 (PST)
Received: from ( []) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id 658723A120B for <>; Sat, 27 Feb 2021 10:31:58 -0800 (PST)
Received: by with SMTP id m9so12454381ybk.8 for <>; Sat, 27 Feb 2021 10:31:58 -0800 (PST)
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:from:date :message-id:subject:to:cc; bh=vRLNsyqTFbMTrcwQhZwhT581Gs9tALI97c0ALL2nlzY=; b=HFuek9kDiNdhgKigDN3IIphACSMXKymdbPN/CSB/aAMMCjT28lXUkkuQXBHKnPvyly aG2FORbzg8DBm+NP9ZPiU7icf/JeFQHh+wuS3fQXAg7z4XluEzIUI48CMyWTYF8RNq1i yRX0iUzedU5H9upXndq/ZjygdV6QzoxyRHaQFHKe4vo9CwXlSZrvFzssDOdB3JQfekvS fZe6lCh28UodxpoeOooJkSOFvVXizVmeBPY52t78bJ4z2/1u+waRw2S25ZxnuQzm+xYb D3UaUv6JDOStk9jN5w9cHsRwiqX/+R/nfUGTpGeIpaQG76welefykxv7+HW0iZ0+5aZd 6CWA==
X-Gm-Message-State: AOAM533nexybUJ8nel+0jgHJisE1wj0KgflAyRT8GjaAQO/bsgpFrkDs vheh0eLygJHKGbmZOAO34eNEBqw6T6LNcFY3fehaidOQYFk=
X-Google-Smtp-Source: ABdhPJxFpGt9qnWXY/nCyUXyJGc240wTg257RLA1+T0e/CwAgjY1rBaAK8juUlCGL9A4Tsipl1Ez6hO63mQLfdolJ8A=
X-Received: by 2002:a25:ad67:: with SMTP id l39mr12898498ybe.172.1614450717304; Sat, 27 Feb 2021 10:31:57 -0800 (PST)
MIME-Version: 1.0
References: <> <> <> <> <LO2P265MB057322BA95B1B44D4175356BC29E9@LO2P265MB0573.GBRP265.PROD.OUTLOOK.COM> <> <> <001d01d70be3$ff0972d0$fd1c5870$> <> <> <> <>
In-Reply-To: <>
From: Phillip Hallam-Baker <>
Date: Sat, 27 Feb 2021 13:31:47 -0500
Message-ID: <>
Subject: Re: document writing/editing tools used by IETF
Cc: "" <>
Content-Type: multipart/alternative; boundary="00000000000083295d05bc5599d9"
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: Sat, 27 Feb 2021 18:32:00 -0000

One of the reasons I have switched from using the pandoc markdown used by
Carsten's tool to github markdown is that the latter is used by Git.

I agree Git has advantages over mailing lists. But we are using a tool that
isn't designed to meet our specific needs. I am for entirely separate
reasons looking at requirements for a tool that is designed to meet those
needs (but for a different community).

Previous attempts to get a discussion going on what tool we would want...
haven't exactly been successful. They turn into a github vs mailing list
editor war when my interest is quite different.

On Fri, Feb 26, 2021 at 2: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 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