Network Working Group P. M. Hallam-Baker Internet-Draft 1 January 2020 Intended status: Informational Expires: 4 July 2020 RFCTool User Guide draft-hallambaker-rfctool-04 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. Copyright Notice Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Hallam-Baker Expires 4 July 2020 [Page 1] Internet-Draft RFCTool User Guide January 2020 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Automating the editing process . . . . . . . . . . . . . 3 2. Installing and Using RFCTool. . . . . . . . . . . . . . . . . 4 2.1. Installation . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Running RFCTool . . . . . . . . . . . . . . . . . . . . . 4 2.3. Converting files . . . . . . . . . . . . . . . . . . . . 5 2.4. Creating Templates . . . . . . . . . . . . . . . . . . . 5 2.5. Support for other standards organizations . . . . . . . . 6 3. Writing an RFCTool Document . . . . . . . . . . . . . . . . . 6 3.1. Document Metadata . . . . . . . . . . . . . . . . . . . . 6 3.2. References . . . . . . . . . . . . . . . . . . . . . . . 7 3.2.1. Citations . . . . . . . . . . . . . . . . . . . . . . 7 3.2.2. Internal . . . . . . . . . . . . . . . . . . . . . . 7 3.3. Including files . . . . . . . . . . . . . . . . . . . . . 7 3.3.1. Include . . . . . . . . . . . . . . . . . . . . . . . 7 3.3.2. Sourcecode . . . . . . . . . . . . . . . . . . . . . 7 3.3.3. Images . . . . . . . . . . . . . . . . . . . . . . . 8 4. Editing with Word . . . . . . . . . . . . . . . . . . . . . . 8 4.1. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2. Character Styles . . . . . . . . . . . . . . . . . . . . 8 4.3. Paragraph Styles . . . . . . . . . . . . . . . . . . . . 9 4.4. Tables . . . . . . . . . . . . . . . . . . . . . . . . . 9 5. Editing with Markdown . . . . . . . . . . . . . . . . . . . . 9 6. Markup Reference . . . . . . . . . . . . . . . . . . . . . . 9 7. Document data . . . . . . . . . . . . . . . . . . . . . . . . 9 7.1. Authors . . . . . . . . . . . . . . . . . . . . . . . . . 10 8. Formatting . . . . . . . . . . . . . . . . . . . . . . . . . 10 9. Processing Instructions . . . . . . . . . . . . . . . . . . . 10 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 11. Security Considerations . . . . . . . . . . . . . . . . . . . 10 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 13. Informative References . . . . . . . . . . . . . . . . . . . 10 1. Introduction RFCTool is a documentation tool for building specifications from multiple sources and multiple source formats. A specification built using RFCTool typically comprises: * A core document containing the bulk of the prose. * Source code * Diagrams * Examples generated from running code Hallam-Baker Expires 4 July 2020 [Page 2] Internet-Draft RFCTool User Guide January 2020 * Reference material generated from schemas 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: * Combining the source documents to publish the material in one or more of the publication formats. * To convert a core document from one source format to another. * The publication formats currently supported are TXT, HTML and XML2RFC. 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: Hallam-Baker Expires 4 July 2020 [Page 3] Internet-Draft RFCTool User Guide January 2020 * 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: * Windows (7, 8.1, 10) x64, ARM32 * Linux (various) x64, ARM64 * macOS (10.13, 10.14, 10.15) 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: Hallam-Baker Expires 4 July 2020 [Page 4] Internet-Draft RFCTool User Guide January 2020 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. Hallam-Baker Expires 4 July 2020 [Page 5] Internet-Draft RFCTool User Guide January 2020 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: