lucene-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael McCandless <luc...@mikemccandless.com>
Subject Re: Composing posts for both JIRA and email (was a JIRA post)
Date Fri, 05 Mar 2010 10:36:41 GMT
Great guidelines Marvin!

I agree w/ most of this, except, I do use Jira's markup (bq., {quote})
when adding comments.  I'm torn between how important the "first read"
(via the email Jira sends) is vs the "I click through to the issue &
read it).  Typically I just click through to the issue unless it's a
smallish comment.

I don't get why Jira can't support email markup (>, >> means nested
levels of quoting) in addition to its own... maybe they are gunning
for some kind of lock-in of their users.  EG I've seen people respond
to normal email threads, but quoting using bq.!

Sometimes I compose with an external editor (in emacs, which wraps)
sometimes directly in the browser.  It's All Text plugin sounds neat
-- what does it gain over simple copy/paste out of your editor?

I can't stand that gmail doesn't do the right thing w/ line wrapping
outgoing email, though -- when I quote a message (like below), the
addition of the >'s causes already wrapped text to be further wrapped,
thus looking hideous (you should see examples below).

And yes I hate that the first line under {code} has no indentation.
Silly.  Sounds like we just need a Jira upgrade @ Apache to fix that
one...

Mike

On Thu, Mar 4, 2010 at 12:28 PM, Marvin Humphrey <marvin@rectangular.com> wrote:
> (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
>
>

Mime
View raw message