Re: authors.ietf.org now ready for review

Mahesh Jethanandani <mjethanandani@gmail.com> Fri, 17 December 2021 18:16 UTC

Return-Path: <mjethanandani@gmail.com>
X-Original-To: wgchairs@ietfa.amsl.com
Delivered-To: wgchairs@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id B21AA3A076C; Fri, 17 Dec 2021 10:16:23 -0800 (PST)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.096
X-Spam-Level:
X-Spam-Status: No, score=-2.096 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DC_PNG_UNO_LARGO=0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, 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: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com
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 3htUMddAbF-J; Fri, 17 Dec 2021 10:16:18 -0800 (PST)
Received: from mail-pg1-x52c.google.com (mail-pg1-x52c.google.com [IPv6:2607:f8b0:4864:20::52c]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id A49673A059F; Fri, 17 Dec 2021 10:16:18 -0800 (PST)
Received: by mail-pg1-x52c.google.com with SMTP id j11so2908843pgs.2; Fri, 17 Dec 2021 10:16:18 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:message-id:mime-version:subject:date:in-reply-to:cc:to :references; bh=HLL0nDcewKVS/7HDm2Eq+SgcQfZ7pn1+R3NIXdgNt9M=; b=oUbrRu9jo3qSvhFJK0XFImemOoSiT7xcpucViQLUfzab5Xflo6Txdp0eK6SoVnneuO UUJoZhFPqcA1tKNbXMOsPZjV4DSOSVytlKfsHoHB2wi2SVCBbQJCnPJd6us3raodULfr BvuKzIBzDDktaLiqY0qZJQfMKpBXGreXyiewe6tJJIquxGgAWcPdw3v2kViSDa6LSu7O sLLVxlP7xm1reGViAlPixEzu1sg0YnWsnOYTDDf9ItzQ5GgCF+FcLVWImbkXnO9kqAEv GxxqHsqoNmWe/h7NFRtIv7GDkjEBWrskLrz6eJ0UIYSPhhLFZzwDrmgT95Aw0qoyE+kW srjg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:message-id:mime-version:subject:date :in-reply-to:cc:to:references; bh=HLL0nDcewKVS/7HDm2Eq+SgcQfZ7pn1+R3NIXdgNt9M=; b=JIpnKsjMRirwu1C+56CmRUz4SGEE5psWkKIL8b4ni3HycLqgXpFAIoH8diGDfTV4dI tT1Ix9uZvHPCJ8XisQWSjX+kitu240J5vtAsiLqenW80QV4tnqm14N46LilDZbECFMSh YO4y95vIPtkP5xHeUyApWMedjIxjjd0U3XqyoYuKjwDVUTOkUomFqpUDPLcp7syxBneP bVV0gPegSEmuxgRuJzKFemW42q+aZtuFr8GsxEMPR9ENJB+N0bTxrQgZHOYWreVCBlXx qLD3De+HJi3W5gogNAZE/dJFHOWNe4/B5i6ywRUg1HlPT8YABGCOCL4pc+RSDchqbIqo g1Vg==
X-Gm-Message-State: AOAM531TYkUwKqcShfjnUVZfURyP5CkR1nRhdNA4tHR0xzLLN+UsjE7w wtJsnVWBkBQ04gZnbwbb1O89YSz/yodzog==
X-Google-Smtp-Source: ABdhPJy2Dpxc1HV+yzabFX1PsdHwLy5ODSWgCwfxlmqq1fCYeAH1yp6hP8rGqYTrqeT5PaD/XK1B3Q==
X-Received: by 2002:a05:6a00:a23:b0:4a4:e9f5:d890 with SMTP id p35-20020a056a000a2300b004a4e9f5d890mr4263315pfh.82.1639764976722; Fri, 17 Dec 2021 10:16:16 -0800 (PST)
Received: from smtpclient.apple (c-69-181-169-15.hsd1.ca.comcast.net. [69.181.169.15]) by smtp.gmail.com with ESMTPSA id d13sm505483pjz.7.2021.12.17.10.16.15 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Fri, 17 Dec 2021 10:16:16 -0800 (PST)
From: Mahesh Jethanandani <mjethanandani@gmail.com>
Message-Id: <4EE1E154-9045-4EB8-9231-56404E7369A5@gmail.com>
Content-Type: multipart/alternative; boundary="Apple-Mail=_6ED86D70-8F19-42DE-A6CF-8FF1610AC412"
Mime-Version: 1.0 (Mac OS X Mail 14.0 \(3654.120.0.1.13\))
Subject: Re: authors.ietf.org now ready for review
Date: Fri, 17 Dec 2021 10:16:15 -0800
In-Reply-To: <96F1DCFE-276B-4A12-938D-6EB4C529CC15@ietf.org>
Cc: Working Chairs <wgchairs@ietf.org>
To: Jay Daley <exec-director@ietf.org>
References: <96F1DCFE-276B-4A12-938D-6EB4C529CC15@ietf.org>
X-Mailer: Apple Mail (2.3654.120.0.1.13)
Archived-At: <https://mailarchive.ietf.org/arch/msg/wgchairs/xTAFmLN9QNkci548BVnccXWa-is>
X-BeenThere: wgchairs@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: Working Group Chairs <wgchairs.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/wgchairs>, <mailto:wgchairs-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/wgchairs/>
List-Post: <mailto:wgchairs@ietf.org>
List-Help: <mailto:wgchairs-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/wgchairs>, <mailto:wgchairs-request@ietf.org?subject=subscribe>
X-List-Received-Date: Fri, 17 Dec 2021 18:16:24 -0000

Hi Jay,

First of all thanks for putting this website together. I can see myself bookmarking it for use right away.

Couple of observations:
The Search option starts by giving an error. See below.
The tool rfcdiff refers to tools.ietf.org site. Is there a plan to move it? I find it particularly useful.
For YANG validation, you might want to mention yanglint and yanger as two other tools to use.
For sometime now idnits v3.x had been giving unexpected errors, till I found an offline v2.x that works for me. Is there a plan to fix v3.x?



> On Dec 16, 2021, at 7:53 PM, Jay Daley <exec-director@ietf.org> wrote:
> 
> For info, the following email has now gone to tools-discuss:
> 
> —— 
> # Context
> 
> At the end of 2020/start of 2021, the analysis of the survey of I-D authors recommended a new central resource site for I-D authors bringing together the documentation that is currently in multiple hard to find places, and we were given notice that the servers running tools.ietf.org would be turned off.  Consequently, work began in 2021 on a new site intended to be both that central resource and the new home for the documentation on tools.ietf.org. This site is now ready for community review at http://authors.ietf.org
> 
> The goals of this new site are:
> 
> - Bring all I-D authoring-related information into one place
> - Put that information into a structure that works equally well for novices, occasional authors and experts.
> - Ensure a full coverage of all the topics that authors need to know
> - Clear up the out of date, duplicate and incorrect information.
> 
> The content comes from the following sources:
> 
> - The catalog of tools on the front page of tools.ietf.org [0] with added categorisation and feature matrix
> - The xml2rfc vocabulary documentation [1] with added examples and schema snippets
> - Some pages on rfc-editor.org with relevant content [2] [3] [4]
> - The Guidelines for I-D authors [5]
> - New content to provide the necessary structure and fill any gaps.
> 
> This site is intended solely for I-D authors and so does not contain the following content:
> 
> - Details of the standards process
> - Documentation on the AUTH48 review and subsequent publication process as those are processes for RFCs not I-Ds.  This remains on rfc-editor.org 
> 
> 
> # Key changes
> 
> The site introduces the following key changes to the existing content:
> 
> 1.  What was previously referred to as "the xml2rfc vocabulary" is now referred to as RFCXML.  This is in line with the normal naming of XML languages and separates out the language from the tool, providing for independent implementations.  This change has been broadly supported by the RSOC, the Temporary RFC Series PM and the community tools developers who have been asked to preview the site.
> 
> 2.  The previous community supplied XML template has been replaced with three 'official' templates in order to:
> 
> - support modern XML editors that provide schema-aware editing
> - ensure that the template reflects best practice as expected by the RPC (e.g. using <sourcecode> for source code, not <artwork>)
> - provide different templates for different levels of expertise
> - reflect the schema and entity changes as noted below
> 
> The templates are:
> 
> 	draft-rfcxml-general-template-standard.xml
> 	draft-rfcxml-general-template-bare.xml
> 	draft-rfcxml-general-template-annotated.xml
> 
> These templates, together with the schemas are all available on the site [6] and in a GitHub repository [7] 
> 
> 3.  The schemas have been reorganised to more accurately reflect their contents and usage.  In particular ensuring that the name matches the contents and matches the RFC that defines those contents.
> 
> - rfc7991.rnc has not changed
> - v3.rnc has been renamed to rfc7991bis.rnc
> - v2.rnc has been renamed to rfc7749.rnc
> - rfc2629.dtd has had all references to it removed as it was effectively deprecated some time ago
> - rfc2629-html.ent and rfc2629-other.ent have been deprecated as special entity processing is not required in v3
> 
> The legacy schemas and associated files are all available in a single GitHub repository [8].
> 
> (In related news, the authors of rfc2629.xslt and kramdown-rfc2629 have agreed to rename their tools to remove the RFC-specific part which refers to v1 of RFCXML.)
> 
> 
> # Known issues
> 
> - In preparation for the migration of tools.ietf.org, some tool links point to placeholder repositories on GitHub rather than the current home for that tool.
> - Some links still point to tools.ietf.org 
> - There are a number of limitations in the underlying wiki product that are due to be addressed in upcoming versions:
>   - The site does not have an IETF look and feel.  This is 
>   - The page contents menu is automatically generated and placed and some people don’t like it.  
>   - Some checklist items render incorrectly.
> 
> 
> # Ongoing maintenance
> 
> Until such time as a community structure is put in place to maintain this site, it will be maintained as required by the tools team, Temporary RFC Series Project Manager, LLC and RPC.  The content is all available on GitHub [9] and issues and pull requests are welcome.
> 
> 
> # Outstanding work
> 
> There is some work that will be completed after community review:
> 
> - Adding MIB/YANG specific XML templates
> - Adding more examples to the vocabulary reference
> 
> 
> # Go live
> 
> The plan is for the site to go live when the big switchover from tools.ietf.org happens (that includes more than just this site).  The front page of tools.ietf.org and possibly it's 404 page will then redirect to this site. In addition, the following needs to happen to ensure that we do not continue with multiple sets of duplicate and inconsistent documentation:
> 
> - the RPC will review the content on the rfc-editor.org site and remove/redirect/refresh as appropriate 
> - xml2rfc will not longer output details of the vocabulary but refer instead to this site
> - the IESG will decide what to do about the Guidelines for I-D Authors 
> 
> 
> # Community review
> 
> Please let us know what you think of this site and if you have any specific issues or suggestions then a GitHub issue or pull request at https://github.com/ietf-authors/authors.ietf.org would be ideal.  It expected that this will be an ongoing process of review and improvement.
> 
> Jay
> 
> [0]  https://tools.ietf.org
> [1]  https://xml2rfc.tools.ietf.org/xml2rfc-doc.html
> [2]  https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html
> [3]  https://www.rfc-editor.org/rse/wiki/doku.php?id=svg_files
> [4]  https://www.rfc-editor.org/rse/wiki/doku.php?id=v3_feature_usage
> [5]  https://www.ietf.org/standards/ids/guidelines/
> [6]  https://authors.ietf.org/en/templates-and-schemas
> [7]  https://github.com/ietf-authors/rfcxml-templates-and-schemas 
> [8]  https://github.com/ietf-authors/legacy-templates-and-schemas
> [9]  https://github.com/ietf-authors/authors.ietf.org
> 
> —— 
> 
> -- 
> Jay Daley
> IETF Executive Director
> exec-director@ietf.org
> 


Mahesh Jethanandani
mjethanandani@gmail.com