133 lines
3.4 KiB
Markdown
133 lines
3.4 KiB
Markdown
---
|
|
title: Vim helpfiles
|
|
category: Vim
|
|
updated: 2017-09-09
|
|
---
|
|
|
|
## Writing help files
|
|
{: .-left-reference}
|
|
|
|
### Creating a document
|
|
|
|
```nohighlight
|
|
:e doc/potion.txt
|
|
:set ft=help
|
|
:set ft=text
|
|
```
|
|
|
|
Use `ft=help` to preview it, and `ft=text` to edit it.
|
|
|
|
### Example
|
|
|
|
```nohighlight
|
|
*ack.txt* Plugin that integrates ack with Vim
|
|
|
|
==============================================================================
|
|
USAGE INSTRUCTIONS *ack-usage*
|
|
|
|
:Ack[!] {pattern} *:Ack*
|
|
|
|
Search recursively for {pattern}. See |:AckAdd|.
|
|
Also see http://beyondgrep.com for more information.
|
|
|
|
vim:tw=78:ts=8:ft=help:norl:
|
|
```
|
|
|
|
This is a cheatsheet for writing Vim help files. See: `:help help-writing`
|
|
|
|
## Syntax
|
|
|
|
### Reference
|
|
|
|
| Code | Description | Example |
|
|
| ----- | ----- | ----- |
|
|
| *Inline items* |
|
|
| ----- | ----- | ----- |
|
|
| `*tags*` | Tags | |
|
|
| `|link-to-tags|` | Links to tags | `|:command|` |
|
|
| `'vimoption'` | Vim option | `'textwidth'` |
|
|
| ----- | ----- | ----- |
|
|
| `{code-text}` | Code text | `{Visual}gf` |
|
|
| `<code-text>` | Code text | `<PageDown>` |
|
|
| `` `code-text` `` | Code text | `` `set fo=want` `` |
|
|
| `CTRL-X` | Code text | |
|
|
| ----- | ----- | ----- |
|
|
| *Block items* |
|
|
| ----- | ----- | ----- |
|
|
| `INTRODUCTION *tag*` | Section header | |
|
|
| `Column heading~` | Highlighting | |
|
|
| `www.url.com` | Web URL | |
|
|
| ----- | ----- | ----- |
|
|
| `=====` | Separator | |
|
|
| `-----` | Separator | |
|
|
|
|
### Tags
|
|
|
|
* Tags are created with asterisks, eg, `*potion-usage*`
|
|
* Links to tags are `|potion-usage|`
|
|
* Press `^]` to jump to a tag
|
|
|
|
### Code blocks
|
|
|
|
```
|
|
Example: >
|
|
xyz
|
|
<
|
|
```
|
|
|
|
Surround with `>` and `<` characters
|
|
|
|
### File header
|
|
|
|
```
|
|
*potion.txt* functionality for the potion programming language
|
|
```
|
|
|
|
It's customary to start a file with a tag of the filename, plus a description.
|
|
|
|
### Heading
|
|
|
|
```
|
|
==============================================================================
|
|
CONTENTS *potion-contents*
|
|
```
|
|
|
|
Starts with `ALL CAPS`, ends with `*a-tag*`
|
|
|
|
### Notes
|
|
Using `*Todo` and `*Error` will highlight your notes.
|
|
|
|
```
|
|
*Todo something to do
|
|
*Error something wrong
|
|
```
|
|
|
|
### Final modeline
|
|
|
|
```nohighlight
|
|
vim:tw=78:ts=8:ft=help:norl:
|
|
```
|
|
|
|
## Conventions
|
|
|
|
### Table of contents
|
|
|
|
```nohighlight
|
|
|rails-introduction| Introduction and Feature Summary
|
|
|rails-commands| General Commands
|
|
|rails-navigation| Navigation
|
|
```
|
|
|
|
```nohighlight
|
|
1.Intro...................................|ergonomic|
|
|
2.Note to use..............................|CAPSLOCK|
|
|
3.Insert Mode Remappings............|ergonomicInsert|
|
|
```
|
|
|
|
### Author lines
|
|
|
|
```nohighlight
|
|
Author: Jack Hackness <captain@time.com> *xyz-author*
|
|
License: Same terms as Vim itself (see |license|)
|
|
```
|