Vimscript documentation

Our Potion plug-in has many useful features, but no one knows this unless we leave a document!

Vim's own documentation is great. I t is not only detailed, but also very thorough. It also inspired many plug-in authors to write good plug-in documents, resulting in a strong document culture in the Vimscript community.

How to use the document

When you read the :help in Vim, you obviously notice that some things are highlighted differently than others. Let's see what's going on.

Open any help entries, :help help help, and :set filetype? V im filetype=help N ow do :set filetype=text and you'll see the highlight disappear. Do it :set filetype=help highlighting is back.

This shows that vim help files just get syntax highlighted text files, just like other file formats! This means that you can write and get the same highlights.

Create a file called doc/potion.txt Vim/Pathogen looks for files under the doc folder when indexing doc so we'll write down the plug-in's help documentation here.

Open the file with Vim and execute :set filetype=help you can see the syntax highlight when you enter it.

The title of the help

The format of the help file is a matter of personal taste. That said, I'm talking about a document format that is becoming more widely used in the current Vimscript community.

The first line of the file should include the file name of the help file, followed by a line describing the plug-in functionality. Add the following .txt the first line of your potion.txt file:

*potion.txt* functionality for the potion programming language

In the help file, a word is enclosed with an asterisk to create a "tag" that can be used for jumps. E xecute: :Helptags get Pathogen to re-index help tags, then open a new Vim window :help potion.txt Vim will open your help documentation as usual.

Next you should put your plug-in name and a description of the elder. S ome authors (including me) like to put a little thought into it and embellish it with some ASCII art words. Add a nice .txt section to the potion.txt file:

*potion.txt* functionality for the potion programming language

                      ___      _   _              ~
                     / _ \___ | |_(_) ___  _ __   ~
                    / /_)/ _ \| __| |/ _ \| '_ \  ~
                   / ___/ (_) | |_| | (_) | | | | ~
                   \/    \___/ \__|_|\___/|_| |_| ~

          Functionality for the Potion programming language.
        Includes syntax highlighting, code folding, and more!

I get these figlet -f ogre "Potion" command. glet is a fun little program that generates ACSII art words. Characters at the end of ~ ensure that Vim does not attempt to highlight or hide certain characters in the art word.

What document to write

This is usually followed by a content catalog. But first, let's decide what document we want to write.

When writing a document for a new plug-in, I usually start with the following list:

• Introduction
• Usage
• Mappings
• Configuration
• License
• Bugs
• Contributing
• Changelog
• Credits

If this is a large plug-in that requires an "outline", I'll write an introductory paragraph outlining its main functions. Otherwise I'll skip it and move on to the next paragraph.

A "usage" paragraph should explain how, in general, the user will use your plug-in. I f they need to interact through mapping, tell them. If the number of maps is not very large, you can simply list them here, otherwise you may need to create a separate "mappings" paragraph to list them one by one.

The "configuration" paragraph should list in detail the variables that users can customize, as well as their functionality and default values.

The "license" paragraph should indicate the protocol used by the plug-in code, along with a URL that points to the full text of the protocol. Don't put the entire protocol in the help file -- most users know what these commonly used protocols mean, which only adds to the confusion.

The "bugs" paragraph should be as short as possible. List all the major bugs you know but haven't resolved yet, and tell users how to report new bugs they've caught to you.

If you want your users to contribute bug fixes and feedures to the project, what do they need to do? S hould pull request be sent to GitHub? O r Bitbucket? Do you want to send patches by email? D o you want to choose one or all of them? A "projecting" paragraph makes it clear how you want to accept the code.

Achanglog is also worth including, so that when users update from version X to version Y, they can immediately see what has changed. I n addition, I highly recommend that you use a reasonable version number plan for your plug-in, such as Semantic Versioning, and always adhere to it. Your users will thank you.

Finally, I like to add a "credits" paragraph to leave my name, list other plug-ins that affect the creation of the plug-in, thank the devotees, and so on.

So we have a successful start. F or many special plug-ins, you may feel the need not to do so, and that's no problem. All you need to do is follow these rules:

• It's clear
• Don't talk nonsense
• Take your users on a stroll through your plug-ins, from nothing to know.

The content catalog

Now that we know what paragraphs you should have, add the following to potion.txt file:

====================================================================
CONTENTS                                            *PotionContents*

    1\. Usage ................ |PotionUsage|
    2\. Mappings ............. |PotionMappings|
    3\. License .............. |PotionLicense|
    4\. Bugs ................. |PotionBugs|
    5\. Contributing ......... |PotionContributing|
    6\. Changelog ............ |PotionChangelog|
    7\. Credits .............. |PotionCredits|

There are a lot of things to mention here. F irst, = made up of characters will be highlighted. Y ou can use these lines to clearly separate the sections of your help documentation. You can - - separate sub-paragraphs, if you want.

*PotionContents* that the user can :help PotionContents to the content directory.

Use | W rapping each word creates a link that jumps to the tag. U sers can move their cursor to the word and press <c-]> :help TheTag They can also be clicked with the mouse.

Vim will hide * | and highlight the contents, so users will see a neat and beautiful directory to make it possible to jump to a place of interest.

Paragraph

You can create a segment header like this:

====================================================================
Section 1: Usage                                       *PotionUsage*

This plugin with automatically provide syntax highlighting for
Potion files (files ending in .pn).

It also...

Make sure that * created the correct tags for the contents that are surrounded so that the links to your directory work.

Continue and create segment headers for each part of the catalog.

Example

I can tell you all about help file syntax and how to use them, but I don't like it. So, why not give you a series of different types of Vim plug-in documents as an example.

For each example, copy the document source code into a Vim buffer and set its fileype as help to observe its rendering. If you want to compare each rendering effect, cut back text see.

You may need to use your Vimscript skills to create a map for the current buffer that help to text and text.

• Clam, the plug-in I used myself to write shell commands. This is a small example that satisfies most of what I've said before.
• NERD tree, a file browsing plug-in written by Scrooloose. Notice the general structure and how he summarizes an easy-to-read list before explaining each item in detail.
• Surround, a plug-in written by Tim Pope that handles surround characters. N otice that it doesn't have a catalog, as well as different header styles and table column items. F ind out how he did it and think about whether you like the style. It's a matter of personal style.
• Splice, which I used myself to solve the plug-in of the three-way merge conflict in version control. N otice how the mapping list is typed and how I use pictures from the ASCII genre to interpret the layout. Sometimes, a picture wins a thousand words.

Don't forget that Vim's own documentation can also serve as an example. This will give you a lot to learn.

Write!

Now that you've seen how other plug-ins plan and write their documents, fill in the documentation for your Potion plug-in.

This can be a challenge if you are not familiar with the writing of technical documents. L earning how to write is not easy, but like other skills, it requires more practice, so start now! You don't have to be perfect to learn from war.

Don't be afraid to write something you don't fully understand, just throw it away and rewrite it. O ften just leave a few pens in the buffer, which will drive your mind into a state of writing. Any time you want to get the stove back on the stove, the old version will always be in version control for you.

A good way to get started is to imagine that you have a good base friend around you who uses Vim. H e's interested in your plug-in but hasn't used it, and your goal is to get him proficient. Before you write down how plug-ins work, consider how introducing them to humans can keep your feet on the ground and avoid getting too deep into the technical aspects.

If you're still stuck and feeling powerless to handle the challenge of writing a complete plug-in document, try something simple. F ind ~/.vimrc and write down the complete documentation for it. E xplain what it does, how it works, how it works. For example, ~/.vimrc

" "Uppercase word" mapping.
"
" This mapping allows you to press <c-u> in insert mode to convert the
" current word to uppercase.  It's handy when you're writing names of
" constants and don't want to use Capslock.
"
" To use it you type the name of the constant in lowercase.  While
" your cursor is at the end of the word, press <c-u> to uppercase it,
" and then continue happily on your way:
"
"                            cursor
"                            v
"     max_connections_allowed|
"     <c-u>
"     MAX_CONNECTIONS_ALLOWED|
"                            ^
"                            cursor
"
" It works by exiting out of insert mode, recording the current cursor
" location in the z mark, using gUiw to uppercase inside the current
" word, moving back to the z mark, and entering insert mode again.
"
" Note that this will overwrite the contents of the z mark.  I never
" use it, but if you do you'll probably want to use another mark.
inoremap <C-u> <esc>mzgUiw`za

It's much shorter than a full plug-in document, but it's a good exercise in writing. ~/.vimrc in Bitbucket or GitHub.

Practice

Write down the documentation for each part of the Potion plug-in.

Read :help help-writing you write help documentation.

Read :help :left :help :right :help :center learn three useful commands to make your ASCII art words look better.