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]