Skip to content

Latest commit

 

History

History
1891 lines (1254 loc) · 71.8 KB

riv_instruction.rst

File metadata and controls

1891 lines (1254 loc) · 71.8 KB
Raw

Riv: Instruction

Author: Rykka G.F
Update:2014-08-09
Version: 0.77
Github:https://github.com/Rykka/riv.vim
  • Index:
    • 1 Instructions : Detailed Instructions
      • 1.1 Vim : Vim Improved Feature
        • 1.1.1 Folding : Overview the structure.
        • 1.1.2 Syntax : Extra highlighting.
        • 1.1.3 Indent : Smarter indent.
        • 1.1.4 Insert : Speed up the input!
      • 1.2 RST : Better RST Supporting
        • 1.2.1 Sections : Easy create, easy view.
        • 1.2.2 Lists : Auto numbered, auto leveled and auto indented.
        • 1.2.3 Links : Jumping and Highlighting.
        • 1.2.4 Table : Auto formatted.
        • 1.2.5 Publish : Convert to html/xml/latex/odt...
      • 1.3 Riv : Management by Riv
        • 1.3.1 Sphinx : Working with Sphinx.
        • 1.3.2 Project : A workspace for your documents.
        • 1.3.3 File : Link local file in the document.
        • 1.3.4 Scratch : Writing notes and diaries.
        • 1.3.5 Todos : Keep track of todo things.
        • 1.3.6 Helpers : Help work with document/project.
    • 2 Appendix : Extra Infomations
      • 2.1 Commands : Commands and Mappings.
      • 2.2 Options : Options and Settings.

Instructions

This is the detailed Instruction for Riv.

To View the Riv Intro , Use :RivIntro

Vim

Following features are improved with vim built-in one.

Folding

Folding is a vim feature.

It shows a range of lines as a single line. Thus you can get a better overview of the document structures.

And you can operate the folded lines with one line actions, like: select(V), copy(yy), paste(p) ... Etc.

See :h folding for more infos.

With Riv, Sections, lists, and blocks are folded automatically, And extra infos are provided.

  • Commands:

    Normal Mode

    These 'z' folding commands can be used. Like 'zo' 'zc' ...

    Also extra commands are provided.

    • Open/Close Folding: zo, zc, zM, zR

    • Update Folding: zx

      And foldings will be auto updated whilst writing buffer to file, :write or :update.

      You can disable it by setting 'g:riv_fold_auto_update' to 0.

      NOTE:

      When you write to a file without updating folding, Previous folding structure of the document will be breaked. Manual updating is needed.

      So use it with caution.
      NOTE:

      When document's folding stucked, you can use :RivReload or <C-E>t` to reload document and the folding.

    • Toggle Folding: za, zA...

      You can define your own mappings for folding in your vimrc, I use <Space><Space> to toggle folding:

      nno <silent> <Space><Space> @=(foldclosed('.')>0?'zv':'zc')<CR>

    • Toggle folding with Cursor.

      Pressing <Enter> or double clicking on folded lines will open the fold. Like zo

      Pressing <Enter> or double clicking on section heading will close the fold of the section. Like zc

  • Extra Infos:

    Some extra info of folded lines will be shown at the first line. And the number of folded lines will be shown.

    • Folded Sections will show it's section number.
    • Folded Todos will show the Todo progress in percentage.
    • Folded Table will show number of rows and columns.
    • 'g:riv_fold_info_pos' can be used to change info's position.

  • Extra Options:

Syntax

Improved highlights for syntax items.

  • File Link are highlighted.
    • normal style: xxx.rst_
    • extension style: xxx.rst xxx.vim
    • moinmoin style: [[xxx]] [[xxx.vim]]
    • Sphinx style: :doc:`xxx` :download:`xxx.vim`
  • Todos Item are highlighted.
  • You can use :set spell for spell checking, and spell is on in Literal-Block.
Code Highlighting

For the code directives (also sourcecode and code-block). Syntax highlighting of Specified languages are on

.. code:: python

    # python highlighting
    # github does not support syntax highlighting rendering for rst file yet.
    x = [0 for i in range(100)]

There are code block indicator for every code directives, It's first column of the line in code block are highlighted to indicate it's a code block.

You can disable it by setting g:riv_code_indicator to 0.

The highlights directives in Sphinx could also be used to highlight big block of codes.

.. highlights:: python

x = [0 for i in range(100)]

.. highlights::
NOTE:

To highlighting codes in converted file, pygments package must installed for docutils to parse syntax highlighting.

See http://docutils.sourceforge.net/sandbox/code-block-directive/tools/pygments-enhanced-front-ends/
Cursor Highlighting

Some item that could operate by cursor are highlighted when cursor is on.

  • Links are highlighted in hl-incSearch
  • Todo items are highlighted in hl-DiffAdd

You can disable Cursor Highlighting by set 'g:riv_link_cursor_hl' to 0

Docstring Highlighting

For python files. DocString can be highlighted using reStructuredText.

You can enable it by setting g:riv_python_rst_hl to 1.

Also you can set the file type to rst to gain riv features in python file.

set ft=rst

Indent

Smarter indent in insert mode.

As indenting in reStructuredText is complicated. Riv will fixed indent for lines in the context of blocks, list, explicit marks.

If no fix is needed, shiftwidth will be used for the indenting.

  • Commands:

    Normal

    • > and < will indent with fixed indent.

      To use original shiftwidth indent.

      Use <C-E>> and <C-E><

    Insert

    • Newline (<Enter> or o in Normal mode): will start newline with fixed indentation
    • <BS> (Backspace key) and <S-Tab> . Will use fixed indentation if no preceding non-whitespace character, otherwise <BS>
    • <Tab> (Tab key). Will use fixed indentation if no preceding non-whitespace character, otherwise <Tab>

Insert

Super <Tab> and Super <Enter> in insert mode.

  • Enter and KEnter (Keypad Enter) (with modifier 'Ctrl' and 'Shift'):

    • When in a grid table: creating table lines.

      See Table for details.

    • When in a list context: creating list lines.

      See Lists for details.

  • Tab and Shift-Tab:

    • If insert-popup-menu is visible, will act as <C-N> or <C-P>

      Disable it by setting 'g:riv_i_tab_pum_next' to 0.

    • When in a table , <Tab> to next cell , <S-Tab> to previous one.

    • When not in a table,

      • If it's a list, and cursor is before the list item, will shift the list.

      • if have fixed indent, will indent with fixed indent. See indent.

      • Otherwise:

        • if 'g:riv_i_tab_user_cmd' is not empty , executing it.

          It's for users who want different behavior with <Tab>:

          " For snipmate user.
let g:riv_i_tab_pum_next = 0
" quote cmd with '"', special key must contain '\'
let g:riv_i_tab_user_cmd = "\<c-g>u\<c-r>=snipMate#TriggerSnippet()\<cr>"

        • else act as <Tab> and <BS>.

    NOTE:<S-Tab> is acting as <BS> when not in list or table .

  • Backspace: indent with fixed indent. See indent.

  • Most commands can be used in insert mode. Like <C-E>ee <C-E>s1 ...

NOTE:

To disable mapping of <Tab> etc. in insert mode.

Set it in 'g:riv_ignored_imaps' , each item is split with ,.

" no <Tab> and <S-Tab>
let g:riv_ignored_imaps = "<Tab>,<S-Tab>"

You can view default mappings with 'g:riv_default.buf_imaps'

RST

Following features are for all document which filetype is rst. And are all standard reStructuredText syntax.

Sections

Section level and numbers are auto detected.

And it's folded by it's level.

  • Commands:

    Normal and Insert Mode

    • Create and Modify titles:

      Use :RivTitle1 <C-E>s1 ... :RivTitle6 <C-E>s6 , To create level 1 to level 6 section title from current word.

      If the line empty, you will be asked to input a title.

      And :RivTitle0 <C-E>s0 will create a section title with an overline.

      Other commands is underline only.

      Riv use following punctuations for titles:

      = - ~ " ' ` , (HTML has 6 levels)

      You can change it with 'g:riv_section_levels'

      The :RivTitle0 will use #

      NOTE:Keep in mind sub titles should be one level deeper than current one.

    • Folding:

      Pressing <Enter> or double clicking on the section title will toggle the folding of the section.

      The section number will be shown when folded.

    • Jumping:

      <Enter> or Clicking on the section reference will bring you to the section title.

      E.g.: click the link of Lists will bring you to the Lists Section (in vim)

    • Create a content table:

      Use :RivCreateContent or <C-E>ic to create it.

      It's similar with the content directive, except it create the content table into the document.

      The advantage is you can jumping with it in vim, and have full control of it.

      The disadvantage is you must update it every time after you have changed the document structure.

      You can set 'g:riv_content_format' to change it's format.

  • Extra Options:

See reStructuredText sections for syntax details.

  • Misc:

    For convenience, Page-break ^L (Ctrl-L in insert mode) was made to break current section in vim, works like transitions.

Lists

There are several types of list items in reStructuredText.

They are highlighted. Some are folded.

  • Auto Leveled:

    Bullet and enumerated list.

    When you shift the list or add child/parent list , the type of list item will be changed automatically.

    The level sequence is as follows:

    * + - 1. A. a. I. i. 1) A) a) I) i) (1) (A) (a) (I) (i)

    You can use any of them as a list item, but the changing sequence is hard coded.

    This means when you shift right or add a child list with a - list item, the new one will be 1.

    And if you shift left or add a parent list item with a a. list item , the new one will be A.

  • Auto Numbered:

    Bullet and enumerated list.

    When you adding a new list or shifting an list, these list items will be auto numbered.

  • Auto Indented:

    Bullet and enumerated list and field list.

    When you adding a new list or shifting an list, these list items will be auto indented.

  • Commands:

    • Shifting:

      Normal and Visual Mode

      • Shift right: > :RivShiftRight or <C-ScrollWheelDown>(UNIX only)

        Shift rightwards with ShiftWidth

        If it's a list item, it will indent to the list item's sub list

      • Shift left: < :RivShiftLeft or <C-ScrollWheelUp>(UNIX only)

        Shift leftwards with ShiftWidth

        If it's a list item, it will indent to the list item's parent list

      • Format: = Format list's level and number.

      • To act as the vim's original < > and =, just preceding a <C-E>, as <C-E>< , <C-E>> and <C-E>=

        Also <S-ScrollWheelDown> and <S-ScrollWheelUp> can be used in UNIX

      Tips:

      To make shifting with mouse more easier.

      You should make sure the vim option 'selectmode' not contain mouse, in order to use mouse to start visual mode, not select mode As commands not working in Select Mode.

      And this option will be reset by :behave mswin. So you should put it behind that.

      Insert Mode

      • <Tab> when cursor is before the list's content will shift right.
      • <S-Tab> when cursor is before the list's content. Will shift left.
      NOTE:

      As this will break the <Tab> inserting operation in visual-block insert.

      You should use <Space> instead of <Tab>

      or use visual-block replace See :h v_b_i and :h v_b_r

    • New List:

      Insert Mode Only. Note that some terminals pass <C-CR> and <S-CR> as different (or indistinguishable) mappings, so the alternative key mapping should be used.

      • <CR>\<KEnter> (enter key and keypad enter key) Insert the content of this list.

        To insert content in new line of this list item. Add a blank line before it.

      • <C-CR>\<C-KEnter> or <C-E>ln Insert a new list of current list level

      • <S-CR>\<S-KEnter> or <C-E>lb Insert a new list of current child list level

      • <C-S-CR>\<C-S-KEnter> or <C-E>lp Insert a new list of current parent list level

      • When it's a field list, only the indent is inserted.

    • Change List Type:

      Normal and Insert Mode:

      • :RivListType0 <C-E>l1 ... :RivListType4 <C-E>l5 Change or add list item symbol of type.

        The list item of each type is:

        '*' , '1.' , 'a.' , 'A)' ,'i)'
        NOTE:

        You should act this on a new list or list with no sub line.

        As list item changes, the indentation of it is changed. But this action does not change the sub item's indent.

        To change a list and it's sub item with indentation fix , use shifting: > or <.

      • :RivListDelete <C-E>lx Delete current list item symbol

Links

You can jumping with links.

And it's highlighted with Cursor Highlighting.

  • Commands:

    Jumping(Normal Mode):

    • Clicking on a links will jump to it's target.

      <Enter>/<KEnter> or double click or <C-E>ko

      • A web link ( www.xxx.xxx or http://xxx.xxx.xxx or xxx@xxx.xxx ):

        Open web browser.

        And if it's an email address xxx@xxx.xxx, mailto: will be added.

        Web browser is set by 'g:riv_web_browser'.

      • A internal reference ( xxx_ [xxx]_ `xxx`_ ):

        Find and Jump to the target.

        If it's an anonymous reference xxx__,

        Will jump to the nearest anonymous target.

      • A internal targets (.. [xxx]: .. _xxx:)

        Find and Jump to the nearest backward reference.

      • A local file (if 'g:riv_file_link_style' is not 0):

        Like (xxx.vim or [[xxx/xxx]])

        Edit the file.

        To split editing: As no split editing commands were defined, you should split document first: <C-W><C-S> or <C-W><C-V>

    • You can jump back to origin position with `` or ''

    Navigate(Normal Mode):

    • Navigate to next/previous link in document.

      <Tab>/<S-Tab> or <C-E>kn/<C-E>kp

    Create (Normal and Insert):

    • :RivCreateLink <C-E>ik create a link from current word.

      If it's empty, you will be asked to input one.

      If the link is not Anonymous References, The target will be put at the end of file by default.

      'g:riv_create_link_pos' can be used to change the target postion.

    • :RivCreateFoot <C-E>if create a auto numbered footnote. And append the footnote target to the end of file.

Table

Tables are highlighted and folded.

For Grid table, it is auto formatted.

  • Grid Table:

    Highlighted and Folded. When folded, the numbers of rows and columns will be shown as '3x2'

    Will be auto formated. Only support equal columns each row (no span). Disable auto-formatting by setting 'g:riv_auto_format_table' to 0.

    • Commands:

      • Create: Use `<C-E>tc or :RivTableCreate to create table

      • Format: Use <C-E>tf or :RivTableFormat to format table.

        It will be auto formatted after leaving insert mode, or pressing <Enter> or <Tab> in insert mode.

      Insert Mode Only:

      • Inside the Table

         

        Grid Table (No column or row span supported yet)

        Lines
        • <Enter> in column to add a new line
        • This is the second line of in same row of table.

        Rows
        • <C-Enter> to add a separator and a new row
        • <C-S-Enter> to add a header seperator and a new row (There could be only one header seperator in a table)
        • <S-Enter> to jump to next line

        Cell
        • <C-E>tn or <Tab> or RivTableNextCell, jump to next cell
        • <C-E>tp or <S-Tab> or RivTablePrevCell, jump to prev cell

        Multi
        • Multi Byte characters are OK
        • 一二三四五 かきくけこ

      See Grid Tables for syntax details.

      NOTE:

      As visual-block insert be overrided and could not be used in a table.

      You can use visual-block Replace instead. see :h v_b_r

  • Simple Table:

    Highlighted and folded. When folded, the numbers of rows and columns will be shown as '3+2'

    No auto formatting.

    A Simple Table

    Col 1

    Col 2

    1

    row 1

    2

    row 2

    3
    • first line row 3
    • second line of row 3

    See Simple Tables for syntax details.

Publish

Convert rst files to html/xml/latex/odt/... (Some command wrapper, docutils required)

  • Commands:

  • Options:

    • If you have installed Pygments , code will be highlighted in html , as the syntax highlight style sheet have been embedded in it by Riv.

      You can change the style sheet with 'g:riv_html_code_hl_style'

      • Syntax highlight for other formatting are not supported yet.

    • Some misc changing have been done on the style sheet for better view in html.

      The literal and literal-block's background have been set to '#eeeeee'.

    • To add some args while converting.

      g:riv_rst2html_args , g:riv_rst2latex_args and Etc. can be used.

    • Output files path

      • For the files that are in a project. The path of converted files by default is under build_path of your project directory.

        1. Default is _build

        2. To change the path. Set it in your vimrc:

          " Assume you have a project name project 1
let project1.build_path = '~/Documents/Riv_Build'

        3. Open the build path: :Riv2BuildPath <C-E>2b

        4. Local file link converting will be done. See local file link converting for details.

        5. Set g:riv_auto_rst2html to 1 to automatic convert after writing. only project file are auto converted.

      • For the files that not in a project. 'g:riv_temp_path' is used to determine the output path

NOTE:

When converting, It will first try rst2xxxx2.py , then try rst2xxxx.py

You'd better install the package of python 2 version.

And make sure it's in your $PATH

Otherwise errors may occur as py3 version uses 'bytes'.

Riv

Following features provides more functions for rst documents.

  • You can change some setting for a better working with Sphinx.
  • Project, Scratch, Helpers are extra function for managing rst documents.
  • File, Todos are extended syntax items for writing rst document.

Sphinx

Riv can work with Sphinx (see Sphinx Home ).

  • For now, you can use Cross-referencing document :doc:`xxx` and downloadable file :download:`xxx` to jump to that document. With setting g:riv_file_link_style to 2.

    The Cross-referencing arbitrary locations :ref:`xxx` are not supported yet.

  • To work with other master_doc and source_suffix, like 'main.txt' instead of 'index.rst'

    Define the global 'g:riv_master_doc' and 'g:riv_source_suffix' or define 'master_doc' and 'source_suffix' in your project.

  • There are no wrapper for making command of Sphinx. You should use :make html by your own.

    And you can view the index page by :RivProjectHtmlIndex or <C-E>wi

Project

Project is a place to hold your rst documents.

Though you can edit reStructuredText documents anywhere. There are some convenience with projects.

File
Write documents and navigating with local file link.
Publish
Convert whole project to html, and view them as wiki.
Todos
Manage all the todo items in a project
Scratch
Writing diary in a project

  • Global Commands:

  • All projects are in g:riv_projects,

    • Define a project with a dictionary of options, If not defined, it will have the default value

      let project1 = { 'Name': 'My Working Notes', 'path': '~/Dropbox/rst',}
let g:riv_projects = [project1]

    • To add multiple projects

      let project2 = { 'path': '~/Dropbox/rst2',}
let g:riv_projects = [project1, project2]

    • if you are editing a rst document outside a project.

      It's settings will using the first one.

File

The link to edit local files. non-reStructuredText syntax

As reStructuredText haven't define a pattern for local files currently.

Riv provides some convenient way to link to other local files in the rst documents.

  • For linking with local file in vim easily, The filename with extension , like xxx.rst ~/Documents/xxx.py, will be highlighted and linked, only in vim.

    And you can disable highlighting it with setting 'g:riv_file_ext_link_hl' to 0.

  • Using Rst's default HyperLink syntax to link local files.

    xxx.rst_
Dir

.. _xxx.rst: xxx.rst
.. _Dir: Dir/index.rst

    The :RivCreateLink (<C-E>ck) command are optimized to simplify working with them.

    You can type a xxx.rst or Dir/ then use the command to make a link.

    For Simpify using, The local file links with g:riv_file_link_ext will be auto opened in vim with <2-Leftmouse>, <CR> and :RivLinkOpen if g:riv_open_link_location is set to 1.

    You can use :RivLinkShow to move to the location only.

    Also, The xxx.rst will be changed to xxx.html when convert to html

  • WARNING! This method is deprecated! Use rst's normal link

    Two types for linking file while converting to other format. (works for document in project only.)

    MoinMoin:

    use [[xxx]] to link to a local file.
    Sphinx:

    use :doc:`xxx` and :download:`xxx.rst` to link to local file and local document.

    See Sphinx_Role_Doc.

    It will be not changed to link with Riv. You'd better use it with Sphinx's tool set.

    • You can switch style with 'g:riv_file_link_style'

      • when set to 1, MoinMoin:

        Words like [[xxx]] [[xxx.vim]] will be detected as file link.

        Words like [[xxx/]]' will link to ``xxx/index.rst

        Words like [[/xxxx/xxx.rst]] will link to DOC_ROOT/xxx/xxx.rst

        Words like [[~/xxx/xxx.rst]] [[x:/xxx/xxx.rst]] will be considered as external file links

        Words like [[/xxxx/xxx/]] [[~/xxx/xxx/]] will be considered as external directory links, and link to the directory.

      • when set to 2, Sphinx:

        Words like :doc:`xxx.rst` :doc:`xxx.py` :doc:`xxx.cpp` will be detected as file link.

        NOTE: words like :doc:`xxx/` are illegal in sphinx, You should use :doc:`xxx/index` , and link to xxx/index.rst

        Words like :doc:`/xxxx/xxx.rst` will link to DOC_ROOT/xxxx/xxx.rst

        Words like :download:`~/xxx/xxx.py` :download:`/xxx/xxx.py` :download:`x:/xxx.rst` will be considered as external file links

        Words like :download:`~/xxx/xxx/` will be considered as external directory links, and link to the directory.

        You can add other extensions with 'g:riv_file_link_ext'.

      • when set to 0, no local file link.

      • default is 1.

    NOTE:

    Difference between extension and link style.

    The [[/xxx]] and :doc:`/xxx` are linked to Document Root DOC_ROOT/xxx.rst both with MoinMoin and sphinx style(?).

    But the /xxx/xxx.rst detected with extension will be linked to /xxx/xxx.rst in your disk

  • The file links are highlighted. See Cursor Highlighting

  • To delete a local file in project.

    :RivDeleteFile <C-E>df it will also delete all reference to this file in index.rst of the directory.

Local File Link Converting

As the local file link is not the default syntax in reStructuredText. The links need converting before Publish.

And it's only converted for rst file in a Project.

Those detected local file link will be converted to an embedded link. in this form:

`xxx.rst <xxx.html>`_ `xxx.py <xxx.py>`_
NOTE:

link converting in a table will make the table error format. So you'd better convert it to a link manually. Use :RivCreateLink or <C-E>ck to create it manually.

file.rst_

.. _file.rst:: file.html

For now it's overhead with substitute by a temp file. A parser for docutils is needed in the future.

And for Sphinx users. You should use Sphinx's tool set to convert it.

Scratch

Scratch is a place for writing diary or notes.

  • :RivScratchCreate <C-E>sc Create or jump to the scratch of today.

    Scratches are created auto named by date in '%Y-%m-%d' format.

  • :RivScratchView <C-E>sv View Scratch index.

    The index is auto created. Separate scratches by years and month

    You can change the month name using 'g:riv_month_names'.

Scratches will be put in scratch folder in project directory. You can change it with 'scratch_path' of project setting ,default is 'Scratch':

" Use another directory
let project1.scratch_path = 'Diary'
" Use absolute path, then no todo helper and no converting for it.
let project1.scratch_path = '~/Documents/Diary'

Todos

Todo items to keep track of todo things. non-reStructuredText syntax

It is Todo-box or Todo-keywords in a bullet/enumerated/field list.

  • Todo Box:

    • [ ] This is a todo item of initial state.
    • [o] This is a todo item that's in progress.
    • [X] This is a todo item that's finished.
    • You can change the todo box item by 'g:riv_todo_levels' ,

  • Todo Keywords:

    Todo Keywords are also supported

    • FIXED A todo item of FIXME/FIXED keyword group.
    • DONE 2012-06-13 ~ 2012-06-23 A todo item of TODO/DONE keyword group.
    • START A todo item of START/PROCESS/STOP keyword group.
    • You can define your own keyword group for todo items with 'g:riv_todo_keywords'

  • Date stamps:

    Todo item's start or end date.

    • [X] 2012-06-23 A todo item with date stamp

    • Double Click or <Enter> or :RivTodoDate on a date stamp to change date.

      If you have Calendar installed , it will use it to choose date.

    • It is controlled by 'g:riv_todo_datestamp'

      • when set to 0 , no date stamp
      • when set to 1 , no initial date stamp , will add a finish date stamp when it's done.
        1. [X] 2012-06-23 This is a todo item with finish date stamp,
      • when set to 2 , will initial with a start date stamp. And when it's done , will add a finish date stamp.
        1. [ ] 2012-06-23 This is a todo item with start date stamp
        2. [X] 2012-06-23 ~ 2012-06-23 A todo item with both start and finish date stamp.
      • Default is 1

  • Priorities:

    The Priorities of todo item

    • [ ] [#A] a todo item of priority A
    • [ ] [#C] a todo item of priority C
    • Double Click or <Enter> or :RivTodoPrior on priority item to change priority.
    • You can define the priority chars by 'g:riv_todo_priorities'

  • Actions:

    Add Todo Item

    Change Todo Status

    • Double Click or <Enter> in the box/keyword to switch the todo progress.

    Delete Item

    • Use :RivTodoDel <C-E>ex to delete the whole todo item

    Helper

  • Folding Info:

    When list is folded. The statistics of the child items (or this item) todo progress will be shown.

  • Highlights:

    Todo items are highlighted.

    As it's not the reStructuredText syntax. So highlighted in vim only.

    When cursor are in a Todo Item , current item will be highlighted.

Helpers

A window for helping project management.

  • Basic Commands:

    • / to enter search mode. Search item matching inputing, <Enter> or <Esc> to quit search mode.

      Set 'g:riv_fuzzy_help' to 1 to enable fuzzy searching in helper.

    • <Tab> to switch content,

    • <Enter> or Double Click to jump to the item.

    • <Esc> or q to quit the window

      Set 'g:riv_todo_helper_ignore_done' to 1 to ignore TODOs that are marked as DONE in the display.

Todo Helper

A helper to manage todo items of current project. When current document is not in a project, will show current file's todo items.

  • :RivHelpTodo or <C-E>ht Open Todo Helper. Default is in search mode.
File Helper

A helper to show rst files of current directory.

Also indicating following files if exists:

'ROOT': 'RT' Root of project
'INDX': 'IN' Index of current directory
'CURR': 'CR' Current file
'PREV': 'PR' Previous file
  • :RivHelpFile or <C-E>hf Open File Helper. Default is in normal mode.
Section Helper

A helper showing current document section numbers

  • :RivHelpSection or <C-E>hs Open Section Helper. Default is in normal mode.

Appendix

Commands

  • Default leader map for Riv is <C-E>. You can change it by 'g:riv_global_leader'

  • To remap a single mapping, use map in your vimrc:

    map <C-E>wi    :RivIndex<CR>

  • All commands can be executed by :{cmd}. For example: :RivIndex to open the default Project Index.

  • You can use menu to view the commands Shortcut either. :popup Riv Can be used when you not showing the menu bar.

  • Global

    • :RivProjectIndex : Open the default Riv project index in vim.

      Normal : <C-E>ww,<C-E><C-W><C-W>

    • :RivProjectList : Show Riv project list.

      Normal : <C-E>wa,<C-E><C-W><C-A>

    • :RivProjectHtmlIndex : Browse project html index.

      Normal : <C-E>wi,<C-E><C-W><C-I>

    • :RivScratchCreate : Create Or Edit Scratch of today.

      Normal : <C-E>sc,<C-E><C-S><C-C>

    • :RivScratchView : View The Index of Scratch Directory

      Normal : <C-E>sv,<C-E><C-S><C-V>

  • View

    • :RivFoldToggle : Toggle Fold

      Normal : <C-E><Space><Space>

    • :RivFoldAll : Toggle all folding

      Normal : <C-E><Space>a

    • :RivFoldUpdate : Update Folding

      Normal : <C-E><Space>u

    • :RivLinkOpen : Open Link under Cursor

      Normal : <C-E>ko

    • :RivLinkShow : Move cursor to the link target.

      Normal : <C-E>ks

    • :RivLinkNext : Jump to Next Link

      Normal : <C-E>kn,<TAB>

    • :RivLinkPrev : Jump to Prev Linx

      Normal : <C-E>kp,<S-TAB>

    • :RivShiftRight : Shift Right with level and indent adjustment.

      Normal,Visual : <C-E>l>,>,<C-ScrollwheelDown>

    • :RivShiftLeft : Shift Left with level and indent adjustment.

      Normal,Visual : <C-E>l<,<,<C-ScrollwheelUp>

    • :RivShiftEqual : Format List level

      Normal,Visual : <C-E>l=,=

    • :RivNormRight : Normal Shift Right

      Normal,Visual : <C-E>>,<S-ScrollwheelDown>

    • :RivNormLeft : Normal Shift Left

      Normal,Visual : <C-E><lt>,<S-ScrollwheelUp>

    • :RivNormEqual : Normal Equal

      Normal,Visual : <C-E>=

    • :RivItemClick : Open Link,Toggle item and toggle section folding

      Normal : <2-LeftMouse>

    • :RivItemToggle : Open Link, Toggle item

      Normal : <CR>,<KEnter>

  • Doc

    • :RivTitle1 : Create Type 1 Title

      Normal,Insert : <C-E>s1

    • :RivTitle2 : Create Type 2 Title

      Normal,Insert : <C-E>s2

    • :RivTitle3 : Create Type 3 Title

      Normal,Insert : <C-E>s3

    • :RivTitle4 : Create Type 4 Title

      Normal,Insert : <C-E>s4

    • :RivTitle5 : Create Type 5 Title

      Normal,Insert : <C-E>s5

    • :RivTitle6 : Create Type 6 Title

      Normal,Insert : <C-E>s6

    • :RivTitle0 : Create Type 0 Title

      Normal,Insert : <C-E>s0

    • :RivTableCreate : Create a Table

      Normal,Insert : <C-E>tc

    • :RivTableFormat : Format table

      Normal,Insert : <C-E>tf

    • :RivTableNextCell : Nav to Next Cell

      Normal,Insert : <C-E>tn

    • :RivTablePrevCell : Nav to Prev Cell

      Normal,Insert : <C-E>tp

    • :RivListNew : Create a New List

      Normal,Insert : <C-E>ln

    • :RivListSub : Create a sub list item

      Normal,Insert : <C-E>lb

    • :RivListSup : Create a sup list item

      Normal,Insert : <C-E>lp

    • :RivListToggle : ToggleList item

      Normal,Insert : <C-E>l`

    • :RivListDelete : Delete List item

      Normal,Insert : <C-E>lx

    • :RivListType0 : Create a List type 0

      Normal,Insert : <C-E>l1

    • :RivListType1 : Create a List type 1

      Normal,Insert : <C-E>l2

    • :RivListType2 : Create a List type 2

      Normal,Insert : <C-E>l3

    • :RivListType3 : Create a List type 3

      Normal,Insert : <C-E>l4

    • :RivListType4 : Create a List type 4

      Normal,Insert : <C-E>l5

    • :RivTodoToggle : Toggle Todo item's status

      Normal,Insert : <C-E>ee

    • :RivTodoDel : Del Todo Item

      Normal,Insert : <C-E>ex

    • :RivTodoDate : Change Date stamp under cursor

      Normal,Insert : <C-E>ed

    • :RivTodoPrior : Change Todo Priorties

      Normal,Insert : <C-E>ep

    • :RivTodoAsk : Show the todo group list

      Normal,Insert : <C-E>e`

    • :RivTodoType1 : Change to group 1

      Normal,Insert : <C-E>e1

    • :RivTodoType2 : Change to group 2

      Normal,Insert : <C-E>e2

    • :RivTodoType3 : Change to group 3

      Normal,Insert : <C-E>e3

    • :RivTodoType4 : Change to group 4

      Normal,Insert : <C-E>e4

    • :RivTodoUpdateCache : Update Todo cache

      Normal : <C-E>uc

  • Edit

    • :RivCreateLink : Create Link based on current word

      Normal,Insert : <C-E>ck

    • :RivCreateFoot : Create Footnote

      Normal,Insert : <C-E>cf

    • :RivCreateDate : Insert Current Date

      Normal,Insert : <C-E>cdd

    • :RivCreateTime : Insert Current time

      Normal,Insert : <C-E>cdt

    • :RivCreateContent : Insert Content Table

      Normal : <C-E>cc

    • :RivCreateEmphasis : Emphasis

      Normal,Insert : <C-E>ce

    • :RivCreateStrong : Strong

      Normal,Insert : <C-E>cs

    • :RivCreateInterpreted : Interpreted

      Normal,Insert : <C-E>ci

    • :RivCreateLiteralInline : LiteralInline

      Normal,Insert : <C-E>cl

    • :RivCreateLiteralBlock : LiteralBlock

      Normal,Insert : <C-E>cb

    • :RivCreateHyperLink : HyperLink

      Normal,Insert : <C-E>ch

    • :RivCreateTransition : Transition

      Normal,Insert : <C-E>cr

    • :RivCreateExplicitMark : ExplicitMark

      Normal,Insert : <C-E>cm

    • :RivDeleteFile : Delete Current File

      Normal : <C-E>df

  • Miscs

    • :Riv2HtmlFile : Convert to html

      Normal : <C-E>2hf

    • :Riv2HtmlAndBrowse : Convert to html and browse current file

      Normal : <C-E>2hh

    • :Riv2HtmlProject : Convert project to html

      Normal : <C-E>2hp

    • :Riv2Odt : Convert to odt

      Normal : <C-E>2oo

    • :Riv2S5 : Convert to S5

      Normal : <C-E>2ss

    • :Riv2Xml : Convert to Xml

      Normal : <C-E>2xx

    • :Riv2Latex : Convert to Latex

      Normal : <C-E>2ll

    • :Riv2Pdf : Convert to Pdf

      Normal : <C-E>2pp

    • :Riv2BuildPath : Show Build Path of the project

      Normal : <C-E>2b

    • :RivReload : Force reload Riv and Current Document

      Normal : <C-E>t`

    • :RivTestFold0 : Test folding time

      Normal : <C-E>t1

    • :RivTestFold1 : Test folding time and foldlevel

      Normal : <C-E>t2

    • :RivTestTest : Test the test

      Normal : <C-E>t4

    • :RivTestObj : Show Test object

      Normal : <C-E>t3

    • :RivSuperBackSpace : Super Backspace

      Insert : <C-E>mq,<BS>

    • :RivSuperTab : Super Tab

      Insert : <C-E>me,<Tab>

    • :RivSuperSTab : Super Shift Tab

      Insert : <C-E>mw,<S-Tab>

    • :RivSuperEnter : Super Enter

      Normal,Insert : <C-E>mm,<Enter>,<KEnter>

    • :RivSuperCEnter : Super Ctrl Enter

      Normal,Insert : <C-E>mj,<C-Enter>,<C-KEnter>

    • :RivSuperSEnter : Super Shift Enter

      Normal,Insert : <C-E>mk,<S-Enter>,<S-KEnter>

    • :RivSuperMEnter : Super Alt Enter

      Normal,Insert : <C-E>mh,<C-S-Enter>,<M-Enter>,<C-S-KEnter>,<M-KEnter>

    • :RivHelpTodo : Show Todo Helper

      Normal : <C-E>ht,<C-E><C-h><C-t>

    • :RivHelpFile : Show File Helper

      Normal : <C-E>hf,<C-E><C-h><C-f>

    • :RivHelpSection : Show Section Helper

      Normal : <C-E>hs

    • :RivVimTest : Run doctest for Vim Script

    • :RivIntro : Show Riv Intro

    • :RivInstruction : Show Riv Instruction

    • :RivQuickStart : Show Riv QuickStart

    • :RivPrimer : Show RST Primer

    • :RivCheatSheet : Show RST CheatSheet

    • :RivSpecification : Show RST Specification

    • :RivGetLatest : Show Get Latest Info

Options

Name Description
Main  

g:riv_default

{...}

 The dictionary contain all riv runtime variables.

g:riv_projects

[]

The list contain your project's settings.

Defaults are:

'path'               : '~/Documents/Riv'
'build_path'         : '_build'
'scratch_path'       : 'Scratch'
'source_suffix'      : `g:riv_source_suffix`_
'master_doc'         : `g:riv_master_doc`_
Commands  

g:riv_global_leader

'<C-E>'

 Leader map for Riv global mapping.
File  

g:riv_master_doc

'index'

The master rst document for each directory in project.

You can set it for each project.

g:riv_source_suffix

'.rst'

The suffix of rst document.

You can set it for each project.

Also for all files with the suffix, filetype will be set to 'rst'

g:riv_file_link_ext

'vim,cpp,c,py,rb,lua,pl'

The file link with these extension will be recognized.

These files will be copied when converting a porject.

These files along with ,'rst,txt' and source_suffixs used in your project will be highlighted.
g:riv_open_link_location 1

The file link with default extension will be recognized. These files will be opened when open it's link reference

when set to 0 , will just jump to the link location.

when set to 1, will open exist files, relative file with g:riv_file_link_ext and links

g:riv_file_ext_link_hl

1

 Syntax highlighting for file with extensions in g:riv_file_link_ext.

g:riv_file_link_invalid_hl

'ErrorMsg'

 Cursor Highlight Group for non-exists file link.

g:riv_file_link_style

1

The file link style.

  • 1:MoinMoin style:

    [[xxx]] => xxx.rst
[[xxx/]] => xxx/index.rst
[[/xxx]] => DOC_ROOT/xxx.rst
[[xxx.vim]] => xxx.vim
('vim' is in `g:riv_file_link_ext`_)
[[~/xxx/xxx.rst]] => ~/xxx/xxx.rst

  • 2: Sphinx style:

    :doc:`xxx` => xxx.rst
:doc:`xxx/index`  => xxx/index.rst

:download:`xxx.py` => xxx.py
Syntax  

g:riv_highlight_code

'lua,python,cpp,javascript,vim,sh'

The language name

is the syntax name used by vim.

For some syntax have different name in pygments and vim, you can use | to seperate it.

e.g: pygments_code_name|vim_code_name

g:riv_code_indicator

1

 Highlight the first column of code directives.

g:riv_link_cursor_hl

1

 Cursor's Hover Highlighting for links.

g:riv_python_rst_hl

0

Highlight DocString in python files

with rst syntax.
Todos  

g:riv_todo_levels

" ,o,X"

The Todo levels for Todo-Box.

Means [ ], [o], [X] by default.

g:riv_todo_priorities

"ABC"

The Todo Priorities for Todo-Items

Only alphabetic or digits.

g:riv_todo_default_group

0

The default Todo Group for ':RivTodoToggle'

  • 0 is the Todo-Box group.
  • 1 and other are the Todo-Keywords group.

g:riv_todo_datestamp

1

The datestamp behavior for Todo-Item.

  • 0: no DateStamp
  • 1: only finish datestamp
  • 2: both initial and finish datestamp

g:riv_todo_keywords

"TODO,DONE;FIXME,FIXED;START,PROCESS,STOP"

The Todo-Keywords groups.

Each group is separated by ';', Each keyword is separated by ','.
Folding  

g:riv_disable_folding

0

Disable Folding or not

  • 0: Enable it.
  • 1: Disable it.

g:riv_fold_blank

2

Folding blank lines in the end of the folding lines.

  • 0: fold one blank line, show rest.
  • 1: fold all blank lines, show one if more than one.
  • 2: fold all blank lines.

g:riv_fold_level

3

Folding more structure for document.

  • 0: 'None'
  • 1: 'Sections'
  • 2: 'Sections and Lists'
  • 3: 'Sections,Lists and Blocks'.

g:riv_fold_section_mark

'.'

 Mark to seperate the section numbers: '1.1', '1.1.1'

g:riv_fold_auto_update

1

 Auto Update folding whilst write to buffer.

g:riv_auto_fold_force

1

 Reducing fold level for editing large files.

g:riv_auto_fold1_lines

5000

 Lines of file exceeds this will fold section only

g:riv_auto_fold2_lines

3000

 Lines of file exceeds this will fold section and list

g:riv_fold_info_pos

'right'

The position for fold info.

  • 'left', infos will be shown at left side.
  • 'right', show infos at right side.
Publish  

g:riv_web_browser

'firefox'

 The browser for browsing html and web links.

g:riv_ft_browser

UNIX:'xdg-open', windows:'start'

 The browser for opening files.

g:riv_rst2html_args

''

 Extra args for converting to html.

g:riv_rst2odt_args

''

 Extra args for converting to odt.

g:riv_rst2xml_args

''

 Extra args for converting to xml.

g:riv_rst2s5_args

''

 Extra args for converting to s5.

g:riv_rst2latex_args

''

 Extra args for converting to latex.

g:riv_temp_path

1

The temp path for converting a file NOT in a project.

  • 0: put under the same directory of converting file.
  • 1: put in the temp path of vim.
  • 'PATH': to the path if it's valid.

g:riv_html_code_hl_style

'default'

The code highlight style for html.

  • 'default', 'emacs', or 'friendly': use pygments's relevant built-in style.
  • 'FULL_PATH': use your own style sheet in path.
Insert  

g:riv_disable_del

0

 Set to 1 to disable the invocation of :fixdel, which disabled the <Del> key from deleting a character under cursor; default is 0.

g:riv_disable_indent

0

 Set to 1 to use vim's default indent expr function. default is 0.

g:riv_i_tab_pum_next

1

 Use <Tab> to act as <C-N> in insert mode when there is a popup menu.

g:riv_i_tab_user_cmd

''

User command to hook <Tab> in insert mode.

let g:riv_i_tab_user_cmd = "<c-g>u<c-r>=snipMate#TriggerSnippet()<cr>"

g:riv_i_stab_user_cmd

''

 User command to hook <S-Tab> in insert mode.

g:riv_ignored_imaps

''

Use to disable mapping in insert mode.

let g:riv_ignored_imaps = "<Tab>,<S-Tab>"

g:riv_ignored_nmaps

''

Use to disable mapping in normal mode.

let g:riv_ignored_nmaps = "<Tab>,<S-Tab>"

g:riv_ignored_vmaps

''

Use to disable mapping in visual mode.

let g:riv_ignored_vmaps = "<Tab>,<S-Tab>"
Miscs  

g:riv_create_link_pos

'$'

Link Target's position when created.

  • '.' : below current line.
  • '$' : append at end of file.

g:riv_month_names

'January,February,March,April, May,June,July,August,September, October,November,December'

 Month Names for Scratch Index

g:riv_section_levels

'=-~"''`'

The section line punctuations for section title.

NOTE Use '' to escape ' in literal-quote 'xxx'.

g:riv_content_format

'%i%l%n %t'

The format for content table.

  • %i is the indent of each line
  • %l is the list symbol '+'
  • %n is the section number
  • %t is the section title

g:riv_fuzzy_help

0

 Fuzzy searching in helper.

g:riv_todo_helper_ignore_done

0

 Ignore TODOs that are marked as DONE in helper.

g:riv_auto_format_table

1

 Auto formating table when leave Insert Mode

g:riv_auto_rst2html

0

 Auto Converting rst to html after writing. file should in project.

g:riv_default_path

'~/Documents/Riv'

 Default path for your project.