| blob | 414e913a39122eca628c03d3d3c0fe050c442c33 |
1 ;; htmlize.el -- Convert buffer text and decorations to HTML.
3 ;; Copyright (C) 1997-2011 Hrvoje Niksic
5 ;; Author: Hrvoje Niksic <hniksic@xemacs.org>
6 ;; Keywords: hypermedia, extensions
8 ;; This program is free software; you can redistribute it and/or modify
9 ;; it under the terms of the GNU General Public License as published by
10 ;; the Free Software Foundation; either version 2, or (at your option)
11 ;; any later version.
13 ;; This program is distributed in the hope that it will be useful,
14 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
15 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 ;; GNU General Public License for more details.
18 ;; You should have received a copy of the GNU General Public License
19 ;; along with this program; see the file COPYING. If not, write to the
20 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 ;; Boston, MA 02111-1307, USA.
23 ;;; Commentary:
25 ;; This package converts the buffer text and the associated
26 ;; decorations to HTML. Mail to <hniksic@xemacs.org> to discuss
27 ;; features and additions. All suggestions are more than welcome.
29 ;; To use this, just switch to the buffer you want HTML-ized and type
30 ;; `M-x htmlize-buffer'. You will be switched to a new buffer that
31 ;; contains the resulting HTML code. You can edit and inspect this
32 ;; buffer, or you can just save it with C-x C-w. `M-x htmlize-file'
33 ;; will find a file, fontify it, and save the HTML version in
34 ;; FILE.html, without any additional intervention. `M-x
35 ;; htmlize-many-files' allows you to htmlize any number of files in
36 ;; the same manner. `M-x htmlize-many-files-dired' does the same for
37 ;; files marked in a dired buffer.
39 ;; htmlize supports three types of HTML output, selected by setting
40 ;; `htmlize-output-type': `css', `inline-css', and `font'. In `css'
41 ;; mode, htmlize uses cascading style sheets to specify colors; it
42 ;; generates classes that correspond to Emacs faces and uses <span
43 ;; class=FACE>...</span> to color parts of text. In this mode, the
44 ;; produced HTML is valid under the 4.01 strict DTD, as confirmed by
45 ;; the W3C validator. `inline-css' is like `css', except the CSS is
46 ;; put directly in the STYLE attribute of the SPAN element, making it
47 ;; possible to paste the generated HTML to other documents. In `font'
48 ;; mode, htmlize uses <font color="...">...</font> to colorize HTML,
49 ;; which is not standard-compliant, but works better in older
50 ;; browsers. `css' mode is the default.
52 ;; You can also use htmlize from your Emacs Lisp code. When called
53 ;; non-interactively, `htmlize-buffer' and `htmlize-region' will
54 ;; return the resulting HTML buffer, but will not change current
55 ;; buffer or move the point.
57 ;; I tried to make the package elisp-compatible with multiple Emacsen,
58 ;; specifically aiming for XEmacs 19.14+ and GNU Emacs 19.34+. Please
59 ;; let me know if it doesn't work on some of those, and I'll try to
60 ;; fix it. I relied heavily on the presence of CL extensions,
61 ;; especially for cross-emacs compatibility; please don't try to
62 ;; remove that particular dependency. When byte-compiling under GNU
63 ;; Emacs, you're likely to get some warnings; just ignore them.
65 ;; The latest version should be available at:
66 ;;
67 ;; <http://fly.srk.fer.hr/~hniksic/emacs/htmlize.el>
68 ;;
69 ;; You can find a sample of htmlize's output (possibly generated with
70 ;; an older version) at:
71 ;;
72 ;; <http://fly.srk.fer.hr/~hniksic/emacs/htmlize.el.html>
74 ;; Thanks go to the multitudes of people who have sent reports and
75 ;; contributed comments, suggestions, and fixes. They include Ron
76 ;; Gut, Bob Weiner, Toni Drabik, Peter Breton, Thomas Vogels, Juri
77 ;; Linkov, Maciek Pasternacki, and many others.
79 ;; User quotes: "You sir, are a sick, sick, _sick_ person. :)"
80 ;; -- Bill Perry, author of Emacs/W3
82 \f
83 ;;; Code:
95 ;; Older versions of GNU Emacs fail to autoload cl-extra even when
96 ;; `cl' is loaded.
101 ;; Incantations to make custom stuff work without customize, e.g. on
102 ;; XEmacs 19.14 or GNU Emacs 19.34.
108 nil ; we've got what we needed
109 ;; No custom or obsolete custom, define surrogates. Define all
110 ;; three macros, so we don't hose another library that expects
111 ;; e.g. `defface' to work after (fboundp 'defcustom) succeeds.
119 "Convert buffer text and faces to HTML."
123 "*Additional tags to insert within HEAD of the generated document."
128 "*Output type of generated HTML, one of `css', `inline-css', or `font'.
129 When set to `css' (the default), htmlize will generate a style sheet
130 with description of faces, and use it in the HTML document, specifying
133 When set to `inline-css', the style will be generated as above, but
134 placed directly in the STYLE attribute of the span ELEMENT: <span
136 other documents.
138 When set to `font', the properties will be set using layout tags
139 <font>, <b>, <i>, <u>, and <strike>.
141 `css' output is normally preferred, but `font' is still useful for
142 supporting old, pre-CSS browsers, and both `inline-css' and `font' for
143 easier embedding of colorized text in foreign HTML documents (no style
144 sheet to carry around)."
149 "*Non-nil means generate the hyperlinks for URLs and mail addresses.
150 This is on by default; set it to nil if you don't want htmlize to
151 insert hyperlinks in the resulting HTML. (In which case you can still
152 do your own hyperlinkification from htmlize-after-hook.)"
157 a {
158 color: inherit;
159 background-color: inherit;
160 font: inherit;
161 text-decoration: inherit;
162 }
163 a:hover {
164 text-decoration: underline;
165 }
166 "
167 "*The CSS style used for hyperlinks when in CSS mode."
172 "*Non-nil means replace form feeds in source code with HTML separators.
173 Form feeds are the ^L characters at line beginnings that are sometimes
174 used to separate sections of source code. If this variable is set to
175 `t', form feed characters are replaced with the <hr> separator. If this
176 is a string, it specifies the replacement to use. Note that <pre> is
177 temporarily closed before the separator is inserted, so the default
179 another replacement, don't forget to close and reopen the <pre> if you
180 want the output to remain valid HTML.
182 If you need more elaborate processing, set this to nil and use
183 htmlize-after-hook."
188 "*The charset declared by the resulting HTML documents.
189 When non-nil, causes htmlize to insert the following in the HEAD section
190 of the generated HTML:
194 where CHARSET is the value you've set for htmlize-html-charset. Valid
198 If you are using non-Latin-1 charsets, you might need to set this for
199 your documents to render correctly. Also, the W3C validator requires
200 submitted HTML documents to declare a charset. So if you care about
201 validation, you can use this to prevent the validator from bitching.
203 Needless to say, if you set this, you should actually make sure that
204 the buffer is in the encoding you're claiming it is in. (Under Mule
206 buffer.) If you don't understand what that means, this option is
207 probably not for you."
209 string)
213 "*Whether non-ASCII characters should be converted to HTML entities.
215 When this is non-nil, characters with codes in the 128-255 range will be
218 code point of the character. If the code point cannot be determined,
219 the character will be copied unchanged, as would be the case if the
220 option were nil.
222 When the option is nil, the non-ASCII characters are copied to HTML
223 without modification. In that case, the web server and/or the browser
224 must be set to understand the encoding that was used when saving the
225 buffer. (You might also want to specify it by setting
226 `htmlize-html-charset'.)
229 which has nothing to do with the charset the page is in. For example,
231 specified by the META tag or the charset sent by the HTTP server. In
234 By default, entity conversion is turned on for Mule-enabled Emacsen and
235 turned off otherwise. This is because Mule knows the charset of
236 non-ASCII characters in the buffer. A non-Mule Emacs cannot tell
237 whether a character with code 0xA9 represents Latin 1 copyright symbol,
239 t without Mule means asserting that 128-255 characters always mean Latin
240 1.
242 For most people htmlize will work fine with this option left at the
243 default setting; don't change it unless you know what you're doing."
248 "*Whether face size should be ignored when generating HTML.
249 If this is nil, face sizes are used. If set to t, sizes are ignored
250 If set to `absolute', only absolute size specifications are ignored.
251 Please note that font sizes only work with CSS-based output types."
258 "*The prefix used for CSS names.
259 The CSS names that htmlize generates from face names are often too
260 generic for CSS files; for example, `font-lock-type-face' is transformed
261 to `type'. Use this variable to add a prefix to the generated names.
267 "*Whether `rgb.txt' should be used to convert color names to RGB.
269 This conversion means determining, for instance, that the color
271 is the X color database that maps hundreds of color names to such RGB
272 triples. When this variable is non-nil, `htmlize' uses `rgb.txt' to
273 look up color names.
275 If this variable is nil, htmlize queries Emacs for RGB components of
276 colors using `color-instance-rgb-components' and `x-color-values'.
277 This can yield incorrect results on non-true-color displays.
279 If the `rgb.txt' file is not found (which will be the case if you're
280 running Emacs on non-X11 systems), this option is ignored."
285 "The mode the newly created HTML buffer will be put in.
286 Set this to nil if you prefer the default (fundamental) mode."
293 "Hook run before htmlizing a buffer.
294 The hook functions are run in the source buffer (not the resulting HTML
298 "Hook run after htmlizing a buffer.
299 Unlike `htmlize-before-hook', these functions are run in the generated
300 HTML buffer. You may use them to modify the outlook of the final HTML
307 \f
308 ;;; Some cross-Emacs compatibility.
310 ;; I try to conditionalize on features rather than Emacs version, but
311 ;; in some cases checking against the version *is* necessary.
315 ;; save-current-buffer, with-current-buffer, and with-temp-buffer
316 ;; are not available in 19.34 and in older XEmacsen. Strictly
317 ;; speaking, we should stick to our own namespace and define and use
318 ;; htmlize-save-current-buffer, etc. But non-standard special forms
319 ;; are a pain because they're not properly fontified or indented and
320 ;; because they look weird and ugly. So I'll just go ahead and
321 ;; define the real ones if they're not available. If someone
322 ;; convinces me that this breaks something, I'll switch to the
323 ;; "htmlize-" namespace.
344 ;; We need a function that efficiently finds the next change of a
345 ;; property (usually `face'), preferably regardless of whether the
346 ;; change occurred because of a text property or an extent/overlay.
347 ;; As it turns out, it is not easy to do that compatibly.
348 ;;
349 ;; Under XEmacs, `next-single-property-change' does that. Under GNU
350 ;; Emacs beginning with version 21, `next-single-char-property-change'
351 ;; is available and does the same. GNU Emacs 20 had
352 ;; `next-char-property-change', which we can use. GNU Emacs 19 didn't
353 ;; provide any means for simultaneously examining overlays and text
354 ;; properties, so when using Emacs 19.34, we punt and fall back to
355 ;; `next-single-property-change', thus ignoring overlays altogether.
359 ;; XEmacs: good.
363 ;; GNU Emacs 21: good.
367 ;; GNU Emacs 20: bad, but fixable.
371 newpos next-value)
372 ;; Loop over positions returned by next-char-property-change
373 ;; until the value of PROP changes or we've hit EOB.
378 ;; Possibly at EOB? Whatever, just don't infloop.
381 ;; PROP hasn't changed -- keep looping.
382 )
386 pos)))
388 ;; GNU Emacs 19.34: hopeless, cannot properly support overlays.
395 limit
396 res)))))
397 \f
398 ;;; Transformation of buffer text: HTML escapes, untabification, etc.
401 ;; Map characters in the 0-127 range to either one-character strings
402 ;; or to numeric entities.
404 ;; Map characters in the 32-126 range to themselves, others to
405 ;; &#CODE entities;
410 ;; Set exceptions manually.
412 ;; Don't escape newline, carriage return, and TAB.
416 ;; Escape &, <, and >.
420 ;; Not escaping '"' buys us a measurable speedup. It's only
421 ;; necessary to quote it for strings used in attribute values,
422 ;; which htmlize doesn't do.
423 ;(aref table ?\") """
424 )
425 table))
427 ;; A cache of HTML representation of non-ASCII characters. Depending
428 ;; on availability of `encode-char' and the setting of
429 ;; `htmlize-convert-nonascii-to-entities', this maps non-ASCII
430 ;; characters to either "&#<code>;" or "<char>" (mapconcat's mapper
431 ;; must always return strings). It's only filled as characters are
432 ;; encountered, so that in a buffer with e.g. French text, it will
433 ;; only ever contain French accented characters as keys. It's cleared
434 ;; on each entry to htmlize-buffer-1 to allow modifications of
435 ;; `htmlize-convert-nonascii-to-entities' to take effect.
439 "HTML-protect string, escaping HTML metacharacters and I18N chars."
440 ;; Only protecting strings that actually contain unsafe or non-ASCII
441 ;; chars removes a lot of unnecessary funcalls and consing.
443 string
447 ;; ASCII: use htmlize-basic-character-table.
450 ;; We've already seen this char; return the cached
451 ;; string.
452 )
454 ;; If conversion to entities is not desired, always
455 ;; copy the char literally.
459 ;; Latin 1: no need to call encode-char.
463 ;; Must check if encode-char works for CHAR;
464 ;; it fails for Arabic and possibly elsewhere.
469 ;; encode-char doesn't work for this char. Copy it
470 ;; unchanged and hope for the best.
479 ;; Like buffer-substring-no-properties, but don't copy invisible
480 ;; parts of the region. Where buffer-substring-no-properties
481 ;; mandates an ellipsis to be shown, htmlize-ellipsis is inserted.
483 visible-list invisible show next-change)
484 ;; Iterate over the changes in the `invisible' property and filter
485 ;; out the portions where it's non-nil, i.e. where the text is
486 ;; invisible.
491 ;; If buffer-invisibility-spec is not a list, then all
492 ;; characters with non-nil `invisible' property are visible.
494 ;; Otherwise, the value of a non-nil `invisible' property can be:
495 ;; 1. a symbol -- make the text invisible if it matches
496 ;; buffer-invisibility-spec.
497 ;; 2. a list of symbols -- make the text invisible if
498 ;; any symbol in the list matches
499 ;; buffer-invisibility-spec.
500 ;; If the match of buffer-invisibility-spec has a non-nil
501 ;; CDR, replace the invisible text with an ellipsis.
510 elem buffer-invisibility-spec
514 nil)))
517 ;; Conflate successive ellipses.
519 htmlize-ellipsis)
527 ;; If VISIBLE-LIST consists of only one element, return it
528 ;; without concatenation. This avoids additional consing in
529 ;; regions without any invisible text.
534 ;; Remove htmlize-ellipses ("...") from the beginning of TEXT if it
535 ;; starts with it. It checks for the special property of the
536 ;; ellipsis so it doesn't work on ordinary text that begins with
537 ;; "...".
540 text))
543 ;; A table of strings with spaces. (aref htmlize-tab-spaces 5) is
544 ;; like (make-string 5 ?\ ), except it doesn't cons.
548 v))
551 "Untabify TEXT, assuming it starts at START-COLUMN."
555 chunks match-pos tab-size)
559 ;; Encountered a tab: create a chunk of text followed by
560 ;; the expanded tab.
562 ;; Increase COLUMN by the length of the text we've
563 ;; skipped since last tab or newline. (Encountering
564 ;; newline resets it.)
566 ;; Calculate tab size based on tab-width and COLUMN.
568 ;; Expand the tab.
573 ;; Reset COLUMN at beginning of line.
576 ;; If no chunks have been allocated, it means there have been no
577 ;; tabs to expand. Return TEXT unmodified.
579 text
581 ;; Push the remaining chunk.
583 ;; Generate the output from the available chunks.
587 "Replace every occurrence of '@' in STRING with @.
588 `htmlize-make-hyperlinks' uses this to spam-protect mailto links
589 without modifying their meaning."
590 ;; Suggested by Ville Skytta.
593 string)
596 "Make hyperlinks in HTML."
597 ;; Function originally submitted by Ville Skytta. Rewritten by
598 ;; Hrvoje Niksic, then modified by Ville Skytta and Hrvoje Niksic.
602 nil t)
613 nil t)
619 ;; Tests for htmlize-make-hyperlinks:
621 ;; <mailto:hniksic@xemacs.org>
622 ;; <http://fly.srk.fer.hr>
623 ;; <URL:http://www.xemacs.org>
624 ;; <http://www.mail-archive.com/bbdb-info@xemacs.org/>
625 ;; <hniksic@xemacs.org>
626 ;; <xalan-dev-sc.10148567319.hacuhiucknfgmpfnjcpg-john=doe.com@xml.apache.org>
629 ;; Juri Linkov reports that an HTML-ized "Local variables" can lead
630 ;; visiting the HTML to fail with "Local variables list is not
631 ;; properly terminated". He suggested changing the phrase to
632 ;; syntactically equivalent HTML that Emacs doesn't recognize.
637 \f
638 ;;; Color handling.
649 "/usr/X11R5/lib/X11/"
650 "/usr/lib/X11R6/X11/"
651 "/usr/lib/X11R5/X11/"
652 "/usr/local/X11R6/lib/X11/"
653 "/usr/local/X11R5/lib/X11/"
654 "/usr/local/lib/X11R6/X11/"
655 "/usr/local/lib/X11R5/X11/"
656 "/usr/X11/lib/X11/"
657 "/usr/lib/X11/"
658 "/usr/local/lib/X11/"
659 "/usr/X386/lib/X11/"
660 "/usr/x386/lib/X11/"
661 "/usr/XFree86/lib/X11/"
662 "/usr/unsupported/lib/X11/"
663 "/usr/athena/lib/X11/"
664 "/usr/local/x11r5/lib/X11/"
665 "/usr/lpp/Xamples/lib/X11/"
666 "/usr/openwin/lib/X11/"
670 "Return a hash table mapping X color names to RGB values.
671 The keys in the hash table are X11 color names, and the values are the
672 #rrggbb RGB specifications, extracted from `rgb.txt'.
674 If RGB-FILE is nil, the function will try hard to find a suitable file
675 in the system directories.
677 If no rgb.txt file is found, return nil."
679 "rgb.txt"
680 htmlize-x-library-search-path)))
688 ;; Skip comments and empty lines.
689 )
699 "Unrecognized line in %s: %s"
700 rgb-file
703 hash))
705 ;; Compile the RGB map when loaded. On systems where rgb.txt is
706 ;; missing, the value of the variable will be nil, and rgb.txt will
707 ;; not be used.
709 \f
710 ;;; Face handling.
713 ;; Return t if face specifies PROP, as opposed to it being inherited
714 ;; from the default face. The problem with e.g.
715 ;; `face-foreground-instance' is that it returns an instance for
716 ;; EVERY face because every face inherits from the default face.
717 ;; However, we'd like htmlize-face-{fore,back}ground to return nil
718 ;; when called with a face that doesn't specify its own foreground
719 ;; or background.
724 ;; Used only under GNU Emacs. Return the color of FACE, but don't
725 ;; return "unspecified-fg" or "unspecified-bg". If the face is
726 ;; `default' and the color is unspecified, look up the color in
727 ;; frame parameters.
729 color)
731 ;; For GNU Emacs 22+ set INHERIT to get the inherited values.
734 ;; For GNU Emacs 21 (which has `face-attribute'): if the color
735 ;; is nil, recursively check for the face's parent.
751 ;; Assuming black on white doesn't seem right, but I can't think
752 ;; of anything better to do.
754 color))
757 ;; Return the name of the foreground color of FACE. If FACE does
758 ;; not specify a foreground color, return nil.
760 ;; XEmacs.
764 ;; GNU Emacs.
768 ;; Return the name of the background color of FACE. If FACE does
769 ;; not specify a background color, return nil.
771 ;; XEmacs.
775 ;; GNU Emacs.
778 ;; Convert COLOR to the #RRGGBB string. If COLOR is already in that
779 ;; format, it's left unchanged.
784 ;; Ignore nil COLOR because it means that the face is not
785 ;; specifying any color. Hence (htmlize-color-to-rgb nil)
786 ;; returns nil.
787 )
789 ;; The color is already in #rrggbb format.
792 htmlize-color-rgb-hash)
793 ;; Use of rgb.txt is requested, and it's available on the
794 ;; system. Use it.
797 ;; We're getting the RGB components from Emacs.
799 ;; Here I cannot conditionalize on (fboundp ...)
800 ;; because ps-print under some versions of GNU Emacs
801 ;; defines its own dummy version of
802 ;; `color-instance-rgb-components'.
813 ;; If RGB-STRING is still nil, it means the color cannot be found,
814 ;; for whatever reason. In that case just punt and return COLOR.
815 ;; Most browsers support a decent set of color names anyway.
818 ;; We store the face properties we care about into an
819 ;; `htmlize-fstruct' type. That way we only have to analyze face
820 ;; properties, which can be time consuming, once per each face. The
821 ;; mapping between Emacs faces and htmlize-fstructs is established by
822 ;; htmlize-make-face-map. The name "fstruct" refers to variables of
823 ;; type `htmlize-fstruct', while the term "face" is reserved for Emacs
824 ;; faces.
827 foreground ; foreground color, #rrggbb
828 background ; background color, #rrggbb
829 size ; size
830 boldp ; whether face is bold
831 italicp ; whether face is italic
832 underlinep ; whether face is underlined
833 overlinep ; whether face is overlined
834 strikep ; whether face is struck through
835 css-name ; CSS name of face
836 )
839 ;; For ATTR and VALUE, set the equivalent value in FSTRUCT.
841 (:foreground
843 (:background
845 (:height
847 (:weight
850 (:slant
853 (:bold
855 (:italic
857 (:underline
859 (:overline
861 (:strike-through
865 ;; The size (height) of FACE, taking inheritance into account.
866 ;; Only works in Emacs 21 and later.
876 "Convert Emacs face FACE to fstruct."
883 ;; XEmacs doesn't provide a way to detect whether a face is
884 ;; bold or italic, so we need to examine the font instance.
885 ;; #### This probably doesn't work under MS Windows and/or
886 ;; GTK devices. I'll need help with those.
899 ;; GNU Emacs 21 and further.
902 ;; Use the INHERIT arg in GNU Emacs 22.
904 ;; Otherwise, fake it.
918 ;; Older GNU Emacs. Some of these functions are only
919 ;; available under Emacs 20+, hence the guards.
926 ;; Generate the css-name property. Emacs places no restrictions
927 ;; on the names of symbols that represent faces -- any characters
928 ;; may be in the name, even ^@. We try hard to beat the face name
929 ;; into shape, both esthetically and according to CSS1 specs.
933 ;; Change font-lock-FOO-face to FOO.
936 ;; Drop the redundant "-face" suffix.
939 ;; Drop the non-alphanumerics.
942 ;; CSS identifiers may not start with a digit.
944 ;; After these transformations, the face could come
945 ;; out empty.
948 ;; Apply the prefix.
950 name))
951 fstruct))
954 ;; Expand the code of the type
955 ;; (and (htmlize-fstruct-ATTR source)
956 ;; (setf (htmlize-fstruct-ATTR dest) (htmlize-fstruct-ATTR source)))
957 ;; for the given list of boolean attributes.
965 ;; Calculate the size of the merge of MERGED and NEXT.
975 merged next)
979 merged)
983 ;; Nothing to do, return a dummy face.
986 ;; Optimize for the common case of a single face, simply
987 ;; return it.
993 ;; GNU Emacs 20+ supports attribute lists in `face' properties. For
994 ;; example, you can use `(:foreground "red" :weight bold)' as an
995 ;; overlay's "face", or you can even use a list of such lists, etc.
996 ;; We call those "attrlists".
997 ;;
998 ;; htmlize supports attrlist by converting them to fstructs, the same
999 ;; as with regular faces.
1002 ;; Like htmlize-face-to-fstruct, but accepts an ATTRLIST as input.
1005 ;; ATTRLIST is (foreground-color . COLOR)
1009 ;; ATTRLIST is (background-color . COLOR)
1013 ;; ATTRLIST is a plist.
1020 fstruct))
1023 "Return non-nil if FACE-PROP is a list of faces, nil otherwise."
1024 ;; If not for attrlists, this would return (listp face-prop). This
1025 ;; way we have to be more careful because attrlist is also a list!
1028 ;; FACE-PROP being nil means empty list (no face), so return t.
1029 t)
1031 ;; A symbol other than nil means that it's only one face, so return
1032 ;; nil.
1033 nil)
1035 ;; Huh? Not a symbol or cons -- treat it as a single element.
1036 nil)
1038 ;; We know that FACE-PROP is a cons: check whether it looks like an
1039 ;; ATTRLIST.
1045 ;; If FACE-PROP is not an ATTRLIST, it means it's a list of
1046 ;; faces.
1050 ;; Return a hash table mapping Emacs faces to htmlize's fstructs.
1051 ;; The keys are either face symbols or attrlists, so the test
1052 ;; function must be `equal'.
1054 css-names)
1057 ;; Haven't seen FACE yet; convert it to an fstruct and cache
1058 ;; it.
1066 ;; Uniquify the face's css-name by using NAME-1, NAME-2,
1067 ;; etc.
1073 face-map))
1076 "If FACE is a string, return it interned, otherwise return it unchanged."
1079 face))
1082 "Return a list of faces used in the current buffer.
1083 Under XEmacs, this returns the set of faces specified by the extents
1084 with the `face' property. (This covers text properties as well.) Under
1085 GNU Emacs, it returns the set of faces specified by the `face' text
1086 property and by buffer overlays that specify `face'."
1088 ;; Testing for (fboundp 'map-extents) doesn't work because W3
1089 ;; defines `map-extents' under FSF.
1094 ;; FACE-PROP can be a face or a list of
1095 ;; faces.
1099 nil)
1100 nil
1101 ;; Specify endpoints explicitly to respect
1102 ;; narrowing.
1104 ;; FSF Emacs code.
1105 ;; Faces used by text properties.
1110 ;; FACE-PROP can be a face/attrlist or a list thereof.
1117 ;; Faces used by overlays.
1120 ;; FACE-PROP can be a face/attrlist or a list thereof.
1126 faces))
1128 ;; htmlize-faces-at-point returns the faces in use at point. The
1129 ;; faces are sorted by increasing priority, i.e. the last face takes
1130 ;; precedence.
1131 ;;
1132 ;; Under XEmacs, this returns all the faces in all the extents at
1133 ;; point. Under GNU Emacs, this returns all the faces in the `face'
1134 ;; property and all the faces in the overlays at point.
1141 ;; extent-list is in reverse display order, meaning that
1142 ;; smallest ones come last. That is the order we want,
1143 ;; except it can be overridden by the `priority' property.
1148 ;; extent's face-list is in reverse order from what we
1149 ;; want, but the `nreverse' below will take care of it.
1157 ;; Faces from text properties.
1161 face-prop))
1163 ;; Faces from overlays.
1165 ;; Collect overlays at point that specify `face'.
1169 list face-prop)
1170 ;; Sort the overlays so the smaller (more specific) ones
1171 ;; come later. The number of overlays at each one
1172 ;; position should be very small, so the sort shouldn't
1173 ;; slow things down.
1175 ;; Sort by ascending...
1176 #'<
1177 ;; ...overlay size.
1181 ;; Overlay priorities, if present, override the above
1182 ;; established order. Larger overlay priority takes
1183 ;; precedence and therefore comes later in the list.
1185 overlays
1186 ;; Reorder (stably) by acending...
1187 #'<
1188 ;; ...overlay priority.
1195 #'htmlize-unstringify-face
1196 face-prop))
1197 list)
1199 ;; Under "Merging Faces" the manual explicitly states
1200 ;; that faces specified by overlays take precedence over
1201 ;; faces specified by text properties.
1203 all-faces))))
1204 \f
1205 ;; htmlize supports generating HTML in two several fundamentally
1206 ;; different ways, one with the use of CSS and nested <span> tags, and
1207 ;; the other with the use of the old <font> tags. Rather than adding
1208 ;; a bunch of ifs to many places, we take a semi-OO approach.
1209 ;; `htmlize-buffer-1' calls a number of "methods", which indirect to
1210 ;; the functions that depend on `htmlize-output-type'. The currently
1211 ;; used methods are `doctype', `insert-head', `body-tag', and
1212 ;; `insert-text'. Not all output types define all methods.
1213 ;;
1214 ;; Methods are called either with (htmlize-method METHOD ARGS...)
1215 ;; special form, or by accessing the function with
1216 ;; (htmlize-method-function 'METHOD) and calling (funcall FUNCTION).
1217 ;; The latter form is useful in tight loops because `htmlize-method'
1218 ;; conses.
1219 ;;
1220 ;; Currently defined output types are `css' and `font'.
1223 ;; Expand to (htmlize-TYPE-METHOD ...ARGS...). TYPE is the value of
1224 ;; `htmlize-output-type' at run time.
1228 ;; Return METHOD's function definition for the current output type.
1229 ;; The returned object can be safely funcalled.
1232 sym
1236 default
1242 "Return the value of GENERATOR, memoized as KEY.
1243 That means that GENERATOR will be evaluated and returned the first time
1244 it's called with the same value of KEY. All other times, the cached
1245 \(memoized) value will be returned."
1252 \f
1253 ;;; Default methods.
1256 nil ; no doc-string
1257 ;; According to DTDs published by the W3C, it is illegal to embed
1258 ;; <font> in <pre>. This makes sense in general, but is bad for
1259 ;; htmlize's intended usage of <font> to specify the document color.
1261 ;; To make generated HTML legal, htmlize's `font' mode used to
1262 ;; specify the SGML declaration of "HTML Pro" DTD here. HTML Pro
1263 ;; aka Silmaril DTD was a project whose goal was to produce a GPL'ed
1264 ;; DTD that would encompass all the incompatible HTML extensions
1265 ;; procured by Netscape, MSIE, and other players in the field.
1266 ;; Apparently the project got abandoned, the last available version
1267 ;; being "Draft 0 Revision 11" from January 1997, as documented at
1268 ;; <http://imbolc.ucc.ie/~pflynn/articles/htmlpro.html>.
1270 ;; Since by now HTML Pro is remembered by none but the most die-hard
1271 ;; early-web-days nostalgics and used by not even them, there is no
1272 ;; use in specifying it. So we return the standard HTML 4.0
1273 ;; declaration, which makes generated HTML technically illegal. If
1274 ;; you have a problem with that, use the `css' engine designed to
1275 ;; create fully conforming HTML.
1279 ;; Now-abandoned HTML Pro declaration.
1280 ;"<!DOCTYPE HTML PUBLIC \"+//Silmaril//DTD HTML Pro v0r11 19970101//EN\">"
1281 )
1284 nil ; no doc-string
1286 \f
1287 ;;; CSS based output support.
1289 ;; Internal function; not a method.
1294 result))
1298 result))
1330 ;; Use `prin1-to-string' rather than `symbol-name'
1331 ;; to get the face name because the "face" can also
1332 ;; be an attrlist, which is not a symbol.
1334 ;; If the name contains `--' or `*/', remove them.
1339 s))
1351 ;; Insert TEXT colored with FACES into BUFFER. In CSS mode, this is
1352 ;; easy: just nest the text in one <span class=...> tag for each
1353 ;; face in FSTRUCT-LIST.
1362 \f
1363 ;; `inline-css' output support.
1373 merged
1384 \f
1385 ;;; `font' tag based output support.
1394 ;; In `font' mode, we use the traditional HTML means of altering
1395 ;; presentation: <font> tag for colors, <b> for bold, <u> for
1396 ;; underline, and <strike> for strike-through.
1399 merged
1416 \f
1418 ;; Internal function; don't call it from outside this file. Htmlize
1419 ;; current buffer, writing the resulting HTML to a new buffer, and
1420 ;; return it. Unlike htmlize-buffer, this doesn't change current
1421 ;; buffer or use switch-to-buffer.
1423 ;; Protect against the hook changing the current buffer.
1426 ;; Convince font-lock support modes to fontify the entire buffer
1427 ;; in advance.
1433 ;; Generate the new buffer. It's important that it inherits
1434 ;; default-directory from the current buffer.
1440 ;; Having a dummy value in the plist allows writing simply
1441 ;; (plist-put places foo bar).
1446 ;; Initialize HTMLBUF and insert the HTML prolog.
1451 htmlize-version htmlize-output-type)
1459 htmlize-html-charset)
1461 htmlize-head-tags)
1472 ;; Get the inserter method, so we can funcall it inside
1473 ;; the loop. Not calling `htmlize-method' in the loop
1474 ;; body yields a measurable speed increase.
1476 ;; Declare variables used in loop body outside the loop
1477 ;; because it's faster to establish `let' bindings only
1478 ;; once.
1479 next-change text face-list fstruct-list trailing-ellipsis)
1480 ;; This loop traverses and reads the source buffer, appending
1481 ;; the resulting HTML to HTMLBUF with `princ'. This method is
1482 ;; fast because: 1) it doesn't require examining the text
1483 ;; properties char by char (htmlize-next-change is used to
1484 ;; move between runs with the same face), and 2) it doesn't
1485 ;; require buffer switches, which are slow in Emacs.
1489 ;; Get faces in use between (point) and NEXT-CHANGE, and
1490 ;; convert them to fstructs.
1494 face-list)))
1495 ;; Extract buffer text, sans the invisible parts. Then
1496 ;; untabify it and escape the HTML metacharacters.
1501 ;; If TEXT ends up empty, don't change trailing-ellipsis.
1508 ;; Don't bother writing anything if there's no text (this
1509 ;; happens in invisible regions).
1511 ;; Insert the text, along with the necessary markup to
1512 ;; represent faces in FSTRUCT-LIST.
1516 ;; Insert the epilog and post-process the buffer.
1527 ;; Change each "\n^L" to "<hr />".
1530 ;; ^L has already been escaped, so search for that.
1534 htmlize-replace-form-feeds
1540 ;; What sucks about this is that the minor modes, most notably
1541 ;; font-lock-mode, won't be initialized. Oh well.
1546 htmlbuf)))
1548 ;; Utility functions.
1551 ;; When forcing fontification of large buffers in
1552 ;; htmlize-ensure-fontified, inform the user that he is waiting for
1553 ;; font-lock, not for htmlize to finish.
1558 ,@body
1564 ;; If font-lock is being used, ensure that the "support" modes
1565 ;; actually fontify the buffer. If font-lock is not in use, we
1566 ;; don't care because, except in htmlize-file, we don't force
1567 ;; font-lock on the user.
1569 font-lock-mode)
1570 ;; In part taken from ps-print-ensure-fontified in GNU Emacs 21.
1583 ;; lazy-shot is amazing in that it must *refontify* the region,
1584 ;; even if the whole buffer has already been fontified. <sigh>
1586 ;; There's also fast-lock, but we don't need to handle specially,
1587 ;; I think. fast-lock doesn't really defer fontification, it
1588 ;; just saves it to an external cache so it's not done twice.
1589 )))
1591 \f
1592 ;;;###autoload
1594 "Convert BUFFER to HTML, preserving colors and decorations.
1596 The generated HTML is available in a new buffer, which is returned.
1597 When invoked interactively, the new buffer is selected in the current
1598 window. The title of the generated document will be set to the buffer's
1599 file name or, if that's not available, to the buffer's name.
1601 Note that htmlize doesn't fontify your buffers, it only uses the
1602 decorations that are already present. If you don't set up font-lock or
1603 something else to fontify your buffers, the resulting HTML will be
1604 plain. Likewise, if you don't like the choice of colors, fix the mode
1605 that created them, or simply alter the faces it uses."
1611 htmlbuf))
1613 ;;;###autoload
1615 "Convert the region to HTML, preserving colors and decorations.
1616 See `htmlize-buffer' for details."
1618 ;; Don't let zmacs region highlighting end up in HTML.
1626 htmlbuf))
1629 "Htmlize the region and return just the HTML as a string.
1630 This forces the `inline-css' style and only returns the HTML body,
1631 but without the BODY tag. This should make it useful for inserting
1632 the text to another HTML buffer."
1642 "Make an HTML file name from FILE.
1644 In its default implementation, this simply appends `.html' to FILE.
1645 This function is called by htmlize to create the buffer file name, and
1646 by `htmlize-file' to create the target file name.
1648 More elaborate transformations are conceivable, such as changing FILE's
1650 overload this function to do it and htmlize will comply."
1653 ;; Older implementation of htmlize-make-file-name that changes FILE's
1654 ;; extension to ".html".
1655 ;(defun htmlize-make-file-name (file)
1656 ; (let ((extension (file-name-extension file))
1657 ; (sans-extension (file-name-sans-extension file)))
1658 ; (if (or (equal extension "html")
1659 ; (equal extension "htm")
1660 ; (equal sans-extension ""))
1661 ; (concat file ".html")
1662 ; (concat sans-extension ".html"))))
1664 ;;;###autoload
1666 "Load FILE, fontify it, convert it to HTML, and save the result.
1668 Contents of FILE are inserted into a temporary buffer, whose major mode
1669 is set with `normal-mode' as appropriate for the file type. The buffer
1670 is subsequently fontified with `font-lock' and converted to HTML. Note
1671 that, unlike `htmlize-buffer', this function explicitly turns on
1672 font-lock. If a form of highlighting other than font-lock is desired,
1673 please use `htmlize-buffer' directly on buffers so highlighted.
1675 Buffers currently visiting FILE are unaffected by this function. The
1676 function does not change current buffer or move the point.
1678 If TARGET is specified and names a directory, the resulting file will be
1679 saved there instead of to FILE's directory. If TARGET is specified and
1680 does not name a directory, it will be used as output file name."
1682 "HTML-ize file: "
1687 target
1691 ;; Try to prevent `find-file-noselect' from triggering
1692 ;; font-lock because we'll fontify explicitly below.
1696 ;; Ignore the size limit for the purposes of htmlization.
1698 ;; Disable font-lock support modes. This will only work in
1699 ;; more recent Emacs versions, so htmlize-buffer-1 still needs
1700 ;; to call htmlize-ensure-fontified.
1703 ;; Insert FILE into the temporary buffer.
1705 ;; Set the file name so normal-mode and htmlize-buffer-1 pick it
1706 ;; up. Restore it afterwards so with-temp-buffer's kill-buffer
1707 ;; doesn't complain about killing a modified buffer.
1709 ;; Set the major mode for the sake of font-lock.
1713 ;; In GNU Emacs (font-lock-mode 1) doesn't force font-lock,
1714 ;; contrary to the documentation. This seems to work.
1716 ;; htmlize the buffer and save the HTML.
1723 ;; I haven't decided on a useful return value yet, so just return
1724 ;; nil.
1725 nil)
1727 ;;;###autoload
1729 "Convert FILES to HTML and save the corresponding HTML versions.
1731 FILES should be a list of file names to convert. This function calls
1732 `htmlize-file' on each file; see that function for details. When
1733 invoked interactively, you are prompted for a list of files to convert,
1734 terminated with RET.
1736 If TARGET-DIRECTORY is specified, the HTML files will be saved to that
1737 directory. Normally, each HTML file is saved to the directory of the
1738 corresponding source file."
1742 ;; Use empty string as DEFAULT because setting DEFAULT to nil
1743 ;; defaults to the directory name, which is not what we want.
1745 "HTML-ize file (RET to finish): "
1752 ;; Verify that TARGET-DIRECTORY is indeed a directory. If it's a
1753 ;; file, htmlize-file will use it as target, and that doesn't make
1754 ;; sense.
1761 ;;;###autoload
1763 "HTMLize dired-marked files."
1769 ;;; htmlize.el ends here