zim-wiki team mailing list archive

[Jaap Karssenberg <jaap.karssenberg@xxxxxxxxx>]

On Sat, Jan 11, 2014 at 5:01 PM, Rui Covelo <rui.covelo@xxxxxxxxx> wrote:

> Hi guys!
>
> Developer talk below.
>
> In order to find my away around the Zim code so I can help killing some
> bugs I am creating a few custom tools using zim module.
>

Disclaimer: I recently checked in all kinds of code refactoring patches in
the "pyzim-refactor" branch. These will be merged to trunk before the next
release. So you might want to pull this dev branch and make sure your tool
still works with that branch.


>
> One of my practices when creating new pages is creating on the top of the
> page links do other namespaces that might relate to each other. A bit like
> some people use tags but I prefer clickable links that can be listed as
> backlinks to when I am visiting a page.
>
> My first idea for a custom tool was to list inside the current page (the
> page I am visiting) some selected pages that have a particular link at the
> top (that I am calling headers for myself).
>

I don't think I understand the goal / use case for this tool. If you want
to list related pages, wouldn't it be easier to put them in a side pane
next to the page instead of embed them in the page source? (See the
"backlinkpane" plugin for an example.)


> For this I get a page list using notebook.get_pagelist() and then go
> through each page content to search the first lines of the page for the
> links.
>
> Question 1:
> Is it OK to use get_pagelist() and not index.list_pages() since I need the
> content of each page?
>

Sure


> Question 2:
> To find the links at the top of the page I understand I can use the
> ElementTree but I found it easier, for my purpose, to parse the source text
> file directly because I don't have to go through the format tags (ex: <p>
> and <link>). Is this ok or I should stick to using the zim module interface?
>
>
For a custom tool it is OK, but for core functions in zim it is not. The
reason is that I still target to support multiple source formats (e.g.
markdown) so functions dealing with formatting should be agnostic of the
source parsing. But if it is a custom tool for your own use you can take
the easier route of course.

If you want to do the complete thing, be aware that the tree interface was
overhauled in the pyzim-refactor branch. Have a look at the tasklist plugin
for a complex parsing example using the new interface.


In some situations I want to create a new page. I have managed to create
> new pages using some code like this:
>
> notebook_path = '<file system path to notebook>'
> new_page_path = '<namespace path to notebook>'
> text = 'sample initial text'
> notebook = get_notebook(notebook_path)
> new_page = notebook.get_new_page(Path(new_page_path))
> template = notebook.get_template(page)
> tree = template.process_to_parsetree(notebook, page)
> new_page.set_parsetree(tree)
> new_page.parse('wiki',text,append=True)
> notebook.store_page(new_page)
> notebook.emit('stored-page',new_path) # not sure if this is necessary
>
> (yep! "stolen" from the zim module code)
>
>
> Question 3:
> Is this code ok for use in custom tools?
>

As far as I can tell without testing it, this looks about right.

Question 4:
> I found that if zim is running, the treeview is not updated immediately.
> Is there a way to force this?
>

If the script is run externally you can't at the moment. Planning to make
zim monitor for file changes, but that is not yet ready. You could try to
call the "update_index" method by an IPC call, should work, but would need
to test to be sure.

Question 5 and 6:
> Is notebook.emit() necessary? Am I using it properly?
>

Only in the zim process itself. This signal notifies other objects  of the
change, but only in the running program, not from outside processes.

Regards,

Jaap