mirror of https://github.com/akelge/vim
628 lines
23 KiB
Plaintext
628 lines
23 KiB
Plaintext
*trac.txt*
|
|
|
|
Vimtrac Usage Notes
|
|
|
|
1. System Requirements |trac-requirements|
|
|
2. Setup |trac-setup|
|
|
3. Server Selection |trac-server|
|
|
4. Wiki Viewing / Editing |trac-wiki-view|
|
|
4.1 Wiki Browsing/Editing |trac-wiki-editing|
|
|
4.2. Adding/ Retrieving an Attachment |trac-wiki-attachments|
|
|
4.3. HTML Preview |trac-wiki-htmlpreview|
|
|
4.4. Saving Wiki's |trac-wiki-save|
|
|
4.5 Wiki Vim Diffs |trac-wiki-diff|
|
|
5. Trac Ticket View |trac-ticket-view|
|
|
5.1 Ticket Filters |trac-ticket-filters|
|
|
5.1.1 Ticket Sorting |trac-ticket-sorting|
|
|
5.2. Adding Comments |trac-ticket-comments|
|
|
5.3. Changing ticket states |trac-ticket-changes|
|
|
5.4. Creating Tickets |trac-ticket-create|
|
|
5.5. Adding/Retrieving attachments |trac-ticket-attachments|
|
|
5.6 Ticket Sessions |trac-ticket-session|
|
|
6. Trac Search View |trac-search-view|
|
|
7. Changeset View |trac-changeset-view|
|
|
8. Timeline View |trac-timeline-view|
|
|
9. WikiFormatting |trac-wiki-formatting|
|
|
9.1 Font Styles |trac-format-font|
|
|
9.1 Notes: |trac-format-notes|
|
|
9.2 Headings |trac-format-headings|
|
|
9.3 Paragraphs |trac-format-paragraphs|
|
|
9.4 Lists |trac-format-lists|
|
|
9.4 Definition Lists |trac-format-definition|
|
|
9.5 Preformatted Text |trac-format-preformatted|
|
|
9.6 Blockquotes |trac-format-blockquotes|
|
|
9.7 Discussion Citations |trac-format-discussion|
|
|
9.8 Tables |trac-format-tables|
|
|
9.9 Links |trac-format-links|
|
|
9.9.1 Trac Links |trac-format-traclinks|
|
|
9.10 Escaping Links and WikiPageNames |trac-format-nolink|
|
|
9.11 Images |trac-format-images|
|
|
9.12 Macros |trac-format-macros|
|
|
9.13 Processors |trac-format-processors|
|
|
9.14 Miscellaneous |trac-format-misc|
|
|
================================================================================
|
|
1. System Requirements *trac-requirements*
|
|
|
|
You must have a working Trac repository version 0.10 or later complete with
|
|
the xmlrpc plugin and a user with suitable access rights.
|
|
|
|
Vim must be compiled with python support and your client must have python
|
|
2.4.4 or later
|
|
|
|
To use the summary view you need to have the Align plugin installed for the
|
|
layout.
|
|
|
|
http://www.vim.org/scripts/script.php?script_id=294
|
|
================================================================================
|
|
2. Setup *trac-setup*
|
|
|
|
You need to create a list of trac servers using this format in your vimrc.
|
|
|
|
"let g:tracServerList = {}
|
|
"let g:tracServerList['(Server Name)'] =
|
|
\'http://(user):(password)@(trac serverpath)/login/xmlrpc'
|
|
|
|
Check out
|
|
|
|
http://www.ascetinteractive.com.au/vimtrac/wiki/UsageNotes and
|
|
http://www.ascetinteractive.com.au/vimtrac/wiki/TricksAndTips
|
|
|
|
for more up to date notes
|
|
|
|
================================================================================
|
|
3. Server Selection *trac-server*
|
|
|
|
|
|
:TWServer [ServerName] *:TWServer*
|
|
:TTServer [ServerName] *:TTServer*
|
|
:TTLServer [ServerName] *:TTLServer*
|
|
|
|
Sets the current trac server where the
|
|
The <tab> key will cycle through available servers.
|
|
|
|
The wiki (TW), ticket (TT) and timeline (TTL) vaiations will open the
|
|
respective views
|
|
================================================================================
|
|
4. Wiki Viewing / Editing *trac-wiki-view*
|
|
|
|
The Trac Wiki view is for browsing an editing a trac websites wiki pages.
|
|
|
|
*:TWOpen*
|
|
|
|
To open the wiki view use the command :TWOpen [OptionalWikiPage]
|
|
|
|
If no page argument is given the plugin will open the main page WikiStart
|
|
by default
|
|
|
|
4.1. Browsing/Editing *trac-wiki-editing*
|
|
|
|
The WIKITOC_WINDOW will show a list of pages. Scrolling up and down and
|
|
Pressing <return> on a page will open the selected page in the WIKI_WINDOW
|
|
|
|
Pressing <space> over the page in the WIKITOC_WINDOW will display the page
|
|
in a browser
|
|
|
|
Trac sites usually have a bunch of in built pages Trac* or Wiki* you can
|
|
hide these from view by setting the global variable in your vimrc. let
|
|
g:tracHideTracWiki = 'yes'
|
|
|
|
At the moment this is done with a simple regexp so if you name your own
|
|
pages Trac... or Wiki... they will not appear on the Table of Contents.
|
|
|
|
You can also load a page by pressing the usual tag jump <c-]> to open the
|
|
page under the cursor. At the moment theres no page name validation so it
|
|
will throw an error if you try an open a nonexistant page.
|
|
|
|
4.2. Adding/ Retrieving an Attachment *trac-wiki-attachments*
|
|
|
|
:TWAddAttachment [file_path] *:TWAddAttachment*
|
|
|
|
adds an attachment to the current active wiki page
|
|
|
|
:TWGetAttachment [file] *:TWGetAttachment*
|
|
|
|
gets an attachment from the active Wiki Page and save it to the current
|
|
working directory.
|
|
|
|
If a Wiki page opened contains attachments The Wiki Attachment window will
|
|
appear. Attachments can be downloaded by hovering over the desired
|
|
attachment and pressing <enter>
|
|
|
|
4.3. HTML Preview *trac-wiki-htmlpreview*
|
|
|
|
:TTPreview *:TWPreview* *:TTPreview*
|
|
|
|
displays the current wiki in html preview (only tested on lynx set
|
|
g:tracBrowser)
|
|
|
|
You can also use the shortcut <leader>tp
|
|
|
|
4.4. Saving Wiki's *trac-wiki-save*
|
|
|
|
To save a page you can type in the command view
|
|
:TWSave [optional_wiki_update_comment] *:TWSave*
|
|
|
|
Alternatively you can quickly save a page with your regular :wq<cr> or :w<cr>
|
|
which I've mapped to perform the TWSave? command.
|
|
|
|
Exiting Trac Wiki View
|
|
|
|
Exiting is done by either the command
|
|
|
|
:TClose, :wq<cr> or :q<cr> in either of the wiki windows
|
|
|
|
4.5 Wiki Vim Diffs *trac-wiki-diff*
|
|
|
|
:TWVimDiff <revision no> *:TWVimDiff*
|
|
|
|
Opens a vertical split diff The current wiki's <revision no>. If theres
|
|
no argument supplied it will be the previous revision.
|
|
|
|
|
|
================================================================================
|
|
5. Trac Ticket View *trac-ticket-view*
|
|
|
|
The Trac ticket view is you browse trac tickets
|
|
|
|
Opening
|
|
|
|
:TTOpen [optional_ticket_id] *:TTOpen*
|
|
|
|
Browsing
|
|
|
|
You can scroll up and down the ticket list. Pressing enter will load the
|
|
ticket id under the cursor.
|
|
|
|
|
|
5.1 Ticket Filters *trac-ticket-filters*
|
|
|
|
:TTFilterMilestone [Milestone] *:TTFilterMilestone*
|
|
:TTFilterType [Type] *:TTFilterType*
|
|
:TTFilterStatus [Status] *:TTFilterStatus*
|
|
:TTFilterResolution [Resolution *:TTFilterResolution*
|
|
:TTFilterPriority [Priority] *:TTFilterPriority*
|
|
:TTFilterSeverity [Severity] *:TTFilterSeverity*
|
|
:TTFilterComponent [Component] *:TTFilterComponent*
|
|
:TTFilterOwner [Owner] *:TTFilterOwner*
|
|
|
|
For filtering on respective ticket attributes. Allows a tab complete option
|
|
for Filter acts as a whitelist ignoring all other tickets not matching the
|
|
attribute
|
|
|
|
:TTIgnoreMilestone [Milestone] *:TTIgnoreMilestone*
|
|
:TTIgnoreType [Type] *:TTIgnoreType*
|
|
:TTIgnoreStatus [Status] *:TTIgnoreStatus*
|
|
:TTIgnoreResolution [Resolution *:TTIgnoreResolution*
|
|
:TTIgnorePriority [Priority] *:TTIgnorePriority*
|
|
:TTIgnoreSeverity [Severity] *:TTIgnoreSeverity*
|
|
:TTIgnoreComponent [Component] *:TTIgnoreComponent*
|
|
:TTIgnoreOwner [Owner] *:TTIgnoreOwner*
|
|
|
|
The Opposite of TTFilter... acts as a blacklist filter on tickets.
|
|
|
|
:TTIgnoreNoMilestone [NoMilestone] *:TTIgnoreNoMilestone*
|
|
:TTIgnoreNoOwner [NoOwner] *:TTIgnoreNoOwner*
|
|
:TTFilterNoMilestone [NoMilestone] *:TTFilterNoMilestone*
|
|
:TTFilterNoOwner [NoOwner] *:TTFilterNoOwner*
|
|
|
|
Special filters for tickets not owned or categorised
|
|
|
|
:TTClearAllFilters *:TTClearAllFilters*
|
|
Resets the filter list to blank
|
|
:TTClearFilter [filter no] *:TTClearFilter*
|
|
Filter numbers and descriptions are displayed at the top of the ticket
|
|
list. Using this filter will remove the filter number
|
|
:TTListFilters *:TTListFilters*
|
|
|
|
5.1.2 Ticket Sorting *trac-ticket-sorting*
|
|
|
|
:TTSortby [sort_option] *:TTSortby*
|
|
|
|
Tickets can either be sorted according to milestone or priority. Milestones
|
|
will appear in order of due date and ticket priority is arranged according
|
|
to the trac-admin priority settings.
|
|
|
|
5.2. Adding Comments *trac-ticket-comments*
|
|
|
|
The TICKET_COMMENT window is for adding comments. To commit a comment write
|
|
the message first and then type
|
|
|
|
:TTAddComment *:TTAddComment*
|
|
|
|
5.3. Changing ticket states *trac-ticket-changes*
|
|
|
|
Trac current ticket option modifications (use tab complete)
|
|
|
|
:TTSetMilestone [Milestone] *:TTSet*
|
|
:TTSetType [Type]
|
|
:TTSetStatus [Status]
|
|
:TTSetResolution [Resolution]
|
|
:TTSetPriority [Priority]
|
|
:TTSetSeverity [Severity]
|
|
:TTSetComponent [Component]
|
|
:TTSetSummary [Summary]
|
|
|
|
The setting will immediately be sent to the server.
|
|
|
|
|
|
:TTUpdateDescrption *:TTUpdateDescrption*
|
|
|
|
Takes the text from the TICKET_COMMENT_WINDOW and updates a tickets
|
|
description. It will prompt for confirmation before committing
|
|
|
|
5.4. Creating Tickets *trac-ticket-create*
|
|
|
|
This is still a bit of a hack. If you add a description in the
|
|
TICKET_COMMENT window and type the command
|
|
|
|
:TTCreateTask [ticket_summary] *TTCreateTask*
|
|
:TTCreateDefect [ticket_summary] *TTCreateDefect*
|
|
:TTCreateEnhancement [ticket_summary] *TTCreateEnhancement*
|
|
|
|
A new ticket will be created with the default attributes (set in trac.ini).
|
|
When creating a ticket you can create a description initially in the
|
|
TICKET_COMMENT_WINDOW or alternatively you can add a description later
|
|
using |TTUpdateDescrption|.
|
|
|
|
5.5. Adding/Retrieving attachments *trac-ticket-attachments*
|
|
|
|
:TTAddAttachment [file_path] *TTAddAttachment*
|
|
|
|
Adds a ticket to the current open ticket
|
|
:TTGetAttachment [file]
|
|
|
|
Retrieves an atteched file and saves it to the current working directory.
|
|
File options for the current ticket may be viewed with <tab> completion.
|
|
|
|
5.6. Ticket Sessions *trac-ticket-session*
|
|
|
|
It's possible to associate a list of open files with a trac ticket on the
|
|
local server which can be handy for reopening tickets another day to make
|
|
further changes.
|
|
|
|
Note: the plugin needs a directory to write to by default it is
|
|
let g:tracSessionDirectory = expand ('$HOME') . '/.vimtrac_session'
|
|
|
|
TTSaveTicketSession *TTSaveTicketSession*
|
|
Saves the open files and line numbers to the active ticket. You must
|
|
have a ticket open in the ticket view for this to take effect.
|
|
|
|
TTLoadTicketSession *TTLoadTicketSession*
|
|
|
|
Loads the Tickets Session information
|
|
|
|
5.7. Exiting
|
|
|
|
:TClose
|
|
|
|
or :q<cr> in either of the Ticket windows will close the view
|
|
|
|
================================================================================
|
|
6. Trac Search View *trac-search-view*
|
|
|
|
*TSearch*
|
|
:TSearch [search_term]
|
|
|
|
Opening Trac Search View
|
|
|
|
Will open search view containing matching wiki/ticket/changesets along with
|
|
basic descrriptions
|
|
|
|
:TClose will close this view or a ticket/wiki view will open if an item is
|
|
selected
|
|
|
|
================================================================================
|
|
7. Changeset View *trac-changeset-view*
|
|
|
|
:TChangesetOpen [changeset_id] *:TChangesetOpen*
|
|
|
|
opens a unified diff changeset view in a split window
|
|
|
|
You can also open a changeset by pressing <enter> on a matching
|
|
Changeset:>> line in the Trac Seatch window
|
|
|
|
================================================================================
|
|
8. Timeline View *trac-timeline-view*
|
|
|
|
Timeline view requires feedparser.py installed.
|
|
|
|
http://www.feedparser.org/
|
|
|
|
The timeline view grabs the rss feed from a trac server.
|
|
|
|
:TTimelineOpen *:TTimelineOpen*
|
|
|
|
You can also open tickets, wikis and changesets by pressing <enter> on a
|
|
matching Changeset:>>, Wiki:>> and Ticket:>> line
|
|
================================================================================
|
|
9. Trac Wiki Formatting *trac-format*
|
|
|
|
This reference is based on the trac wiki information provided with trac.
|
|
(WikiFormatting) Made easier to read within vim. I'd suggest you read the
|
|
document in your browser and use this as a quick refresher
|
|
|
|
Access this file with :TWikiFormat
|
|
|
|
|
|
Wiki markup is a core feature in Trac, tightly integrating all the other
|
|
parts of Trac into a flexible and powerful whole.
|
|
|
|
Trac has a built in small and powerful wiki rendering engine. This wiki
|
|
engine implements an ever growing subset of the commands from other popular
|
|
Wikis, especially [http://moinmoin.wikiwikiweb.de/ MoinMoin].
|
|
|
|
|
|
This page demonstrates the formatting syntax available anywhere
|
|
WikiFormatting is allowed.
|
|
|
|
|
|
9.1 Font Styles *trac-format-font*
|
|
|
|
The Trac wiki supports the following font styles:
|
|
{{{
|
|
* '''bold''', '''!''' can be bold too''', and '''! '''
|
|
* ''italic''
|
|
* '''''bold italic'''''
|
|
* __underline__
|
|
* {{{monospace}}} or `monospace`
|
|
* ~~strike-through~~
|
|
* ^superscript^
|
|
* ,,subscript,,
|
|
}}}
|
|
|
|
|
|
9.1 Notes: *trac-format-notes*
|
|
|
|
`{{{...}}}` and {{{`...`}}} commands not only select a monospace font, but
|
|
also treat their content as verbatim text, meaning that no further wiki
|
|
processing is done on this text.
|
|
|
|
{{{ ! }}} tells wiki parser to not take the following characters as wiki
|
|
format, so pay attention to put a space after !, e.g. when ending bold.
|
|
|
|
9.2 Headings *trac-format-headings*
|
|
|
|
You can create heading by starting a line with one up to five ''equal''
|
|
characters ("=") followed by a single space and the headline text. The line
|
|
should end with a space followed by the same number of ''='' characters.
|
|
The heading might optionally be followed by an explicit id. If not, an
|
|
implicit but nevertheless readable id will be generated.
|
|
|
|
Example:
|
|
{{{
|
|
= Heading =
|
|
== Subheading ==
|
|
=== About ''this'' ===
|
|
=== Explicit id === #using-explicit-id-in-heading
|
|
}}}
|
|
|
|
9.3 Paragraphs *trac-format-paragraphs*
|
|
|
|
A new text paragraph is created whenever two blocks of text are separated
|
|
by one or more empty lines.
|
|
|
|
A forced line break can also be inserted, using:
|
|
{{{
|
|
Line 1[[BR]]Line 2
|
|
}}}
|
|
|
|
|
|
9.4 Lists *trac-format-lists*
|
|
|
|
The wiki supports both ordered/numbered and unordered lists.
|
|
|
|
Example:
|
|
{{{
|
|
* Item 1
|
|
* Item 1.1
|
|
* Item 2
|
|
|
|
1. Item 1
|
|
a. Item 1.a
|
|
a. Item 1.b
|
|
i. Item 1.b.i
|
|
i. Item 1.b.ii
|
|
1. Item 2
|
|
And numbered lists can also be given an explicit number:
|
|
3. Item 3
|
|
}}}
|
|
|
|
Note that there must be one or more spaces preceding the list item markers,
|
|
otherwise the list will be treated as a normal paragraph.
|
|
|
|
|
|
9.4 Definition Lists *trac-format-definition*
|
|
|
|
The wiki also supports definition lists.
|
|
|
|
Example:
|
|
{{{
|
|
llama::
|
|
some kind of mammal, with hair
|
|
ppython::
|
|
some kind of reptile, without hair
|
|
(can you spot the typo?)
|
|
}}}
|
|
|
|
Note that you need a space in front of the defined term.
|
|
|
|
|
|
9.5 Preformatted Text *trac-format-preformatted*
|
|
|
|
Block containing preformatted text are suitable for source code snippets,
|
|
notes and examples. Use three ''curly braces'' wrapped around the text to
|
|
define a block quote. The curly braces need to be on a separate line.
|
|
|
|
Example:
|
|
{{{
|
|
{{{
|
|
def HelloWorld():
|
|
print "Hello World"
|
|
}}}
|
|
}}}
|
|
|
|
9.6 Blockquotes *trac-format-blockquotes*
|
|
|
|
In order to mark a paragraph as blockquote, indent that paragraph with two
|
|
spaces.
|
|
|
|
Example:
|
|
{{{
|
|
This text is a quote from someone else.
|
|
}}}
|
|
|
|
9.7 Discussion Citations *trac-format-discussion*
|
|
|
|
To delineate a citation in an ongoing discussion thread, such as the ticket
|
|
comment area, e-mail-like citation marks (">", ">>", etc.) may be used.
|
|
|
|
Example:
|
|
{{{
|
|
>> Someone's original text
|
|
> Someone else's reply text
|
|
My reply text
|
|
}}}
|
|
|
|
|
|
''Note: Some WikiFormatting elements, such as lists and preformatted text,
|
|
are lost in the citation area. Some reformatting may be necessary to
|
|
create a clear citation.''
|
|
|
|
9.8 Tables *trac-format-tables*
|
|
|
|
Simple tables can be created like this:
|
|
{{{
|
|
||Cell 1||Cell 2||Cell 3||
|
|
||Cell 4||Cell 5||Cell 6||
|
|
}}}
|
|
|
|
Note that more complex tables can be created using
|
|
[wiki:WikiRestructuredText#BiggerReSTExample reStructuredText].
|
|
|
|
|
|
9.9 Links *trac-format-links*
|
|
|
|
Hyperlinks are automatically created for WikiPageNames and URLs.
|
|
!WikiPageLinks can be disabled by prepending an exclamation mark "!"
|
|
character, such as {{{!WikiPageLink}}}.
|
|
|
|
Example:
|
|
{{{
|
|
TitleIndex, http://www.edgewall.com/, !NotAlink
|
|
}}}
|
|
|
|
Links can be given a more descriptive title by writing the link followed by
|
|
a space and a title and all this inside square brackets. If the
|
|
descriptive title is omitted, then the explicit prefix is discarded, unless
|
|
the link is an external link. This can be useful for wiki pages not
|
|
adhering to the WikiPageNames convention.
|
|
|
|
Example:
|
|
{{{
|
|
* [http://www.edgewall.com/ Edgewall Software]
|
|
* [wiki:TitleIndex Title Index]
|
|
* [wiki:ISO9000]
|
|
}}}
|
|
|
|
9.9.1 Trac Links *trac-format-traclinks*
|
|
|
|
Wiki pages can link directly to other parts of the Trac system. Pages can
|
|
refer to tickets, reports, changesets, milestones, source files and other
|
|
Wiki pages using the following notations:
|
|
|
|
{{{
|
|
* Tickets: #1 or ticket:1
|
|
* Reports: {1} or report:1
|
|
* Changesets: r1, [1] or changeset:1
|
|
* ...
|
|
}}}
|
|
|
|
See TracLinks for more in-depth information.
|
|
|
|
|
|
9.10 Escaping Links and WikiPageNames *trac-format-nolink*
|
|
|
|
You may avoid making hyperlinks out of TracLinks by preceding an expression
|
|
with a single "!" (exclamation mark).
|
|
|
|
Example:
|
|
{{{
|
|
!NoHyperLink
|
|
!#42 is not a link
|
|
}}}
|
|
|
|
9.11 Images *trac-format-images*
|
|
|
|
Urls ending with `.png`, `.gif` or `.jpg` are no longer automatically
|
|
interpreted as image links, and converted to `<img>` tags.
|
|
|
|
You now have to use the ![[Image]] macro (see below).
|
|
|
|
|
|
9.12 Macros *trac-format-macros*
|
|
|
|
Macros are ''custom functions'' to insert dynamic content in a page.
|
|
|
|
Example:
|
|
{{{
|
|
[[Timestamp]]
|
|
}}}
|
|
|
|
|
|
See WikiMacros for more information, and a list of installed macros.
|
|
|
|
|
|
9.13 Processors *trac-format-processors*
|
|
|
|
Trac supports alternative markup formats using WikiProcessors. For example,
|
|
processors are used to write pages in
|
|
[wiki:WikiRestructuredText reStructuredText] or [wiki:WikiHtml HTML].
|
|
|
|
Example 1:
|
|
{{{
|
|
#!html
|
|
<pre class="wiki">{{{
|
|
#!html
|
|
<h1 style="text-align: right; color: blue">HTML Test</h1>
|
|
}}}</pre>
|
|
}}}
|
|
|
|
Example:
|
|
{{{
|
|
#!html
|
|
<pre class="wiki">{{{
|
|
#!python
|
|
class Test:
|
|
|
|
def __init__(self):
|
|
print "Hello World"
|
|
if __name__ == '__main__':
|
|
Test()
|
|
}}}</pre>
|
|
}}}
|
|
|
|
|
|
Perl:
|
|
{{{
|
|
#!perl
|
|
my ($test) = 0;
|
|
if ($test > 0) {
|
|
print "hello";
|
|
}
|
|
}}}
|
|
|
|
See WikiProcessors for more information.
|
|
|
|
|
|
9.14 Miscellaneous *trac-format-misc*
|
|
|
|
Four or more dashes will be replaced by a horizontal line (<HR>)
|
|
|
|
Example:
|
|
{{{
|
|
----
|
|
}}}
|
|
|
|
See also: TracLinks, TracGuide, WikiHtml, WikiMacros, WikiProcessors,
|
|
TracSyntaxColoring.
|