The Cover PagesThe OASIS Cover Pages: The Online Resource for Markup Language Technologies
SEARCH | ABOUT | INDEX | NEWS | CORE STANDARDS | TECHNOLOGY REPORTS | EVENTS | LIBRARY
SEARCH
Advanced Search
ABOUT
Site Map
CP RSS Channel
Contact Us
Sponsoring CP
About Our Sponsors
NEWS
Cover Stories
Articles & Papers
Press Releases
CORE STANDARDS
XML
SGML
Schemas
XSL/XSLT/XPath
XLink
XML Query
CSS
SVG
TECHNOLOGY REPORTS
XML Applications
General Apps
Government Apps
Academic Apps
EVENTS
LIBRARY
Introductions
FAQs
Bibliography
Technology and Society
Semantics
Tech Topics
Software
Related Standards
Historic
Last modified: June 09, 2010
Specification Production: Software Automation Tools

Overview

Collection of references for software automation tools and related resources used by standards organizations in the authoring, editing, structural validation, publication rules checking, publishing, management, and maintenance of technical specifiations.

IETF (Internet Engineering Task Force)

[Provisional listing: IETF supplies a range of software tools to support the automated production and validation of Internet-Draft and RFC specifications. The current recommended path for specification production is XML source, processed using the xml2rfc software tools.]

  • RFC Editor: Support for editorial review of IETF documents. See:

  • ID Tracker. Search by file name, RFC number, Working Group, filtered by Document State, Responsible Area Director, Status, Document State, Document Sub-state, and Area Acronym. See also the State Diagram and explanation of specification development states.

  • IETF Workgroup Status Pages. The collection of status pages provides navigation interfaces for IETF specifications in development, including IETF Documents lookup (RFC number, draft name, URL — with regex) and Google search [Use Google to search drafts and RFCs], with listings for "New RFCs in the repository during the last 14 days" and "New Drafts during the last 72 hours". The listing of Working Groups in the left navigation bar includes use of a siglum to note new work: "WGs marked with an "*" (asterisk) has had at least one new draft made available during the last 5 days." Each Working Group's status page (for example, SIP) provides a listing of specifications in different stages of development. Each WG page also provides a Internet Draft dependency graph. For example: the graph for specifications produced by the IETF KEYPROV Working Group (2009-05-02 snapshot; see further below).

  • Upload tool: IETF Internet-Draft Submission Interface. This page is used to submit IETF Internet-Drafts to the Internet-Draft repository. The list of current Internet-Drafts can be accessed online. From the documentation: "The Upload screen is the first screen that a user will see when he or she starts the I-D submission process. A user can submit four different formats of an I-D, plain text, XML, PDF, and postscript, at the same time. Failure to submit a plain-text version will cause an error, and an error screen will be displayed... After a user uploads a plain-text version, or multiple versions of an I-D, the tool will parse the plain-text version, validate the I-D, and display the validation results with option(s) for next steps. The validation includes: checking for all IPR-related notices and I-D boilerplate described in Guidelines to Authors of Internet-Drafts; the required sections described in the I-D Check List; the version number; and the creation date. If the submission does not have any validation errors, then the user will be allowed to proceed with the automated posting process..."

  • "Writing I-Ds and RFCs Using XML (Revised)", by Marshall T. Rose. April 5, 2005 (or later). "This memo presents a technique for using XML (Extensible Markup Language) as a source format for documents in the IETF's Internet-Drafts (I-Ds) and Request for Comments (RFC) series. The memo is an upwards-compatible revision to RFC 2629. It describes a simple XML Document Type Definition (DTD) that is powerful enough to handle the simple formatting requirements of RFC-like documents whilst allowing for meaningful markup of descriptive qualities. It also describes software that processes XML source files, including a tool that produces documents conforming to RFC 2223, HTML format, and so on..." See also RFC 2629, HTML and RFC 2629, XML.

  • xml2rfc. A package to convert memos written in XML to the RFC format. There is an online Conversion tool ("Convert Your XML Source") for users who prefer not to install the xml2rfc software: one nominates an XML file on the local file system and generates text, HTML, nroff, etc. See the README file.

    Update note 2009-02: A handy little tool, xml2rfc, will allow you to take your XML source (using the format defined in RFC 2629 ["Writing I-Ds and RFCs using XML"] and its unofficial successor Writing I-Ds and RFCs using XML (revised)) and see how the results look like in the original ASCII look-and-feel or the new modern HTML rendition of that look-and-feel. An experimental [v1.34pre3 or later] "Bleeding-edge Development Version" was created as a preliminary implementation to support the IETF Trust language of November 2008 and February 2009. As announced: this is a development version and its use should be considered experimental. Here's the feature list: (1) The ipr attribute of the rfc element now accepts seven additional values: trust200811, noModificationTrust200811, noDerivativesTrust200811 trust200902, noModificationTrust200902, noDerivativesTrust200902, and pre5378Trust200902. (2) Use of the appendix element is now deprecated (no longer in the DTD); use the section element instead. See the updated README file. Additional information: xml2rfc Frequently Asked Questions and The xml2rfc List Archives for 'xml2rfc': Mailing list for software packages implementing RFC 2629.

  • Transforming RFC2629-formatted XML Through XSLT. By Julian F. Reschke (greenbytes). April 2009 or later. This document describes a set of XSLT transformations that can be used to transform RFC2629-compliant XML to various output formats, such as HTML, XHTML, PDF, CHM. On RFC 2629, see: "Writing I-Ds and RFCs using XML (revised)." The main topics are: compliance to the xml2rfc XML element set (Section 2); support for xml2rfc processing instructions (Section 3); the names of anchor elements generated in HTML and PDF output (Section 4); various XSLT engines that can be used (Section 5); outputting HTML (Section 6) and XHTML (Section 7); outputting CHM (Compiled Microsoft Help, Section 8); outputting PDF (Section 9); extensions to the xml2rfc vocabulary (Section 10); various utilities (Section 11). The full distribution is available at online (ZIP package).

  • Google Code: xml2rfc-xxe. xml2rfc-format editing configuration for XMLMind XML Editor. See the Google Groups list 'xml2rfc-xxe users'. Summary: " This configuration works with both Personal and Professional editions. Some features (e.g., format using XSLT) only work with Professional edition. This is a WYSIKN (What You See Is Kinda Neat) addon for the very configurable XMLMind XML Editor ('xxe'). The personal version of xxe is free and very capable. It's also written in java, so one addon works on many platforms (I've tested it on MacOS, Windows 2000 and FreeBSD). The addon is capable of graphical editing of sections, anchors, lists, cross-references, etc. and allows word processor-like behavior of "enter" to create a new paragraph or list item. It can use a locally-installed xml2rfc to format the document for preview or conversion, or use xxe's built-in XSL transform or submit the document to the xml.resource.org web form. It provides easy hooks to validate the references to other IETF documents in your document to make sure they're up to date..."

  • xml2rfc validator. [xml2rfc Validator altername URI.] A Validator for XML input to xml2rfc. xml2rfc generates (un)paginated I-D text format, HTML, and nroff from XML source. "This validator does up to three (3) passes on the uploaded XML document: [1] Expand <?rfc include=''?> processing instructions, if present; note that this step can change line numbers by reformatting the XML. [2] Check, using xmllint, against the RFC2629(bis) DTD (currently using the DTD released with xml2rfc 1.29, April 6, 2005, modified to include all the entities that 1.29 supports). This checks both that the XML is well-formed and that it matches the DTD. Any external entities are loaded during this phase. [3] Check, using a funky XSL transform, additional issues that just checking against the DTD can't, e.g., [a] Require anchors on references if using symrefs or sortrefs PIs; [b] Warn that figure inside t is deprecated; [c] Long titles need short abbrev attributes; [d] No duplicate anchors; [e] FYI on unreferenced anchors — error when it's a reference; [f] FYI when plain text contains something that looks like an anchor; [g] Warn about multiple <city>, <region>, <code> or <country>; [h] Note that 'Internet Draft' or 'I-D' in seriesInfo should be 'Internet-Draft'; [i] Require IPR or number on <rfc> element unless <?rfc private?>; [j] Warn that iprExtract is meaningless unless the ipr declared is restrictive; [k] Note that historic documents don't get a seriesNo; [l] Note that pre-3978 IPR will not be accepted after 6 May 2005; [m] <?rfc strict="yes"?> items, FYI unless the strict PI is in the document, for No more than 5 authors, No references in abstract, Missing abstract."

  • [June 14, 2007] Converting Annotated RELAX NG Schemas for Use in I-Ds or RFCs. Edited by Ladislav Lhotka (CESNET, z.s.p.o.). IETF Network Working Group. Internet Draft 'draft-lhotka-relaxng-to-rfc-00'. June 14, 2007, expires December 16, 2007. Intended status: Informational. source; see the I-D Tracker. This memo presents a method for annotating XML schemas expressed in the RELAX NG language and transforming them to a form suitable for direct inclusion in an XML source of an IETF Internet Draft (I-D) or Request for Comments (RFC). The Extensible Stylesheet Language Transformations (XSLT) stylesheet performing the transformation also automatically generates cross-references between RELAX NG pattern definitions and their references. In the context of IETF activities, the most natural way of publishing and/or standardizing an XML schema is to make it a part of an Internet Draft or RFC that describes the application the schema is used for. However, including an annotated schema directly in an I-D or RFC is not optimal since the annotations wrapped in XML elements are clumsy and hard to read. XML comments are better in this respect, but still the best option for rendering the annotations is to convert them into standard paragraphs of the I-D or RFC. The strategy presented here for annotating RELAX NG schemas and transforming them for inclusion into XML source follows methods documented in 'Writing I-Ds and RFCs using XML' (RFC 2629). The method presented in this memo is similar in spirit to 'literate programming in XML', which may be applied to arbitrary XML documents, for example XSLT stylesheets. However, its main benefit, namely that it allows for arbitrary modularization and reordering of the original document, just duplicates the intrinsic functionality of RELAX NG based on the 'define' and 'ref' elements. Therefore, the specialized XSLT stylesheet rng2rfc.xsl is considerably simpler and yet achieves better results..." Related: (1) XML and Literate Programming; (2) L Lhotka, "Annotating XML Schemas with reStructuredText" (Technical Report 3/2006, Praha: CESNET, June 2006).

  • Requirements for IETF Technical Publication Service. By Allison Mankin and Stephen Hayes. IETF Network Working Group. May 8, 2006. Expires November 8, 2006. 23 pages. In May 2006, the IESG announced that a request had been received to consider the I-D as an Informational RFC; comments were solicited through 2006-06-06. "The IETF technical publisher is responsible for the final steps in the production of the published technical specifications. This document sets forth requirements on the duties of the IETF technical publisher and how it interacts with the IETF in the production of those publications... Standards development organizations all have technical publication as part of their process. However, the boundaries between what is done by the technical committees and the technical publisher vary. The following are potential tasks of a technical publisher. The following list was derived after analyzing the technical publication policies of the IETF and other standards development organizations. For each of these tasks we discuss its relevance to IETF and how it is realized within the IETF processes. Based upon this information we derive requirements on the IETF technical editor: 1. Pre-approval review or editing; 2. Preliminary specification availability; 3. Post-approval editorial cleanup; 4. Validation of references; 5. Validation of formal languages; 6. Insertion of parameter values; 7. Post approval, pre-publication corrections; 8. Allocation of permanent stable identifiers; 9. Document format conversions; 10.Language translation; 11.Publication status tracking; 12.Expedited handling; 13.Exception handling; 14.Notification of publication; 15.Post-publication corrections (errata); 16.Indexing: maintenance of the catalog; 17.Access to published documents; 18.Maintenance of a vocabulary document; 19.Providing publication statistics and status reports; 20.Process and document evolution; 21.Tutorial and help services..."

  • A Not So Wild Sheep Chase: IETF Definition of Shepherding. Edited by A. Mankin. Informational I-D. February 2004. Produced by members of the IESG Process and Tools (PROTO) Team. Source .txt. "This draft looks at IETF document shepherding. Currently [2004] this is done largely by the Area Directors, though good working group chairs will recognize tasks they already perform here... The basic concept of document shepherding is for a a single person (an AD currently) to take responsibility for a document from the time the WG Chair(s) requests the IESG to publish it to the time that it is given final edits by the RFC Editor. The motivation is for the shepherd to provide needed coordination. It is easy to lose important information or cause delays without the shepherd's coordination... The draft attempts to define current AD shepherding in some specificity, but in a manner so that the definition can be turned into a guide for WG Chair shepherding, once WG Chairs have good support and facilities for shepherding efforts. To this end, the AD work is separated into its components of shepherding, IESG review, and approval steps... The PROTO Team is working on an Internet-Draft that defines document shepherding. One purpose of this document will be to make a clear distinction between shepherding tasks and approval tasks, both of which are currently handled by the responsible AD during the later stages of our document handling procedures..."

  • "Document Shepherding from Working Group Last Call to Publication." Edited by Henrik Levkowetz, David Meyer, Lars Eggert, and Allison Mankin. Reference: IETF Network Working Group, Informational Request for Comments #4858. May 2007. Produced by members of the IESG Process and Tools (PROTO) Team in an an IESG-driven activity focused on improving the work flow (e.g. speed) of approval of documents, and the tools that support this work flow. See the DataTracker entry. ID-Tracker. The document references formal grammar QA, including XML. Does the Document Shepherd have concerns that the document needs more review from a particular or broader perspective, e.g., security, operational complexity, someone familiar with AAA, internationalization, or XML (IETF XML Directorate)... Document Shepherd should personally verify that the document satisfies all ID nits: see Checklist for Internet-Drafts (IDs) Submitted for RFC Publication and Idnits Tool... Document Shepherd should verify that sections of the document that are written in a formal language, such as XML code, BNF rules, MIB definitions, etc., validate correctly in an automated checker... Document Shepherd ensures that the IANA process completes, checks that the registry is correct and that the IANA Matrix is complete and consistent...

  • RFC Tools Overview. Henrik Levkowetz.

  • IETF Tools Team. The purpose of the IETF Tools Team is "to provide IETF feedback and guidance during the development of software tools to support various parts of IETF activities." The group was chartered to supply requirements and prototypes for resources like: publication of IETF meta-information; components needed by multiple tools; Web interface for WG milestone changes; WG Meeting scheduler; WG / Draft Status Pages; Notification services; HTML-ized WG Agendas; Publication request tool; Additional WG Page components; Provide the WG tools also to BOFs/Proposed WGs. I-D Tracker extended for use by WG Chairs. The IETF Tools Pages maintained by the IETF Tools Team are designed to help the IETF community by (1) making it easy to find existing tools; (2) providing means of feedback on existing and new tools — wiki and mailing list; (3) providing information on new and updated tools. The IETF Tools Team Members [August 2005] were: Alex Rousskov, Andrew Sullivan, Bill Fenner, Donald Eastlake, Henrik Levkowetz (Chair), Larry Masinter, and Stanislav Shalunov. References:

    • IETF Tools Team Charter Page [cache]
    • All IETF Tools List. Diff tools, Verification (ABNF parser in Perl, ABNF parsing web service, ABNF to Regexp converter, ABNF Parser Generator), I-D Tracker, Henrik Levkowetz' I-D Nits tool, Authoring tools, Draft Dependency Vizualisation, etc.
    • Prototype Workgroup Status Pages. "Drafts belonging to the following working groups are available here, together with related information such as IETF ID-tracker status, RFC-editor status, etc. These pages are updated regularly with new information from repositories, mailing lists, and other online information..."
    • XML (XHTML) version of WG agenda

  • IETF Tools-discuss. A mailing list for announcement and discussion of IETF related tools, with email tools-discuss archive. Post to tools-discuss@ietf.org. An initial test message was sent to this list on September 03, 2004.

  • IETF Tools Wiki. As of August 2005, included pages for (1) ToolSuggestions - suggest an existing or new tool for IETF toolset; (2) ToolPrototypeComments; (3) ToolPriorityList; (4) ProposedCharterUpdate; (5) ToolsStatusIETF-63.

  • IETF Tools Team Status. By Henrik Levkowetz. Presented at the IETF-63 plenary. August 3, 2005. "The IETF Tools Team activity was initiated by Harald Alvestrand and Allison some time before IETF-60. The team charter and the members were presented at IETF-60; it's an experimental activity, answering to the General Area Director..."

  • Checklist for Internet-Drafts (IDs) Submitted for RFC Publication. Maintained by Bert Wijnen (Lucent Technologies) for the IESG. ID-Checklist Revision 1.3 was published June 07, 2005. July 04, 2008 cache copy. "This memo defines a list of often called 'ID-NITS' that need to be checked before an Internet-Draft will be accepted for IESG consideration. The intent is that WG chairs check an I-D for any nits before submitting a request-for-publication, so that is before AD-review." See the news story "IETF Releases QA Checklist Document for Specification Production Using XML."

  • idnits. "'idnits' looks for violations of Section 2.1 and 2.2 of the requirements listed on Checklist for Internet-Drafts (IDs)... idnits works on Linux, OS-X, Windows under Cygwin, on *BSD and may work on Solaris. Testing on *BSD and Solaris has been minimal, though. To install, simply download the script, place it in your path and make it executable. idnits uses awk and sh internally..." As of June 2005, there was an online Idnits web form. See PyHt, which "reads a HTML file with embedded XML processing commands calling for a processor 'python', and passes the HTML straight through, while the python instructions are passed to the python interpreter..."

  • Requirements for an IETF Draft Submission Toolset. Edited by Alex Rousskov (The Measurement Factory). IETF Network Working Group, Informational Request for Comments, #4228. December 2005. With credit to Marshall Rose for his xml2rfc tool. "This document specifies requirements for an IETF toolset to facilitate Internet-Draft submission, validation, and posting... Current Internet-Draft submission and posting mechanisms hinder efficient and timely communication while creating an unnecessary load on the IETF Secretariat. The IETF Tools team recommends formalization and automation of the current mechanisms. This document contains specific automation requirements."

  • "Requirements for an IETF Draft Submission Toolset." By Alex Rousskov (The Measurement Factory). Internet-Draft: 'draft-ietf-tools-draft-submission-09'. IETF Tools Team. May 12, 2005, expires November 13, 2005. Versions: see datatracker. This document specifies requirements for an IETF toolset to facilitate Internet-Draft submission, validation, and posting. The IETF Tools team recommends formalization and automation of the current mechanisms... The IETF Secretariat and many IETF participants have long been proponents of automation; this document attempts to reflect their known needs and wishes, as interpreted by the Tools team. Currently deals with draft format as any draft source or presentation format, including original and preprocessed XML, original or generated plain text as well as PDF, PostScript, and HTML formats... With experience, the rules may be simplified so that, for example, only submissions containing nothing but XML or plain text sources can be posted without Secretariat involvement and all other submissions require manual actions to match formats or extract meta-data..."

  • rfcmarkup is a a cgi-bin script which reads a document in text format, typically an RFC or Internet-Draft, and produces HTML output with the same formatting, but with HTML links to pages, sections, references, RFCs and drafts. The script is written in Python, so the HTTP server on which you run it must have Python installed. You can download Python from www.python.org. This [version 1.16] script has been verified to work with Python 1.5.2 and Python 2.2.2. It may be called by either http POST or GET...

  • rfcdiff (Rfcdiff Web Services) takes two RFCs or Internet-Drafts in text form as input, and produces output (HTML is the default) which indicates the differences found in one of various forms, controlled by the designated options... In all cases, page headers and page footers are stripped before looking for changes. Output formats: (1) side-by-side HTML diff; (2) HTML wdiff output in a text terminal; (3) a text file with changebars in the left margin; (4) a simple unified diff output. One example. You can also use this web-service with an URL query-string of the form http://tools.ietf.org//rfcdiff?url1=http-url-to-doc-1&url2=http-url-to-doc-2 which makes it possible to send around links to diffs between document versions withouth actually generating the diff yourself, as long as the two document versions are available by HTTP (for example: http://tools.ietf.org/rfcdiff?url1=http://tools.ietf.org/id/draft-ietf-atompub-format-10.txt& url2=http://tools.ietf.org/id/draft-ietf-atompub-format-11.txt.

  • "Version 2.0 Microsoft Word Template for Creating Internet Drafts and RFCs." By Joe Touch (USC/ISI). IETF Network Working Group. July 1, 2005. Reference: 'draft-touch-msword-template-v2.0-03.txt'. "This document describes the properties and use of a revised Microsoft Word template (.dot) for writing Internet Drafts and RFCs. It updates the initial template described in RFC 3285 to more fully support Word's outline modes and to be easier to use. This template can be direct-printed and direct-viewed, where either is line-for-line identical with RFC Editor-compliant ASCII output. This version is intended as an update to RFC3285." See related ISI software resources.

  • Bruce Lilly IETF Software and Tools. troff/nroff macros for Internet-Draft/RFC formatting, RFC and Internet-Draft reference preprocessors, and ABNF formatter ... works with dformat, chem, grap, eqn, tbl, pic to generate formatted plain text, postscript, PDF, and HTML from easily-edited source. See: (1) Tools for formatting Internet-Drafts and RFCs; (2) IDIDRFCRFC Files (The Indispensable, Detailed Internet-Draft/RFC Reviewer's Flaw Checklist — IDIDRFCRFC); (3) mparse, open source library for parsing, validating, and generating Internet messages, in accordance with RFC 822, RFC 2822, the MIME RFCs, and extensions..."

  • Writing Internet-Drafts and Requests For Comments using troff and nroff." By Bruce Lilly.

  • doublespace "is a filter which fixes up the intra-sentence spacing so as to fulfil this paragraph in the RFC Editor's Instructions to Authors Section 3.1(7)... You should run doublespace on your .XML file, rather than on the .txt file, so that the final formatting (line lengths etc.) will be correct..."

  • IETF Draft Dependencies. See the online interactive "Draft Dependency Tool". These dependency relationships are automatically extracted using heuristics that look for strings starting with 'draft-' or 'rfc'. This notably means that references to I-Ds by title only, as is relatively common, are not in this database..." See example for KEYPROV. See also the collection of PDF documents with graphs for visualization. [older reference - status?]

  • Internet-Draft Repositories and Lookup Tools:

    • Internet-Drafts Database Interface. Provides draft title, status, state, intended RFC category, RFC number, related documents, abstract, author names and email addresses.
    • IETF Draft Tracker. The Internet-Drafts Tracker provides draft name, version, status, state, shepherding AD name, modification date, WG name, and IESG discussion details.
    • Prototype Workgroup Status Pages. Lists the IETF Working Groups in descending alphabetical order (but sortable). Clicking on the name of a Working Group gets a Working Group Status Page with names of Chairs, links to draft pages, draft dependency graph documents, IETF ID-tracker status, RFC-editor status, etc. From Henrik Levkowetz, based upon PyHt.
    • Potaroo Internet Drafts. RFC Index and ID Index. The repository provides draft name, date, author names, WG name, abstract. It includes expired drafts.

  • RFC 2629 XSLT Package [rfc2629.xslt package]. By Julian Reschke. Authoring tool. "An XSLT stylesheet for conversion from RFC2629-conforming format to HTML. The rfc2629.xslt package also supports conversion to PDF (via XSL-FO). There is a full distribution ZIP file, containing all scripts and documentation. alt URL

  • "Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols." By Scott Hollenbeck (VeriSign, Inc), Marshall T. Rose (Dover Beach Consulting, Inc), and Larry Masinter (Adobe Systems Incorporated). IETF Network Working Group. Request for Comments: 3470. Best Current Practice (BCP): #70. January 2003. There are a wide variety of Internet protocols being developed; many have need for a representation for structured data relevant to their application. There has been much interest in the use of XML as a representation method. This document describes basic XML concepts, analyzes various alternatives in the use of XML, and provides guidelines for the use of XML within IETF standards-track protocols. It recommends, as policy, what specifications for Internet protocols — and, in particular, IETF standards track protocol documents — should include as normative language within them... Many Internet protocol designers are considering using XML and XML fragments within the context of existing and new Internet protocols. This document is intended as a guide to XML usage and as IETF policy for standards track documents. Experienced XML practitioners will likely already be familiar with the background material here, but the guidelines are intended to be appropriate for those readers as well..." [cache]

  • [January 09, 2008] "Using XML in Internet Protocols." By Tim Bray (Distinguished Engineer, Director of Web Technologies, Sun Microsystems). 39 tutorial slides. These slides were provided as part of the IETF 70 Meeting Materials (Training Materials), and were used in the NETCONF Working Group session at this 70th IETF Meeting in Vancouver, BC, Canada. The slides also reference RFC #3470 (Scott Hollenbeck/Marshall T. Rose/Larry Masinter) "Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols." "Tutorial Agenda: Should you use XML? Should you invent a new XML language? If you're inventing a new XML language, how do you maximize your chances of success? Other options include: Hardwired binary, ASN.1, Plain text, and JSON. Use XML if: (a) Your data is document-flavored; (b) You're worried about i18n; (c) You're worried about extensibility; (d) You're worried about reusability. XML Schema Language Options include DTD, XSD (W3C XML Schemas), RelaxNG, and Schematron [slides are provided for each]. As to XML Extensibility, Three Options: No changes; 'Must-Understand' policy (e.g., as in SOAP), and 'Must-Ignore' policy (e.g., as in Atom)..." [cache, MD5: 87d10472346284b533d890066e353e0f, 299054 bytes]

  • "Requirements for Providing Information on IETF Internet-Drafts." By Alex Rousskov (The Measurement Factory). Reference: IETF Tools Team. Internet Draft 'draft-ietf-tools-draft-info-01'. Date: February 20, 2005. HTML. "Public Internet-Drafts are primary means of structured communication within IETF. The information that IETF currently provides about any given draft is decentralized and often insufficient to facilitate on-going draft review and use by IETFers and third parties. The IETF Tools team recommends creation of a single, authoritative, and comprehensive IETF source for draft information. This document specifies what information IETF should provide about an IETF Internet-Draft. Information requirements cover submitted, posted, published, expired, and other personal or Working Group drafts..." [perhaps here]

  • "Requirements for Document Notification Service." By Stanislav Shalunov (Internet2). IETF Network Working Group. Internet Draft: 'draft-ietf-tools-notification-03.txt'. January 31, 2005, expires August 4, 2005. HTML. "The output of the IETF consists of documents. The IETF process is largely related to changing the status of documents. Active participation in the work of the IETF often consists of writing or editing documents or providing input to the process of changing the documents' status. Passive participation often consists of reading documents and observing the changes of their status. This document describes the requirements for an automated service that helps the IETF participants to learn about the existence and follow the changes of status of any particular document..." [perhaps here]

OASIS (Organization for the Advancement of Structured Information Standards)

OASIS provides specification templates and usage guides for writing specifications; a draft document on naming practices is also available.

W3C (World Wide Web Consortium)

W3C provides a wide range of online and downloadable software tools which automate the production of technical specifications and manage their presentation to the public: authoring, markup validation, publication rules checking, publishing, feedback tracking, etc. Use of the tools in specification design and authoring is documented in a number of specifications in the W3C QA Framework. Tools examples:

  • W3C Editors' Home Page. This page gathers resources that can help editors do their job: documentation, tools, tutorials, etc. See especially the list of software tools.

  • W3C Specification Matrix, produced using XML, RDF, XSLT, and XHTML. The Matrix of W3C specifications displays a table for deliverables at least at Last Call stage, except if the team is working on a Test Suite at Working Draft stage. The default view is sorted by title; a view sorted by status is also available. For each specification in the Matrix, the table indicates the URI (URL), the specification maturity level, a validator icon if the specification has a validator, a W3C Test suite icon if the specification has a Test Suite located on the W3C server, a generic/remote Test Suite icon if the specification has such a Test Suite, and a Conformance section icon if the specification has a conformance section. Related documents are displayed (with hyperlinks) if available: Errata, Implementation Report, Primer, Requirements Document, Use Cases, Accessibility Support Document, Authoring Techniques Document, etc. The displayed XHTML output has been produced with an XSL stylesheet; the Matrix represents an XHTML ouput of an RDF maintained list of QA related information merged with the RDF version of the TR page. Production details are described in the Manual and in the document "Why the QA Matrix in RDF?"

  • W3C Specification Matrix Manual. Manual to Edit the QA Matrix. The W3C Specification Matrix "is maintained by adding any new information received on a given technical report to an existing base of knowledge formatted in Notation3 (N3), an easy-to-write syntax for RDF. This knowledge base uses a specially crafted RDF Schema. This knowledge base is then merged with the base of knowledge about W3C Technical Reports, maintained by the Webmaster, to generate an RDF view of the Matrix, which is then transformed into its main XHTML view through XSLT.

  • W3C Quality Assurance Activity. The W3C Quality Assurance Activity "improves the quality of W3C specifications through the use of guidelines and reviews of specifications at critical stages of their development. QA promotes wide deployment and proper implementation of these specifications through articles, tutorials, and validation services. QA communicates the value of test suites and helps Working Groups produce quality test suites. And QA also designs effective processes that, if followed, will help groups achieve these goals." References:

  • The XML Spec Schema and Stylesheets. By Norman Walsh. This document describes the various releases of the XML Spec schema and stylesheets. New XML Spec schema and stylesheets were announced October 13, 2005: "tweaked the DTD to make the content model of latestloc "loc+" instead of mixed content; supporting multiple loc elements is for the pubrules changes that allow multiple latest locs; the stylesheets also support multiple loc elements." Version 2.10 of the XML Spec schema, in all three flavors; version 1.13 of the HTML and XHTML stylesheets; version 1.10 of the FO stylesheets.

    Version 2.9 of the XML Spec schema was released May 06, 2005 in all three flavors; version 1.12 of the HTML and XHTML stylesheets were also released. The 2.9 version supports the new W3C document type review for identifying 'Editor's Drafts'. Version 2.9 of the XML Spec schema is available as a RELAX NG Grammar .rng (or in the compact syntax, .rnc), as a W3C XML Schema, or as an XML DTD.

    The HTML stylesheets produce HTML; correspondingly, the XHTML stylesheets produce XHTML. For best results, you may still need to run the results through tidy. Using tidy with indentation turned off general saves a little space on the servers. The HTML Version 1.12, released May 06, 2005, supports publishing 'Editor's Drafts'. If either the w3c-doctype attribute on spec is review or the w3c-doctype element in the header contains the phrase 'Editor', the resulting draft will be styled according to the guidelines for group-internal drafts. This version also produces documents with an encoding of utf-8, which is now the default for documents published in W3C TR space.

    Also available: diffspec.xsl, a stylesheet that produces 'color-coded' HTML from diff markup in the XML document and slices.xsl (plus slices-common.xsl), a stylesheet that produces 'chunked' HTML specifications..." Compare: W3C HTML Diff Tools.

    The XML Spec Stylesheets are XSLT stylesheets for converting instances of the XML Spec DTD into HTML, XHTML, or PDF. The XSL Formatting Objects stylesheets produce FO documents that can be transformed into PDF and other print formats with an appropriate XSL FO processor; see the XSL page for more details..."

    "Some XSLT Hacks for xmlspec Documents." Posted October 24, 2007 by Thomas Roessler. See bibsort.xsl to sort bibliography entries in an xmlspec document, and fix-style.xsl to do several other things, like: make anchor names visible upon hover, adding navigation links, mark broken specprod references in nasty red, turn headings into links to themselves to make copy and paste of anchors easier, different markup and formatting for <note> elements, etc.

  • W3C XML Specification DTD ('xmlspec'). The XML specification DTD [PUBLIC "-//W3C//DTD Specification V2.9//EN"] at http://www.w3.org/2002/xmlspec/dtd/2.9/xmlspec.dtd is designed for use with W3C specifications and other technical reports; it is based in part on the TEI Lite and Sweb DTDs. Use of XMLSpec is reported to save hours of tedious work fixing pubrules issues. References:

  • 'HTML Diff' Wiki Reference Page, and the online Web tool to Create Diff Between HTML Pages. See the sample output and 2007-10-03 posting from Dominique Hazäel-Massieux. Example output:

  • W3C spec-prod. The W3C spec-prod effort focuses on the design and creation of facilities for producing and managing W3C specifications. There is an associated 'spec-prod@w3.org' public mailing list and a CVS spec-prod development area providing a collection of doctypes and stylesheets that are used (by some W3C WGs) to produce working drafts and the various stages of recommendations.

  • W3C TR Automation Project. The document "Automating the Publication of Technical Reports" describes the use of Semantic Web tools and technologies which has allowed W3C to streamline the publication paper trail of W3C Technical Reports, to maintain an RDF-formalized index of these specifications, and to create a number of tools using these newly available data. The goal is to "automate the process behind the publication of W3C Technical Reports."

    Maintenance of the TR Page: "Previously done by hand, the process of updating the list of Technical Reports (referred as the TR page) is now entirely automated; this means that the system is able to extract all the necessary information from a given Technical Report and to process it as described by the W3C Process to produce an updated version of the TR page. Using an appropriate style sheet, various views of the page can be generated: View by Status, View by Title, View by Author/Editor, View by Date, View by Activity, Configurable Views.

    The TR Automation data is used, sometimes now with other tools/data, to support generation of several other resources:

  • W3C Online Pubrules Checker. The Pubrules Checker depends upon formal features of XHTML document source, RDF's XML serialization, XSLT transformations, and well-defined RDF Schemas to perform automatic checking of Technical Reports. In order to be published as a W3C Technical Report, a document has to comply with a set of rules called pubrules [W3C Publication Rules]. For example: (1) the Status of This Document section must be novel and complete, according to requirements specific to each maturity level; (2) all XML namespaces follow established conventions; (3) there are no broken links, internal to the document or otherwise; (4) normative versions are clearly identified; (5) format requirements are satisfied; (6) accessibility requirements are satisfied; (7) the document head is consistent with W3C conventions. These rules are formal enough that most of them can be checked automatically, which has permitted W3C to build the pubrules checker tool. The publication rules also support programatic extraction of enough specific metadata from candidate documents to identify the properties needed to update the W3C TR page." A collection of XSLT stylesheets, together with RDF Schemas and an RDF/XML formatter, is used to create the common XML/RDF database used by several tools in the W3C TR Automation suite.

    The Online Pubrules Checker is basically an XSLT style sheet: one can use it directly on a local computer (without going through the Web interface), or one may use the online Web tool, supplying the URI of the document. The pubrules checker will check the compliance of technical reports against the publication rules. Optionally, one may recursively check the HTML and CSS validity of the dependent documents, which is useful for compound documents."

  • ReSpec.js — W3C Specification Writing Tool. "A tool that helps with specification editing primarily within a W3C context." Source code [2010-05] in the W3C public mercurial repositories, with Atom feed. Introduced in the August 6, 2009 posting Editing specifications with ReSpec.js, by Robin Berjon. See also the discussion list thread from 2010-05 (ReSpec 2 repository as a work in progress).

    ReSpec details: "ReSpec is a Javascript based tool that unobtrusively allows editors to write a specification focusing on the actual features and correctness, while needing to pay as little attention as possible to issues pertaining to styling, referential integrity, and [other rules]... The general structure of a ReSpec document is that of an HTML5 [HTML5] document, with a few extra conventions so that the ReSpec processor may infer additional semantics... The fundamental ideas that underlie ReSpec.js are: (1) You just edit HTML, with some extra convention but nothing extra. All the decoration is performed by the script, informed by some very basic configuration; a simple template can help you get started. (2) You never have to run a tool outside of your editor and browser. While the specification is being developed that's all that's needed. When a snapshot is needed for publication, all it takes is saving the generated DOM to a file; the script is very careful to cleanly remove itself and its dependencies so that you should normally get a document that's PubRules compliant. (3) DRY (don't repeat yourself) — you shouldn't have to repeat anything within a specification, or across specifications, apart from the template. For instance, marking RFC 2119 keywords is automatic, the WebIDL support makes it possible to specify both the WebIDL and its documentation in the same place without repeating a single part of it, etc."

  • "W3C Manual of Style: Help for Editors and Authors of W3C Technical Reports." Edited by Susan Lesch (W3C). Written for editors and authors of W3C technical reports, this document assumes that the reader has mastered publishing on the W3C Web site, and is familiar with the Style Guide for Online Hypertext. It is a companion to the required W3C Publication Rules, called "pubrules" for short... Chapter 2 covers validation. Chapters 3 and 4 cover accessibility and internationalization. Chapter 5 describes parts of a W3C technical report. Chapters 6, 7, and 8 cover errata, references and revisions. Chapter 9 introduces XMLspec and XSLT. Chapter 10 addresses RFC 2119 key words. Chapter 11 presents editorial guidelines, and, finally, chapter 12 documents commonly misspelled terms.

  • Proposed W3C Specification Conventions. Edited by Doug Schepers. See the February 11, 2010 posting and discussion thread on the 'spec-prod' list. The document outlines "proposed markup and style conventions for W3C Technical Reports, including Working Group Notes, Recommendation-Track specifications, and other applicable documents. This is a compilation of best practices exercised by some W3C working groups. The aim in standardizing these conventions is to promote more precise specification practices, to make it easier for authors, implementers, and reviewers to read and understand specifications, and to more easily allow automatic processing of specifications (e.g., mining them for terms, markup features, or APIs)..."

  • W3C Open Source Software. See the tabular listing and the archive for W3C Open Source Software News. "The W3C Community has created useful Open Source Software. The most popular is the W3C validator, which can help you with HTML, CSS, mobileOK content, and other W3C technologies.... The natural complement to W3C specifications is running code. Implementation and testing is an essential part of specification development and releasing the code promotes exchange of ideas in the developer community. All W3C software is Open Source/ Free Software, and GPL compatible. See the license for details... Note that as this license is GPL compatible, it is possible to redistribute software based on W3C sources under a GPL license... Most W3C software is available directly from our CVS base. You can browse the CVS content and its history on the cvsweb front-end; it also carries instruction on how to extract a local CVS tree..."

  • Using JigEdit to Publish in W3C's Web Site. "JigEdit is a special purpose HTTP server that allows authenticated users to perform an HTTP/PUT on our servers. To request a JigEdit account, you must be a Collaborator... JigEdit is a Jigsaw server enhanced with CVS functionalities. With this tool you can use the CVS system through a form interface and therefore edit the W3C Web space in a safe way. It provides authentication, so that W3C Collaborators can edit some restricted areas of the W3C Web space..."

  • Using WebDAV to Edit W3C Web Site. "WebDAV is an HTTP-based protocol that allows accessing the content of an HTTP server as a networked filesystems; to put it simply, it allows to edit directly a Web site as if it were an additional disk on your computer. There is preliminary support to edit W3C Web site using WebDAV, but due to the number of interoperability issues with the protocol, this support is only experimental; [several] clients have been reported to work with the current implementation... [Cadaver; davfs; Goliath; Konqueror; nd (a Unix command-line based tool); Windows WebFolders; OSX WebDAVFS Webdav mount; XMLSpy Entreprise Edition; Dreamweaver WebDAV]"

  • Use of Mercurial DVCS in W3C. Following a discussion about relative merits of DVCS systems Mercurial and Git ('Decentralized versioning system at W3C', the W3C Team [Alexandre Bertails] introduced Mercurial, noting that all resources in W3C Mercurial are World readable. See the Web interface to the W3C public mercurial repositories. About Mercurial: "Traditional version control systems such as Subversion are typical client-server architectures with a central server to store the revisions of a project. In contrast, Mercurial is truly distributed, giving each developer a local copy of the entire development history. This way it works independent of network access or a central server. Committing, branching and merging are fast and cheap..."

  • Use of CVS in W3C. "CVS is used to edit most parts of the W3C web site.. It provides logs, history, and handy backups for each page under its control, allows many people to maintain a shared information space using versioning control, and is supported by our JigEdit distributed authoring tool." See the W3C Public CVS Repository.

  • Working Group Tools. Various tools for:

    • Creating a Working Group: Organizing a Workshop, Getting the Working Group charter reviewed
    • Starting a Working Group: Creating a Call for Participation, Maintaining WG participants list, Creating a WG Web space
    • Organizing regular meetings: Setting up meetings, Managing meetings
    • Getting to consensus: Tracking issues, Organizing straw poll and votes
    • Publishing documents: Getting write-access for Editors, Making progresses on internal drafts, Getting document ready to publish, Getting a document published, Managing document transitions
    • Tracking and responding to feedback: Setting a feedback system, Tracking feedback, Generating a disposition of comments, Managing patent disclosures
    • Managing implementation reports: Managing test cases, Managing test results, Generating Implementation Reports

  • TR References Checker. Part of W3C TR Automation. The online web form "uses an XSLT style sheet to flag links to W3C TR documents in a given XHTML that aren't the latest version of a document; this makes it a convenient tool to detect outdated references. Note that it only detects links that start with http://www.w3.org/TR/, and that follows the usual naming pattern for dated URIs in TR space. This means it will miss links to the oldest Technical Reports which didn't follow this scheme...

  • W3C Technical Reports Shopping List Tool: it allows you to create your reference list from W3C Technical Reports database by picking the technical reports you want [click checkboxes]; the tool will format the references according to the manual of style. This tool uses an XSLT stylesheet run on the TR data in RDF ('tr-shopping.xsl'); it generates a label when none is given, based on the latest version URI of the reference." See the announcement: "TR references generator with a nicer interface".

  • Bibliography Generator for TR Publications. "This tools allows to get an XHTML formatted data for TR publications, embedded in a <dd> element, using an XSLT style sheet. See the Stylesheet to format bibliographic data for our TR publications.

  • Online Minutes Generator. "Generate HTML formatted minutes from your meeting's log... This tool generates an HTML-formatted version of your meeting's minutes using Scribe.perl, a script developed by David Booth. The source code and documentation are available from the W3C Public CVS server... Scribe.perl is a perl script for generating meeting minutes from an IRC, IM or other log file that follows some simple minuting conventions. It is easy to use and requires no installation. It was primarily designed for use in and around W3C, but can also be used in other environments..."

  • W3C Markup Validation Service. The W3C Markup Validation Service is "a free service that checks Web documents in formats like HTML and XHTML for conformance to W3C Recommendations and other standards. The online Web interface supports validation by URL, by File Upload, and by direct Input. The validator can process documents written in most markup languages. Supported document types include the HTML (through HTML 4.01) and XHTML (1.0 and 1.1) family, MathML, SMIL and SVG (1.0 and 1.1, including the mobile profiles). The Markup Validator can also validate Web documents written with an SGML or XML DTD, provided they use a proper document type declaration..."

    One may download the Validator to run on a local system. For Web design departments or agencies it can be a very good idea, saving time and allowing one to not send documents under work or confidential pages over the wire. The developers have prepared a simple Installation manual, which, along with the Developer's information, should help you install a local instance of the Markup Validator in your own network easily.

    Validation Service References:

  • W3C LinkChecker. This now indepedent W3C LinkChecker from the Systems Team "comes from a tool initially developed by one of the W3C Webmasters to help finding broken links in the to-be-published TR documents. The link checker reads an HTML or XHTML document and extracts a list of anchors and links. It checks that no anchor is defined twice. It then checks that all the links are dereferenceable, including the fragments. It warns about HTTP redirects, including directory redirects. It can also check recursively a part of a Web site; the user may specify the recursion depth. There is a command line version and a CGI version. They both support HTTP basic authentication. This is achieved in the CGI version by passing through the authorization information from the user browser to the site tested. The source code is available publicly under the W3C IPR software notice from CPAN and CVS (development and archived release versions). The W3C LinkChecker was developed by Renaud Bruyeron, Hugo Haas, Ville Skyttä and many other volunteers." References:

  • W3C Log Validator. "Log Validator is a web server log analysis tool with focus on the quality of Web documents. It is a flexible piece of software which can be used to batch process a large number of document through the Markup Validator, CSS Validator and Link Checker. Coupled with step-by-step Web Site strategies, it can be a very efficient ally in finding documents that need fixing. Version 1.0 of the Log Validator has a 'link checker' processing module... The log validator works with Perl, has a modular architecture, and is fairly easy to install on most platforms already running a Web server. This tool works by taking a web server's latest logs and processing them through validation modules. Those validation modules check the most popular documents' validity for a certain technology. The default module is HTML validation, but others are available. The (X)HTML validation module, for example, helps you find, among the most popular pages on your site, which are invalid, and thus tell you which (invalid) pages you should fix first. This is a step-by-step process, you can set up this tool to run every week, and painlessly fix only a few documents at the time. References:

  • CSS Validation Service (Cascading Style Sheets). The W3C CSS Validation Service is a free service that checks Cascading Style Sheets (CSS) in (X)HTML documents or standalone for conformance to W3C recommendations. The default [2005-09] is for validating Cascading Style Sheets, level 2. You can run it on a web server, on the command line or use it in your new browser. You can validate CSS stylesheets nominated by URI, or via File Upload, or entered through direct input. The tool's creators and maintainers include Philippe Le Hégaret and Sijtsche Smeman. References:

  • W3C RDF Validation Service. The RDF validator may be used by nominating a URI or by pasting an RDF/XML document into the text field of the online form. "A 3-tuple (triple) representation of the corresponding data model as well as an optional graphical visualization of the data model will be displayed. This online service now supports the RDFCore specifications issued by the RDF Core Working Group, including datatypes. It supports a range of display options (PNG, SVG, GIF); a zoomable representation of the graph is available by selecting option IsaViz/ZVTM (Dynamic View) as the desired Graph Format. This Java applet is based on IsaViz and requires the Java Plug-in to be installed and properly configured for your browser... The RDF validation service is based on Another RDF Parser (ARP); ARP was created and is maintained by Jeremy Carroll at HP-Labs in Bristol... The servlet source code is available online. The servlet uses ARP 2 thus it depends on Xerces 2 and SAX2 as documented at the ARP home page. The servlet also uses Apache's RE (Regexp) class..." References:

  • Multi-Blog/Multi-Users Blog. "Blog software to make it possible for W3C groups to maintain blogs. The W3C Systems Team initially chose b2evolution rather than some other software: (1) it is multi-users / multi-blogs by design (2) it handles reasonably well encodings considerations (3) it allows to build standard-compliant blogs (4) it is open-source, with a reactive maintainer; (5) it had been tested by users in the the Mobile Web Best Practices Working Group, the Mobile Web Initiative, and the W3C Internationalization Activity."

  • From Dominique Hazaël-Massieux: WRT the so-called "comma-tools" on www.w3.org: e.g., by appending ,validate on a www.w3.org page, one gets redirected to the results of the markup validation for that page. A number of groups are now using dev.w3.org to do their specification development work, so we have enabled a number of these comma-tools on dev.w3.org URIs as well:

    • ,text turns the page in plain text
    • ,checklinks verifies the links on the said page
    • ,validate verifies the markup validity
    • ,cssvalidate verifies the CSS validity
    • ,headers tells you the HTTP headers sent by the page
    • ,cvslog redirects you to the CVS history of the page
    • ,spell runs the page through the spellchecker
    • ,pubrules runs the page through the pubrules checker

    Earlier description: W3C Comma-Text Tool [,text]. This 'html2txt' tool converts HTML to text, with a number of options: (1) don't include references inline with the text; (2) don't include numbers next to references; (3) include an extra list of references at the end; (3) don't skip document-internal references. Comes in handy for pasting link-retained HTML into plain-text email formats, etc. From Gerald Oskoboiny and Dominique Hazaël-Massieux.

  • Transforming XHTML to LaTeX and BibTeX. transform XHTML to LaTeX and BibTeX to allow technical articles to be developed using familiar XHTML authoring tools and techniques. See the XSLT stylesheet xh2bibl.xsl and the PDF. Announced in the posting by Dan Connolly (May 06, 2004).

  • Other references:
Hosted By
OASIS - Organization for the Advancement of Structured Information Standards

Sponsored By

IBM Corporation
ISIS Papyrus
Microsoft Corporation
Oracle Corporation

Primeton

XML Daily Newslink
Receive daily news updates from Managing Editor, Robin Cover.

 Newsletter Subscription
 Newsletter Archives
Globe Image

Document URI: http://xml.coverpages.org/specProduction.html  —  Legal stuff
Robin Cover, Editor: robin@oasis-open.org