Internet DRAFT - draft-hallambaker-rfctool

draft-hallambaker-rfctool







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:

   <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



Hallam-Baker               Expires 4 July 2020                  [Page 6]

Internet-Draft             RFCTool User Guide               January 2020


   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.




Hallam-Baker               Expires 4 July 2020                  [Page 7]

Internet-Draft             RFCTool User Guide               January 2020


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.



Hallam-Baker               Expires 4 July 2020                  [Page 8]

Internet-Draft             RFCTool User Guide               January 2020


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:



Hallam-Baker               Expires 4 July 2020                  [Page 9]

Internet-Draft             RFCTool User Guide               January 2020


7.1.  Authors


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,
              August 1982, <https://www.rfc-editor.org/rfc/rfc822>.











Hallam-Baker               Expires 4 July 2020                 [Page 10]