Subject: [TOOLS-DEVELOPMENT] Another very raw start at an SoW: rfclint

From: Robert Sparks <[email-masked]>
Date: Mon, 19 May 2014 15:45:25 -0500

Again, sending something very early to stimulate discussion.
Do you think this is going in the right direction?
If so, what big pieces are missing?

RjS

Overview

There are several tasks in making an RFC ready for publication that can 
be automated or assisted programmatically. The current production steps 
involve several programs to validate or manipulate the document content. 
These programs perform tasks like verifying conformance criteria, 
identifying duplicate words, locating dangling references, and checking 
spelling. The RFC Editor wishes to unify and streamline this processing 
as the effort shifts to producing documents in the upcoming xml2rfc v3 
format. This project will create a command-line program that can be used 
to incrementally process an xml2rfc v3 formatted document towards being 
publication ready.

Detailed Description

The application will help the RFC Editor:
. Verify that the document is well-formed per the definition of the 
xml2rfc v3 grammar. If the document is not well-formed, identify the 
places where change is needed.
. Verify, to the extent possible, that the document satisfies the 
style-guide requirements. For instance, verify that the document 
provides at least one author, and for each author, verify the name 
satisfies the style-guide requirements as modified by 
draft-flanagan-nonascii, and that each author section includes an email 
address. (TBD -- this should be replaced with a series of specific 
requirements)
. Identify use of non-ascii UTF-8 and ensure such uses are within the 
guidelines specified in draft-flanagan-nonascii.

  *

    Identify and optionally remove duplicate words

  *

    Identify and optionally correct misspelled words

  *

    Verify that imbedded XML stanzas are well formed

  *

    Verify that imbedded ABNF is complete and well formed
    The application will take an xml2rfc v3 formatted document and a set
    of command line arguments, and produce diagnostic output and, when
    appropriate, an output xml2rfc v3 formatted document. The operations
    must not modify the input file directly.
    It is not the intent to re-invent functionality that is already
    well-implemented. For example, we anticipate that this application
    will use aspell (either through it's command-line interface or by
    integrating its library) rather than implementing its own spell
    checker. Similarly, the application should integrate as much of the
    existing toolchain as is reasonable. Other candidate sources of
    functionality include

  *

    Idnits

  *

    xmllint

  *

    bap
    While the application is being developed primarily for the use of
    the RFC editor, it would also be useful to draft authors. While
    making the application accessible to the authors is not in scope for
    this project, any design choices should consider

making it easy to run the application as a web service, or on an 
individual author's computer.
The application must be usable both interactively, and in a batch mode. 
In batch mode, all decisions will assume a default input instead of 
requiring interaction.

Microsoft Word - rfclint-00.docx

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 20 May 2014 10:50:09 +0100

I have a few questions - in-line:
>
> RjS
>
> Overview
>
> There are several tasks in making an RFC ready for publication that
> can be automated or assisted programmatically. The current production
> steps involve several programs to validate or manipulate the document
> content. These programs perform tasks like verifying conformance
> criteria, identifying duplicate words, locating dangling references,
> and checking spelling. The RFC Editor wishes to unify and streamline
> this processing as the effort shifts to producing documents in the
> upcoming xml2rfc v3 format. This project will create a command-line
> program that can be used to incrementally process an xml2rfc v3
> formatted document towards being publication ready.
>
> Detailed Description
>
> draft-flanagan-nonascii, and that each author section includes an
> email address. (TBD -- this should be replaced with a series of
> specific requirements)
>

Is it better to say "satisfy the style guide requirements" or "satisfy
the style guide requirement in such a way as to use the proper v3
grammar"?  Or are we talking about just flagging where there might be
problems and leaving it to a human to modify the document as necessary? 

> guidelines specified in draft-flanagan-nonascii.
Note to self - clean up the web page so the latest version of the
non-ASCII guidance is consumable.

>     The application will take an xml2rfc v3 formatted document and a
>     set of command line arguments, and produce diagnostic output and,
>     when appropriate, an output xml2rfc v3 formatted document. The
>     operations must not modify the input file directly.
>     checker. Similarly, the application should integrate as much of
>     the existing toolchain as is reasonable. Other candidate sources
>     of functionality include
>
>  *
>
>     Idnits
>
>  *
>
>     xmllint
>
>  *
>
>     bap
>     making the application accessible to the authors is not in scope
>     for this project, any design choices should consider
>
> The application must be usable both interactively, and in a batch
> mode. In batch mode, all decisions will assume a default input instead
> of requiring interaction.
>

Same comments on explicitly mentioning documentation and training as
with textsubmission-converter.

-Heather

---

From: Robert Sparks <[email-masked]>
Date: Tue, 20 May 2014 07:19:51 -0500

> problems and leaving it to a human to modify the document as necessary?
The intent here is to list things that a human needs to look at and 
possibly change, similar to what idnits does now.
The tool would be building xml as it goes, but can report on missing 
required things, or content that it has converted that otherwise will 
not meet the style-guide requirements.
>>     well-implemented. For example, we anticipate that this
>>     application will use aspell (either through it's command-line
>>     interface or by integrating its library) rather than implementing
>>     its own spell checker. Similarly, the application should
>>     integrate as much of the existing toolchain as is reasonable.
>>     Other candidate sources of functionality include
>>
>>  *
>>
>>     Idnits
>>
>>  *
>>
>>     xmllint
>>
>>  *
>>
>>     bap
>> mode. In batch mode, all decisions will assume a default input 
>> instead of requiring interaction.
>>
>
> _______________________________________________
> TOOLS-DEVELOPMENT mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-development