Internet-Draft RFCTool User Guide January 2020
Hallam-Baker Expires 4 July 2020 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-hallambaker-rfctool
Published:
Intended Status:
Informational
Expires:
Author:
P. M. Hallam-Baker

RFCTool User Guide

Abstract

RFCTool is a documentation tool for building specifications from multiple sources and multiple source formats. Source formats currently supported are OOXML/Word, Markdown, XML2RFC and SVG. Publication formats supported are plaintext, HTML and XML2RFC. This document provides information on how to use RFCTool to generate Internet Drafts and RFCs.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 4 July 2020.

▲

Table of Contents

1. Introduction

RFCTool is a documentation tool for building specifications from multiple sources and multiple source formats. A specification built using RFCTool typically comprises:

Automating the process of building specifications allows the inconsistencies that inevitably occur in a manual process where a single change requires modification to multiple parts of the specification.

Multiple source formats are supported but some formats are more appropriate for certain tasks. While it is certainly possible to generate examples in OOXML (Word) format, Markdown is considerably better suited to the task. Contrawise, while Markdown is certainly sufficient for producing short specifications, attempting to produce a large specification of several hundred pages without the benefit of spelling and grammar checking is likely to be tiresome.

The following source formats are preferred:

Core document

OOXML(Word), Markdown or XML2RFC

Source code

Markdown or Verbatim source

Diagrams

SVG source

Examples

Markdown

Reference material generated from schemas

Markdown

Support for OOXML as a source format allows documents to be produced with practically any word processor released in the past decade.

The RFCTool supports two principal modes of use:

RFCTool is Open source (MIT License) and self-contained. It is not necessary to install Word to process OOXML documents using RFCTool.

1.1. Automating the editing process

RFCTool is designed to automate as much of the document production process as possible. In particular:

  • References to RFCs and Internet Drafts are automatically identified and resolved.
  • BCP14 normative text (MUST, SHOULD, MAY) is automatically recognized and tagged.
  • Document version numbers, dates, expiry times etc are automatically determined.
  • Boilerplate is inserted automatically.

Automation operations not currently supported but being considered include:

  • Strip SVG files to eliminate elements not permitted in the RFC format.
  • Allow equations to be specified using a TeX style mathematical notation.

2. Installing and Using RFCTool.

RFCTool is available as source code from the GITHub repository or as a standalone executable for any of the platforms supported by .NET Core 3.1:

RFCTool may be run on numerous other platforms by installing and configuring .NET Core 3.1 on that platform.

2.1. Installation

RFCTool is installed by simply placing the executable file in a directory that is in the user's shell executable discovery path.

The files are actually self-extracting ZIP files which unpack themselves the first time they are run.

2.2. Running RFCTool

The /about command returns the tool version and build information:

The /help command provides usage information for the RFCTool commands:

2.3. Converting files

A file is converted using RFCTool by specifying the file to be converted followed by the output formats to be generated:

The input format is inferred from the input file extension as follows:

.xml

XML2RFC format. The v2 and v3 formats are both supported.

.docx

OOXML (Word) document format as described in Section 4

.md

Markdown format as described in Section 5

The document publication formats may be selected as outputs using the following options:

/txt

HTML format

/html

HTML (Internet draft/RFC conventions)

/xml

XML2RFCv3 format

/auto

Produce txt, html and xml outputs using a file name automatically constructed from the identifier specified in the document.

The source document may be converted to other source formats using the following options:

/docx

OOXML (Word) format document.

/md

Markdown format.

The output file name may be specified explicitly (e.g. /html=file.html) and otherwise defaults to the input filename with the appropriate extension.

2.4. Creating Templates

The template command generates a template which may be used to get started with a new document. This is particularly useful for creating Word documents as all the template document is prepopulated with the styles recognized by the tool.

2.5. Support for other standards organizations

RFCTool could be modified to support other documentation standards (e.g. W3C) with little additional effort.

3. Writing an RFCTool Document

The quickest way to using RFCTool to create a new specification is use the template command to create a starting point in the desired source format.

If an existing draft is being revised, conversion mode may be used to create a Word or Markdown source for editing.

Note that due to subtle differences in the internal representations used in Markdown/OOXML and XML2RFC, the conversion process is not guaranteed to be lossless.

3.1. Document Metadata

Document metadata declarations may be made at any point in a document. It is usually most convenient to place this data at the start. The metadata declaration for this document is:

<title>RFCTool User Guide
<subtitle>RFCTool User Guide
<series>draft-hallambaker-rfctool
<status>informational
<stream>independent
<ipr>trust200902
<author>Phillip Hallam-Baker
    <surname>Hallam-Baker
    <initials>P. M.
    <firstname>Phillip
    <email>phill@hallambaker.com

The tag syntax is very loosely based on XML. It is not necessary to specify end tags in most cases but authors may do so if it makes them feel comfortable. The tag names are based on those defined in XML2RFCv3 with some additions.

A complete list of tags used in RFCTool is given in Section 6.

3.2. References

3.2.1. Citations

Citations in the text are specified using the <info/> and <norm/> tags. If the argument provided begins with the text 'RFC' or 'draft', it is treated as a reference to an RFC or Internet Draft and resolved automatically. Thus <info="RFC822"/> is automatically expanded as an informational reference to [RFC822].

Note that these tags must be closed.

If the option /cache=<<filename> is specified on the command line, it is read at the start of reference processing and used to resolve references if found. Otherwise, the references retrieved from the net are automatically appended to the file.

3.2.2. Internal

Paragraphs and headings may be declared as potential targets of internal references using the <anchor/> tag. The argument being the label to be used to identify the anchor.

References to document sections may be specified using the <xref/> tag. The argument being the target anchor label.

3.3. Including files

Material may be included from external files using the include, sourcecode and svgimage declarations.

3.3.1. Include

The include directive causes the specified text file to be read as input source. It is expected that the source format is Markdown but other source formats probably work.

3.3.2. Sourcecode

The sourcecode directive is planned to cause the specified file to be read as verbatim text and labelled with the specified programming language.

3.3.3. Images

The SVGimage directive currently causes the target file to be incorporated into the body of the output document as a data URI. This is not the intended final functionality.

4. Editing with Word

Office Open XML (ECMA-376) (OOXML) is an open standard for document markup format with ubiquitous support in word processing software. Introduced in Microsoft Office 2007, the format is notably supported by Google Docs and LibreOffice as a native document format.

RFCTool recognizes many OOXML paragraph and character styles and interprets them as XML2RFC markup instructions. This allows 95% or more of a typical specification to be written using the native capabilities of the word processor without the need to remember markup or metadata tags.

One peculiarity encountered in Word document format is that it is possible for the paragraph style catalog to have multiple entries with the same name presented to the user but these are interpreted differently internally. This typically results from attempts to cut and paste between documents. Should this glitch be encountered, only one set of tags is properly recognized.

< serves as an escape.

4.1. Metadata

For convenience, the document title and subtitle may be specified by marking the text with the Title and Subtitle styles respectively.

All other Metadata fields must be specified in paragraphs marked with the Meta style.

4.2. Character Styles

Text in bold, italic, superscript or subscript format in the source document is rendered in the same format in the output document.

Since XML2RFC format does not make use of underline text, this is used to specify the fixed space font rendering used for identifiers, etc.

BCP14 language (MUST/SHOULD/MAY) is automatically recognized and tagged. References to RFCs, Internet Drafts and certain other document series are automatically recognized and extracted.

4.3. Paragraph Styles

RFCTool uses named Word paragraph styles to specify block formatting. The formatting used to present the text in Word is ignored. Thus a paragraph in the style li will be represented as a bulleted list entry, ni as a numbered list entry and so on.

The paragraph style names recognized are:

Meta

Metadata entry (see above)

Title

Document title (see above)

Subtitle

Document short title (see above)

li

Bullet point list item

nli

Numbered list item

dt

Defined term

dd

Defined data

pre

Preformatted text

4.4. Tables

Word tables are automatically recognized and processed. Rowspan and colspan directives are not currently recognized. Nor are headers or footers.

5. Editing with Markdown

The Markdown input format is based on that used by GitHub.

At present, tables and some other features do not work as they are rendered internally to the XML2RFCv2 structures which are no longer used.

6. Markup Reference

7. Document data

The tool is intentionally lax in allowing specification of document data and metadata using the metadata tags specified in all versions of the xml schema plus additional tags defined for use with markdown.

The following tags are preferred:

8. Formatting

Cref - comment (Not currently implemented?)

Eref - external link (not added to references)

RelRef - reference to a specific anchor within a referenced doc.

Iref - term for the index

Xref - reference to an anchor in this document

9. Processing Instructions

RFCTool preserves the value of processing instructions when generating XML2RFC output but ignores them when producing output in HTML or TXT. It is the inalienable right of a user to have a table of contents, figures etc. This is not a choice that should be left to the author.

10. Acknowledgements

11. Security Considerations

12. IANA Considerations

This document contains no actions for IANA.

This section may be removed in the published version of this document.

13. Informative References

[RFC822]
Crocker, D., "STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES", STD 11, RFC 822, DOI 10.17487/RFC0822, , <https://www.rfc-editor.org/rfc/rfc822>.