---
title: Chapter 12. Editor Configuration
prev: books/fdp-primer/writing-style
next: books/fdp-primer/see-also
description: Configuration used in the texts editors in the FreeBSD Documentation Project
tags: ["editor", "configuration", "vim", "emacs", "FreeBSD"]
showBookMenu: true
weight: 13
path: "/books/fdp-primer/"
---

[[editor-config]]
= Editor Configuration
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 12
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/fdp-primer/

ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]

ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]

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

[[editor-config-vim]]
== Vim

Install from package:editors/vim[], package:editors/vim-console[], or package:editors/vim-tiny[] then follow the configuration instructions in <<editor-config-vim-config>>.

[[editor-config-vim-use]]
=== Use

Press kbd:[P] to reformat paragraphs or text that has been selected in Visual mode.
Press kbd:[T] to replace groups of eight spaces with a tab.

[[editor-config-vim-config]]
=== Configuration

Edit [.filename]#~/.vimrc#, adding these lines to the end of the file:

[.programlisting]
....
if has("autocmd")
    au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
    au BufNewFile,BufRead *.[1-9] call ShowSpecial()
endif " has(autocmd)

function Set_Highlights()
    "match ExtraWhitespace /^\s* \s*\|\s\+$/
    highlight default link OverLength ErrorMsg
    match OverLength /\%71v.\+/
    return 0
endfunction " Set_Highlights()

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

function Set_SGML()
    setlocal number
    syn match sgmlSpecial "&[^;]*;"
    setlocal syntax=sgml
    setlocal filetype=xml
    setlocal shiftwidth=2
    setlocal textwidth=70
    setlocal tabstop=8
    setlocal softtabstop=2
    setlocal formatprg="fmt -p"
    setlocal autoindent
    setlocal smartindent
    " Rewrap paragraphs
    noremap P gqj
    " Replace spaces with tabs
    noremap T :s/        /\t/<CR>
    call ShowSpecial()
    call Set_Highlights()
    return 0
endfunction " Set_SGML()
....

[[editor-config-emacs]]
== Emacs

Install from package:editors/emacs[] or package:editors/emacs-devel[].

[[editor-config-emacs-validation]]
=== Validation

Emacs's nxml-mode uses compact relax NG schemas for validating XML.
A compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included in the documentation repository.
To configure nxml-mode to validate using this schema, create [.filename]#~/.emacs.d/schema/schemas.xml# and add these lines to the file:

....
locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0"
  documentElement localName="section" typeId="DocBook"
  documentElement localName="chapter" typeId="DocBook"
  documentElement localName="article" typeId="DocBook"
  documentElement localName="book" typeId="DocBook"
  typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc"
locatingRules
....

[[editor-config-emacs-igor]]
=== 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 [.filename]#~/.emacs#, [.filename]#~/.emacs.el#, or [.filename]#~.emacs.d/init.el#) to make this change permanent.

To install Flycheck, evaluate

....
(package-install 'flycheck)
....

Create a Flycheck checker for package: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.

[[editor-config-emacs-specifc]]
=== FreeBSD Documentation Specific Settings

To apply settings specific to the FreeBSD documentation project, create [.filename]#.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"))))
....

[[editor-config-nano]]
== nano

Install from package:editors/nano[] or package:editors/nano-devel[].

[[editor-config-nano-config]]
=== Configuration

Copy the sample XML syntax highlight file to the user's home directory:

[source,shell]
....
% cp /usr/local/share/nano/xml.nanorc ~/.nanorc
....

Use an editor to replace the lines in the [.filename]#~/.nanorc# `syntax "xml"` block with these rules:

....
syntax "xml" "\.([jrs]html?|xml|xslt?)$"
# 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}"
# lines longer than 70 characters
color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"
....

Process the file to create embedded tabs:

[source,shell]
....
% perl -i'' -pe 's/TAB/\t/g' ~/.nanorc
....

[[editor-config-nano-use]]
=== Use

Specify additional helpful options when running the editor:

[source,shell]
....
% nano -AKipwz -r 70 -T8 _index.adoc
....

Users of man:csh[1] can define an alias in [.filename]#~/.cshrc# to automate these options:

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

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

[source,shell]
....
% nano _index.adoc
....