Draft proposal: JEP 2.0
per at bothner.com
Tue Apr 15 19:34:05 UTC 2014
[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":
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 at bothner.com http://per.bothner.com/
More information about the discuss