Re: How to use vim to write a aligned plain text (txt) file as the vim help files?

On Sat, Sep 22, 2018 at 11:48 PM Hausen Schaff <seaspeak@gmail.com> wrote:
>
> vim help files are in plain text format. They'are under /vim/vim80/doc.Lots of <Tab> characters are used to align the contents.
>
> Interestingly, I can't find a good way to write such <Tab> aligned texts by vim. Every plugin use space to align words. Some bring this issue up on these project homes, and no solution is provided.
>
> I'm curious how the vim developers write the help documents?
>
> Plugins
> -----------------------------------------------------------
> vim-easy-align: Align to Nearest Tabstop #58 https://git.io/fAdXc
> tabular: https://git.io/fAdXW
>
> Excerpted from vim's help
> -----------------------------------------------------------
> Development of Vim. *development*
>
> This text is important for those who want to be involved in further developing
> Vim.
>
> 1. Design goals |design-goals|
> 2. Coding style |coding-style|
> 3. Design decisions |design-decisions|
> 4. Assumptions |design-assumptions|

The following answer does not cover any third-party plugin, as I
personally don't use them for tabbing. OTOH, all or part of it may (or
may not) rely to running in 'nocompatible' mode, which nowadays is
IIUC the default except when the -C command-line switch (or -u
followed by other than DEFAULTS) is used.

Several options govern what happens when you hit the Tab key in Insert
mode in Vim. Once they are set the way you want them, aligning files
by tabbing should become a piece of cake. I'm summarizing them below
but you should check the online help about them, it is more detailed.

* 'expandtab' or 'et' is a Boolean buffer-local option, default off.
When on, hitting the Tab key produces an appropriate number of spaces.
Existing hard tabs won't be altered until or unless you |:retab|
(q.v.) but new ones won't be added unless you "force" them by hitting
Ctrl-V (in Insert mode) immediately before hitting Tab (or Ctrl-I).
(On the latter "forcing" point, see the help about |i_CTRL-V|.)
* 'tabstop' or 'ts' is a numeric buffer-local option, default 8. When
a hard tab is encountered in a text file, it will push the next
character by n columns, where 1 <= n <= &ts, in order to bring that
"next character after the tab" in a column whose number (the leftmost
column being 1) is 1 more than a multiple of &ts. For the default
value of 8, this means that the next character will be in the next
column in the list [9, 17, 25, 33, 41, …]. (Column 1 can of course not
be preceded by a tab ending in column 0.)
* 'softtabstop' or 'sts' is a numeric buffer-local option; its default
is 0 which means "soft tabs are off". When positive and 'et' above is
off, hitting the Tab key moves to the next "soft tab" of this width by
inserting the appropriate number of "hard tabs" (calculated as for
'ts' above) and, if this "soft tab stop point" does not coincide with
a "hard tab stop point", additional spaces are added as necessary.
When 'sts' is any negative number, the value of 'sw' (below) is used.
* 'shiftwidth' or 'sw' is a numeric option (default 8) which is only
used for indenting. It governs by how much autoindenting (if enabled)
and the manual indent commands (such as << >> etc.) will move the
whole line left or right when going from one indentation level to the
next. When zero the value of 'ts' above is used.
* 'smarttab' or 'sta' is a Boolean global option, default off. When it
is on, hitting the Tab key will insert tabs if used at the start of a
line, or spaces if used elsewhere.

See the online help for each of these options, and a few additional
ones, as follows:
:h 'et'
:h :retab
:h i_CTRL-V
:h 'ts'
:h 'sts'
:h 'sw'
:h 'sta'
:h ins-expandtab (and the whole 33-line section starting with it)
:h :set
and note that ":set option?" with question mark always
displays the value while ":set option" with nothing after the name
sets the value to TRUE when used with a Boolean option but displays
the value when used with a non-Boolean option. So when in doubt (and
maybe even when not in doubt), always use a question mark to display
the value without changinig it. (If the value of a Boolean option is
FALSE, the option name will be displayed prefixed by "no".)

The help for 'tabstop' also has a discussion of the various possible
ways to use the tabbing options described above.

Oh, and for help files in particular, see also ":h modeline"

Best regards,
Tony.

--
--
You received this message from the "vim_use" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php

---
You received this message because you are subscribed to the Google Groups "vim_use" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vim_use+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.