Trac formatting

[Simon Marlow]

On 14/11/13 10:11, Herbert Valerio Riedel wrote:
> On 2013-11-13 at 11:36:13 +0100, Simon Marlow wrote:
>> On 12/11/13 15:53, Joachim Breitner wrote:
>>
>>> Am Dienstag, den 12.11.2013, 15:24 +0000 schrieb Simon Peyton-Jones:
>>>> When Trac formats commit messages it is doing a terrible job.  See for
>>>> example: https://ghc.haskell.org/trac/ghc/ticket/5996
>>>>
>>>> The commit message is nigh illegible until typeset without makup (see
>>>> comment 10).
>>>
>>> I believe it is a feature, not a bug: Trac encourages you to use
>>> markdown markup (which supposedly looks good also in plain text) in your
>>> commit messages. This not only makes them look nice, provides additional
>>> features like automatic linking (compare the reference to #5996 in
>>> comment 9 and comment 10).
>>>
>>> In this case the tables should have been indented by 4 spaces, or
>>> surrounded by {{{..}}}, in the commit message to make it come out
>>> nicely.
>>>
>>> Whether this is desirable is a different question. I like it, but the
>>> heavy users of the repository and trac need to decide what they prefer –
>>> the ability to use markup in the commit messages, or the freedom to do
>>> any kind of ascii art.
>>
>> I'm with Simon on this one.  I much preferred the old plain-text
>> rendering of commit messages.
>
> Luckily, this is an exposed trac.ini setting
> (for future reference: changeset.wiki_format_messages)
>
> I've disabled wiki-rendering for commit messages so you can see the
> effect. As Joachim already observed, since this is an an all-or-nothing
> setting, you lose automatic hyperlinking to Trac tickets, Wiki pages,
> other changesets, and even HTTP URLs in every places where commit
> messages are rendered.
>
> See for instance,
>
>      https://ghc.haskell.org/trac/ghc/changeset/5a3918febb7354e0900c4f04151599d833716032/ghc
>
> where you have to manually lookup the ticket-no. as well as the
> commit-id of the referenced other commit that this commit tries to
> compensate for.

That's unfortunate. Ideally the tickets and commit hashes should be 
hyperlinked.

Commit logs are viewed more often in a terminal or an editor than on 
Trac itself, so I think markup isn't worth the effort.  Also you don't 
get to compose your commit message in the browser, so you can't see 
whether you've made a markup error.

> So this undermines one of Trac's principal design goals, that is
>
>      "Trac allows wiki markup in issue descriptions and commit messages,
>      creating links and seamless references between bugs, tasks,
>      changesets, files and wiki pages."
>
> as is written in the introductory front-page at http://trac.edgewall.org
>
>> I don't want to start using a particular markup format (which is not
>> markdown, it's Trac's own format AIUI) in our commit messages.  What
>> happens if we switch from Trac to something else in the future?
>
> It's an unfortunate situation that when Trac came to life around 2005 it
> wasn't clear that Markdown would become so popular (and it couldn't have
> been used as-is without syntax extensions to allow seamless hyperlinks).
>
> However, if you don't like Trac's Wiki markup and its primary goal of
> tight & seamless hyperlinking from everywhere to everywhere, why did you
> chose to deploy Trac in the first place?

We chose Trac because it was better than SourceForge :-) (also github 
wasn't usable at the time)

> After all, should the GHC
> project ever want to switch from Trac to something else, converting the
> existing Trac tickets and the GHC Wiki Commentary will be quite an
> undertaking retaining the crossrefs as well as stripping out all
> Trac-isms... just saying...
>
> PS: Btw, fwiw, http://trac.edgewall.org/wiki/WikiCreole.

Obviously this is all just MHO, if everyone else wants markup in commit 
messages then I won't complain.

Cheers,
	Simon