[rfc-i] draft-flanagan-rfc-framework-02 composition tools

[wesley.george at twcable.com (George, Wes)]

On 11/3/14, 12:58 PM, "Heather Flanagan (RFC Series Editor)"
<rse at rfc-editor.org> wrote:


>If I were to hazard a guess based on Stewart's previous posts, this
>isn't about xml2rfc, it's about authoring docs.  If there was
>something easy to install and use that required no domain-specific
>knowledge (e.g., knowledge of the xml2rfc v3 vocabulary) that had
>"save as xml2rfc v2/3" as an option, that would be fine and dandy.
>
>I am hearing the point loud and clear.  I will be discussing this with
>the IESG in Honolulu.

WG] I agree with Stewart and with Heather's summary here, as this has been
an ongoing source of frustration for me as a document author. The idea is
to have something that pretty much anyone *can* use to author documents,
but with an open back-end that allows for other folks to use something
else as they see fit.
However, every conversation we try to have about this devolves really
rapidly into a beauty contest between everyone's pet tools (some of which
are pretty useful already, some of which need work before they're widely
useful, all of which are limited by the support "structure" and
documentation that they have and/or their learning curve) and usually a
subtext debate about whether authoring tools are necessary at all, along
with a side of pro/anti MS rhetoric. Most of it is based on valid points,
but the discussion is rarely productive.

So might I suggest that we get a section of the RFC Editor Wiki
specifically devoted to composition/authoring toolchain (may already
exist, I'm composing this on an airplane and therefore can't check), where
the requirements above are clearly and more completely documented, and
each possible solution can be documented along with some pros and cons,
and a pointer to the method to try it out, so that interested people can
discover potential solutions and test them out in a slightly more
structured way than "when someone suggests it as a potential solution in
an email response". It might even be something we can turn into a formal
RFI, though I'm less confident that selecting something via RFI response
rather than IETF consensus is the right thing here, and I mainly suggest
that as a way to find out what options we should be evaluating.

Here's my initial quick and dirty attempt to flesh out the explicit and
implied requirements:

- Easy to use for someone familiar with a basic word-processor (yes, this
is subjective and needs to be better defined)
- Directly outputs canonical I-D (xml2rfc) format. (I say this because IMO
solutions that require multiple tools/steps to make translations before we
get to xml are a step away from "easy")
- Actively supported (either via code sprints and IETF folks or via an
IETF-paid support contract to a third party)
- WYSIWYG editing mode including support for tables, references, code
blocks, sections, and other bits of layout integral to an I-D without
requiring direct XML editing - though true WYSIWYG would require defining
the derivative output format (HTML, plaintext, etc)
- Multi-platform (at least common versions of Windows, OSX, Linux/Unix)
- Unicode support
- Well-documented for both beginner and advanced users
Optional:
- Android/iOS support
- Open Source
- In-tool SVG creation/editing
- Web-based client instead of requiring local installation
- Free to use for IETF participants (even if this takes the form of a
limited-function version that ONLY allows authoring XML docs in IETF's
template, rather than getting a full-featured XML editor for free), or
possibly the lite version doesn't include the full suite of features that
the RSE would need for document layout and final production
- Support for collaborative editing (this probably covers two big things
that are both separately optional - simple tracking changes plus the
ability to tie into something like git as a document repository)
- Offline editing mode
- Outputs files or shows WYSIWYG previews of multiple derivative formats
(using XML2RFC or via other means)

The break between required and optional is certainly debatable, and I'm
not necessarily suggesting that we do it right now on this thread, I just
wanted to provide something to get this moving toward a productive
discussion, and I think having this list of requirements might help to
frame the discussion Heather plans to have with IESG and/or the discussion
Joe H might have with RSOC.

Thanks,

Wes George


Anything below this line has been added by my company?s mail server, I
have no control over it.
-----------


This E-mail and any of its attachments may contain Time Warner Cable proprietary information, which is privileged, confidential, or subject to copyright belonging to Time Warner Cable. This E-mail is intended solely for the use of the individual or entity to which it is addressed. If you are not the intended recipient of this E-mail, you are hereby notified that any dissemination, distribution, copying, or action taken in relation to the contents of and attachments to this E-mail is strictly prohibited and may be unlawful. If you have received this E-mail in error, please notify the sender immediately and permanently delete the original and any copy of this E-mail and any printout.