Documentation is lacking guidance for template usage

[pmatulis]

For those unaccustomed to vimscript the usage of the templates feature is difficult to penetrate.

By looking at a past project issue I came up with the following:

let g:wiki_root = '~/data/sync/wiki'
let g:wiki_filetypes = ['md']
let g:wiki_link_extension = '.md'
let g:wiki_link_target_type = 'md'
let g:wiki_global_load = 0

let s:journal_template = g:wiki_root . '/.templates/journal.md'
let s:generic_template = g:wiki_root . '/.templates/generic.md'

let g:wiki_templates = [
      \ { 'match_re': '^\d\d\d\d-\d\d-\d\d$',
      \   'source_filename': s:journal_template},
      \ { 'match_func': {x -> v:true},
      \   'source_filename': s:generic_template}
      \]

The file ~/data/sync/wiki/.templates/journal.md exists and is deliberately simple at the moment:

# Heading one

## Todo

## Notes

However, doing the following does not use the template; the file (2022-06-22.md) comes up blank:

vim +WikiJournal

My ambitions are simple at this time. I want a journal file template that will produce file content like:

# Journal <date>

## Todo

## Notes

[lervag]

That's strange. For me, it works as expected with the exact same configuration.

To be clear, I did this:

• Created a test directory with the following content:

  .
  ├── test.vim
  └── wiki
      ├── index.md
      ├── journal
      └── .templates
          ├── g.md
          └── j.md
  

• Contents of test.vim is this:

  set nocompatible
  set runtimepath^=~/.local/plugged/wiki.vim
  filetype plugin indent on
  syntax enable
  
  let g:wiki_root = fnamemodify('wiki', ':p')
  let g:wiki_filetypes = ['md']
  let g:wiki_link_extension = '.md'
  let g:wiki_link_target_type = 'md'
  let g:wiki_global_load = 0
  
  let s:journal_template = g:wiki_root . '/.templates/j.md'
  let s:generic_template = g:wiki_root . '/.templates/g.md'
  
  let g:wiki_templates = [
        \ { 'match_re': '^\d\d\d\d-\d\d-\d\d$',
        \   'source_filename': s:journal_template},
        \ { 'match_func': {x -> v:true},
        \   'source_filename': s:generic_template}
        \]

  Some comments here:

  • You need runtimepath to be the path to wiki.vim, it may be different on your end.
  • I used a relative g:wiki_root expanded with fnamemodify here, but this should not matter.
  • For no reason I used j.md and g.md as template filenames, but that should also not matter.

• Contents of

  • g.md

    # Heading one
    
    ## Todo
    
    ## Notes

  • j.md

    # Journal {date}
    
    ## Todo
    
    ## Notes

• Open with nvim --clean -u test.vim, then do \ww to open the index file. It is initially an empty file.

• Insert the word Test, then from normal mode I do <cr>. It creates a link. I click <cr> again to enter, and the Test.md file is created with the template content as expected.

• Continue with \w\w to open the journal, and the journal content is templated, as expected.

---

Perhaps there's an error with your paths? Can you add this to your vimrc to check?

" As before
let s:journal_template = g:wiki_root . '/.templates/journal.md'
let s:generic_template = g:wiki_root . '/.templates/generic.md'

" Add this
echom filereadable(s:journal_template) s:journal_template
echom filereadable(s:generic_template) s:generic_template

[lervag]

For those unaccustomed to vimscript the usage of the templates feature is difficult to penetrate.

I'd be happy to help make it easier to understand. Perhaps you could suggest something or help me see what's unclear after we get it to work on your end?

[pmatulis]

First off, nothing works if I include --clean. When I add --startuptime ~/tmp/vimstartup the file contains this.

Dropping that option allows me to continue (the Wiki* commands become available).

Using vim -u ~/tmp/test.vim, these lines get printed to STDOUT:

0 ~/data/sync/wiki/.templates/journal.md
0 ~/data/sync/wiki/.templates/generic.md
Press ENTER or type command to continue

However, after hitting ENTER, opening a new generic or journal file does not use a template.

To be clear, this is my test.vim file:

set nocompatible
set runtimepath^=~/.vim/pack/plugins/start/wiki/plugin/wiki.vim
filetype plugin indent on
syntax enable

let g:wiki_root = '~/data/sync/wiki'
let g:wiki_filetypes = ['md']
let g:wiki_link_extension = '.md'
let g:wiki_link_target_type = 'md'
let g:wiki_global_load = 0

let s:journal_template = g:wiki_root . '/.templates/journal.md'
let s:generic_template = g:wiki_root . '/.templates/generic.md'
echom filereadable(s:journal_template) s:journal_template
echom filereadable(s:generic_template) s:generic_template

let g:wiki_templates = [
      \ { 'match_re': '^\d\d\d\d-\d\d-\d\d$',
      \   'source_filename': s:journal_template},
      \ { 'match_func': {x -> v:true},
      \   'source_filename': s:generic_template}
      \]

head -1 ~/.vim/pack/plugins/start/wiki/plugin/wiki.vim gives:

" A simple wiki plugin for Vim

I would be willing to give you feedback on how the documentation can be improved once I can wrap my head around how things work.

[lervag]

First off, nothing works if I include --clean.

Ah, you are using Vim, not neovim. In that case, --clean is not necessary.

Using vim -u ~/tmp/test.vim, these lines get printed to STDOUT:

0 ~/data/sync/wiki/.templates/journal.md
0 ~/data/sync/wiki/.templates/generic.md

Ah, exactly. The above 0s shows that the files are not there/readable. Can you triple check that the paths are correct here and that these files exist?

I would be willing to give you feedback on how the documentation can be improved once I can wrap my head around how things work.

Great! Let's get things working first, then :)

[lervag]

I believe I found a minor bug/unexpected behaviour where the ~/ is not recognized in the template paths. I've fixed it so that ~/ is expanded as expected. Please try again now.

[pmatulis]

Thanks for the update. Works.

So those zeroes are a good thing right? An exit status code of0 usually means success.

[pmatulis]

I'm not sure if I should open a bug for the matter of using variables in templates as well as functions when working with templates.

I also have other questions like how to create a directory hierarchy for journal files (year, month).

Why not turn on GitHub Discussions?

[lervag]

Thanks for the update. Works.

Glad to hear it!

So those zeroes are a good thing right? An exit status code of 0 usually means success.

No; in Vimscript, 0 is equivalent to false. See :help eval for more info, in particular :help expr4. So, filereadable(FILE) returns 1 if the file is readable.

I'm not sure if I should open a bug for the matter of using variables in templates as well as functions when working with templates.

Well, do you have a problem here? What do you want to do; what did you try? (I suggest a new issue for that.)

I also have other questions like how to create a directory hierarchy for journal files (year, month).

Feel free to open an issue and ask. It is easier to answer when you provide a detailed request.

Why not turn on GitHub Discussions?

I don't have much experience with it, and in my experience, the discussions in issue threads are more than sufficient for me. I don't have that much time for following up these things either. If there were more people involved in maintaining and developing, then I guess a discussion forum is more relevant.