*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 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 on a page will open the selected page in the WIKI_WINDOW Pressing 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 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 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 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 or :w which I've mapped to perform the TWSave? command. Exiting Trac Wiki View Exiting is done by either the command :TClose, :wq or :q in either of the wiki windows 4.5 Wiki Vim Diffs *trac-wiki-diff* :TWVimDiff *:TWVimDiff* Opens a vertical split diff The current wiki's . 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 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 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 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 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 `` 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 
{{{
    #!html
    <h1 style="text-align: right; color: blue">HTML Test</h1>
    }}}
}}} Example: {{{ #!html 
{{{
    #!python
    class Test:

        def __init__(self):
            print "Hello World"
    if __name__ == '__main__':
       Test()
    }}}
}}} 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 (
) Example: {{{ ---- }}} See also: TracLinks, TracGuide, WikiHtml, WikiMacros, WikiProcessors, TracSyntaxColoring.