Re: [Tools-discuss] [rfc-i] Recommendation 9 from Results and analysis of the survey of I-D authors on formats and tools

Carsten Bormann <cabo@tzi.org> Sun, 07 February 2021 03:10 UTC

Return-Path: <cabo@tzi.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 B42833A2EE7 for <tools-discuss@ietfa.amsl.com>; Sat, 6 Feb 2021 19:10:59 -0800 (PST)
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, SPF_HELO_NONE=0.001, SPF_PASS=-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 U98TlAy3mrI2 for <tools-discuss@ietfa.amsl.com>; Sat, 6 Feb 2021 19:10:57 -0800 (PST)
Received: from gabriel-vm-2.zfn.uni-bremen.de (gabriel-vm-2.zfn.uni-bremen.de [134.102.50.17]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id EE9E53A2EE6 for <tools-discuss@ietf.org>; Sat, 6 Feb 2021 19:10:56 -0800 (PST)
Received: from [192.168.217.152] (p5089a828.dip0.t-ipconnect.de [80.137.168.40]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by gabriel-vm-2.zfn.uni-bremen.de (Postfix) with ESMTPSA id 4DYDgf1z9qzyVV; Sun, 7 Feb 2021 04:10:54 +0100 (CET)
Content-Type: multipart/alternative; boundary="Apple-Mail=_634B3A97-B1E9-4359-A6A6-B4FCFE6F45C6"
Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.60.0.2.21\))
From: Carsten Bormann <cabo@tzi.org>
In-Reply-To: <29774.1612663657@localhost>
Date: Sun, 07 Feb 2021 04:10:53 +0100
Cc: RFC Interest <rfc-interest@rfc-editor.org>, tools-discuss <tools-discuss@ietf.org>
Message-Id: <139065E7-F8DF-418D-89E9-156BE35C4DFA@tzi.org>
References: <161240956258.5082.18097054694330751435@ietfa.amsl.com> <CAA=duU1c3g0qmNmSN9jpfq3o4Lggxg_vT3xLdmwxAzLPm0r-iQ@mail.gmail.com> <15878309-55BA-4BE0-BD26-060308BA1270@tzi.org> <E77A02FF-4DF8-4030-BC77-4355A705E00E@adobe.com> <A2CC3D3F-3920-4E51-AAD7-1FFE83CA5ECB@tzi.org> <18192.1612647870@localhost> <CADyWQ+HoVg9H8xKLLoGkatVoDTg60bdNANNADyDWxnBz=cbdWQ@mail.gmail.com> <29774.1612663657@localhost>
To: Michael Richardson <mcr+ietf@sandelman.ca>
X-Mailer: Apple Mail (2.3654.60.0.2.21)
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-discuss/FPl_l9BeTBAeLvZGTSdEGasLH1s>
Subject: Re: [Tools-discuss] [rfc-i] Recommendation 9 from Results and analysis of the survey of I-D authors on formats and 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: Sun, 07 Feb 2021 03:11:00 -0000

On 7. Feb 2021, at 03:07, Michael Richardson <mcr+ietf@sandelman.ca> wrote:
> 
> That actually is less helpful, if you haven't uploaded all the required files
> to the DT.

Right.  So an include feature probably should include a preparation feature that allows you to create a combined version to upload.

But why not include the conversion to XML with that preparation round?

Actually, when you use kramdown-rfc to create XML, the original source (combined!) is included in the XML as a comment (extract with kramdown-rfc-extract-markdown), so we already have the best of both worlds.

Re the {::include fn} feature:  I used to create documents like RFC 7400 (which is mostly generated text) from a script.
But then I found it easier to edit the text around the generated snippets with the {::include fn} feature.
Of course, there still needs to be a Makefile and the generation scripts for the snippets themselves.
(Including those in the markdown isn’t advisable for security reasons.)

While there is a bit of redundancy in ...

~~~~
<CODE BEGINS> file "ietf-sid-file@2020-02-05.yang"
{::include ietf-sid-file@2020-02-05.yang}
<CODE ENDS>
~~~~

…, I’m not sure avoiding that warrants a Perl script by itself.

Grüße, Carsten