Chapter 13. Editor Configuration | FreeBSD Documentation Portal
Description: Configuration used in the texts editors in the FreeBSD Documentation Project
Keywords: editor,configuration,vim,emacs,FreeBSD

# Chapter 13. Editor Configuration

Adjusting your text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines.

## 13.1. Vim

Install from editors/vim, then follow the configuration instructions in Configuration. More advanced users can use a proper linter like Ale which can also act as a Vim Language Server Protocol client.

### 13.1.1. Use

Manual page writers can use the following keyboard shortcuts to reformat:

- Press `P` to reformat paragraphs or text that has been selected in Visual mode.

- Press `T` to replace groups of eight spaces with a tab.

A linter named Vale has been introduced to check grammatical and cosmetic errors on the documents. Vale has support for various editors and IDEs.

Vale may already be installed as a dependency of the textproc/docproj meta-port. If not, install textproc/vale with:

    $ pkg install vale

Install Ale to integrate into editors/vim, for using textproc/vale.

    % mkdir -p ~/.vim/pack/vendor/start
    % git clone --depth 1 https://github.com/dense-analysis/ale.git ~/.vim/pack/vendor/start/ale

Users who are using plugin managers for editors/vim do not need the above and should follow the instructions of that plugin manager to install Ale.

At this moment due to a bug in Vale it is necessary to copy the Vale configuration to the home directory. Considering the repository was cloned into ~/doc copy as following:

    % cp -R ~/doc/.vale* ~/

### 13.1.2. Configuration

Edit ~/.vimrc, adding these lines to the end of the file:

`~/.vimrc`

    if has("autocmd")
      au BufNewFile,BufRead *.adoc call Set_ADOC()
      au BufNewFile,BufRead *.[1-9] call Set_MAN()
    endif " has(autocmd)

    function Set_Highlights()
      "match ExtraWhitespace /^\s* \s*\|\s\+$/
      return 0
    endfunction " Set_Highlights_Adoc()

    function Set_Highlights_MAN()
      highlight default link OverLength ErrorMsg
      match OverLength /\%71v.\+/
      return 0
    endfunction " Set_Highlights_MAN()

    function ShowSpecial()
      setlocal list listchars=tab:>>,trail:*,eol:$
      hi def link nontext ErrorMsg
      return 0
    endfunction " ShowSpecial()

    function Set_COMMON()
      setlocal number
      setlocal shiftwidth=2
      setlocal tabstop=8
      setlocal softtabstop=2
      setlocal formatprg="fmt -p"
      setlocal autoindent
      setlocal smartindent
      call ShowSpecial()
      call Set_Highlights()
      return 0
    endfunction " Set_COMMON()

    function Set_ADOC()
      setlocal syntax=asciidoc
      setlocal filetype=asciidoc
      call Set_COMMON()
      return 0
    endfunction " Set_ADOC()

    function Set_MAN()
      setlocal syntax=man
      setlocal filetype=man
      setlocal textwidth=70
      " Rewrap paragraphs
      noremap P gqj
      " Replace spaces with tabs
      noremap T :s/        /\t/<CR>
      call Set_COMMON()
      call Set_Highlights_MAN()
      return 0
    endfunction " Set_Man()

    let g:ale_fixers = {
    \   '*': ['remove_trailing_lines', 'trim_whitespace'],
    \}
    let g:ale_linters = {
    \   'asciidoc': ['vale'],
    \}
    let g:ale_fix_on_save = 1

| Above configuration will automatically remove trailing line, trailing space and multiple spaces which might display additional unwanted changes in `git diff` output. In such cases properly mention that in the commit log.

## 13.2. Emacs

Install from editors/emacs or editors/emacs-devel.

### 13.2.1. Automated Proofreading with Flycheck and Igor

The Flycheck package is available from Milkypostman’s Emacs Lisp Package Archive (MELPA). If MELPA is not already in Emacs’s packages-archives, it can be added by evaluating

    (add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)

Add the line to Emacs’s initialization file (one of ~/.emacs, ~/.emacs.el, or ~.emacs.d/init.el) to make this change permanent.

To install Flycheck, evaluate

    (package-install 'flycheck)

Create a Flycheck checker for textproc/igor by evaluating

    (flycheck-define-checker igor
      "FreeBSD Documentation Project sanity checker.

    See URLs https://www.freebsd.org/docproj/ and
    http://www.freshports.org/textproc/igor/."
      :command ("igor" "-X" source-inplace)
      :error-parser flycheck-parse-checkstyle
      :modes (nxml-mode)
      :standard-input t)

      (add-to-list 'flycheck-checkers 'igor 'append)

Again, add these lines to Emacs’s initialization file to make the changes permanent.

### 13.2.2. FreeBSD Documentation Specific Settings

To apply settings specific to the FreeBSD documentation project, create .dir-locals.el in the root directory of the documentation repository and add these lines to the file:

    ;;; Directory Local Variables
    ;;; For more information see (info "(emacs) Directory Variables")

    ((nxml-mode
      (eval . (turn-on-auto-fill))
      (fill-column . 70)
      (eval . (require 'flycheck))
      (eval . (flycheck-mode 1))
      (flycheck-checker . igor)
      (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))

## 13.3. nano

Install from editors/nano.

### 13.3.1. Configuration

Currently there is no adoc/asciidoc syntax highlight file with nano distribution. So let’s create one from scratch and use an editor to create new file or add lines in the ~/.nanorc with these contents:

`~/.nanorc`

    syntax "asciidoc" "\.(adoc|asc|asciidoc)$"
    # main header
    color red "^====+$"
    # h1
    color red "^==[[:space:]].*$"
    color red "^----+$"
    # h2
    color magenta "^===[[:space:]].*$"
    color magenta "^~~~~+$"
    # h4
    color green "^====[[:space:]].*$"
    color green "^\^\^\^\^+$"
    # h5
    color brightblue "^=====[[:space:]].*$"
    color brightblue "^\+\+\+\++$"
    # attributes
    color brightgreen ":.*:"
    color brightred "\{[a-z0-9]*\}"
    color red "\\\{[a-z0-9]*\}"
    color red "\+\+\+\{[a-z0-9]*\}\+\+\+"
    # Paragraph Title
    color yellow "^\..*$"
    # source
    color magenta "^\[(source,.+|NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]"
    # Other markup
    color yellow ".*[[:space:]]\+$"
    color yellow "_[^_]+_"
    color yellow "\*[^\*]+\*"
    color yellow "\+[^\+]+\+"
    color yellow "`[^`]+`"
    color yellow "\^[^\^]+\^"
    color yellow "~[^~]+~"
    color yellow "'[^']+'"
    color cyan "`{1,2}[^']+'{1,2}"
    # bullets
    color brightmagenta "^[[:space:]]*[\*\.-]{1,5}[[:space:]]"
    # anchors
    color brightwhite "\[\[.*\]\]"
    color brightwhite "<<.*>>"
    # trailing whitespace
    color ,blue "[[:space:]]+$"
    # multiples of eight spaces at the start a line
    # (after zero or more tabs) should be a tab
    color ,blue "^([TAB]*[ ]{8})+"
    # tabs after spaces
    color ,yellow "( )+TAB"
    # highlight indents that have an odd number of spaces
    color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"

Process the file to create embedded tabs:

    % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc

### 13.3.2. Use

Specify additional helpful options when running the editor:

    % nano -AKipwz -T8 _index.adoc

Users of csh(1) can define an alias in ~/.cshrc to automate these options:

    alias nano "nano -AKipwz -r 70 -T8"

After the alias is defined, the options will be added automatically:

    % nano _index.adoc

Last modified on: February 18, 2025 by Fernando Apesteguía

Prev
Home
Next