[Wg-uma] RFC: Specification authoring process

Eve Maler eve at xmlgrrl.com
Mon Aug 24 15:43:53 PDT 2009


This approach seems sound to me.  It meets my goals of:

- Authoring in a format that multiple people can contribute to
- Targeting IETF in deed as well as in word
- Producing native HTML in an attractive format that will hopefully  
appeal to developers
- At least middling levels of content management, such that diff  
redlines can be viewed

I think we're still fine with native Confluence as the source form for  
auxiliary non-normative documents.  (Note that xml2rfc wouldn't be  
suitable for any document that relies on graphics, as it doesn't allow  
non-ASCII graphics per IETF.)

Thanks for looking into it, Paul!

	Eve

On 24 Aug 2009, at 3:16 PM, Paul C. Bryan wrote:

> During our discussion in last week's conference call, we began
> addressing how the specification should be authored, where content is
> hosted, etc.
>
> I was leaning towards using a tool like xml2rfc [1], as it provides
> IETF-compliant output in a number of useful formats.
>
> Before proposing an approach, I first wanted to determine how Kantata
> would be hosting files. After contacting staff, I have learned that  
> they
> allow revision control of files via Subversion and allow publication  
> of
> raw HTML on the wiki.
>
> This seems to be a good fit for me to propose the following approach:
>
> 1. The protocol specification will be authored in the xml2rfc schema.
> 2. The master source file(s) for the protocol specification will be  
> kept
> in Subversion.
> 3. When changes are made, xml2rfc will be run to generate HTML  
> content.
> 4. HTML content will be published through the wiki as raw HTML.
> 5. Formal versions of the spec will be tagged in the Subversion
> repository.
> 6. HTML output of the formal versions be retained separately in the
> wiki.
>
> Please let me know if you have any questions or objections to this
> proposed approach.
>
> Paul
>
> [1] http://xml.resource.org/
>
>
> _______________________________________________
> Wg-uma mailing list
> Wg-uma at kantarainitiative.org
> http://kantarainitiative.org/mailman/listinfo/wg-uma_kantarainitiative.org


Eve Maler
eve at xmlgrrl.com
http://www.xmlgrrl.com/blog




More information about the Wg-uma mailing list