04b118c626
Correct some grammar, some factual information and a misrepresentation of that the "word list" is. Submitted by: ceri PR: 253467
217 lines
5.9 KiB
Text
217 lines
5.9 KiB
Text
---
|
|
title: Chapter 12. Editor Configuration
|
|
prev: books/fdp-primer/writing-style
|
|
next: books/fdp-primer/see-also
|
|
---
|
|
|
|
[[editor-config]]
|
|
= Editor Configuration
|
|
:doctype: book
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:icons: font
|
|
:sectnums:
|
|
:sectnumlevels: 6
|
|
:source-highlighter: rouge
|
|
:experimental:
|
|
:skip-front-matter:
|
|
:xrefstyle: basic
|
|
:relfileprefix: ../
|
|
:outfilesuffix:
|
|
:sectnumoffset: 12
|
|
|
|
toc::[]
|
|
|
|
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/shared/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,bash]
|
|
....
|
|
% cp /usr/local/shared/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,bash]
|
|
....
|
|
% perl -i'' -pe 's/TAB/\t/g' ~/.nanorc
|
|
....
|
|
|
|
[[editor-config-nano-use]]
|
|
=== Use
|
|
|
|
Specify additional helpful options when running the editor:
|
|
|
|
[source,bash]
|
|
....
|
|
% 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,bash]
|
|
....
|
|
% nano _index.adoc
|
|
....
|