Debian Codegraph @

README.markdown

raw ◀ ▶
1 Debian patch touch this file
1 Many modern editors and IDEs can graphically indicate the location of the
2 fill column by drawing a thin line (in design parlance, a "rule") down the
3 length of the editing window. Fill-column-indicator implements this
4 facility in Emacs:
5
6 #### Please Note
7
8 There is a small incompatibility between this package and the current stable
9 Emacs relase (v24.3). See [issue #31](https://github.com/alpaker/Fill-Column-Indicator/issues/31) for more
10 information.
11
12 #### Installation and Usage
13
14 Put the package file in your load path and put
15
16 `(require 'fill-column-indicator)`
17
18 in your .emacs.
19
20 To toggle graphical indication of the fill column in a buffer, use the
21 command `fci-mode`.
22
23 #### Configuration
24
25 * By default fci-mode draws a vertical line at the fill column. If you'd
26 like it to be drawn at a different location, set `fci-rule-column` to the
27 desired column number. (A case in which this might be useful is when you
28 want to fill comments at, for example, column 70, but want a vertical rule
29 at column 80 or 100 to indicate the maximum line length for code.) The
30 default behavior (showing the indicator at the fill column) is specified by
31 setting fci-rule-column to nil. Note that this variable becomes buffer
32 local when set.
33
34 * On graphical displays the fill-column rule is drawn using a bitmap
35 image. Its color is controlled by the variable `fci-rule-color`, whose
36 value can be any valid color name. The rule's width in pixels is
37 determined by the variable `fci-rule-width`; the default value is 1.
38
39 * The rule can be drawn as a solid or dashed line, as specified by the
40 variable `fci-rule-use-dashes`; the default is nil. The length of the
41 dashes is controlled by `fci-dash-pattern`, which is the ratio of dash
42 length to line height; the default value is 0.75. (The value should be a
43 number between 0 and 1; values outside that interval are coerced to the
44 nearest endpoint.)
45
46 * The image formats fci-mode can use are XPM and PBM. If Emacs has
47 been compiled with the appropriate library it uses XPM images by default;
48 if not it uses PBM images, which are natively supported. You can specify a
49 particular format by setting `fci-rule-image-format` to either `xpm` or `pbm`.
50
51 * On character terminals the rule is drawn using the character specified by
52 `fci-rule-character`; the default is \`|' (ascii 124). If
53 `fci-rule-character-color` is nil, then it is drawn using fci-rule-color
54 (or the closest approximation thereto that the terminal is capable of); if
55 it is a color name, then that color is used instead.
56
57 * If you'd like the rule to be drawn using fci-rule-character even on
58 graphical displays, set `fci-always-use-textual-rule` to a non-nil value.
59
60 These variables (as well as those in the next section) can be given
61 buffer-local bindings.
62
63
64 #### Other Options
65
66 When `truncate-lines` is nil, the effect of drawing a fill-column rule is
67 very odd looking. Indeed, it makes little sense to use a rule to indicate
68 the position of the fill column in that case (the positions at which the
69 fill column falls in the visual display space won't in general be
70 collinear). For this reason, fci-mode sets truncate-lines to t in buffers
71 in which it is enabled and restores it to its previous value when
72 disabled. You can turn this feature off by setting
73 `fci-handle-truncate-lines` to nil.
74
75 If `line-move-visual` is t, then vertical navigation can behave oddly in
76 several edge cases while fci-mode is enabled (this is due to a bug in Emacs's
77 C code). Accordingly, fci-mode sets line-move-visual to nil in buffers in
78 which it is enabled and restores it to its previous value when
79 disabled. This can be suppressed by setting `fci-handle-line-move-visual` to
80 nil. (But you shouldn't want to do this. There's no reason to use
81 line-move-visual if truncate-lines is t, and it doesn't make sense to use
82 something like fci-mode when truncate-lines is nil.)
83
84 Fci-mode needs free use of two characters (specifically, it needs the use
85 of two characters whose display table entries it can change
86 arbitrarily). By default, it uses the first two characters of the Private
87 Use Area of the Unicode BMP, viz. U+E000 and U+E001. If you need to use
88 those characters for some other purpose, set `fci-eol-char` and
89 `fci-blank-char` to different values.
90
91 #### Troubleshooting
92
93 * Fci-mode is intended to be used with monospaced fonts. If you're using
94 a monospaced font and the fill-column rule is missing or misaligned on a
95 few lines but otherwise appears normal, then most likely (a) there are
96 non-ascii characters on those lines that are being displayed using a
97 non-monospaced font, or (b) your font-lock settings use bold or italics
98 and those font variants aren't monospaced.
99
100 * Fci-mode in not currently compatible with Emacs's
101 `show-trailing-whitespace` feature (given the way the latter is
102 implemented, such compatilibility is going to be hard to achieve). A
103 workaround is to use `whitespace-mode` with an appropriate
104 configuration. This will provide the same functionality as
105 show-trailing-whitespace while remaning compatible with fci-mode. The
106 appropriate whitespace setting is:
107
108 (setq whitespace-style '(face trailing))
109
110 #### Known Issues
111
112 * The indicator extends only to end of the buffer contents (as opposed to
113 running the full length of the editing window).
114
115 * When portions of a buffer are invisible, such as when outline mode is
116 used to hide certain lines, the fill-column rule is hidden as
117 well.
118
119 * Fci-mode should work smoothly when simultaneously displaying the same
120 buffer on both a graphical display and on a character terminal. It does
121 not currently support simultaneous display of the same buffer on window
122 frames with different default font sizes. (It would be feasible to
123 support this use case, but thus far there seems to be no demand for
124 it.)
125
126 * An issue specific to the Mac OS X (NextStep) port, versions 23.0-23.2:
127 Emacs won't, in these particular versions, draw a cursor on top of an
128 image. Thus on graphical displays the cursor will disappear when
129 positioned directly on top of the fill-column rule. The best way to deal
130 with this is to upgrade to v23.3 or v24 (or downgrade to v22). If that
131 isn't practical, a fix is available via the mini-package `fci-osx-23-fix.el`,
132 which can be downloaded from this page. Directions for its use are given
133 in the file header.
134
135 #### Todo
136
137 * Accommodate non-nil values of `hl-line-sticky-flag` and similar cases.
138
139 * Accommodate linum-mode more robustly.
140
141 * Compatibility with non-nil `show-trailing-whitespace`.
142
143
144 #### Acknowledgements
145
146 Thanks to Ami Fischman, Christopher Genovese, Michael Hoffman, José Alfredo
147 Romero L., R. Lange, Joe Lisee, José Lombera, Frank Meffert, Mitchell
148 Peabody, sheijk, and an anonymous BT subscriber for bug reports and
149 suggestions. Special thanks to lomew, David Röthlisberger, and Pär
150 Wieslander for code contributions.