Allow specific revision of a file in the repository to be specified

[Ryan J Ollos]

As noted in #6622, I'm having an issue getting the new *CodeExamplePath macros to work, but from looking at the documentation, I have a suggestion that would improve a particular use case that I had in mind for this macro.

I don't have a good code review tool in place for my companies' SCM system, so we typically use tickets to track changes that result from code reviews. The ability to display code from the repository is a great feature that would fit well with our code review process, however a few changes would make it even more useful.

When performing code review, we identify particular segments of code that are bad in some way. These segments of code are subsequently fixed, so when identifying bad code in the ticket we'd like to include code from a specific revision of a file in the repository. The following concise syntax would be consistent with Trac's source TracLink syntax:

path:/dir1/dir2/file1@436:26-30

This would display (highlight) lines 26-30 of from the path /dir1/dir2/file1 at revision 436.

A source TracLink has a similar syntax. If you wish to highlight lines 26-30 from the path /dir1/dir2/file1 at revision 436, you'd use the syntax:

source:/dir1/dir2/file1@436:26-30

With this path specification in place, you could also consider just allowing path to be specified as an option to the existing *CodeExample macros (rather than having a separate set of macros). For example:

#!path:/dir1/dir2/file1@436:26-30

Finally, with that in mind perhaps a link to the source code in the repository browser could be added to the code example box. In the example above, clicking somewhere in the code example box would take you to source:/dir1/dir2/file1@436:26-30#L26. In the interest of keeping the Code Example box clean and simple, I'd be in favor of having Example be a link to the repository browser.

[Ryan J Ollos]

I gave some more thought to the specifics of this feature set:

• In addition to the #path: option, there could be a #!regex:, as is currently supported, to specify searching for a regular expression in the case were line numbers are not specified. Using the #! syntax for options could allow having only 3 macro names rather than 6.
• For the #!path specification:
  • @426:26-30,32-34,40. for example, could specify that several non-contiguous lines be displayed in the code box. Non-contiguous segments could be separated with a line separator (for which the wiki syntax is ----).
  • A #!linenumbers:on option could be used to specify that line numbers are displayed, as the repository browser does. For the display of non-contiguous segments of code, you might consider having line numbers displayed by default.
  • If a specific starting line number is displayed using the #L26 syntax, it might have no effect on the code displayed in the code box, but would determine the starting line that is displayed when linking the repository browser (assuming the quickjump to repository browser link is implemented, as suggested previously).

[Alexander Slesarev]

Replying to rjollos:

• In addition to the #path: option, there could be a #!regex:, as is currently supported, to specify searching for a regular expression in the case were line numbers are not specified. Using the #! syntax for options could allow having only 3 macro names rather than 6.

I don't think it's so good idea. *Path-macros have completely new logic, and mixing usual and *Path macros can confuse end users. For example, "#!path" (and other options) may be a a part of the user code, and macros will introduce unwanted behaviour.

• A #!linenumbers:on option could be used to specify that line numbers are displayed, as the repository browser does. For the display of non-contiguous segments of code, you might consider having line numbers displayed by default.

It's not compatible with "pygmentizing" (as you can see, Trac doesn't show any colors in the source browser). Also it can break SELECT ALL functionality.

[Alexander Slesarev]

Fixed in r7632.