(CC to lucy-dev and general, reply-to set to general)
On Thu, Mar 04, 2010 at 06:18:28AM +0000, Shai Erera (JIRA) wrote:
> (Warning, this post is long, and is easier to read in JIRA)
I consume email from many of the Lucene lists, and I hate it when people force
me to read stuff via JIRA. It slows me down to have to jump to all those
forum web pages. I only go the web page if there are 5 or more posts in a row
on the same issue that I need to read.
For what it's worth, I've worked out a few routines that make it possible to
compose messages which read well in both mediums.
* Never edit your posts unless absolutely necessary. If JIRA used diffs,
things would be different, but instead it sends the whole frikkin' post
twice (before and after), which makes it very difficult to see what was
edited. If you must edit, append an "edited:" block at the end to
describe what you changed instead of just making changes inline.
* Use FireFox and the "It's All Text" plugin, which makes it possible to edit
JIRA posts using an external editor such as Vim instead of typing into a
textarea. <http://trac.gerf.org/itsalltext>
* After editing, use the preview button (it's a little monitor icon to the
upper right of the textarea) to make sure the post looks good in JIRA.
* Use "> " for quoting instead of JIRA's "bq." and "{quote}" since JIRA's
mechanisms look so crappy in email. This is easy from Vim, because
rewrapping a long line (by typing "gq" from visual mode to rewrap the
current selection) that starts with "> " causes "> " to be prepended to
the wrapped lines.
* Use asterisk bullet lists liberally, because they look good everywhere.
* Use asterisks for *emphasis*, because that looks good everywhere.
* If you wrap lines, use a reasonably short line length. (I use 78; Mike
McCandless, who also wraps lines for his Jira posts, uses a smaller
number). Otherwise you'll get nasty wrapping in narrow windows, both in
email clients and web browsers.
There are still a couple compromises that don't work out well. For email,
ideally you want to set off code blocks with indenting:
int foo = 1;
int bar = 2;
To make code look decent in JIRA, you have to wrap that with {code} tags,
which unfortunately look heinous in email. Left-justifying the tags but
indenting the code seems like it would be a rotten-but-salvageable compromise,
as it at least sets off the tags visually rather than making them appear as
though they are part of the code fragment.
{code}
int foo = 1;
int bar = 2;
{code}
Unfortunately, that's going to look like this in JIRA, because of a bug that
strips all leading whitespace from the first line.
|-------------------------|
| int foo; |
| int bar; |
|-------------------------|
It seems that this has been fixed by Atlassian in the Confluence wiki
(<http://jira.atlassian.com/browse/CONF-4548>), but the issue remains for the
JIRA installation at issues.apache.org. So for now, I manually strip
indentation until the whole block is flush left.
{code}
int foo = 1;
int bar = 2;
{code}
(Gag. I vastly prefer wikis that automatically apply fixed-width styling to
any indented text.)
One last tip for Lucy developers (and other non-Java devs). JIRA has limited
syntax highlighting support -- Java, JavaScript, ActionScript, XML and SQL
only -- and defaults to assuming your code is Java. In general, you want to
override that and tell JIRA to use "none".
{code:none}
int foo = 1;
int bar = 2;
{code}
Marvin Humphrey
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: java-dev-h...@lucene.apache.org
