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

Jay Daley <jay@ietf.org> Thu, 01 October 2020 02:19 UTC

Return-Path: <jay@ietf.org>
X-Original-To: tools-discuss@ietfa.amsl.com
Delivered-To: tools-discuss@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id AA9E93A08A9 for <tools-discuss@ietfa.amsl.com>; Wed, 30 Sep 2020 19:19:12 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.898
X-Spam-Level:
X-Spam-Status: No, score=-1.898 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, HTML_MESSAGE=0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id wQrqmR8LpKYF; Wed, 30 Sep 2020 19:19:11 -0700 (PDT)
Received: from jays-mbp.localdomain (unknown [158.140.230.105]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPSA id 7E78E3A0891; Wed, 30 Sep 2020 19:19:10 -0700 (PDT)
From: Jay Daley <jay@ietf.org>
Message-Id: <50239C55-5575-490D-9D39-1E0329D52672@ietf.org>
Content-Type: multipart/alternative; boundary="Apple-Mail=_3B3ABB7E-080D-470A-ACEF-7FA2B792EFE5"
Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.120.23.2.1\))
Date: Thu, 1 Oct 2020 15:19:08 +1300
In-Reply-To: <87mu1666qa.fsf@hobgoblin.ariadne.com>
Cc: rfc-interest@rfc-editor.org, tools-discuss@ietf.org
To: "Dale R. Worley" <worley@ariadne.com>
References: <87mu1666qa.fsf@hobgoblin.ariadne.com>
X-Mailer: Apple Mail (2.3608.120.23.2.1)
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-discuss/iy9tnZ9PT1DRF0jYtfdzwrTbqt4>
Subject: Re: [Tools-discuss] Proposed survey on I-D authoring tools
X-BeenThere: tools-discuss@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: IETF Tools Discussion <tools-discuss.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-discuss>, <mailto:tools-discuss-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-discuss/>
List-Post: <mailto:tools-discuss@ietf.org>
List-Help: <mailto:tools-discuss-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-discuss>, <mailto:tools-discuss-request@ietf.org?subject=subscribe>
X-List-Received-Date: Thu, 01 Oct 2020 02:19:13 -0000

Thanks Dale

> On 1/10/2020, at 3:05 PM, Dale R. Worley <worley@ariadne.com> wrote:
> 
> Jay Daley <jay@ietf.org> writes:
> 
>> [QUESTION - Matrix/Rating Scale]
>> How often have you used the following document format(s) and associated output process(es) (editor/template/converter) when authoring an I-D? (Ignore any you don’t know about)
>> Items
>> 	• Plain text using no markup
>> 	• Plain text using a different output process
>> 	• Markdown using the kramdown-rfc2629 converter
>> 	• Markdown using the mmark converter
>> 	• Markdown using the draftr converter
>> 	• Markdown using the Pandoc2rfc converter
>> 	• Markdown using a different output process
>> 	• XML using the XMLMind editor and xml2rfc-xxe
>> 	• XML using a different output process
>> 	• AsciiDoc using the metanorma-ietf (formerly known as asciidoctor-rfc) converter
>> 	• AsciiDoc using a different output process
>> 	• TeX / LaTeX using Lyx editor and lyx2rfc
>> 	• TeX / LaTeX using a different output process
>> 	• nroff using the Nroff Edit editor
>> 	• nroff using nroff2xml template
>> 	• nroff using a different output process
>> 	• Microsoft Word rich text using Joe Touch’s Word Template (RFC5385)
>> 	• Microsoft Word rich text using a different output process (This means specifically using rich text styles that a template/convertor will recognise, it does not mean using this an editor for one of the other formats)
>> 	• Other format (Only use this option if you author in a different format to all of those above) [PLEASE SPECIFY what format you author in and what output process you use]
> 
> There seem to be category inconsistency here.  It appears to me that the
> major differentiator in this list is "What do you write the I-D in?",
> viz., plain text, markdown, XML, AsciiDoc, TeX, nroff, MS Word.  Then
> attached to that is "How do you output the I-D from that source?", which
> seems to be "no markup", "a different output process", etc., etc.  And
> then there's the element "What tool do you use to write the source?",
> which can vary from completely unstated to tools specifically designed
> to write I-Ds (e.g., Joe Touch's Word template).
> 
> What makes the choices hard to parse is that while all of the choices
> contain the source file type, only some specify the editing tool, and
> only some have the output process.  E.g., there are "XMLMind editor ->
> XML -> xml2rfc", "XML -> a different output process", and "plain text",
> each of which specifies a different subset of these elements.
> 
> Perhaps splitting out the three elements would make the choices clearer,
> and possibly allow you to cover the universe of possibilities more
> thoroughly.

I initially wrote this with those elements split out but from early reviews it became clear that was just too complex because the two elements of format and output tool are so closely linked and we actually need to understand that as a whole process.

I suspect I need to add something to explain that we’re not really interested in what the editor is and the only reason we mentioned editors is because they are tied to the specific output tools.  i.e. lyx2rfc only works with lyx, xml2rfc-xxe only works with XMLMind, nroff Edit is a standalone product solely for I-D authoring, and Joe Touch’s template only works on MS Word.  I could reword those as

- Tex / LaTeX using lyx2rfc (requires Lyx)
- XML using xml2rfc-xxe (requires XMLMind)
- MS Rich text using Joe Touch’s Word Template (requires MS Word)

Does that work better?

Jay

> 
> Dale
> 

-- 
Jay Daley
IETF Executive Director
jay@ietf.org