| 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. |