vimoku 1.0.4

Python wrapper around Clingo/Answer Set Programming

vimoku

Edit pages of a dokuwiki instance with your favorite editor.

Use the RPC-XML interface of dokuwiki, accessed using dokuwikixmlrpc.

Tested with python 3.8. Should work with 3.6. Will not with 3.5 (sorry, f-strings are the best).

Installation

setup (manual)

Install vimoku.py somewhere, make it executable. You probably want to rename it just vimoku, or create aliases in your dot files.

Create a new repository with git init, and, in the git/config file, add the following section: You need to create the file $XDG_CONFIG_HOME/vimoku/vimoku.ini (Your $XDG_CONFIG_HOME is probably equal to ~/.config) as follow:

[wiki:default]
url = https://yourwiki.url.net
user = john
password = yourpassword

The url is the url of your wiki. User and password are the login for the account you will use to publish your editions on the wiki. It therefore must be an existing dokuwiki user allowed to use RTC calls.

Other options are available, notably editor to set the editor to choose and editor_options for its options. See editor options section for an example. This readme explains more options and features.

setup (semi-manual)

pip install vimoku  # don't forget to verify version of pip, python, OS, timeline, blahblah

Python dependencies are automatically installed, but you still need to install a vimoku.ini in your config directory. Only now, you have vimoku ready to fire with python -m vimoku.

dependencies

Only one, really : dokuwikixmlrpc. If you are to browse it, there is no documentation, but the code is short and understandable. You probably look for the DokuWikiClient object.

pip install dokuwikixmlrpc should be enough, probably with --user. You could also copy paste in place of the imports the single source file of dokuwikixmlrpc in vimoku.py. Don't forget to remove the (call to) main function.

Usage

Edition

Use vimoku --help for help.

Basic usage:

vimoku pageid

You can edit multiple pages, using standard dokuwiki naming conventions for categories:

vimoku categ1:page1 page2 categ2:categ3:page3

And you may set a commit message (by default, it's undocumented remote modification):

vimoku page2 -m "guess from where i edit that page ??"

Your editor will fire a first time, letting you modify the pages you requested. It will fire a second time to let you modify, for each page, the commit message. And, if you opened other files, it will be fired a third time to ask you if they are wiki pages to retrieve and edit (see cycling).

Move and copy

Using flags --move-to and --copy-to, you can modify your wiki structure easily ! The only difference between the two is that moving deletes the page after copy. Note the existence of specific flags, such as --redirect and --fix-backlinks. See the below examples.

Change the name of a page, if the new name is not an existing page:

vimoku categ:pageid --move-to othercateg:newpageid

Change the name of a page, if the new name is not an existing page, with a redirection in the old page to the new one:

vimoku categ:pageid --move-to othercateg:newpageid --redirect

Copy the category bar into another (note the : that indicate that the category, not the page, is to be considered):

vimoku bar: --copy-to baz

Move all content of a category bar into baz, and put a redirection message in the moved pages:

vimoku bar:* --move-to baz --redirect

Rename a page, and fix all links that were linking to it before the renaming:

vimoku page --move-to movedpage --fix-backlinks

Vimoku will try to detect any possible fault with what you provided, then will ask you to review the move with your editor. There, you can go wild and erase entire pages by not paying attention to what you do.

Categories selection

The next example shows some advanced details regarding categories. Let's consider the wiki containing the following pages:

a
b
b:d:e
b:f
c
c:g

The following command:

vimoku a b: c --move-to h --redirect

Should move the pages to obtain:

b
c:g
h:a
h:b:d:e
h:b:f
h:c

If you also wanted to move b and c:g, you should indicate that you want to move b and c:, thus:

vimoku a b b: c c: --move-to h --redirect

Edit on different dokuwiki instances

Vimoku supports the existence of many wikis in the configuration file. This is achieved by populating your vimoku.ini with different wikis. This also allows you to handle multiple identities on a single wiki. The following ini file provides an example of three different accounts on two different wikis, setting one of them as the default:

[wiki:default]
url = https://wiki.one.example.net
user = john
password = passwordone
[wiki:second]
url = https://wiki.two.example.net
user = john
password = passwordtwo
[wiki:alt]
url = https://wiki.one.example.net
user = mysteriousguy
password = mysteriouspassword

Now, you can specify explicitely which wiki to consider when using the CLI. For instance, you could edit a page using your alternative identity on the first wiki:

vimoku categ:page alt:::page second/page

This will enable you to edit categ:page on the default wiki, page with your alternative identity on the same wiki, and page on the second wiki. Slash or triple colons means the same thing.

You can also copy from one instance to another, here copying all meeting reports from wiki one to wiki two:

vimoku one/meeting:* --copy-to two/meeting:

More details:

• slashes are accepted in input as wiki separator, but internally the token triple colon ::: is used.
• before the slash/triple colon is the wiki name, as defined in the configuration file. After the slash/triple colon is the page name in the remote wiki.
• when no wiki name is given, default is used. You can change this.

tips

cycling

Once in your editor, if you create more files in the temporary directory containing the files you asked for edition, they will not be removed. Instead, you will be prompted (using your $EDITOR) about which files you want to edit properly.

The whole program will run again, this time retrieving the new files you asked for.

NB: if you wrote things in those manually opened files, you will loose your data. Even if the page doesn't exists on the wiki. Yes, that sucks. Help me.

editor options

Your vimoku.ini accept the option editor, to explicitely set the editor if you don't trust your $EDITOR environment variable, and the option editor_options, which is formated with the variable cwd, the path to the directory holding the files you will be editing. Files to open are fed after those options. For instance, using vim, i ended up with the following value:

[options]
editor=/usr/bin/vim
editor_options=-c ":cd {cwd}" -p

This ensures that vim opens each file in its tab (-p), and uses the temporary directory containing all files as working dir so opening more files is easy (-c "…").

Set a different default wiki

When setting multiple wikis in your ini file, you may use the option default_wiki to provide which wiki to use when no name is given. Example:

[options]
default_wiki = second
[wiki:first]
url = https://wiki.one.example.net
user = john
password = passwordone
[wiki:second]
url = https://wiki.two.example.net
user = john
password = passwordtwo

Work to be done

• fix the data loss problem when writing a new file and asking the program to upload it.
• what about using a watchdog to automatically download and lock the newly opened file ? Or provide a vim plugin ?
• use the CLI's --minor flag
• use tmpfile instead of flooding .config/vimoku
• is it possible to upload a media ? yes, it is. see client.put_file
• there is few TODOs in the code.