Tips to edit asciidoc in neovim or Vim like a boss !

Après avoir passé une année et plus à éditer en asciidoc, j’ai pensé partager quelques suggestions et astuces que j’ai trouvé pratique.

There do exist dozens of parameters, settings, and options in neovim/Vim which will determine the presentation of the text within vim itself. At times the presentation can improve or enhance the reading experience. On the other hand, remeber the <raison d’être > for asciidoc, est that a document toolchain will take care of the presentation of the final product. Fortunately by following the Asciidoc recommention of 'One sentence per line', we can put aside a lot of the initial vim formating. Asciidoctor will do its work, and css, asciidoctor-pdf and your web server will look after the final presentation of the document.

It is interesting to note that the suggestions in the old ascidoc Tips and trickspour vim, suggest some parametrers for formatting numbered and alphanumeric lists. However when you think about it, asciidoc does not need this. In asciidoc an unordered list starts with *. Thats’t it! Now asciidoc will format your document. There is no actual need for any visual formatting within vim.

Recommended plugins

Vim Asciidoctor
- syntax highlighting
- folding
- run the toolchain (create html/pdf output)
Ultisnips
- create 'snippits' of text that you often enter

Formatting and text presentation within Neovim/VIM:

Let’s start with a parameter that rules the others:

set formatoptions=tcqr

tc means vim manages the text format of code comments. This formatting is disabled as long as the parameter textwidth=0 is set, but will be enabled manually by using the gq shortcut. (And this is exactly what we want! see below.)
q enables the 'gq' shortcut to manually format text wth formatexp.
r indicates that the comment symbol is inserted automatically after pressing kbd:[Enter] (Again this is exactly what we need, see below!)

These two parameters are among the most important:

textwidth=0
wrap

This effectively prevents Vim from formatting and inserting 'hard breaks' in your document. The text will the visibly flow according to the width of the terminal, but for vim internally its still a single line. However in order for the text to be more readable, and so that you can 'see' what’s happening, add the following:

setl linebreak  "don't split words when creating a new line"

The following three paramaters create a paragraph indent for each line following the first. From the second line onward vim will indicate 'soft returns' with an 2 character indent followed by a ↳ and the rest of the sentence.

setl showbreak = ↳
setl breakindent
setl breakindentopt = min:20,shift:2

Incorrectly formatted or pasted text

Sometimes you may have pasted text or the text comes from another document formatted with 80 characters per line. Vim to the rescue!. Include this function that you can call from the manual formatting command gq.

function! OneSentencePerLine()
 if mode() =~# '^[iR]'
  return
 endif
 let start = v:lnum
 let end = start + v:count - 1
 execute start.','.end.'join'
 s/[.!?]\zs\s*\ze\S/\r/g
endfunction
set formatexpr=OneSentencePerLine()

You can select a paragraph with kbd:[v] kbd:[i] kbd:[p] followed by kbd:[g+q] in order to transform the texte into a single line per sentence!

Neovim/Vim functionalitty

The following parameter allows the cursor to act as in a traditional word processor, using the arrow keys as well as the vim keys kbd:[j] and kbd:[k]. Using these keys at the start and end of lines will move the cursor to the previous or next line.

setl whichwrap+=<,>,h,l,[,]

Quand il a a une 'soft wrap', sur l’écran, le déplacement 'normal' du curseur dans Vim serait de 'sauter' la ligne. Si vous voulez éditer au milieu de cette phrase coupée, cela peut être frustrant. Le paramètre suivant permet de déplacer le curseur 'normalement' à travers ces lignes avec un 'soft wrap'. (Voir cette discussion pour voir les avantages/désavantages de ce changement.)

nnoremap <expr> j v:count ? (v:count > 5 ? "m'" . v:count : '') . 'j' : 'gj'
nnoremap <expr> k v:count ? (v:count > 5 ? "m'" . v:count : '') . 'k' : 'gk'

Maintenant comment faciliter la création de listes ? Comme déjà mentionné, il n’y a pas vraiment besoin de 'formater' les listes asciidoc d’une façon particulière dans Vim. Par contre un paramètre peut aider plutôt à les saisir. On utilise la fonctionnalité de 'commentaires' dans Vim pour répéter le caractère à début des lignes selon certaines critères. Souvent cela peut être une préférence personnelle ou bien dépend du document. Donc les suggestions suivantes sont des idées qui peuvent s’adapter.

Le paramètre suivant peut bien servir de défaut pour les asciidocs. Si vous tapez un -, *, +, ., ., suivi par une espace et texte, Vim va commencer la ligne suivante avec le même caractère. (Pas besoin de formater des IV, a) etc) Dans le cas du '|', pas besoin d’espace pour déclencher le formatage automatique. Si quelqu’un a des suggestions ici, je serais ravis de les connaître.

setl comments=://,b:#,:%,:XCOMM,b:-,b:*,b:.,:\|

Mais si vous devez saisir plein de listes au même format comme :

Fruits
1. Passion
2. Pineaples
3. Mangoustine

set comments=slb:*,mb-2:.,elx:\

or:

Countries with English and Franch as official languages:
- Cameroun
- Canada

set comments=sb:*,mb-2:**,elx:\

There are a lot of possibilities here. h: comments is your friend! If you are editing a table, withe the former suggestion, the vertical bar will be added automatically on each new line. But for table options, I would suggest using the Ultisnips (or other according to your preference) plugin, which can really be useful for editing advanced tables.