Option to disable CamelCase for non-direct-Wiki pages.

[jamesm@…]

The readability of Timeline changeset descriptions is reduced by the use of CamelCase.
Most of my changeset descriptions mention Java class names which are all displayed with the CamelCase notation. While some may find this extremely useful, I find the injection of question marks in the descriptions pretty annoying.
I don't necessarily want to use Trac to document absolutely everything about the source code that it is managing - especially since we have documentation processes in place. I do want to use the Trac site as the hub of development activity and collaboration. It excels at this and future revisions will only be better.
While CamelCase is a great feature for direct Wiki pages, I would like to see either a feature to disable CamelCase on non-direct-wiki pages or I would like to see a notation that explicitly enables CamelCase rather than what I suspect is a text auto-detection scheme.

[trac@…]

Another possibility would be to change so that the undefined wiki links are present, but do not show as such until you hover over them. The question marks would go away from all but wiki pages.

Then you wouldn't need a configuration option, and I think the reduced discoverability is not a big deal; it'd be the kind of feature you would discover exactly when you need it.

[ludde]

Patch to ignore missing wiki links in changeset messages

[ludde]

Attached a patch that disables the unknown wiki links in changesets.

IMO Invalid wiki links should only be displayed in Wiki pages, and should not be shown on pages like the time line, or the changeset messages.

[cboos]

That would go against Trac integration goals.

Wiki pages can be used to refer to software components and software features. Then, it quicly becomes natural in changeset comments to add references to appropriate Wiki pages, in addition to references to tickets or other changesets. Appropriate Wiki pages could be pages dedicated to the component or the feature being worked on.

In this context, when a changeset is the first to introduce a component or a feature, it's practical to put the new wiki names in the commit log, and use the resulting missing wiki link to actually create the page when browsing the changeset in Trac.

Also for ClassNames... why not use that missing link as an invitation to create (or to link to) some documentation for that class?

Therefore, I personally would like to not disable CamelCase for non-direct-Wiki page, as I like to see Trac as a Wiki-everywhere application :)

[cmlenz]

I'm undecided on this issue. I can see how the current behavior can lead to very cluttered log messages if you use CamelCase to refer to classes etc.

Luddes comment was not about disabling CamelCase outside of Wiki pages. It's only about not marking up missing links. The theory behind that is that you should probably have a link to the new page on a real wiki page anyway, so you shouldn't need to create it directly from a non-wiki context. As I said, I'm not sure whether that's such a good idea. The current behavior is at least consistent and predictable.

Also for ClassNames... why not use that missing link as an invitation to
create (or to link to) some documentation for that class?

Because these days nobody wants to document classes outside of the source code, it just gets out of sync way too quickly. So you already have documentation for the class, and a wiki page will likely never be created.

[cboos]

Sure, that's why I said: or to link to...

If I remember correctly, someone wrote a WikiMacro for jumping to the JavaDoc? of a class given as argument. I want to create a similar one for Doxygen.

e.g. the content of a MyBankAccount page could be something like:

[[Doxygen(trunk/bank/src/MyBankAccount)]]

Refactoring: Consider merging the features from YourBankAccount
with this one.

It's not about replacing the code documentation, which has its own structure, it's more talking precisely about things (here classes) during the development process.

Other (further) possibilities:

• With the xrefs, one could also see in which changesets that class was involved (i.e. the changesets in which that class name was mentionned in the commit message; this could be a changeset which does not involve the filename for the class, but rather some files that are using the class)
• With wiki templates, when one would like to create a page for a class, selecting e.g. the CppClassTemplate would automatically add the Doxygen link

[mgood]

#1490 has been marked as a duplicate of this ticket.

[anonymous]

Just to add to the discussion, the group I'm in at work has been using Trac for a while now and we do not like the links in svn commit messages. I'm not against links since there are obvious uses for them (good examples above), but the auto-link to missing pages is not working for us. The inability to do a preview is a show-stopper for me. Even though I try to put ! symbols before the class names, I miss a couple sometimes. I don't find out until after the commit. I would vote for the wiki:LinkName syntax for commit messages, since it is extremely rare and obvious in the text. Or just have a config option in Trac that would enable/disable auto-wiki linking in commit messages.

[mgood]

#1604 has been marked as a duplicate of this ticket.

[anonymous]

Just a quick note to point out that all wiki markup, not just links, are problematic. This is half-evoked in some comments, but to me having a reference to a variable name __foo turned into foo and the rest of the line is underlined poses a bigger problem, because it mangles the log information, whereas autolinking "just" makes it a bit more tedious to read.

For the markup not related to links, I don't see much justification of having the font styles, paragraphs or header transforms applied to the log message. The two markup features I can find a use for in my case (fwiw) are:

• Lists, because " * itemized commit messages" convert gracefully to html lists. This could be left out though, if the cost of processing just that is too much.
• Links, mainly for references to issues.

[cboos]

I think that all the problems evoked here boils down to not being able to either preview or fix the comment log once created.

While it is possible to simulate the preview (write the commit log message in a Wiki page and preview), I know that this is cumbersome...

But it should definitely be possible to fix a comment log. This is planned (#781) and I think we should consider disabling Wiki formatting in comment logs only if the problems described here persist after it's possible to edit the change logs.

In the meantime... well, personally I created a FixMe page where I keep a list of all the changelogs that would need to be reformatted once #781 is available...

[Ian Leader <__ian.leader__@…>]

I think being able to modify the SVN log is a good idea, but I would still like to see a global option to disable wiki markup in changelogs (with the possible exception of '*' bullet points and 1. numbering).

Normally we don't put any other wiki markup in the changelogs, but instead refer to tickets, and put any links, etc. there. So it makes sense (for us) to turn the feature off, and use the change feature to put it in on the (rare for us) occasions when it is required.

[tim.alsop@…]

I would like to suggest a global configuration parameter (in trac.ini ?) which is used to determine the required default format for ticket comments (e.g. full-wiki, no-wiki, and maybe other format combinations should be provided). An example format option might be No-CamelCase, in which case when this format option is selected all other wiki formatting is enabled, but CamelCase is not (by default).

An override should also be possible, so whenever I am typing text into a ticket comment I can select the format required for the particular comment. I might have a ticket with multiple comments, but in some comments I want wiki formatting, in other comments I might not.

Using this approach would allow me to configure the default format to no-wiki and then every ticket comment that does not have override would be displayed with no-wiki formatting. When a case comment has an override (e.g. specify that full-wiki is required) the wiki formatting should be used for this case comment).

I am also looking forward to ticket #781 being available so I can correct many of our comments, and I consider this ticket to be complementary to being able to edit ticket comments.

[john@…]

As an avid user of Trac in our environment, I'd say that the Wiki formatting causes more trouble than fixes problems. We like the ability to reference changesets and tickets, but beyond that, we don't use the wiki formatting. We're forever getting caught with naming and having awkward formatting in the changeset view (underlines is really the biggest problem since it isn't all that uncommon to have double underscores in code). Also the bullet formatting is off and doesn't properly line things up, so we end up with nested comments that are indented 7 or 8 levels deep.

A way to disable, or selectively choose what could be formatted via the conf file would be a very handy feature.

[Andrew Skiba <andrews@…>]

I want to add my vote for that fix. I think there is a strong need to do this configurable, possibly via TracIni. Actually, I changed this ticket's patch to make things even more strict on our system - any camel case that has no corresponding page is shown as a regular text everywhere. There is always fancy link format to define a link explicitly. And another feature I'd want to be able to configure, too: the double underscore issue in the changeset comments they talked in #1604. But it must turn off the formatting not only in the changeset view, but also in the timeline view.

[pbrengard]

Hi, I am a collegue of Christian Boos (cboos). This comment follows a discussion we had at lunch about the auto-link creation when the text is in camel case.

I don't like this feature (Christian forbid me to use the word "sucks" :-) ). As a heavy user and contributor to Wikipedia, I really like the way it is done in MediaWiki (the software behind Wikipedia).

IMHO, the Wiki syntax must be descriptive only, and the wiki must not guess anything thanks to some crazy heuristics. Computers must obey their masters :-)

I think pages could really be prettier without dead links and words written in CamelCase.

[cboos]

(I feel compelled to say something for my defense)

I didn't like the original idea proposed here, because:

1. it was not consistent to have the Wiki behave in one way here, differently there.
2. it makes it harder to create new pages

Now, in 0.9, the syntax for fancy links has been extended a bit, so that one can write [wiki:NewPage] in order to get a link to NewPage?, so the second point isn't such a big deal for me anymore (e.g. when I do a commit on some new topic that I want to describe further in the Wiki, I can now just write [wiki:TrickyStuff] instead of the cumbersome [wiki:TrickyStuff TrickyStuff] needed before).

And Andrew's comment makes sense:

any camel case that has no corresponding page is shown as a regular text everywhere. There is always fancy link format to define a link explicitly.

This is good, because we have at the same time the auto-links to CamelCase pages for those who like them, and they won't annoy those who don't. This is also nice because all those quiescent links can suddenly become active in the case their corresponding Wiki page get created.

If this was made configurable, I could agree on that (to please that MediaWiki worshiper above :) )

[cboos]

Proof-of-concept implementation of the above:

Index: api.py
===================================================================
--- api.py	(revision 2113)
+++ api.py	(working copy)
@@ -140,14 +140,19 @@
     # IWikiSyntaxProvider methods
     
     def get_wiki_syntax(self):
+        ignore_missing = self.config.get('wiki', 'ignore_missing_page', False)
         yield (r"!?(^|(?<=[^A-Za-z/]))[A-Z][a-z]+(?:[A-Z][a-z]*[a-z/])+"
                 "(?:#[A-Za-z0-9]+)?(?=\Z|\s|[.,;:!?\)}\]])",
-               lambda x, y, z: self._format_link(x, 'wiki', y, y))
+               lambda x, y, z: self._format_link(x, 'wiki', y, y,
+                                                 ignore_missing))
 
     def get_link_resolvers(self):
-        yield ('wiki', self._format_link)
+        yield ('wiki', self._format_fancy_link)
 
-    def _format_link(self, formatter, ns, page, label):
+    def _format_fancy_link(self, f, n, p, l):
+        return self._format_link(f, n, p, l, False)
+
+    def _format_link(self, formatter, ns, page, label, ignore_missing):
         anchor = ''
         if page.find('#') != -1:
             anchor = page[page.find('#'):]
@@ -156,6 +161,8 @@
         label = urllib.unquote(label)
 
         if not self.has_page(page):
+            if ignore_missing:
+                return label
             return '<a class="missing wiki" href="%s" rel="nofollow">%s?</a>' \
                    % (formatter.href.wiki(page) + anchor, label)
         else:

[cboos]

Implemented the above in r2135 (now it's ignore_missing_pages, though)

The problem with the underscores can be solved by taking the habit of using inline quoting (that's cheap with 0.9, use backticks: `__c_var`). If that's not enough, r2134 makes it easier to change the hardcoded syntax for underline text. If that's still not OK, well, feel free to propose something in a new enhancement ticket, as we're going off-topic now :)

[mgood]

I'd really like to see this get some more discussion before the current implementation goes into 0.9. I had some reservations initially about differences between whether or not the Wiki formatting was "direct" or not, but I find this distinction more obvious than the fact that with this option enabled CamelCase still has special meaning, but only if the page happens to exist. I think that it would make more sense to just provide an option to completely disable CamelCase recognition.

[cboos]

I don't like so much the idea of requiring a specific markup for identifying WikiPageNames. Quite the contrary, I already implemented a way to easily support alternative WikiPageNames schemes (see #425).

If a specific markup is made necessary, I'd like it to be very lightweight, even more than [wiki:NewPage]. I'd suggest being able to use simply [:NewPage] (wiki would be the default namespace), or even [NewPage].

Now that I think about it, this shortcut form could also have an interest on its own for enabling an easier creation of page names containing spaces: [Revision Control System].

In the above scheme, labelled links would require explicit quoting:

[Revision Control System "RCS"]

[dmbrucker@…]

Being that there are so many sides and ideas and requests on this ticket, I think more needs to be done to accommodate peoples requirements here. What I propose is really based on a lot of the comments above. I'm just trying to put some concrete bits in place to show how it could be done.

I think there should be two new variables in trac.ini that control wiki formatting in ticket comments and commit logs (call them what you will):

ticket_wiki_formats =
commit_wiki_formats =

Being set to WIKI_ALL, would create the current behavior of wiki formatting throughout and I think this should be the default for consistency. Being left empty would disable all auto-formatting. But, each could be set to an or'd list of constants that would enable auto-formatting of those respective basic wiki formats.

Adapted from WikiFormatting:
WIKI_FONT would enable the bold, italic, etc font styles,
WIKI_HEADING would enable the wiki headings,
WIKI_BR would enable the special handling of paragraphs,
etc, etc, etc.

So, to accomplish just lists and links in commit logs, as has been requested above:
commit_wiki_formats = WIKI_LIST | WIKI_LINK

There could even be some shortcut formats that would include several of the basic formats, so just adding the shortcut would enable all the included basics:
WIKI_MARKUP == WIKI_FONT | WIKI_HEADING | WIKI_LIST | WIKI_TABLE
WIKI_SPECIAL == WIKI_MACRO | WIKI_PROCESSOR
Actually, WIKI_ALL would be the largest and most common shortcut.

Then, even if they were turned off, some of the formats could be overridden on a case by case basis, using the full [wiki:SomePage] for example, if the commiter really wanted to link to that wiki page.

I haven't looked at the code for the wiki processor, so I don't know if breaking up all of its capabilities is easily possible, esp. for 0.9. But, I think that its a worthy goal and that this would satisfy a larger group of people then just a binary "on or off" setup.

I personally like and use all the linking and wiki heavily to document my projects. I find that the wiki is more flexible and allows me to more completely document things then just API docs like Doxygen. Plus, I can rip wiki pages out into a PDF and have a really nice looking API doc that I can had to someone.

[cboos]

The proposal made above by dmbrucker would allow a great deal of flexibility, but at the cost of adaptations to the Wiki engine we certainly don't want to introduce at this point, given the feature freeze for the upcoming release.

Anyway, at this point, this ticket shouldn't be considered high prio for 0.9 as I think I've implemented a reasonable solution in r2135.

If someone wants to come up with a better patch that has not the complexity implied by the above proposal, this might still go in 0.9.

[cdleonard@…]

I don't think that disabling camel case only some times (like in commit messages) is a good thing, it's best to have the same wiki everywhere.

However, a lot of people have projects with CamelCase names in code and don't like to type ! all the time. What I want is to have a way disable CamelCase and have to link to other pages with an explicit syntax, just like media wiki

[cboos]

Someone proposed in #2532 to disable CamelCase globally:

Index: api.py
===================================================================
--- api.py      (revision 2692)
+++ api.py      (working copy)
@@ -196,6 +196,8 @@
     # IWikiSyntaxProvider methods
     def get_wiki_syntax(self):
+        if self.config.getbool('wiki', 'no_camelcase'):
+            return
         ignore_missing = self.config.getbool('wiki',
'ignore_missing_pages')
         yield (r"!?(?<!/)\b[A-Z][a-z]+(?:[A-Z][a-z]*[a-z/])+"
                 "(?:#[A-Za-z0-9]+)?(?=\Z|\s|[.,;:!?\)}\]])",

However, I don't really see how this would improve upon the ignore_missing_pages switch... In particular, this will break all the builtin help (the default Trac* wiki pages), unless all the existing CamelCase links are previously converted... And if one wants to do that in an automated way, then he'll probably end of with all his JavaClases links transformed into [wiki:JavaClases] too :) So the above patch is provided with a use at your own risk warning.

[anonymous]

i like the proposal on moinmoin featurerequests allowing also WikiPPIsAWikiName:

    word_rule = ur'(?:(?<![%(l)s])|^)%(parent)s(?:%(subpages)s(?:[%(u)s][%(l)s]+){2,})+(?![%(u)s%(l)s]+)' % {
        'u': config.chars_upper,
        'l': config.chars_lower,
        'subpages': config.allow_subpages and (wikiutil.CHILD_PREFIX + '?') or '',
        'parent': config.allow_subpages and (ur'(?:%s)?' % re.escape(PARENT_PREFIX)) or '',
    }

[cboos]

The above comment is not really relevant for this ticket. Rather you should have a look at the FlexibleWikiPageNames proposal and to ticket #425 and #2339.

[Jon <jon@…>]

The WebKit trac system is encountering this problem (or one related, since this ticket covers a wide range of wiki issues) in the rendering of their Changeset Message field. Optionally disabling wiki code for this field, or automatically wrapping its content in triple brackets would be a good solution.

[tim@…]

Feels like:

either this ticket should have its summary changed ("customisable formatting for tickets & commits") or should be closed! (cause its summary is more or less done in 0.9 isn't it)

As a compromise between the two:

Suggest that something be on the lines of dmbrucker@…'s 09/22/05 13:19:41: comment - but in a stepwise fashion...

The first step would be to have the config options:

• ticket_wiki_formats =
• commit_wiki_formats =

Each of which would have only two possibilities: WIKI_ALL or blank (or maybe PLAINTEXT might be a more readable synonym).

Other features proposed in the comment (the very nice or'd set) could be then introduced when/if the wiki engine gets refactored.

I'd suggest that this option if implemented would close this ticket as resolved and the or'd proposed becomes a new enhancement ticket (with a very clear scope).

[cboos]

I agree, this ticket was about the possibility to disable CamelCase links because when rendering text which contains lots of CamelCase names which are not meant to be names of Wiki pages, displaying them as missing links makes the whole text hard to read.

This was addressed in 0.9, with the option

[wiki]
ignore_missing_pages = true

which solves that specific problem (the option defaults to false, though).

Now, for the problem of wiki formatting in changesets, there's been the addition in 0.10 of yet another option:

[changeset]
wiki_format_messages = false

(defaults to true, of course). See #2526.

In parallel, there will be some additional changes for 0.10 that will make the wiki formatting of Changelog-like texts much better by default (see #124).

To conclude with this, I'll reiterate the suggestion of tim that a new ticket should be created if one wants an even greater control over what will get wiki formatted or not. But before doing that, I'd suggest the author of such a ticket waits for the development of 0.11 to start, and in particular, for the WorkFlow branch to be integrated. In fact, the WorkFlow branch has already a mechanism in place for deciding whether ticket fields should be .plaintext or not. Currently, it's only about custom fields, but we already discussed about extending that mechanism to cover the default fields. It should be possible to generalize the approach even further. Will see by then.