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-2017 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 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 a relative directory name. Hardly
967 bombproof, but good enough in the context in which it is being used.
969 @item hfy-html-dekludge-buffer
970 @findex hfy-html-dekludge-buffer
971 @anchor{hfy-html-dekludge-buffer}
975 (hfy-html-dekludge-buffer)
978 Transform all dangerous characters marked with the @code{hfy-quoteme} property
979 using @ref{hfy-html-quote}
981 See also @ref{hfy-html-enkludge-buffer}.
983 @item hfy-copy-and-fontify-file
984 @findex hfy-copy-and-fontify-file
985 @anchor{hfy-copy-and-fontify-file}
989 (hfy-copy-and-fontify-file @var{srcdir} @var{dstdir} @var{file})
992 Open @var{file} in @var{srcdir}---if fontified, write a fontified copy to @var{dstdir}
993 adding an extension of @ref{hfy-extn}. Fontification is actually done by
994 @ref{htmlfontify-buffer}. If the buffer is not fontified, just copy it.
1002 (hfy-decor @var{tag} @var{val})
1005 Derive CSS text-decoration specifiers from various Emacs font attributes.
1013 (hfy-slant @var{slant})
1016 Derive a font-style CSS specifier from the Emacs :slant
1017 attribute---CSS does not define the reverse-* styles, so just maps
1018 those to the regular specifiers.
1020 @item hfy-tags-for-file
1021 @findex hfy-tags-for-file
1022 @anchor{hfy-tags-for-file}
1026 (hfy-tags-for-file @var{srcdir} @var{file})
1029 List of etags tags that have definitions in this @var{file}. Looks up
1030 the tags cache in @ref{hfy-tags-cache} using @var{srcdir} as the key.
1038 (hfy-width @var{width})
1041 Convert an Emacs @code{:width} attribute to a CSS font-stretch attribute.
1043 @comment /AUTOGENERATED BLOCK
1050 Important variables that are not customization items:
1054 @item hfy-tags-cache
1055 @vindex hfy-tags-cache
1056 @anchor{hfy-tags-cache}
1058 This is an alist of the form:
1061 (("/src/dir/0" . tag-hash0) ("/src/dir/1" tag-hash1) @dots{} )
1064 Each tag hash entry then contains entries of the form:
1067 "tag_string" => (("file/name.ext" line char) @dots{} )
1070 i.e., an alist mapping (relative) file paths to line and character offsets.
1072 See @ref{hfy-load-tags-cache}.
1075 @vindex hfy-tags-rmap
1076 @anchor{hfy-tags-rmap}
1078 @code{hfy-tags-rmap} is an alist of the form:
1081 (("/src/dir" . tag-rmap-hash))
1084 Where tag-rmap-hash has entries of the form:
1087 "tag_string" => ( "file/name.ext" line char )
1090 Unlike @ref{hfy-tags-cache} these are the locations of occurrences of
1091 tagged items, not the locations of their definitions.
1093 @item hfy-tags-sortl
1094 @vindex hfy-tags-sortl
1095 @anchor{hfy-tags-sortl}
1097 @code{hfy-tags-sortl} is an alist of the form:
1100 (("/src/dir" . (tag0 tag1 tag2)) @dots{} )
1103 Where the tags are stored in descending order of length.
1105 See: @ref{hfy-load-tags-cache}.
1109 @node Data Structures
1110 @section Data Structures
1111 @cindex Data Structures
1113 Some of the (informal) data structures used in Htmlfontify are detailed here:
1117 @item hfy-style-assoc
1118 @cindex hfy-style-assoc
1119 @anchor{hfy-style-assoc}
1121 An assoc representing/describing an Emacs face. Properties may be repeated,
1122 in which case later properties should be treated as if they were inherited
1123 from a ``parent'' font. (For some properties, only the first encountered value
1124 is of any importance, for others the values might be cumulative, and for
1125 others they might be cumulative in a complex way.)
1130 (hfy-face-to-style 'default) =>
1132 (("background" . "rgb(0, 0, 0)" )
1133 ("color" . "rgb(255, 255, 255)")
1134 ("font-style" . "normal" )
1135 ("font-weight" . "500" )
1136 ("font-stretch" . "normal" )
1137 ("font-family" . "misc-fixed" )
1138 ("font-size" . "13pt" )
1139 ("text-decoration" . "none" ))
1141 (hfy-face-to-style 'Info-title-3-face) =>
1143 (("font-weight" . "700" )
1144 ("font-family" . "helv" )
1145 ("font-size" . "120%" )
1146 ("text-decoration" . "none") )
1149 @item hfy-sheet-assoc
1150 @cindex hfy-sheet-assoc
1151 @anchor{hfy-sheet-assoc}
1153 An assoc with elements of the form @samp{(face-name style-name . style-string)}.
1154 The actual stylesheet for each page is derived from one of these.
1157 ((default "default" . "@{ background: black; color: white@}")
1158 (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}"))
1161 @item hfy-facemap-assoc
1162 @cindex hfy-facemap-assoc
1163 @anchor{hfy-facemap-assoc}
1165 An assoc of @code{(point . @var{face-symbol})} or
1166 @code{(point . @code{defface} attribute list)} and @code{(point
1167 . end)} elements, in descending order of point value (i.e., from the
1168 file's end to its beginning). The map is in reverse order because
1169 inserting a @samp{<style>} tag (or any other string) at @var{point}
1170 invalidates the map for all entries with a greater value of point. By
1171 traversing the map from greatest to least @var{point}, we still
1172 invalidate the map as we go, but only those points we have already
1173 dealt with (and therefore no longer care about) will be invalid at any
1178 (64744 . font-lock-comment-face)
1180 (64722 . font-lock-string-face)
1182 (64623 . font-lock-string-face)
1184 ;; Big similar section elided. You get the idea.
1186 (5431 . (:inherit font-lock-keyword-face :background "7e7e7e"))
1188 (4285 . font-lock-constant-face)
1190 (4221 . font-lock-comment-face)
1192 (4197 . font-lock-constant-face)
1194 (1 . font-lock-comment-face))
1203 The following is a lump of code I use to fontify source code on my
1204 site, @url{http://rtfm.etla.org/} (which was the reason, incidentally,
1205 that Htmlfontify was written in the first place).
1208 (defvar rtfm-section nil)
1210 ;; Constructs an appropriate header string to fit in with rtfm's
1211 ;; templating system, based on the file and the stylesheet string
1212 (defun rtfm-build-page-header (file style)
1213 (format "#define TEMPLATE red+black.html
1215 #include <build/menu-dirlist|>\n
1216 html-css-url := /css/red+black.css
1217 title := rtfm.etla.org ( %s / src/%s )
1219 head <=STYLESHEET;\n
1222 main-title := rtfm / %s / src/%s\n
1223 main-content <=MAIN_CONTENT;\n" rtfm-section file style rtfm-section file))
1226 (defun rtfm-build-page-footer (file) "\nMAIN_CONTENT\n")
1228 (defun rtfm-fontify-buffer (section)
1229 (interactive "s section[eg- emacs / p4-blame]: ")
1230 (require 'htmlfontify)
1231 (let ((hfy-page-header 'rtfm-build-page-header)
1232 (hfy-page-footer 'rtfm-build-page-footer)
1233 (rtfm-section section))
1234 (htmlfontify-buffer)
1238 ;; Here's the function I actually call---it asks me for a section label,
1239 ;; and source and destination directories, and then binds a couple of
1240 ;; customization variable in a let before calling htmlfontify:
1241 (defun rtfm-build-source-docs (section srcdir destdir)
1243 "s section[eg- emacs / p4-blame]:\nD source-dir: \nD output-dir: ")
1244 (require 'htmlfontify)
1245 (hfy-load-tags-cache srcdir)
1246 (let ((hfy-page-header 'rtfm-build-page-header)
1247 (hfy-page-footer 'rtfm-build-page-footer)
1248 (rtfm-section section)
1249 (hfy-index-file "index")
1250 (auto-mode-alist (append auto-mode-alist
1251 '(("dbi\\(shell\\|gtk\\)$" . cperl-mode)
1252 ("\\.xpm$" . c-mode ))))
1254 (htmlfontify-run-etags srcdir)
1255 (htmlfontify-copy-and-link-dir srcdir destdir ".src" ".html")))
1259 @chapter Customization
1260 @cindex variables (customization)
1262 Htmlfontify provides the following variable and customization entries:
1265 @comment AUTOGENERATED BLOCK
1267 @item hfy-link-style-fun
1268 @vindex hfy-link-style-fun
1269 @anchor{hfy-link-style-fun}
1271 Set this to a function, which will be called with one argument
1272 (a @samp{@{ foo: bar; @dots{}@}} CSS style-string)---it should return a copy of
1273 its argument, altered so as to make any changes you want made for text which
1274 is a hyperlink, in addition to being in the class to which that style would
1275 normally be applied.
1277 @item hfy-html-quote-regex
1278 @vindex hfy-html-quote-regex
1279 @anchor{hfy-html-quote-regex}
1281 @c FIXME: the cross-reference below looks ugly
1282 Regex to match (with a single back-reference per match) strings in HTML
1283 which should be quoted with @ref{hfy-html-quote}
1284 (and @pxref{hfy-html-quote-map}) to make them safe.
1286 @item hfy-page-footer
1287 @vindex hfy-page-footer
1288 @anchor{hfy-page-footer}
1290 As @ref{hfy-page-header}, but generates the output footer
1291 (and takes only 1 argument, the filename).
1293 @item hfy-display-class
1294 @vindex hfy-display-class
1295 @anchor{hfy-display-class}
1297 Display class to use to determine which display class to use when
1298 calculating a face's attributes. This is useful when, for example, you
1299 are running Emacs on a tty or in batch mode, and want Htmlfontify to have
1300 access to the face spec you would use if you were connected to an X display.
1302 Some valid class specification elements are:
1315 Multiple values for a tag may be combined, to indicate that any one or more
1316 of these values in the specification key constitutes a match. For
1317 example, @code{((class color grayscale) (type tty))} would match any of:
1322 ((class color grayscale)))
1325 ((type tty) (class color))
1328 @item hfy-page-header
1329 @vindex hfy-page-header
1330 @anchor{hfy-page-header}
1332 Function called with two arguments (the filename relative to the top
1333 level source directory being etagged and fontified), and a string containing
1334 the @samp{<style>@dots{}</style>} text to embed in the document---the string
1335 returned will be used as the header for the htmlfontified version of
1338 See also: @ref{hfy-page-footer}
1340 @item hfy-src-doc-link-style
1341 @vindex hfy-src-doc-link-style
1342 @anchor{hfy-src-doc-link-style}
1344 String to add to the @samp{<style> a} variant of an Htmlfontify CSS class.
1346 @item hfy-split-index
1347 @vindex hfy-split-index
1348 @anchor{hfy-split-index}
1350 Whether or not to split the index @ref{hfy-index-file} alphabetically
1351 on the first letter of each tag. Useful when the index would otherwise
1352 be large and take a long time to render or be difficult to navigate.
1355 @vindex hfy-find-cmd
1356 @anchor{hfy-find-cmd}
1358 The ``find'' command used to harvest a list of files to attempt to fontify.
1364 File extension used for output files.
1366 @item hfy-default-face-def
1367 @vindex hfy-default-face-def
1368 @anchor{hfy-default-face-def}
1370 Fallback @code{defface} specification for the face @code{default}, used
1371 when @ref{hfy-display-class} has been set (the normal Htmlfontify way of
1372 extracting potentially non-current face information doesn't necessarily
1373 work for @code{default}).
1375 For example, I customize this to:
1378 ((t :background "black" :foreground "white" :family "misc-fixed"))
1381 @item hfy-init-kludge-hooks
1382 @vindex hfy-init-kludge-hooks
1383 @anchor{hfy-init-kludge-hooks}
1385 List of functions to call when starting htmlfontify-buffer to do any
1386 kludging necessary to get highlighting modes to behave as you want, even
1387 when not running under a window system.
1389 @item hfy-shell-file-name
1390 @vindex hfy-shell-file-name
1391 @anchor{hfy-shell-file-name}
1393 Should be set to a Bourne compatible shell, which will be invoked
1394 for the more complex shell interactions needed by Htmlfontify.
1395 Currently this is only required/used when using GNU etags, see
1396 @ref{hfy-etags-cmd-alist} for details.
1398 @item hfy-optimizations
1399 @vindex hfy-optimizations
1400 @anchor{hfy-optimizations}
1402 Optimizations to turn on. So far, the following have been implemented:
1405 @item merge-adjacent-tags
1406 If two (or more) span tags are adjacent, identical and separated by nothing
1407 more than whitespace, they will be merged into one span.
1409 @item zap-comment-links
1410 Suppress hyperlinking of tags found in comments.
1412 @item zap-string-links
1413 Suppress hyperlinking of tags found in strings.
1416 Add @samp{<div class="default"> </div>} tags around the fontified body.
1417 (Some people like this because they cut and paste the html into
1418 a page with different colors than the fontified code.)
1421 Preserve overlay highlighting (cf.@: @code{ediff} or @code{goo-font-lock})
1422 as well as basic faces. Can result in extremely verbose highlighting
1423 if there are many overlays (as is the case with @code{goo-font-lock}).
1427 And the following are planned but not yet available:
1430 @item kill-context-leak
1431 Suppress hyperlinking between files highlighted by different modes.
1435 Note: like compiler optimizations, these optimize the @emph{output} of
1437 not the processing of the source itself, and are therefore likely to slow
1438 Htmlfontify down, at least a little. Except for skip-refontification,
1439 which can never slow you down, but may result in incomplete fontification.
1441 @item hfy-src-doc-link-unstyle
1442 @vindex hfy-src-doc-link-unstyle
1443 @anchor{hfy-src-doc-link-unstyle}
1445 Regex to remove from the @samp{<style> a} variant of an Htmlfontify CSS class.
1448 @vindex hfy-link-extn
1449 @anchor{hfy-link-extn}
1451 File extension used for href links---useful where the Htmlfontify
1452 output files are going to be processed again, with a resulting change
1453 in file extension. If @code{nil}, then any code using this should fall back
1456 @item hfy-istext-command
1457 @vindex hfy-istext-command
1458 @anchor{hfy-istext-command}
1460 Command to run with the name of a file, to see whether it is a text file
1461 or not. The command should emit a string containing the word @samp{text} if
1462 the file is a text file, and a string not containing @samp{text} otherwise.
1464 @item hfy-etags-cmd-alist
1465 @vindex hfy-etags-cmd-alist
1466 @anchor{hfy-etags-cmd-alist}
1468 An alist of possible shell commands that will generate etags output that
1469 Htmlfontify can use. @samp{%s} will be replaced by @ref{hfy-etags-bin}.
1472 @vindex hfy-etags-bin
1473 @anchor{hfy-etags-bin}
1475 The location of the etags binary (we begin by assuming it's in your path).
1477 Note that if etags is not in your path, you will need to alter the shell
1478 commands in @ref{hfy-etags-cmd-alist}.
1480 [As of version 0.17, this requirement has been removed: it should
1484 @vindex hfy-etags-cmd
1485 @anchor{hfy-etags-cmd}
1487 An etags shell command to run in the source directory to generate a tags
1488 file for the whole source tree from there on down. The command should emit
1489 the etags output on standard output.
1491 Two canned commands are provided---they drive Emacs's etags and
1492 exuberant-ctags's etags respectively.
1494 @item hfy-etag-regex
1495 @vindex hfy-etag-regex
1496 @anchor{hfy-etag-regex}
1498 Regex used to parse an etags entry: must have 3 subexps, corresponding,
1507 The character (point) at which the tag occurs
1510 @item hfy-index-file
1511 @vindex hfy-index-file
1512 @anchor{hfy-index-file}
1514 Name (sans extension) of the index file produced during
1515 fontification-and-hyperlinking.
1517 @item hfy-instance-file
1518 @vindex hfy-instance-file
1519 @anchor{hfy-instance-file}
1521 Name (sans extension) of the tag usage index file produced during
1522 fontification-and-hyperlinking.
1524 @item hfy-html-quote-map
1525 @vindex hfy-html-quote-map
1526 @anchor{hfy-html-quote-map}
1528 An alist of character -> entity mappings used to make the text html-safe.
1530 @comment /AUTOGENERATED BLOCK
1534 @chapter Requirements
1535 @cindex Requirements, Prerequisites
1537 Htmlfontify has a couple of external requirements:
1542 GNU Emacs 20.7+ or 21.1+
1544 Other versions may work---these have been used successfully by the
1545 author. If you intend to use Htmlfontify in batch mode, 21.1+ is
1546 pretty much required. The author does not know if XEmacs, NTemacs,
1547 or J.Random Emacs will run Htmlfontify, but reports/patches/bags of
1548 money are always welcome.
1551 A copy of etags (exuberant-ctags or GNU etags). Htmlfontify attempts
1552 to autodetect the version you have and customize itself accordingly,
1553 but you should be able to override this.
1555 See: @ref{Customization}
1558 A copy of find (e.g., GNU find) that provides the @code{-path} predicate.
1560 You may be able to work around this with a suitable clever shell
1561 command and the customization entry: @ref{hfy-find-cmd}
1564 A copy of sed (e.g., GNU sed).
1567 A copy of the @code{file} command.
1571 @node GNU Free Documentation License
1572 @appendix GNU Free Documentation License
1573 @include doclicense.texi
1585 @item Variables & Customization
1590 @setchapternewpage odd