Let Vimwiki supports Gitit's syntax (markdonwn)

[GoogleCodeExporter]

[Gitit][] is the wiki system I currently use.
It stores page in a git, darcs, or mercurial repository.

[Gitit]: https://github.com/jgm/gitit.git

I was using vimwiki to edit those pages as normal markdown files prior.
However, there is a little different between gitit's markdown and the markdown 
syntax support by vimwiki.

For example, the "Preformatted Text" in gitit is "~~~" rather than "```".
Other syntaxes like "**bold**", "*italic*" and ",,sub-script,," are also 
inconsistent.

I think Vimwiki and Gitit are not competitors, and they could cooperate nicely. 
:)
There is a patch I've attached.

Thank you.

Original issue reported on code.google.com by themacropodus@gmail.com on 23 Feb 2013 at 10:28

Attachments:

• support_gitit.patch

[GoogleCodeExporter]

Hi,

thx for the patch.

Stuart, could you review it? I believe that small differences in syntax should 
not result in 3 new files (_custom, _base, syntax).

Ideally there should be 1 new syntax file and some tinkering in existent 
ftplugin/plugin files, but with markdown if I rememember correctly you planned 
to do some fancy things? And his patch is based on it...

Original comment by habamax on 23 Feb 2013 at 2:44

• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

I can only take a quick look at the code ...

As it turned out, I was unable to effectively program the markdown syntax using 
changes in the syntax file alone.  My solution was to include syntax specific 
functions, wherever needed, using a poor-man's OO programming strategy.   See 
vimwiki#base#follow_link() for example:

" vimwiki#base#follow_link
function! vimwiki#base#follow_link(split, ...) "{{{ Parse link at cursor and 
pass 
  " to VimwikiLinkHandler, or failing that, the default open_link handler
  if exists('*vimwiki#'.VimwikiGet('syntax').'_base#follow_link')
    [[ ... code for non-default syntax ...  ]] 
  else
    [[ ... code for default syntax ...  ]] 
  endif
endfunction

This approach moves the syntax-specific code into separate files rather than 
lumping it all together.  This approach might serve us well for the time being, 
as long as we include only a minimal set of "hooks" linking out from the 
default code.

Original comment by stu.andrews on 26 Feb 2013 at 3:13

[GoogleCodeExporter]

Stu, that is ok and I can see the point. I just need your conclusion about this 
patch and the way 'markdown'-style syntaxes could be added to vimwiki.

If it is ok for you we'll think about including it into vimwiki if 
themacropodus would like to join us and maintain gitit stuff.

Original comment by habamax on 26 Feb 2013 at 3:57

[GoogleCodeExporter]

I am honored to be able to join this project.

Original comment by themacropodus@gmail.com on 26 Feb 2013 at 2:20

[GoogleCodeExporter]

I think it is more appropriate to use the term `pandoc` rather than `gitit`.
I will attach the new patch if needed.

Original comment by themacropodus@gmail.com on 2 Mar 2013 at 8:10

[GoogleCodeExporter]

This is really interesting.  Great effort!   

And pandoc works, too.  If you wait a sec, I can push some comments I've made 
to the current code.  

Thanks, -S.

Original comment by stu.andrews on 2 Mar 2013 at 2:44

[GoogleCodeExporter]

I added a "pandoc" branch that can be checked-out for testing and future 
merging; see r2feb11f63d79.  

On this branch I added themacropodus's gitit files, and renamed them to pandoc. 
 I also added comments to improve the vimdiff comparison among default, 
markdown and pandoc files.  From what I can tell, the OP has a detailed grasp 
of the code, and the changes look appropriate.  I can't say that I've tested 
this code.

The pandoc files implement a minimal markdown syntax and link behavior.  It's 
simpler than the corresponding markdown files, since the earlier markdown 
implementation supported both default-vimwiki links in addition to various 
markdown link types.  Updating the docs would help to clarify these differences.

@themacropodus: 1. It's convenient to share new features by submitting branches 
(assuming you have the correct permissions).  2. Do you have a companion 
custom_wiki2html script that calls gitit's compiler?  Perhaps the script could 
just start the gitit server, and then send a request to open the page in your 
browser ...

@habamax: I recommend adding themacropodus to the list of devs.

Original comment by stu.andrews on 2 Mar 2013 at 5:48

[GoogleCodeExporter]

Thanks, Stuart!

Welcome themacropodus!

Original comment by habamax on 3 Mar 2013 at 5:27

• Changed state: Accepted

[GoogleCodeExporter]

Thank Stuart and habamax. :)

@Sturat: I don't have the script to generate static html files.

My using scenario is, there is a server running gitit already, so I could just 
commit files and push it to server.  Gitit will renders the newest page 
according to the repository.  Actually, I have a script to commit & push 
automatically every hour.

Since Gitit's markup is based on Pandoc, I've try to execute pandoc directly.
However, it seems Pandoc only supports `Inline link [link](url)` but not `Wiki 
link [link]()`, so every wikilinks will become useless.

If you only want to read the single page, I think it is fine by execute the 
following command:

    pandoc -s -f markdown -t html (src) (target)

Start gitit server involve other issues, including port number and other 
configurations.  We also need to prevent start multiple instances of Gitit.  I 
think these a bit too complicated.

In my opinion, it would be convenient to make a commit (and optional push?) 
through Vimwiki.
As for start/stop the gitit, maybe it is better to let user do it themselves?

Original comment by themacropodus@gmail.com on 3 Mar 2013 at 9:12

[GoogleCodeExporter]

This is a recurring challenge with most markdown converters, and there are 
various extensions like the one implemented by gitit which add support for 
wikilink behavior 
(c.f. http://code.google.com/p/vimwiki/issues/detail?id=384).

It would be helpful if themacropodus could clarify in the docs how wikilinks 
are handled under the newly added pandoc syntax.  Are directory links 
supported?  Schemes?  Are there any major inconsistencies between vimwiki's 
handling of wikilinks and/or weblinks?

Vimwiki is a great wiki editor, but ultimately, it's a long way away from being 
able to support arbitrary syntaxes in a general way.  In my experience 
extending vimwiki with markdown support,  I chose to maintain support for the 
default vimwiki links in order to keep vimwiki and its documentation simple and 
consistent.  

I recommend that users learn both vimwiki's default syntax and markdown syntax 
for links, and how to efficiently convert between them.  In my markdown 
implementation, hitting <shift-'+'> over a wikilink alternates between 
markdown's `[link][url]` syntax and the default `[[url|link]]` syntax.

Original comment by stu.andrews on 3 Mar 2013 at 8:31

[GoogleCodeExporter]

I have to say, I haven't using custom_wiki2html before.  For now, I think it is 
possible to handle Wikilink by simple `sed` command.  I also wondering how 
Pandoc handling Wikilink when the front-end is Gitit.  I will look-into it 
later, but I need some more time.

Follwing are the results of the link behaviors in the pandoc syntax.

1. Directory link
   It has the same behavior just like default syntax.  However, it seems the absolute path isn't handling correctly for both syntaxies.  When I am trying to open the link `/home/somebody/`, it always opens the path `/path_to_wiki//home/somebody/'.

2. Raw URL
   Not supported by Pandoc. The functions in syntax file is remove by me.

3. Interwiki, Diary, Local, File
   Not supported by Pandoc.  However, It still supported by Vimwiki currently.  What I do in `pandoc_base#follow_link` is really simple, I just parse the syntax '[name](url)' and retrieve the `url` part (or `name` part if the `url` part is empty) and pass it to `open_link`. It seems the logic of handling these scheme links is behind
   `open_link`, so I don't need to do anything and it works.

4. Schemeless
   I cannot understand what it is. I believe I have some kind of reading disabilities. :P

Since Gitit not supported (2) & (3), Should we encourage people to use those 
syntaxies?  I'm not sure which one is better, but for me, I will avoid to use 
those syntaxies.

Original comment by themacropodus@gmail.com on 4 Mar 2013 at 11:37

[GoogleCodeExporter]

Writing the custom_wiki2html script is much harder than I original think...

There are 3 types of links:
1. [link]()       =>   [link](link.html)
2. [desc](link)   =>   [desc](link.html)
3. [desc](http://url/) => [desc](http://url/)

I couldn't found any sed command to distinguish case 2 & case 3 correctly.
So I just append ".html" to both cases and then remove ".html" in case 3.

Now it's work just like customwiki2html.sh. :)

Original comment by themacropodus@gmail.com on 18 Mar 2013 at 4:06

Attachments:

• gitit2html.sh