htmlfontify: Customization
3 Customization
***************
Htmlfontify provides the following variable and customization entries:
‘hfy-link-style-fun’
Set this to a function, which will be called with one argument (a
‘{ foo: bar; ...}’ CSS style-string)—it should return a copy of its
argument, altered so as to make any changes you want made for text
which is a hyperlink, in addition to being in the class to which
that style would normally be applied.
‘hfy-html-quote-regex’
Regex to match (with a single back-reference per match) strings in
DONTPRINTYET HTML which should be quoted with hfy-html-quote (and *noteDONTPRINTYET HTML which should be quoted with hfy-html-quote (and
hfy-html-quote-map) to make them safe.
‘hfy-page-footer’
As hfy-page-header, but generates the output footer (and
takes only 1 argument, the filename).
‘hfy-display-class’
Display class to use to determine which display class to use when
calculating a face’s attributes. This is useful when, for example,
you are running Emacs on a tty or in batch mode, and want
Htmlfontify to have access to the face spec you would use if you
were connected to an X display.
Some valid class specification elements are:
(class color)
(class grayscale)
(background dark)
(background light)
(type x-toolkit)
(type tty)
(type motif)
(type lucid)
Multiple values for a tag may be combined, to indicate that any one
or more of these values in the specification key constitutes a
match. For example, ‘((class color grayscale) (type tty))’ would
match any of:
((class color))
((class grayscale))
((class color grayscale)))
((class color foo))
((type tty))
((type tty) (class color))
‘hfy-page-header’
Function called with two arguments (the filename relative to the
top level source directory being etagged and fontified), and a
string containing the ‘<style>...</style>’ text to embed in the
document—the string returned will be used as the header for the
htmlfontified version of the source file.
See also: hfy-page-footer
‘hfy-src-doc-link-style’
String to add to the ‘<style> a’ variant of an Htmlfontify CSS
class.
‘hfy-split-index’
Whether or not to split the index hfy-index-file
alphabetically on the first letter of each tag. Useful when the
index would otherwise be large and take a long time to render or be
difficult to navigate.
‘hfy-find-cmd’
The “find” command used to harvest a list of files to attempt to
fontify.
‘hfy-extn’
File extension used for output files.
‘hfy-default-face-def’
Fallback ‘defface’ specification for the face ‘default’, used when
hfy-display-class has been set (the normal Htmlfontify way
of extracting potentially non-current face information doesn’t
necessarily work for ‘default’).
For example, I customize this to:
((t :background "black" :foreground "white" :family "misc-fixed"))
‘hfy-init-kludge-hooks’
List of functions to call when starting htmlfontify-buffer to do
any kludging necessary to get highlighting modes to behave as you
want, even when not running under a window system.
‘hfy-shell-file-name’
Should be set to a Bourne compatible shell, which will be invoked
for the more complex shell interactions needed by Htmlfontify.
Currently this is only required/used when using GNU etags, see
hfy-etags-cmd-alist for details.
‘hfy-optimizations’
Optimizations to turn on. So far, the following have been
implemented:
‘merge-adjacent-tags’
If two (or more) span tags are adjacent, identical and
separated by nothing more than whitespace, they will be merged
into one span.
‘zap-comment-links’
Suppress hyperlinking of tags found in comments.
‘zap-string-links’
Suppress hyperlinking of tags found in strings.
‘div-wrapper’
Add ‘<div class="default"> </div>’ tags around the fontified
body. (Some people like this because they cut and paste the
html into a page with different colors than the fontified
code.)
‘keep-overlays’
Preserve overlay highlighting (cf. ‘ediff’ or ‘goo-font-lock’)
as well as basic faces. Can result in extremely verbose
highlighting if there are many overlays (as is the case with
‘goo-font-lock’).
And the following are planned but not yet available:
‘kill-context-leak’
Suppress hyperlinking between files highlighted by different
modes.
Note: like compiler optimizations, these optimize the _output_ of
the code, not the processing of the source itself, and are
therefore likely to slow Htmlfontify down, at least a little.
Except for skip-refontification, which can never slow you down, but
may result in incomplete fontification.
‘hfy-src-doc-link-unstyle’
Regex to remove from the ‘<style> a’ variant of an Htmlfontify CSS
class.
‘hfy-link-extn’
File extension used for href links—useful where the Htmlfontify
output files are going to be processed again, with a resulting
change in file extension. If ‘nil’, then any code using this
should fall back to hfy-extn.
‘hfy-istext-command’
Command to run with the name of a file, to see whether it is a text
file or not. The command should emit a string containing the word
‘text’ if the file is a text file, and a string not containing
‘text’ otherwise.
‘hfy-etags-cmd-alist’
An alist of possible shell commands that will generate etags output
that Htmlfontify can use. ‘%s’ will be replaced by
hfy-etags-bin.
‘hfy-etags-bin’
The location of the etags binary (we begin by assuming it’s in your
path).
Note that if etags is not in your path, you will need to alter the
shell commands in hfy-etags-cmd-alist.
[As of version 0.17, this requirement has been removed: it should
all just work(tm).]
‘hfy-etags-cmd’
An etags shell command to run in the source directory to generate a
tags file for the whole source tree from there on down. The
command should emit the etags output on standard output.
Two canned commands are provided—they drive Emacs’s etags and
exuberant-ctags’s etags respectively.
‘hfy-etag-regex’
Regex used to parse an etags entry: must have 3 subexps,
corresponding, in order, to:
1. The tag
2. The line
3. The character (point) at which the tag occurs
‘hfy-index-file’
Name (sans extension) of the index file produced during
fontification-and-hyperlinking.
‘hfy-instance-file’
Name (sans extension) of the tag usage index file produced during
fontification-and-hyperlinking.
‘hfy-html-quote-map’
An alist of character -> entity mappings used to make the text
html-safe.