1 of 25

Head first with vim specific helpfile

By Jaysinh Shukla

2 of 25

WHOAMI

3 of 25

“There needs to be something for people to read, even if it’s rudimentary and incomplete”

By K.Fogel, Producing opensource software

4 of 25

https://goo.gl/os2BDy

5 of 25

Naming a helpfile

  • You should name with the plugin name and add file extension of text file.
  • For example if you are writing documentation for your plugin named “Kutto” then the helpfile name should be “kutto.txt”

6 of 25

Where to put helpfile?

  • Common convention is to create “doc” directory under the root of your plugin and put your helpfile beneath that directory.
  • For example if we are writing documentation of our custom plugin “Kutto” then directory tree should look like below

kutto/

└── doc

└── kutto.txt

  • Pathogen friendly.

7 of 25

Tag

  • Unique value from all the available custom user-defined or already existing tags in vim.
  • Wrap a tag name between Asterisk (*) and it will be parsed as tag.
  • Tag are similar to link. Use tags for linking text bits.
  • It is common practice to prefix a tagname with the name of the plugin to create namespace.
  • Link your tag using Piple (|) during your documentation.
  • Vim will create a link to tag named “kutto-content” when we write |kutto-content|.

8 of 25

Mentioning existing vim option

  • Use Single quote (') to mention any existing vim option.
  • If I want to mention quote command I will mention in below format
    • ':q'

9 of 25

Section

  • Section are separated with double equalto (=).
  • Introduction section will be written below
  • Add Tilde (~) for highlighting your column heading

​

Introduction ~ *kutto-introduction*

=========================================================

​

  • Use dash (-) for dividing sub-sections.

10 of 25

Quote / Block

  • Wrap text between greater than (>) and (<) to highlight the text as one block.
  • You should put code examples using this example
    • >� function! s:kutto_enter()� ...� endfunction�<

11 of 25

Special Key

  • A special key should be mentioned between less than (<) and greater than (>) symbols.
  • For example
      • <CTRL-W> +
    • Will highlight CTRL and W as vim specific control key.

​

12 of 25

Defining arguments

  • You can use curly braces ({}) to give different color highlighting.
  • For example:
    • {OFFSET-X}

13 of 25

Other

  • Keywords like *Todo, *Error will be highlighted differently from normal text by vim editor.

14 of 25

Architecture

  • HEADER
  • INDEX
  • DETAILED SECTIONS

15 of 25

Header

  • It should mention three important point.
    • Name of the file
    • Supported Vim version
    • Last updated date
  • Format:
    • *document_filename.format* For Vim version X.X Last change: Date
  • Consider below as an example for vim plugin “Kutto”
    • *kutto.txt* For Vim version 7.3 Last change: 2017 June

16 of 25

Table of Content

  • Example https://raw.githubusercontent.com/ultimatecoder/goyo-doc/master/doc/goyo_doc.txt

17 of 25

Load helpfile manually

  • Construct the tags from the helpfile using command. Tags will help to traverse functionality.
  • Example:
    • :helptags ~/.vim/doc
    • Where, ~/.vim/doc is the folder which is having documentation text file.
  • Plugins like Pathogen automates the task of creating tags at the time of installing plugin.

18 of 25

Important Sections

  • Table of Content
  • Introduction / About
  • Installation
  • Usage / API
  • License
  • Bugs
  • Changelog
  • Credits
  • Other

19 of 25

“Build Documentation In, Don’t Bolt it On”

by A.Hunt and D.Thomas, The Pragmatic Programmer

20 of 25

Various States of documentation

  • Github wiki or README.md
  • Webpage of Plugin
  • Description at vim plugin page
  • Vim specific helpfile
  • Possibly some more :)

21 of 25

DRY :(

22 of 25

Problems

  • Maintain state of all the documentations
  • Sometimes plugin does little job. Single feature plugins can be explained better at the front page of the code repository page using GIF images. What if user want to get help after installing your plugin?
  • Is your documentation accessible without the Internet?
  • It is easy to start documentation but sometimes motivation less to maintain.

23 of 25

Solution

  • Headfirst for vim specific helpfile.
  • Use google/vimdoc(https://github.com/google/vimdoc) and construct your documentation with while you code.
  • Construct the file in a way you can generate various state of it.
  • vimdoc2html: https://github.com/xaizek/vimdoc2html
  • Vimhelppdf: https://github.com/nathangrigg/vimhelppdf

24 of 25

Why vim specific helpfile?

  • In your vim world with your keybindings
  • No internet connection is required.
  • No extra efforts

25 of 25

Thanks :)