2 @comment %**start of header
3 @setfilename ../../info/htmlfontify.info
4 @settitle Htmlfontify User Manual
7 @comment %**end of header
10 This manual documents Htmlfontify, a source code -> crosslinked +
11 formatted + syntax colorized html transformer.
13 Copyright @copyright{} 2002-2003, 2013-2018 Free Software Foundation,
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
21 and with the Back-Cover Texts as in (a) below. A copy of the license
22 is included in the section entitled ``GNU Free Documentation License''.
24 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
25 modify this GNU manual.''
29 @dircategory Emacs misc features
31 * Htmlfontify: (htmlfontify). Convert source code to html.
35 @title Htmlfontify User Manual
37 @subtitle Htmlfontify version 0.20
41 @author Vivek Dasmohapatra
44 @vskip 0pt plus 1filll
59 * Introduction:: About Htmlfontify.
60 * Usage & Examples:: How to use Htmlfontify.
61 * Customization:: Fine-tuning Htmlfontify's behavior.
62 * Requirements:: External programs used by Htmlfontify.
63 * GNU Free Documentation License:: The license for this documentation.
64 * Index:: Index of contents.
71 Htmlfontify provides a means of converting individual Emacs buffers,
72 source files, or entire source trees to html, preserving formatting
73 and Emacs colorization / syntax highlighting as much as possible
74 through careful application of CSS stylesheets and html tags.
76 It can also turn instances of functions, methods and (for some
77 languages) variables and other constructs and items into links
78 to their definitions, and create an index file (or files) of
79 all such symbols, also linked to their points of definition.
81 Htmlfontify also provides several customization items, which should
82 allow it to mesh more-or-less seamlessly with various templating or
83 publishing systems (in the event, for instance, that you don't want
84 to produce the html pages directly).
86 @node Usage & Examples
87 @chapter Usage & Examples
88 @cindex Usage & Examples
90 Htmlfontify can be used both interactively and as part of another
91 elisp function. If you're running it in a modern Emacs, it will also
92 run when attached to a terminal (i.e., without X) or even when in
96 * Interactive:: Using Htmlfontify interactively.
97 * Non-interactive:: Using Htmlfontify from elisp.
98 * Variables:: Variables (other than customization entries).
99 * Data Structures:: Important data structures.
100 * Examples:: Example(s) of Htmlfontify in use.
106 @cindex functions (interactive)
108 Htmlfontify provides the following interactive functions:
111 @item htmlfontify-buffer
112 @findex htmlfontify-buffer
113 @anchor{htmlfontify-buffer}
117 (htmlfontify-buffer &optional @var{srcdir} @var{file})
120 Create a new buffer, named for the current buffer + a .html extension,
121 containing an inline CSS-stylesheet and formatted CSS-markup html that
122 reproduces the look of the current Emacs buffer as closely as possible.
124 ``Dangerous'' characters in the existing buffer are turned into html
125 entities, so you should even be able to do html-within-html fontified
128 You should, however, note that random control or non-ASCII characters
129 such as ^L (U+000C FORM FEED (FF)) or ยค (U+00A4 CURRENCY SIGN) won't
132 If the @var{srcdir} and @var{file} arguments are set, lookup etags
133 derived entries in the @ref{hfy-tags-cache} and add html anchors
134 and hyperlinks as appropriate.
136 @item htmlfontify-run-etags
137 @findex htmlfontify-run-etags
138 @anchor{htmlfontify-run-etags}
142 (htmlfontify-run-etags @var{srcdir})
145 Load the etags cache for @var{srcdir}. See @ref{hfy-load-tags-cache}.
147 @item htmlfontify-copy-and-link-dir
148 @findex htmlfontify-copy-and-link-dir
149 @anchor{htmlfontify-copy-and-link-dir}
153 (htmlfontify-copy-and-link-dir @var{srcdir} @var{dstdir} &optional @var{f-ext} @var{l-ext})
156 Trawl @var{srcdir} and write fontified-and-hyperlinked output in
157 @var{dstdir}. @var{f-ext} and @var{l-ext} specify values for
158 @ref{hfy-extn} and @ref{hfy-link-extn}.
160 You may also want to set @ref{hfy-page-header} and @ref{hfy-page-footer}.
162 @item htmlfontify-load-rgb-file
163 @findex htmlfontify-load-rgb-file
164 @anchor{htmlfontify-load-rgb-file}
168 (htmlfontify-load-rgb-file &optional @var{file})
171 Load an X11 style rgb.txt file (search @code{hfy-rgb-load-path} if
172 @var{file} is not specified).
174 Note that this is not necessary if all you want is the standard X11
175 (XFree86 4.1.0) color name -> rgb triplet mapping. Htmlfontify has
176 a copy built in, for use when it cannot contact an X server.
178 Loads the variable @code{hfy-rgb-txt-color-map}, which is used by
179 @ref{hfy-fallback-color-values}.
181 @item htmlfontify-unload-rgb-file
182 @findex htmlfontify-unload-rgb-file
183 @anchor{htmlfontify-unload-rgb-file}
187 (htmlfontify-unload-rgb-file)
190 Unload the currently loaded X11 style rgb.txt file (if any).
193 @node Non-interactive
194 @section Non-interactive
195 @cindex Noninteractive
196 @cindex functions (noninteractive)
198 In addition to the aforementioned interactive methods, Htmlfontify
199 provides the following non-interactive ones:
202 @comment AUTOGENERATED BLOCK
204 @item hfy-face-to-style
205 @findex hfy-face-to-style
206 @anchor{hfy-face-to-style}
210 (hfy-face-to-style @var{fn})
213 Take @var{fn}, a font or @code{defface} style font specification,
214 (as returned by @code{face-attr-construct} or @ref{hfy-face-attr-for-class})
215 and return a @ref{hfy-style-assoc}.
217 See also: @ref{hfy-face-to-style-i}, @ref{hfy-flatten-style}.
219 @item hfy-fallback-color-values
220 @findex hfy-fallback-color-values
221 @anchor{hfy-fallback-color-values}
225 (hfy-fallback-color-values @var{color-string})
228 Use a fallback method for obtaining the rgb values for a color.
229 If @ref{htmlfontify-load-rgb-file} has been called, it uses the
230 color map specified, otherwise it uses Htmlfontify's built in map.
232 @item hfy-combined-face-spec
233 @findex hfy-combined-face-spec
234 @anchor{hfy-combined-face-spec}
238 (hfy-combined-face-spec @var{face})
241 Return a @code{defface} style alist of possible specifications for
242 @var{face}, with any entries resulting from user customization
243 (@code{custom-set-faces}) taking precedence.
245 See also: @ref{hfy-default-face-def}
248 @findex hfy-word-regex
249 @anchor{hfy-word-regex}
253 (hfy-word-regex @var{string})
256 Return a regex that matches @var{string} as the first @code{match-string},
257 with non word characters on either side (vaguely emulating the perl @code{\b}
260 @item hfy-force-fontification
261 @findex hfy-force-fontification
262 @anchor{hfy-force-fontification}
266 (hfy-force-fontification)
269 Emacs's fontification is designed for interactive use. As such, it sometimes
270 does things like deferring fontification until a section of the buffer is
271 exposed and rendered, or until Emacs is idle for a while. Sometimes, in
272 non-interactive circumstances, or if it can't see X, it doesn't bother
273 with some of the harder stuff. While this is all great from the perspective
274 of a user waiting for Emacs to load a 20000 line file and colorize it,
275 it's a pain from the point of view from non-interactive code. This function
276 lies, cheats, steals and generally bullies Emacs into fontifying a buffer
277 from start to finish, with all the extra frills, whether it thinks it needs
278 to or not. Oh yes: it operates on the current buffer.
280 @item hfy-link-style-string
281 @findex hfy-link-style-string
282 @anchor{hfy-link-style-string}
286 (hfy-link-style-string @var{style-string})
289 Replace the end of a CSS style declaration @var{style-string} with the contents
290 of the variable @ref{hfy-src-doc-link-style}, removing text matching the
291 regex @ref{hfy-src-doc-link-unstyle} first, if necessary.
294 @item hfy-prepare-index-i
295 @findex hfy-prepare-index-i
296 @anchor{hfy-prepare-index-i}
300 (hfy-prepare-index-i @var{srcdir} @var{dstdir} @var{filename} &optional @var{stub} @var{map})
303 Prepare a tags index buffer for @var{srcdir}.
304 @ref{hfy-tags-cache} must already have an entry for @var{srcdir} for
305 this to work. @ref{hfy-page-header}, @ref{hfy-page-footer},
306 @ref{hfy-link-extn} and @ref{hfy-extn} all play a part here.
308 If @var{stub} is set, prepare an (appropriately named) index buffer
309 specifically for entries beginning with @var{stub}.
311 If @var{map} is set, use that instead of @ref{hfy-tags-cache}.
313 @item hfy-compile-stylesheet
314 @findex hfy-compile-stylesheet
315 @anchor{hfy-compile-stylesheet}
319 (hfy-compile-stylesheet)
322 Trawl the current buffer, construct and return a @ref{hfy-sheet-assoc}.
326 @anchor{hfy-css-name}
330 (hfy-css-name @var{fn})
333 Strip some of the boring bits from a font-name and return a CSS style
334 name. If @var{fn} is a @code{defface} attribute list, either construct
335 a name for it, store it in the cache, and return it, or just fetch it
336 from the cache if it's already there.
338 @item hfy-make-directory
339 @findex hfy-make-directory
340 @anchor{hfy-make-directory}
344 (hfy-make-directory @var{dir})
347 Approximate equivalent of @code{mkdir -p @var{dir}}.
355 (hfy-triplet @var{color})
358 Takes a color name (string) and return a CSS rgb(R, G, B) triplet string.
359 Uses the definition of ``white'' to map the numbers to the 0-255 range, so
360 if you've redefined white, (especially if you've redefined it to have
361 a triplet member lower than that of the color you are processing,
362 strange things may happen).
364 @item hfy-default-footer
365 @findex hfy-default-footer
366 @anchor{hfy-default-footer}
370 (hfy-default-footer @var{file})
373 Default value for @ref{hfy-page-footer}
376 @findex hfy-list-files
377 @anchor{hfy-list-files}
381 (hfy-list-files @var{directory})
384 Return a list of files under @var{directory}.
385 Strips any leading @samp{./} from each filename.
388 @findex hfy-color-vals
389 @anchor{hfy-color-vals}
393 (hfy-color-vals @var{color})
396 Where @var{color} is a color name or #XXXXXX style triplet, return a list of
397 3 (16 bit) rgb values for said color. If a window system is unavailable,
398 calls @ref{hfy-fallback-color-values}.
401 @findex hfy-href-stub
402 @anchor{hfy-href-stub}
406 (hfy-href-stub @var{this-file} @var{def-files} @var{tag})
409 Return an href stub for a tag href: if @var{def-files} (list of files
410 containing definitions for the tag in question) contains only one entry,
411 the href should link straight to that file. Otherwise, the link should
412 be to the index file.
414 We are not yet concerned with the file extensions/tag line number and
417 If @ref{hfy-split-index} is set, and the href will be to an index file
418 rather than a source file, append a @samp{.X} to @ref{hfy-index-file}, where
419 @samp{X} is the uppercased first character of @var{tag}.
421 See also: @ref{hfy-relstub}, @ref{hfy-index-file}.
423 @item hfy-line-number
424 @findex hfy-line-number
425 @anchor{hfy-line-number}
432 Returns the line number of the point in the current buffer.
434 @item hfy-merge-adjacent-spans
435 @findex hfy-merge-adjacent-spans
436 @anchor{hfy-merge-adjacent-spans}
440 (hfy-merge-adjacent-spans @var{face-map})
443 Where @var{face-map} is a @ref{hfy-facemap-assoc} for the current buffer,
444 this function merges adjacent style blocks which are of the same value
445 and are separated by nothing more interesting than whitespace.
447 @code{<span class="foo">narf</span> <span class="foo">brain</span>}
449 (as interpreted from @var{face-map}) would become:
451 @code{<span class="foo">narf brain</span>}
453 Returns a modified copy of @var{face-map} (also a @ref{hfy-facemap-assoc}).
455 @item hfy-mark-tag-names
456 @findex hfy-mark-tag-names
457 @anchor{hfy-mark-tag-names}
461 (hfy-mark-tag-names @var{srcdir} @var{file})
464 Mark tags in @var{file} (lookup @var{srcdir} in @ref{hfy-tags-cache}) with the
465 @code{hfy-anchor} property, with a value of @samp{tag.line-number}.
473 (hfy-weight @var{weight})
476 Derive a font-weight CSS specifier from an Emacs weight specification symbol.
484 (hfy-size @var{height})
487 Derive a CSS font-size specifier from an Emacs font @code{:height} attribute.
488 Does not cope with the case where height is a function to be applied to
489 the height of the underlying font.
491 @item hfy-default-header
492 @findex hfy-default-header
493 @anchor{hfy-default-header}
497 (hfy-default-header @var{file} @var{style})
500 Default value for @ref{hfy-page-header}
508 (hfy-family @var{family})
511 Derives a CSS font-family specifier from an Emacs @code{:family} attribute.
513 @item hfy-mark-tag-hrefs
514 @findex hfy-mark-tag-hrefs
515 @anchor{hfy-mark-tag-hrefs}
519 (hfy-mark-tag-hrefs @var{srcdir} @var{file})
522 Mark href start points with the @code{hfy-link} property (value: href string).
524 Mark href end points with the @code{hfy-endl} property (value @code{t}).
526 Avoid overlapping links, and mark links in descending length of
527 tag name in order to prevent subtags from usurping supertags;
528 e.g., ``term'' for ``terminal'').
539 Derive CSS border-* attributes from the Emacs @code{:box} attribute.
541 @item hfy-box-to-style
542 @findex hfy-box-to-style
543 @anchor{hfy-box-to-style}
547 (hfy-box-to-style @var{spec})
550 Convert a complex @code{:box} Emacs font attribute set to a list of
551 CSS border-* attributes. Don't call this directly---it is called by
552 @ref{hfy-box} when necessary.
554 @item hfy-html-enkludge-buffer
555 @findex hfy-html-enkludge-buffer
556 @anchor{hfy-html-enkludge-buffer}
560 (hfy-html-enkludge-buffer)
563 Mark dangerous @samp{["<>]} characters with the @code{hfy-quoteme} property.
565 See also @ref{hfy-html-dekludge-buffer}.
576 Generate and return an Htmlfontify html output buffer for the current
577 buffer. May trample an existing buffer.
579 @item hfy-fontified-p
580 @findex hfy-fontified-p
581 @anchor{hfy-fontified-p}
588 @code{font-lock} doesn't like to say a buffer's been fontified when in
589 batch mode, but we want to know if we should fontify or raw copy, so in
590 batch mode we check for non-default face properties. Otherwise we test
591 @code{font-lock-mode} and @code{font-lock-fontified} for truth.
599 (hfy-lookup @var{face} @var{style})
602 Where @var{style} is a @ref{hfy-sheet-assoc} and @var{face} is an Emacs face,
603 return the relevant @var{css} style name.
605 @item hfy-fontify-buffer
606 @findex hfy-fontify-buffer
607 @anchor{hfy-fontify-buffer}
611 (hfy-fontify-buffer &optional @var{srcdir} @var{file})
614 Implement the guts of @ref{htmlfontify-buffer}.
622 (hfy-color @var{color})
625 Convert an Emacs :foreground property to a CSS color property.
627 @item hfy-flatten-style
628 @findex hfy-flatten-style
629 @anchor{hfy-flatten-style}
633 (hfy-flatten-style @var{style})
636 Take @var{style} (see @ref{hfy-face-to-style-i}, @ref{hfy-face-to-style})
637 and merge any multiple attributes appropriately. Currently only font-size is
638 merged down to a single occurrence---others may need special handling, but I
639 haven't encountered them yet. Returns a @ref{hfy-style-assoc}.
641 @item hfy-size-to-int
642 @findex hfy-size-to-int
643 @anchor{hfy-size-to-int}
647 (hfy-size-to-int @var{spec})
650 Convert @var{spec}, a CSS font-size specifier, back to an Emacs
651 @code{:height} attribute value. Used while merging multiple font-size
654 @item hfy-sprintf-stylesheet
655 @findex hfy-sprintf-stylesheet
656 @anchor{hfy-sprintf-stylesheet}
660 (hfy-sprintf-stylesheet @var{css} @var{file})
663 Generates a header, via @ref{hfy-page-header}, for @var{file}, containing the
664 stylesheet derived from @var{css}, which is a @ref{hfy-sheet-assoc}. Returns a
665 string containing the same.
673 (hfy-relstub @var{file} &optional @var{start})
676 Return a @samp{../} stub of the appropriate length for the current source
677 tree depth (as determined from @var{file}). @c iyswim.
679 @item hfy-compile-face-map
680 @findex hfy-compile-face-map
681 @anchor{hfy-compile-face-map}
685 (hfy-compile-face-map)
688 Compile and return a @ref{hfy-facemap-assoc} for the current buffer.
690 @item hfy-prepare-index
691 @findex hfy-prepare-index
692 @anchor{hfy-prepare-index}
696 (hfy-prepare-index @var{srcdir} @var{dstdir})
699 Return as list of index buffer(s), as determined by @ref{hfy-split-index}.
700 Uses @ref{hfy-prepare-index-i} to do this.
702 @item hfy-prepare-tag-map
703 @findex hfy-prepare-tag-map
704 @anchor{hfy-prepare-tag-map}
708 (hfy-prepare-tag-map @var{srcdir} @var{dstdir})
711 Prepare the counterpart(s) to the index buffer(s)---a list of buffers with
712 the same structure, but listing (and linking to) instances of tags (as
713 opposed to their definitions).
715 See also: @ref{hfy-prepare-index}, @ref{hfy-split-index}
717 @item hfy-subtract-maps
718 @findex hfy-subtract-maps
719 @anchor{hfy-subtract-maps}
723 (hfy-subtract-maps @var{srcdir})
726 Internal function---strips definitions of tags from the instance map.
727 See: @ref{hfy-tags-cache} and @ref{hfy-tags-rmap}
729 @item hfy-face-to-style-i
730 @findex hfy-face-to-style-i
731 @anchor{hfy-face-to-style-i}
735 (hfy-face-to-style-i @var{fn})
738 The guts of @ref{hfy-face-to-style}. @var{fn} should be a @code{defface}
739 font specification, as returned by @code{face-attr-construct} or
740 @ref{hfy-face-attr-for-class}. Note that this function does not get
741 font-sizes right if they are based on inherited modifiers (via the
742 :inherit) attribute, and any other modifiers that are cumulative if they
743 appear multiple times need to be merged by the user---@ref{hfy-flatten-style}
746 @item hfy-face-to-css
747 @findex hfy-face-to-css
748 @anchor{hfy-face-to-css}
752 (hfy-face-to-css @var{fn})
755 Take @var{fn}, a font or @code{defface} specification (c.f.
756 @code{face-attr-construct}) and return a CSS style specification.
758 See also: @ref{hfy-face-to-style}
761 @findex hfy-html-quote
762 @anchor{hfy-html-quote}
766 (hfy-html-quote @var{char-string})
769 Map a string (usually 1 character long) to an html safe string
773 @findex hfy-link-style
774 @anchor{hfy-link-style}
778 (hfy-link-style @var{style-string})
781 Convert the CSS style spec @var{style-string} to its equivalent
784 See: @ref{hfy-link-style-fun}.
787 @findex hfy-p-to-face
788 @anchor{hfy-p-to-face}
792 (hfy-p-to-face @var{props})
795 Given @var{props}, a list of text-properties, return the value of the
796 face property, or @code{nil}.
798 @item hfy-box-to-border-assoc
799 @findex hfy-box-to-border-assoc
800 @anchor{hfy-box-to-border-assoc}
804 (hfy-box-to-border-assoc @var{spec})
807 Helper function for @ref{hfy-box-to-style}.
809 @item hfy-face-attr-for-class
810 @findex hfy-face-attr-for-class
811 @anchor{hfy-face-attr-for-class}
815 (hfy-face-attr-for-class @var{face} &optional @var{class})
818 Return the face attributes for @var{face}. If @var{class} is set, it
819 must be a @code{defface} alist key [see below]. Prior to version 0.18,
820 the first face specification returned by @ref{hfy-combined-face-spec}
821 which @emph{didn't} clash with @var{class} was returned. In versions
822 from 0.18 onwards, each font attribute list is scored, and the
823 non-conflicting list with the highest score is returned. (A specification
824 with a class of @code{t} is considered to match any class you specify.
825 This matches Emacs's behavior when deciding on which face attributes to
826 use, to the best of my understanding ).
828 If @var{class} is @code{nil}, then you just get whatever
829 @code{face-attr-construct} returns; i.e., the current specification in
830 effect for @var{face}.
832 See @ref{hfy-display-class} for details of valid values for @var{class}.
843 Find face in effect at point P@. If overlays are to be considered
844 (see @ref{hfy-optimizations}) then this may return a @code{defface} style
845 list of face properties instead of a face symbol.
853 (hfy-bgcol @var{color})
856 As per @ref{hfy-color} but for background colors.
858 @item hfy-kludge-cperl-mode
859 @findex hfy-kludge-cperl-mode
860 @anchor{hfy-kludge-cperl-mode}
864 (hfy-kludge-cperl-mode)
867 cperl mode does its best to not do some of its fontification when not
868 in a windowing system---we try to trick it@dots{}
876 (hfy-href @var{this-file} @var{def-files} @var{tag} @var{tag-map})
879 Return a relative href to the tag in question, based on
881 @var{this-file} @ref{hfy-link-extn} @ref{hfy-extn} @var{def-files} @var{tag} and @var{tag-map}
883 @var{this-file} is the current source file
884 @var{def-files} is a list of file containing possible link endpoints for @var{tag}
885 @var{tag} is the @var{tag} in question
886 @var{tag-map} is the entry in @ref{hfy-tags-cache}.
897 Returns a best guess at a Bourne compatible shell to use: If the current
898 shell doesn't look promising, fall back to @ref{hfy-shell-file-name}.
900 @item hfy-load-tags-cache
901 @findex hfy-load-tags-cache
902 @anchor{hfy-load-tags-cache}
906 (hfy-load-tags-cache @var{srcdir})
909 Run @ref{hfy-etags-cmd} on @var{srcdir}: load @ref{hfy-tags-cache} and @ref{hfy-tags-sortl}.
911 @item hfy-parse-tags-buffer
912 @findex hfy-parse-tags-buffer
913 @anchor{hfy-parse-tags-buffer}
917 (hfy-parse-tags-buffer @var{srcdir} @var{buffer})
920 Parse a @var{buffer} containing etags formatted output, loading the
921 @ref{hfy-tags-cache} and @ref{hfy-tags-sortl} entries for @var{srcdir}.
929 (hfy-interq @var{set-a} @var{set-b})
932 Return the intersection (using @code{eq}) of 2 lists.
940 (hfy-text-p @var{srcdir} @var{file})
943 Is @var{srcdir}/@var{file} text? Uses @ref{hfy-istext-command} to determine this.
951 (hfy-opt @var{symbol})
954 Is @ref{hfy-optimizations} member @var{symbol} set or not?
962 (hfy-dirname @var{file})
965 Return everything preceding the last @samp{/} from a relative filename,
966 on the assumption that this will produce the name of a relative
967 directory. Hardly bombproof, but good enough in the context in which
970 @item hfy-html-dekludge-buffer
971 @findex hfy-html-dekludge-buffer
972 @anchor{hfy-html-dekludge-buffer}
976 (hfy-html-dekludge-buffer)
979 Transform all dangerous characters marked with the @code{hfy-quoteme} property
980 using @ref{hfy-html-quote}
982 See also @ref{hfy-html-enkludge-buffer}.
984 @item hfy-copy-and-fontify-file
985 @findex hfy-copy-and-fontify-file
986 @anchor{hfy-copy-and-fontify-file}
990 (hfy-copy-and-fontify-file @var{srcdir} @var{dstdir} @var{file})
993 Open @var{file} in @var{srcdir}---if fontified, write a fontified copy to @var{dstdir}
994 adding an extension of @ref{hfy-extn}. Fontification is actually done by
995 @ref{htmlfontify-buffer}. If the buffer is not fontified, just copy it.
1003 (hfy-decor @var{tag} @var{val})
1006 Derive CSS text-decoration specifiers from various Emacs font attributes.
1014 (hfy-slant @var{slant})
1017 Derive a font-style CSS specifier from the Emacs :slant
1018 attribute---CSS does not define the reverse-* styles, so just maps
1019 those to the regular specifiers.
1021 @item hfy-tags-for-file
1022 @findex hfy-tags-for-file
1023 @anchor{hfy-tags-for-file}
1027 (hfy-tags-for-file @var{srcdir} @var{file})
1030 List of etags tags that have definitions in this @var{file}. Looks up
1031 the tags cache in @ref{hfy-tags-cache} using @var{srcdir} as the key.
1039 (hfy-width @var{width})
1042 Convert an Emacs @code{:width} attribute to a CSS font-stretch attribute.
1044 @comment /AUTOGENERATED BLOCK
1051 Important variables that are not customization items:
1055 @item hfy-tags-cache
1056 @vindex hfy-tags-cache
1057 @anchor{hfy-tags-cache}
1059 This is an alist of the form:
1062 (("/src/dir/0" . tag-hash0) ("/src/dir/1" tag-hash1) @dots{} )
1065 Each tag hash entry then contains entries of the form:
1068 "tag_string" => (("file/name.ext" line char) @dots{} )
1071 i.e., an alist mapping (relative) file paths to line and character offsets.
1073 See @ref{hfy-load-tags-cache}.
1076 @vindex hfy-tags-rmap
1077 @anchor{hfy-tags-rmap}
1079 @code{hfy-tags-rmap} is an alist of the form:
1082 (("/src/dir" . tag-rmap-hash))
1085 Where tag-rmap-hash has entries of the form:
1088 "tag_string" => ( "file/name.ext" line char )
1091 Unlike @ref{hfy-tags-cache} these are the locations of occurrences of
1092 tagged items, not the locations of their definitions.
1094 @item hfy-tags-sortl
1095 @vindex hfy-tags-sortl
1096 @anchor{hfy-tags-sortl}
1098 @code{hfy-tags-sortl} is an alist of the form:
1101 (("/src/dir" . (tag0 tag1 tag2)) @dots{} )
1104 Where the tags are stored in descending order of length.
1106 See: @ref{hfy-load-tags-cache}.
1110 @node Data Structures
1111 @section Data Structures
1112 @cindex Data Structures
1114 Some of the (informal) data structures used in Htmlfontify are detailed here:
1118 @item hfy-style-assoc
1119 @cindex @code{hfy-style-assoc}
1120 @anchor{hfy-style-assoc}
1122 An assoc representing/describing an Emacs face. Properties may be repeated,
1123 in which case later properties should be treated as if they were inherited
1124 from a ``parent'' font. (For some properties, only the first encountered value
1125 is of any importance, for others the values might be cumulative, and for
1126 others they might be cumulative in a complex way.)
1131 (hfy-face-to-style 'default) =>
1133 (("background" . "rgb(0, 0, 0)" )
1134 ("color" . "rgb(255, 255, 255)")
1135 ("font-style" . "normal" )
1136 ("font-weight" . "500" )
1137 ("font-stretch" . "normal" )
1138 ("font-family" . "misc-fixed" )
1139 ("font-size" . "13pt" )
1140 ("text-decoration" . "none" ))
1142 (hfy-face-to-style 'Info-title-3-face) =>
1144 (("font-weight" . "700" )
1145 ("font-family" . "helv" )
1146 ("font-size" . "120%" )
1147 ("text-decoration" . "none") )
1150 @item hfy-sheet-assoc
1151 @cindex @code{hfy-sheet-assoc}
1152 @anchor{hfy-sheet-assoc}
1154 An assoc with elements of the form @samp{(face-name style-name . style-string)}.
1155 The actual stylesheet for each page is derived from one of these.
1158 ((default "default" . "@{ background: black; color: white@}")
1159 (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}"))
1162 @item hfy-facemap-assoc
1163 @cindex @code{hfy-facemap-assoc}
1164 @anchor{hfy-facemap-assoc}
1166 An assoc of @code{(point . @var{face-symbol})} or
1167 @code{(point . @code{defface} attribute list)} and @code{(point
1168 . end)} elements, in descending order of point value (i.e., from the
1169 file's end to its beginning). The map is in reverse order because
1170 inserting a @samp{<style>} tag (or any other string) at @var{point}
1171 invalidates the map for all entries with a greater value of point. By
1172 traversing the map from greatest to least @var{point}, we still
1173 invalidate the map as we go, but only those points we have already
1174 dealt with (and therefore no longer care about) will be invalid at any
1179 (64744 . font-lock-comment-face)
1181 (64722 . font-lock-string-face)
1183 (64623 . font-lock-string-face)
1185 ;; Big similar section elided. You get the idea.
1187 (5431 . (:inherit font-lock-keyword-face :background "7e7e7e"))
1189 (4285 . font-lock-constant-face)
1191 (4221 . font-lock-comment-face)
1193 (4197 . font-lock-constant-face)
1195 (1 . font-lock-comment-face))
1204 The following is a lump of code I use to fontify source code on my
1205 site, @url{http://rtfm.etla.org/} (which was the reason, incidentally,
1206 that Htmlfontify was written in the first place).
1209 (defvar rtfm-section nil)
1211 ;; Constructs an appropriate header string to fit in with rtfm's
1212 ;; templating system, based on the file and the stylesheet string
1213 (defun rtfm-build-page-header (file style)
1214 (format "#define TEMPLATE red+black.html
1216 #include <build/menu-dirlist|>\n
1217 html-css-url := /css/red+black.css
1218 title := rtfm.etla.org ( %s / src/%s )
1220 head <=STYLESHEET;\n
1223 main-title := rtfm / %s / src/%s\n
1224 main-content <=MAIN_CONTENT;\n" rtfm-section file style rtfm-section file))
1227 (defun rtfm-build-page-footer (file) "\nMAIN_CONTENT\n")
1229 (defun rtfm-fontify-buffer (section)
1230 (interactive "s section[eg- emacs / p4-blame]: ")
1231 (require 'htmlfontify)
1232 (let ((hfy-page-header 'rtfm-build-page-header)
1233 (hfy-page-footer 'rtfm-build-page-footer)
1234 (rtfm-section section))
1235 (htmlfontify-buffer)
1239 ;; Here's the function I actually call---it asks me for a section label,
1240 ;; and source and destination directories, and then binds a couple of
1241 ;; customization variable in a let before calling htmlfontify:
1242 (defun rtfm-build-source-docs (section srcdir destdir)
1244 "s section[eg- emacs / p4-blame]:\nD source-dir: \nD output-dir: ")
1245 (require 'htmlfontify)
1246 (hfy-load-tags-cache srcdir)
1247 (let ((hfy-page-header 'rtfm-build-page-header)
1248 (hfy-page-footer 'rtfm-build-page-footer)
1249 (rtfm-section section)
1250 (hfy-index-file "index")
1251 (auto-mode-alist (append auto-mode-alist
1252 '(("dbi\\(shell\\|gtk\\)$" . cperl-mode)
1253 ("\\.xpm$" . c-mode ))))
1255 (htmlfontify-run-etags srcdir)
1256 (htmlfontify-copy-and-link-dir srcdir destdir ".src" ".html")))
1260 @chapter Customization
1261 @cindex variables (customization)
1263 Htmlfontify provides the following variable and customization entries:
1266 @comment AUTOGENERATED BLOCK
1268 @item hfy-link-style-fun
1269 @vindex hfy-link-style-fun
1270 @anchor{hfy-link-style-fun}
1272 Set this to a function, which will be called with one argument
1273 (a @samp{@{ foo: bar; @dots{}@}} CSS style-string)---it should return a copy of
1274 its argument, altered so as to make any changes you want made for text which
1275 is a hyperlink, in addition to being in the class to which that style would
1276 normally be applied.
1278 @item hfy-html-quote-regex
1279 @vindex hfy-html-quote-regex
1280 @anchor{hfy-html-quote-regex}
1282 @c FIXME: the cross-reference below looks ugly
1283 Regex to match (with a single back-reference per match) strings in HTML
1284 which should be quoted with @ref{hfy-html-quote}
1285 (and @pxref{hfy-html-quote-map}) to make them safe.
1287 @item hfy-page-footer
1288 @vindex hfy-page-footer
1289 @anchor{hfy-page-footer}
1291 As @ref{hfy-page-header}, but generates the output footer
1292 (and takes only 1 argument, the filename).
1294 @item hfy-display-class
1295 @vindex hfy-display-class
1296 @anchor{hfy-display-class}
1298 Display class to use to determine which display class to use when
1299 calculating a face's attributes. This is useful when, for example, you
1300 are running Emacs on a tty or in batch mode, and want Htmlfontify to have
1301 access to the face spec you would use if you were connected to an X display.
1303 Some valid class specification elements are:
1316 Multiple values for a tag may be combined, to indicate that any one or more
1317 of these values in the specification key constitutes a match. For
1318 example, @code{((class color grayscale) (type tty))} would match any of:
1323 ((class color grayscale)))
1326 ((type tty) (class color))
1329 @item hfy-page-header
1330 @vindex hfy-page-header
1331 @anchor{hfy-page-header}
1333 Function called with two arguments (the filename relative to the top
1334 level source directory being etagged and fontified), and a string containing
1335 the @samp{<style>@dots{}</style>} text to embed in the document---the string
1336 returned will be used as the header for the htmlfontified version of
1339 See also: @ref{hfy-page-footer}
1341 @item hfy-src-doc-link-style
1342 @vindex hfy-src-doc-link-style
1343 @anchor{hfy-src-doc-link-style}
1345 String to add to the @samp{<style> a} variant of an Htmlfontify CSS class.
1347 @item hfy-split-index
1348 @vindex hfy-split-index
1349 @anchor{hfy-split-index}
1351 Whether or not to split the index @ref{hfy-index-file} alphabetically
1352 on the first letter of each tag. Useful when the index would otherwise
1353 be large and take a long time to render or be difficult to navigate.
1356 @vindex hfy-find-cmd
1357 @anchor{hfy-find-cmd}
1359 The ``find'' command used to harvest a list of files to attempt to fontify.
1365 File extension used for output files.
1367 @item hfy-default-face-def
1368 @vindex hfy-default-face-def
1369 @anchor{hfy-default-face-def}
1371 Fallback @code{defface} specification for the face @code{default}, used
1372 when @ref{hfy-display-class} has been set (the normal Htmlfontify way of
1373 extracting potentially non-current face information doesn't necessarily
1374 work for @code{default}).
1376 For example, I customize this to:
1379 ((t :background "black" :foreground "white" :family "misc-fixed"))
1382 @item hfy-init-kludge-hook
1383 @vindex hfy-init-kludge-hook
1384 @anchor{hfy-init-kludge-hook}
1386 List of functions to call when starting htmlfontify-buffer to do any
1387 kludging necessary to get highlighting modes to behave as you want, even
1388 when not running under a window system.
1390 @item hfy-shell-file-name
1391 @vindex hfy-shell-file-name
1392 @anchor{hfy-shell-file-name}
1394 Should be set to a Bourne compatible shell, which will be invoked
1395 for the more complex shell interactions needed by Htmlfontify.
1396 Currently this is only required/used when using GNU etags, see
1397 @ref{hfy-etags-cmd-alist} for details.
1399 @item hfy-optimizations
1400 @vindex hfy-optimizations
1401 @anchor{hfy-optimizations}
1403 Optimizations to turn on. So far, the following have been implemented:
1406 @item merge-adjacent-tags
1407 If two (or more) span tags are adjacent, identical and separated by nothing
1408 more than whitespace, they will be merged into one span.
1410 @item zap-comment-links
1411 Suppress hyperlinking of tags found in comments.
1413 @item zap-string-links
1414 Suppress hyperlinking of tags found in strings.
1417 Add @samp{<div class="default"> </div>} tags around the fontified body.
1418 (Some people like this because they cut and paste the html into
1419 a page with different colors than the fontified code.)
1422 Preserve overlay highlighting (cf.@: @code{ediff} or @code{goo-font-lock})
1423 as well as basic faces. Can result in extremely verbose highlighting
1424 if there are many overlays (as is the case with @code{goo-font-lock}).
1428 And the following are planned but not yet available:
1431 @item kill-context-leak
1432 Suppress hyperlinking between files highlighted by different modes.
1436 Note: like compiler optimizations, these optimize the @emph{output} of
1438 not the processing of the source itself, and are therefore likely to slow
1439 Htmlfontify down, at least a little. Except for skip-refontification,
1440 which can never slow you down, but may result in incomplete fontification.
1442 @item hfy-src-doc-link-unstyle
1443 @vindex hfy-src-doc-link-unstyle
1444 @anchor{hfy-src-doc-link-unstyle}
1446 Regex to remove from the @samp{<style> a} variant of an Htmlfontify CSS class.
1449 @vindex hfy-link-extn
1450 @anchor{hfy-link-extn}
1452 File extension used for href links---useful where the Htmlfontify
1453 output files are going to be processed again, with a resulting change
1454 in file extension. If @code{nil}, then any code using this should fall back
1457 @item hfy-istext-command
1458 @vindex hfy-istext-command
1459 @anchor{hfy-istext-command}
1461 Command to run with the name of a file, to see whether it is a text file
1462 or not. The command should emit a string containing the word @samp{text} if
1463 the file is a text file, and a string not containing @samp{text} otherwise.
1465 @item hfy-etags-cmd-alist
1466 @vindex hfy-etags-cmd-alist
1467 @anchor{hfy-etags-cmd-alist}
1469 An alist of possible shell commands that will generate etags output that
1470 Htmlfontify can use. @samp{%s} will be replaced by @ref{hfy-etags-bin}.
1473 @vindex hfy-etags-bin
1474 @anchor{hfy-etags-bin}
1476 The location of the etags binary (we begin by assuming it's in your path).
1478 Note that if etags is not in your path, you will need to alter the shell
1479 commands in @ref{hfy-etags-cmd-alist}.
1481 [As of version 0.17, this requirement has been removed: it should
1485 @vindex hfy-etags-cmd
1486 @anchor{hfy-etags-cmd}
1488 An etags shell command to run in the source directory to generate a tags
1489 file for the whole source tree from there on down. The command should emit
1490 the etags output on standard output.
1492 Two canned commands are provided---they drive Emacs's etags and
1493 exuberant-ctags's etags respectively.
1495 @item hfy-etag-regex
1496 @vindex hfy-etag-regex
1497 @anchor{hfy-etag-regex}
1499 Regex used to parse an etags entry: must have 3 subexps, corresponding,
1508 The character (point) at which the tag occurs
1511 @item hfy-index-file
1512 @vindex hfy-index-file
1513 @anchor{hfy-index-file}
1515 Name (sans extension) of the index file produced during
1516 fontification-and-hyperlinking.
1518 @item hfy-instance-file
1519 @vindex hfy-instance-file
1520 @anchor{hfy-instance-file}
1522 Name (sans extension) of the tag usage index file produced during
1523 fontification-and-hyperlinking.
1525 @item hfy-html-quote-map
1526 @vindex hfy-html-quote-map
1527 @anchor{hfy-html-quote-map}
1529 An alist of character -> entity mappings used to make the text html-safe.
1531 @comment /AUTOGENERATED BLOCK
1535 @chapter Requirements
1536 @cindex Requirements, Prerequisites
1538 Htmlfontify has a couple of external requirements:
1543 GNU Emacs 20.7+ or 21.1+
1545 Other versions may work---these have been used successfully by the
1546 author. If you intend to use Htmlfontify in batch mode, 21.1+ is
1547 pretty much required. The author does not know if XEmacs, NTemacs,
1548 or J.Random Emacs will run Htmlfontify, but reports/patches/bags of
1549 money are always welcome.
1552 A copy of etags (exuberant-ctags or GNU etags). Htmlfontify attempts
1553 to autodetect the version you have and customize itself accordingly,
1554 but you should be able to override this.
1556 See: @ref{Customization}
1559 A copy of find (e.g., GNU find) that provides the @code{-path} predicate.
1561 You may be able to work around this with a suitable clever shell
1562 command and the customization entry: @ref{hfy-find-cmd}
1565 A copy of sed (e.g., GNU sed).
1568 A copy of the @code{file} command.
1572 @node GNU Free Documentation License
1573 @appendix GNU Free Documentation License
1574 @include doclicense.texi
1586 @item Variables & Customization
1591 @setchapternewpage odd