Draft proposal: JEP 2.0

[Per Bothner]

[Sorry for the bad message linkage - I just subscribed.]

On Apr 12 Mark Reinhold wrote:

 >  - Some people, including yours truly, find any amount of non-trivial
 >    text editing in a web browser to be extraordinarily painful.   ...

 >  - Incoming JEPs invariably require at least some light copy-editing.
 >    Some JEPs require much more than that.  ...

As you point out "The largest constituency for JEPs is the people who
read them, not those who write or edit them."  I think most people
(even those of us more comfortable with Emacs) can handle editing
in a web browser.

 >    JIRA, unfortunately, does not do a
 >    very good job of displaying large bodies of structured text.

Actually, JIRA supports rich text tolerably well - about as well
as the Markdown use by JEP (thought it doesn't have the "escape to
HTML" fall-back).  Of course they use their own idiosyncratic
markup format, which matches the Confluence wiki engine.  Any text
field can be configured to the use the "Wiki Style Renderer":

https://confluence.atlassian.com/display/JIRA/Configuring+Renderers
https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa

The result is quite readable, and looks decent enough.

(There are plugins to use Markdown, but I don't believe any is supported 
by Atlassian, so I think its more simple and robust to stick
with the native markup format.)

 >    It's certainly possible to encode a long-form text document into
 >    some text fields in a JIRA issue, but the result is far from easy
 >    to read, never mind actually attractive.

One could use a separate JIRA field for each JEP section, or just put
it all in the Description field and use headings to mark the sections.
It's not clear which is better.

 >  - JIRA's history display is fairly primitive, showing just the new
 >    and old values for each field modified in a particular transaction.
 >    To comprehend the changes to a long document over time you really
 >    need something more like an actual diff.

Yes, JIRA isn't very diff-friendly nor very friendly to the kind of
workflow we're used to from Mercurial, including patches.

I wrote some experimental tools in this area.  The idea is to use
JIRA's REST interface, which allows you to extract the fields of an
issue in a JSON representation - as well as optionally update them.
I wrote a filter to convert to and from what I call "pretty JSON",
which does line-breaking, indentation, removes the redundant commas,
and quotes around field names.  This format is much more diff-friendly - 
as well as friendlier to human readers and editors.  Our goal was to 
version-control JIRA configuration information, as well as copy 
information from one JIRA instance to another.  It seems we could
modify these command-line tools could to make it more pleasant to diff
(or even patch) JEP issues.
-- 
	--Per Bothner
per at bothner.com   http://per.bothner.com/