Making wiki.vim support multi-filetype links

[saccarosium]

continues: #295

Objective

Be able to simply work with multiple filetype and let wiki.vim change dynamically behaviour based on the user selected extensions.

Solution

Having a global dictionary where define all the info we need for every supported filetype depending on the current filetype and selected filetypes of the user.

let g:wiki_filetypes = {
      \ 'markdown': {
      \   'link_type': 'wiki'|'md',
      \   'extension': 'md | markdown',
      \   'heading': 'atx | headex',
      \ },
      \ 'asciidoc': {
      \   'link_type': 'wathever'
      \   'extention': 'adoc | asciidoc'
      \ },
      \ 'org': {
      \   'extension': 'org'
      \ },
      \}

Dictionary where user can decide what filetype wiki.vim will consider as part of the wiki. The user needs to call the names of the filetypes, as defined in vim, because a filetype can have multiple extentions and we want this to work for every extention.

let g:wiki_active_filetypes = ['markdown', 'asciidoc', 'text']

[lervag]

Thanks! And sorry for replying late.

I think it would help to get some clear ideas of which concept we want to generalize for each filetype. Here are some I've recognized, perhaps there are more:

• Link type: The default link type to use when creating links.
• Extension: Which extension a URL should have.
• Default scheme: The default URL scheme when a url does not have a scheme. Currently, this is hard coded to wiki:, but I think it should be generlaized. E.g. in [[URL]], URL could have the adoc scheme if the user wanted.
• Heading: Which heading is used in the current markup. This is relevant for several things. Today, ATX is more or less generally assumed, except you helped generalize this somewhat for the TOC features.

The end goal would be an option similar to what you proposed, to configure behaviour for a given filetype with several available options. At first, I think perhaps the following would be quite easy to implement:

let g:wiki_filetype = {
      \ 'markdown': {
      \   'link_type': 'wiki'|'md',
      \   'link_extension': '.md',
      \   'index': 'index'|'README'|...,
      \ },
      \}

This would already deprecate the following options:

• g:wiki_link_extension
• g:wiki_link_target_type
• g:wiki_index_name

[saccarosium]

I think that the index should be separate from the filetype since we want only one entry point to the wiki. If every filetype had an independent index when pressing <leader>ww will generate multiple indexes, and I don't think is the best approach.

I think it would help to get some clear ideas of which concept we want to generalize for each filetype. Here are some I've recognized, perhaps there are more

Yeah, is probably the best approach. I think we should make atomic issues of this one and track the progress here and also make very incremental modifications. Is probably better working on a feature branch and then, when we close this issue, merge it in to master.

thing to generalise:

• Links
  • Extention
  • Default scheme
  • Graph
  • Renaming links
• Headings
  • support markdown setext (low priority)
  • better orgmode table of content handling (low priority)

I think is probably the best idea to start with generalising the default link scheme and extention. This would deprecate, as you said, g:wiki_link_extension and g:wiki_link_target_type. Also your implementation seams good except for the index.

[lervag]

WARNING: Long post!

I think that the index should be separate from the filetype since we want only one entry point to the wiki. If every filetype had an independent index when pressing <leader>ww will generate multiple indexes, and I don't think is the best approach.

Yes, interesting point. Pressing <leader>ww has two possible outcomes, depending on context. If the current buffer is "recognized" as part of a wiki, then the mapping should go to the current index. Else it should go to g:wiki_root index.

Yeah, is probably the best approach. I think we should make atomic issues of this one and track the progress here and also make very incremental modifications. Is probably better working on a feature branch and then, when we close this issue, merge it in to master.

Yes, I agree. Let's use this issue as a "concept discussion phase" where we agree on a (draft) spec, then we can gradually make the changes through a set of PR's.

thing to generalise: …

I think your list is good, but I've had some more thoughts. First, I think we should start by allowing to specify the default link schemes:

*g:wiki_link_default_schemes*
  A dictionary to configure the default URL scheme for the various link types.
  The default scheme is the implied scheme for a link URL when the URL lacks
  a scheme.

  The values are either strings, in which case they specify the default scheme,
  or dictionaries between |filetype|s and default schemes.

  Default: >vim

    let g:wiki_link_default_schemes = {
          \ 'wiki': {'wiki: 'wiki', 'adoc': 'adoc'},
          \ 'md': 'wiki',
          \ 'md_img': 'file',
          \ 'ref': '',
          \ 'org': 'wiki',
          \ 'date': 'journal',
          \ 'adoc_xref_inline': 'adoc',
          \ 'adoc_xref_bracket': 'adoc',
          \ 'adoc_link': 'file',
          \ 'shortcite': 'zot',
          \}

The current behaviour is that any URL without a scheme is assumed to be a wiki-schemed URL. This is clearly not optimal. I think this particular suggestion can be raised as a new issue and that it should be more or less straightforward to implement it.

Next, I think we should also allow some generalization of the different schemes. Something like this:

*g:wiki_link_schemes*
  A dictionary to configure resolvers and handlers for some of the supported
  URL schemes. The keys are link schemes and the values are dictionaries to
  configure behaviour for the specified scheme. The following options are
  supported:

    resolver ~
      The name of the function to resolve URLs.

    handler ~
      The name of the function used to handle or follow URLs.

  Default: >vim

    let g:wiki_link_schemes = {
          \ 'wiki': {
          \   'resolver': 'wiki#url#wiki#resolver',
          \   'handler': 'wiki#url#wiki#handler',
          \ },
          \ 'file': {
          \   'resolver': '',
          \   'handler': 'wiki#url#file#handler',
          \ },
          \ …
          \}

This does not feel 100%, though. But my thought is that this will be very good, because it means we can reuse various handlers and easily create multiple resolvers that can all be combined by the user to create custom schemes. One could imagine defining a md: scheme combined with a resolver and a handler, and then set g:wiki_link_default_schemes.md = 'md'.

This does mean a major refactoring job, but I believe it is in order and that it will not really take so much time. The main obstacle is understanding how to actually define the "outer interface"; and I think we are already close.

---

We need to consider the various actions we are actually considering here:

1. Quickly creating links by

   1. converting text to link (e.g. <cr> or visual mode + <cr>)
   2. completion

2. Parsing existing links of different types. Parsing a link should yield a potential text string and a URL.

3. Resolving and handling URLs with different schemes.

I think point 2 means we need an option or a set of options that control link parsing, such as g:wiki_link_default_schemes. Point 3 is the last thing I wrote about above. Currently, we have the g:wiki_resolver and g:wiki_file_handler options that I think can both be removed in favor of g:wiki_link_schemes (or g:wiki_schemes).

To circle back, I believe the original idea of this thread is mostly about point 1, right? I'm thinking it may be better to change the perspective from filetype back to links. I therefore suggest something like this:

*g:wiki_link_creation*
  A dictionary to configure how links are created from text for any given
  filetype. Each key represents a |filetype| and the values are a dictionary
  of options for the specified filetype. The valid options are:

    link_type ~
      The type of link to create.

    url_transform ~
      A function used to transform the text to the desired URL.

  Default: >vim

    let g:wiki_link_creation = {
          \ 'wiki': {
          \   'link_type': 'wiki',
          \   'url_transform': { x -> x },
          \ },
          \ 'markdown': {
          \   'link_type': 'md',
          \   'url_transform': { x -> x . '.md' },
          \ },
          \ …
          \}

This would also deprecate g:wiki_map_text_to_link and possibly also g:wiki_map_create_page, and since url_transform is powerful we no longer need the link_extension thing. I believe this proposal is also something we could start implementing quite fast.

Finally: I think all of the proposed changes will also require a large update of the docs. :)

[lervag]

I've implemented the proposed filetype-based feature now, please see #299. I would appreciate feedback on this. Mostly on the documentation and proposed names for things, but if anyone feels tempted I would also not mind anyone reviewing the code.

After this part is settled, I think we should possibly continue in the same branch (or new branches from that one) to consider my other proposals.

[saccarosium]

Sorry was a busy day. Tomorrow I will review and test the PR. As for the proposed prototype I think looks good! If we can divide the work now in actionable task would be great, so I can work on something myself.

[lervag]

I've opened a feature request for the default scheme proposal: #301. I believe this should not be too hard, so if you want to look at it, you are very welcome.

[lervag]

I've also opened a feature request for the generalized scheme handling in #302.

[lervag]

I'm tempted to close this particular issue as resolved through #299, but I'll let you decide on that, @saccarosium. Also, feel free to propose other things; but let's do that in new threads.