Re: [Tools-discuss] [rfc-i] Proposed survey on I-D authoring tools

Phillip Hallam-Baker <> Thu, 01 October 2020 16:28 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 3B3933A10EC; Thu, 1 Oct 2020 09:28:20 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -1.649
X-Spam-Status: No, score=-1.649 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, FREEMAIL_FORGED_FROMDOMAIN=0.001, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, HTML_MESSAGE=0.001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001] autolearn=no autolearn_force=no
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id nD2La6S_xF5D; Thu, 1 Oct 2020 09:28:18 -0700 (PDT)
Received: from ( []) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id 95B353A10E9; Thu, 1 Oct 2020 09:28:18 -0700 (PDT)
Received: by with SMTP id w141so1360829oia.2; Thu, 01 Oct 2020 09:28:18 -0700 (PDT)
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=033OWc3W2uzDvw24XALJ4Ft8Ko3bjvDKYS6TdmUULmU=; b=OhkWlHIot/O4ILV+ty4n2l9enLcn4YV9iO9WCsoqOdnv45jon6+P24SF7ltI4Z5X8S VZ71E0Mm0JUYeNIxHuNyXlDHga+8HUynFAyhCwBUoeLmqKDpi2YzYdmz8dj8dlEycNyc DZA/CSHDI01mWoIU/fGLJ6pLqt8d5/A5KnqioqfoCLAOhp1OPfUhkc9zw0AT2jJGZGX4 He0Z9LKkv3DffwBYZMeISLgDW6aTuYsWbkcYul7ExDc3tGySmLdONO6fMDIW7Pk1u8us 4JbNRw86JWJUf2fWEbMdATeB8IRWSWEsFJtUSoR1KmDnBJJ09VdkgHy23Qs/RMuztKGo Fdxg==
X-Gm-Message-State: AOAM531s1g4ntBj0co45c0gId99C68690QfIY1OqWg7HRY9Kg6KSZag/ lgwNGpgksn7Me8VlgUIKfGh+39a9oyqZThvBmUfLP+qC
X-Google-Smtp-Source: ABdhPJzXXg5V3Y1TqlFNkwvSWFEkCXGQhodHewZ7Zy8v/QId/ke1qIO/tD/FQ4wjOHmmNq/gTdWK7SEbmtQ0F7eoQRo=
X-Received: by 2002:aca:bbd7:: with SMTP id l206mr468338oif.173.1601569697419; Thu, 01 Oct 2020 09:28:17 -0700 (PDT)
MIME-Version: 1.0
References: <> <> <> <> <> <> <> <19017.1601561002@localhost> <> <>
In-Reply-To: <>
From: Phillip Hallam-Baker <>
Date: Thu, 1 Oct 2020 12:28:06 -0400
Message-ID: <>
To: Jay Daley <>
Cc: Randy Bush <>, RFC Interest <>, Tools Discussion <>
Content-Type: multipart/alternative; boundary="000000000000e5daa105b09e8044"
Archived-At: <>
Subject: Re: [Tools-discuss] [rfc-i] Proposed survey on I-D authoring tools
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: IETF Tools Discussion <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Thu, 01 Oct 2020 16:28:20 -0000

I am not so sure what the value of asking what people do today is. The
question that really matters is what people would do if they knew what all
the options were.

I use Microsoft Word and Markdown to edit my specs. All the code is open
source but I seem to be the only person interested in this approach.

I edit the main body of the text in regular word format. I use regular
outlining etc. and it looks like word all the time I am editing. It does
not look like a plaintext rfc. That gives me spell checking and grammar.
Change control etc. also work.

The biggest deficiency of Word as a source format is that it is a pig to
generate from a tool. So I also use markdown similar to that used in
Carsten's tool but aligned with the markup used by GitHub because thats the
other tool we interact with.

So my word documents link to the generated markdown documents.

The tool will convert the Word/Markdown text into any of the input sources,
HTML, XML or plaintext output. Or all three.

The advantage of my approach is that it allows an editor who is using Word
to interact with contributors who insist on Markdown.

If you look at my output, I have produced 15 substantial drafts over the
past two years. The Mesh is similar in size and complexity to X.509v3 PKI
or SAML and I have designed and implemented it with very little outside
help. The reason I can do what would be a 30 person team at most companies
is that I am using a very powerful toolset that locks the documentation and
the code together.

Every example in my documents is generated from the reference code that is
derived from the same source as the schema. I am just implementing a tool
that locks the constant tables and cryptographic functions of the code and
documentation. It will be take me about four hours.