Commit | Line | Data |
---|---|---|
7fca93e2 | 1 | \input texinfo |
b55349fb GM |
2 | @comment %**start of header |
3 | @setfilename ../../info/htmlfontify | |
7fca93e2 | 4 | @settitle Htmlfontify User Manual |
7fca93e2 | 5 | @exampleindent 2 |
c6ab4664 | 6 | @documentencoding UTF-8 |
b55349fb GM |
7 | @comment %**end of header |
8 | ||
9 | @copying | |
10 | This manual documents Htmlfontify, a source code -> crosslinked + | |
677d5c92 | 11 | formatted + syntax colorized html transformer. |
b55349fb | 12 | |
ba318903 PE |
13 | Copyright @copyright{} 2002-2003, 2013-2014 Free Software Foundation, |
14 | Inc. | |
b55349fb GM |
15 | |
16 | @quotation | |
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''. | |
23 | ||
24 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
25 | modify this GNU manual.'' | |
26 | @end quotation | |
27 | @end copying | |
28 | ||
29 | @dircategory Emacs misc features | |
30 | @direntry | |
f9405d87 | 31 | * Htmlfontify: (htmlfontify). Convert source code to html. |
b55349fb | 32 | @end direntry |
7fca93e2 VD |
33 | |
34 | @titlepage | |
35 | @title Htmlfontify User Manual | |
36 | @sp 4 | |
37 | @subtitle Htmlfontify version 0.20 | |
38 | @sp 1 | |
39 | @subtitle Jun 2002 | |
40 | @sp 5 | |
41 | @author Vivek Dasmohapatra | |
42 | @page | |
43 | ||
44 | @vskip 0pt plus 1filll | |
45 | @noindent | |
b55349fb GM |
46 | @insertcopying |
47 | @end titlepage | |
7fca93e2 | 48 | |
b55349fb | 49 | @contents |
7fca93e2 | 50 | |
b55349fb GM |
51 | @ifnottex |
52 | @node Top | |
53 | @top Htmlfontify | |
7fca93e2 | 54 | |
b55349fb GM |
55 | @insertcopying |
56 | @end ifnottex | |
7fca93e2 VD |
57 | |
58 | @menu | |
59 | * Introduction:: About Htmlfontify. | |
60 | * Usage & Examples:: How to use Htmlfontify. | |
da5ecfa9 | 61 | * Customization:: Fine-tuning Htmlfontify's behavior. |
7fca93e2 | 62 | * Requirements:: External programs used by Htmlfontify. |
b55349fb GM |
63 | * GNU Free Documentation License:: The license for this documentation. |
64 | * Index:: Index of contents. | |
7fca93e2 VD |
65 | @end menu |
66 | ||
b55349fb | 67 | @node Introduction |
7fca93e2 VD |
68 | @chapter Introduction |
69 | @cindex Introduction | |
70 | ||
b55349fb GM |
71 | Htmlfontify provides a means of converting individual Emacs buffers, |
72 | source files, or entire source trees to html, preserving formatting | |
677d5c92 | 73 | and Emacs colorization / syntax highlighting as much as possible |
7fca93e2 VD |
74 | through careful application of CSS stylesheets and html tags. |
75 | ||
b55349fb GM |
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 | |
7fca93e2 VD |
79 | all such symbols, also linked to their points of definition. |
80 | ||
677d5c92 | 81 | Htmlfontify also provides several customization items, which should |
b55349fb GM |
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). | |
7fca93e2 | 85 | |
b55349fb | 86 | @node Usage & Examples |
7fca93e2 VD |
87 | @chapter Usage & Examples |
88 | @cindex Usage & Examples | |
89 | ||
b55349fb GM |
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 | |
93 | batch mode. | |
7fca93e2 VD |
94 | |
95 | @menu | |
b55349fb GM |
96 | * Interactive:: Using Htmlfontify interactively. |
97 | * Non-interactive:: Using Htmlfontify from elisp. | |
677d5c92 | 98 | * Variables:: Variables (other than customization entries). |
b55349fb GM |
99 | * Data Structures:: Important data structures. |
100 | * Examples:: Example(s) of Htmlfontify in use. | |
7fca93e2 VD |
101 | @end menu |
102 | ||
b55349fb | 103 | @node Interactive |
7fca93e2 VD |
104 | @section Interactive |
105 | @cindex Interactive | |
106 | @cindex functions (interactive) | |
107 | ||
108 | Htmlfontify provides the following interactive functions: | |
109 | ||
110 | @table @code | |
111 | @item htmlfontify-buffer | |
112 | @findex htmlfontify-buffer | |
113 | @anchor{htmlfontify-buffer} | |
114 | ||
115 | @lisp | |
116 | ||
117 | (htmlfontify-buffer &optional @var{srcdir} @var{file}) | |
118 | @end lisp | |
119 | ||
120 | Create a new buffer, named for the current buffer + a .html extension, | |
b55349fb GM |
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. | |
7fca93e2 | 123 | |
b55349fb GM |
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 | |
126 | display. | |
7fca93e2 | 127 | |
681ebc33 PE |
128 | You should, however, note that random control or non-ASCII characters |
129 | such as ^L (\x0c) or ยค (\xa4) won't get mapped yet. | |
7fca93e2 | 130 | |
b55349fb GM |
131 | If the @var{srcdir} and @var{file} arguments are set, lookup etags |
132 | derived entries in the @ref{hfy-tags-cache} and add html anchors | |
7fca93e2 VD |
133 | and hyperlinks as appropriate. |
134 | ||
135 | @item htmlfontify-run-etags | |
136 | @findex htmlfontify-run-etags | |
137 | @anchor{htmlfontify-run-etags} | |
138 | ||
139 | @lisp | |
140 | ||
141 | (htmlfontify-run-etags @var{srcdir}) | |
142 | @end lisp | |
143 | ||
b55349fb | 144 | Load the etags cache for @var{srcdir}. See @ref{hfy-load-tags-cache}. |
7fca93e2 VD |
145 | |
146 | @item htmlfontify-copy-and-link-dir | |
147 | @findex htmlfontify-copy-and-link-dir | |
148 | @anchor{htmlfontify-copy-and-link-dir} | |
149 | ||
150 | @lisp | |
151 | ||
152 | (htmlfontify-copy-and-link-dir @var{srcdir} @var{dstdir} &optional @var{f-ext} @var{l-ext}) | |
153 | @end lisp | |
154 | ||
b55349fb GM |
155 | Trawl @var{srcdir} and write fontified-and-hyperlinked output in |
156 | @var{dstdir}. @var{f-ext} and @var{l-ext} specify values for | |
7fca93e2 VD |
157 | @ref{hfy-extn} and @ref{hfy-link-extn}. |
158 | ||
159 | You may also want to set @ref{hfy-page-header} and @ref{hfy-page-footer}. | |
160 | ||
161 | @item htmlfontify-load-rgb-file | |
162 | @findex htmlfontify-load-rgb-file | |
163 | @anchor{htmlfontify-load-rgb-file} | |
164 | ||
165 | @lisp | |
166 | ||
167 | (htmlfontify-load-rgb-file &optional @var{file}) | |
168 | @end lisp | |
169 | ||
b55349fb | 170 | Load an X11 style rgb.txt file (search @code{hfy-rgb-load-path} if |
7fca93e2 VD |
171 | @var{file} is not specified). |
172 | ||
173 | Note that this is not necessary if all you want is the standard X11 | |
b55349fb | 174 | (XFree86 4.1.0) color name -> rgb triplet mapping. Htmlfontify has |
7fca93e2 VD |
175 | a copy built in, for use when it cannot contact an X server. |
176 | ||
b55349fb GM |
177 | Loads the variable @code{hfy-rgb-txt-color-map}, which is used by |
178 | @ref{hfy-fallback-color-values}. | |
7fca93e2 VD |
179 | |
180 | @item htmlfontify-unload-rgb-file | |
181 | @findex htmlfontify-unload-rgb-file | |
182 | @anchor{htmlfontify-unload-rgb-file} | |
183 | ||
184 | @lisp | |
185 | ||
186 | (htmlfontify-unload-rgb-file) | |
187 | @end lisp | |
188 | ||
b55349fb | 189 | Unload the currently loaded X11 style rgb.txt file (if any). |
7fca93e2 VD |
190 | @end table |
191 | ||
b55349fb | 192 | @node Non-interactive |
7fca93e2 VD |
193 | @section Non-interactive |
194 | @cindex Noninteractive | |
195 | @cindex functions (noninteractive) | |
196 | ||
b55349fb | 197 | In addition to the aforementioned interactive methods, Htmlfontify |
7fca93e2 VD |
198 | provides the following non-interactive ones: |
199 | ||
200 | @table @code | |
201 | @comment AUTOGENERATED BLOCK | |
202 | ||
203 | @item hfy-face-to-style | |
204 | @findex hfy-face-to-style | |
205 | @anchor{hfy-face-to-style} | |
206 | ||
207 | @lisp | |
208 | ||
209 | (hfy-face-to-style @var{fn}) | |
210 | @end lisp | |
211 | ||
212 | Take @var{fn}, a font or @code{defface} style font specification, | |
b55349fb | 213 | (as returned by @code{face-attr-construct} or @ref{hfy-face-attr-for-class}) |
7fca93e2 VD |
214 | and return a @ref{hfy-style-assoc}. |
215 | ||
216 | See also: @ref{hfy-face-to-style-i}, @ref{hfy-flatten-style}. | |
217 | ||
b55349fb GM |
218 | @item hfy-fallback-color-values |
219 | @findex hfy-fallback-color-values | |
220 | @anchor{hfy-fallback-color-values} | |
7fca93e2 VD |
221 | |
222 | @lisp | |
223 | ||
b55349fb | 224 | (hfy-fallback-color-values @var{color-string}) |
7fca93e2 VD |
225 | @end lisp |
226 | ||
b55349fb | 227 | Use a fallback method for obtaining the rgb values for a color. |
7fca93e2 | 228 | If @ref{htmlfontify-load-rgb-file} has been called, it uses the |
b55349fb | 229 | color map specified, otherwise it uses Htmlfontify's built in map. |
7fca93e2 VD |
230 | |
231 | @item hfy-combined-face-spec | |
232 | @findex hfy-combined-face-spec | |
233 | @anchor{hfy-combined-face-spec} | |
234 | ||
235 | @lisp | |
236 | ||
237 | (hfy-combined-face-spec @var{face}) | |
238 | @end lisp | |
239 | ||
b55349fb | 240 | Return a @code{defface} style alist of possible specifications for |
677d5c92 | 241 | @var{face}, with any entries resulting from user customization |
7fca93e2 VD |
242 | (@code{custom-set-faces}) taking precedence. |
243 | ||
244 | See also: @ref{hfy-default-face-def} | |
245 | ||
246 | @item hfy-word-regex | |
247 | @findex hfy-word-regex | |
248 | @anchor{hfy-word-regex} | |
249 | ||
250 | @lisp | |
251 | ||
252 | (hfy-word-regex @var{string}) | |
253 | @end lisp | |
254 | ||
b55349fb GM |
255 | Return a regex that matches @var{string} as the first @code{match-string}, |
256 | with non word characters on either side (vaguely emulating the perl @code{\b} | |
7fca93e2 VD |
257 | regex atom). |
258 | ||
259 | @item hfy-force-fontification | |
260 | @findex hfy-force-fontification | |
261 | @anchor{hfy-force-fontification} | |
262 | ||
263 | @lisp | |
264 | ||
265 | (hfy-force-fontification) | |
266 | @end lisp | |
267 | ||
b55349fb GM |
268 | Emacs's fontification is designed for interactive use. As such, it sometimes |
269 | does things like deferring fontification until a section of the buffer is | |
270 | exposed and rendered, or until Emacs is idle for a while. Sometimes, in | |
271 | non-interactive circumstances, or if it can't see X, it doesn't bother | |
272 | with some of the harder stuff. While this is all great from the perspective | |
677d5c92 | 273 | of a user waiting for Emacs to load a 20000 line file and colorize it, |
b55349fb GM |
274 | it's a pain from the point of view from non-interactive code. This function |
275 | lies, cheats, steals and generally bullies Emacs into fontifying a buffer | |
677d5c92 | 276 | from start to finish, with all the extra frills, whether it thinks it needs |
b55349fb | 277 | to or not. Oh yes: it operates on the current buffer. |
7fca93e2 VD |
278 | |
279 | @item hfy-link-style-string | |
280 | @findex hfy-link-style-string | |
281 | @anchor{hfy-link-style-string} | |
282 | ||
283 | @lisp | |
284 | ||
285 | (hfy-link-style-string @var{style-string}) | |
286 | @end lisp | |
287 | ||
b55349fb GM |
288 | Replace the end of a CSS style declaration @var{style-string} with the contents |
289 | of the variable @ref{hfy-src-doc-link-style}, removing text matching the | |
7fca93e2 VD |
290 | regex @ref{hfy-src-doc-link-unstyle} first, if necessary. |
291 | ||
292 | ||
293 | @item hfy-prepare-index-i | |
294 | @findex hfy-prepare-index-i | |
295 | @anchor{hfy-prepare-index-i} | |
296 | ||
297 | @lisp | |
298 | ||
299 | (hfy-prepare-index-i @var{srcdir} @var{dstdir} @var{filename} &optional @var{stub} @var{map}) | |
300 | @end lisp | |
301 | ||
302 | Prepare a tags index buffer for @var{srcdir}. | |
b55349fb GM |
303 | @ref{hfy-tags-cache} must already have an entry for @var{srcdir} for |
304 | this to work. @ref{hfy-page-header}, @ref{hfy-page-footer}, | |
7fca93e2 VD |
305 | @ref{hfy-link-extn} and @ref{hfy-extn} all play a part here. |
306 | ||
307 | If @var{stub} is set, prepare an (appropriately named) index buffer | |
308 | specifically for entries beginning with @var{stub}. | |
309 | ||
310 | If @var{map} is set, use that instead of @ref{hfy-tags-cache}. | |
311 | ||
312 | @item hfy-compile-stylesheet | |
313 | @findex hfy-compile-stylesheet | |
314 | @anchor{hfy-compile-stylesheet} | |
315 | ||
316 | @lisp | |
317 | ||
318 | (hfy-compile-stylesheet) | |
319 | @end lisp | |
320 | ||
321 | Trawl the current buffer, construct and return a @ref{hfy-sheet-assoc}. | |
322 | ||
323 | @item hfy-css-name | |
324 | @findex hfy-css-name | |
325 | @anchor{hfy-css-name} | |
326 | ||
327 | @lisp | |
328 | ||
329 | (hfy-css-name @var{fn}) | |
330 | @end lisp | |
331 | ||
b55349fb GM |
332 | Strip some of the boring bits from a font-name and return a CSS style |
333 | name. If @var{fn} is a @code{defface} attribute list, either construct | |
7fca93e2 VD |
334 | a name for it, store it in the cache, and return it, or just fetch it |
335 | from the cache if it's already there. | |
336 | ||
337 | @item hfy-make-directory | |
338 | @findex hfy-make-directory | |
339 | @anchor{hfy-make-directory} | |
340 | ||
341 | @lisp | |
342 | ||
343 | (hfy-make-directory @var{dir}) | |
344 | @end lisp | |
345 | ||
b55349fb | 346 | Approximate equivalent of @code{mkdir -p @var{dir}}. |
7fca93e2 VD |
347 | |
348 | @item hfy-triplet | |
349 | @findex hfy-triplet | |
350 | @anchor{hfy-triplet} | |
351 | ||
352 | @lisp | |
353 | ||
b55349fb | 354 | (hfy-triplet @var{color}) |
7fca93e2 VD |
355 | @end lisp |
356 | ||
b55349fb GM |
357 | Takes a color name (string) and return a CSS rgb(R, G, B) triplet string. |
358 | Uses the definition of ``white'' to map the numbers to the 0-255 range, so | |
359 | if you've redefined white, (especially if you've redefined it to have | |
360 | a triplet member lower than that of the color you are processing, | |
361 | strange things may happen). | |
7fca93e2 VD |
362 | |
363 | @item hfy-default-footer | |
364 | @findex hfy-default-footer | |
365 | @anchor{hfy-default-footer} | |
366 | ||
367 | @lisp | |
368 | ||
369 | (hfy-default-footer @var{file}) | |
370 | @end lisp | |
371 | ||
372 | Default value for @ref{hfy-page-footer} | |
373 | ||
374 | @item hfy-list-files | |
375 | @findex hfy-list-files | |
376 | @anchor{hfy-list-files} | |
377 | ||
378 | @lisp | |
379 | ||
380 | (hfy-list-files @var{directory}) | |
381 | @end lisp | |
382 | ||
383 | Return a list of files under @var{directory}. | |
b55349fb | 384 | Strips any leading @samp{./} from each filename. |
7fca93e2 | 385 | |
b55349fb GM |
386 | @item hfy-color-vals |
387 | @findex hfy-color-vals | |
388 | @anchor{hfy-color-vals} | |
7fca93e2 VD |
389 | |
390 | @lisp | |
391 | ||
b55349fb | 392 | (hfy-color-vals @var{color}) |
7fca93e2 VD |
393 | @end lisp |
394 | ||
b55349fb GM |
395 | Where @var{color} is a color name or #XXXXXX style triplet, return a list of |
396 | 3 (16 bit) rgb values for said color. If a window system is unavailable, | |
397 | calls @ref{hfy-fallback-color-values}. | |
7fca93e2 VD |
398 | |
399 | @item hfy-href-stub | |
400 | @findex hfy-href-stub | |
401 | @anchor{hfy-href-stub} | |
402 | ||
403 | @lisp | |
404 | ||
405 | (hfy-href-stub @var{this-file} @var{def-files} @var{tag}) | |
406 | @end lisp | |
407 | ||
b55349fb | 408 | Return an href stub for a tag href: if @var{def-files} (list of files |
7fca93e2 | 409 | containing definitions for the tag in question) contains only one entry, |
b55349fb | 410 | the href should link straight to that file. Otherwise, the link should |
7fca93e2 VD |
411 | be to the index file. |
412 | ||
b55349fb | 413 | We are not yet concerned with the file extensions/tag line number and |
7fca93e2 VD |
414 | so on at this point. |
415 | ||
b55349fb GM |
416 | If @ref{hfy-split-index} is set, and the href will be to an index file |
417 | rather than a source file, append a @samp{.X} to @ref{hfy-index-file}, where | |
418 | @samp{X} is the uppercased first character of @var{tag}. | |
7fca93e2 VD |
419 | |
420 | See also: @ref{hfy-relstub}, @ref{hfy-index-file}. | |
421 | ||
422 | @item hfy-line-number | |
423 | @findex hfy-line-number | |
424 | @anchor{hfy-line-number} | |
425 | ||
426 | @lisp | |
427 | ||
428 | (hfy-line-number) | |
429 | @end lisp | |
430 | ||
431 | Returns the line number of the point in the current buffer. | |
432 | ||
433 | @item hfy-merge-adjacent-spans | |
434 | @findex hfy-merge-adjacent-spans | |
435 | @anchor{hfy-merge-adjacent-spans} | |
436 | ||
437 | @lisp | |
438 | ||
439 | (hfy-merge-adjacent-spans @var{face-map}) | |
440 | @end lisp | |
441 | ||
b55349fb | 442 | Where @var{face-map} is a @ref{hfy-facemap-assoc} for the current buffer, |
7fca93e2 VD |
443 | this function merges adjacent style blocks which are of the same value |
444 | and are separated by nothing more interesting than whitespace. | |
445 | ||
446 | @code{<span class="foo">narf</span> <span class="foo">brain</span>} | |
447 | ||
448 | (as interpreted from @var{face-map}) would become: | |
449 | ||
450 | @code{<span class="foo">narf brain</span>} | |
451 | ||
452 | Returns a modified copy of @var{face-map} (also a @ref{hfy-facemap-assoc}). | |
453 | ||
454 | @item hfy-mark-tag-names | |
455 | @findex hfy-mark-tag-names | |
456 | @anchor{hfy-mark-tag-names} | |
457 | ||
458 | @lisp | |
459 | ||
460 | (hfy-mark-tag-names @var{srcdir} @var{file}) | |
461 | @end lisp | |
462 | ||
b55349fb GM |
463 | Mark tags in @var{file} (lookup @var{srcdir} in @ref{hfy-tags-cache}) with the |
464 | @code{hfy-anchor} property, with a value of @samp{tag.line-number}. | |
7fca93e2 VD |
465 | |
466 | @item hfy-weight | |
467 | @findex hfy-weight | |
468 | @anchor{hfy-weight} | |
469 | ||
470 | @lisp | |
471 | ||
472 | (hfy-weight @var{weight}) | |
473 | @end lisp | |
474 | ||
b55349fb | 475 | Derive a font-weight CSS specifier from an Emacs weight specification symbol. |
7fca93e2 VD |
476 | |
477 | @item hfy-size | |
478 | @findex hfy-size | |
479 | @anchor{hfy-size} | |
480 | ||
481 | @lisp | |
482 | ||
483 | (hfy-size @var{height}) | |
484 | @end lisp | |
485 | ||
b55349fb | 486 | Derive a CSS font-size specifier from an Emacs font @code{:height} attribute. |
7fca93e2 VD |
487 | Does not cope with the case where height is a function to be applied to |
488 | the height of the underlying font. | |
489 | ||
490 | @item hfy-default-header | |
491 | @findex hfy-default-header | |
492 | @anchor{hfy-default-header} | |
493 | ||
494 | @lisp | |
495 | ||
496 | (hfy-default-header @var{file} @var{style}) | |
497 | @end lisp | |
498 | ||
499 | Default value for @ref{hfy-page-header} | |
500 | ||
501 | @item hfy-family | |
502 | @findex hfy-family | |
503 | @anchor{hfy-family} | |
504 | ||
505 | @lisp | |
506 | ||
507 | (hfy-family @var{family}) | |
508 | @end lisp | |
509 | ||
b55349fb | 510 | Derives a CSS font-family specifier from an Emacs @code{:family} attribute. |
7fca93e2 VD |
511 | |
512 | @item hfy-mark-tag-hrefs | |
513 | @findex hfy-mark-tag-hrefs | |
514 | @anchor{hfy-mark-tag-hrefs} | |
515 | ||
516 | @lisp | |
517 | ||
518 | (hfy-mark-tag-hrefs @var{srcdir} @var{file}) | |
519 | @end lisp | |
520 | ||
b55349fb | 521 | Mark href start points with the @code{hfy-link} property (value: href string). |
7fca93e2 | 522 | |
b55349fb | 523 | Mark href end points with the @code{hfy-endl} property (value @code{t}). |
7fca93e2 VD |
524 | |
525 | Avoid overlapping links, and mark links in descending length of | |
b55349fb GM |
526 | tag name in order to prevent subtags from usurping supertags; |
527 | e.g., ``term'' for ``terminal''). | |
7fca93e2 VD |
528 | |
529 | @item hfy-box | |
530 | @findex hfy-box | |
531 | @anchor{hfy-box} | |
532 | ||
533 | @lisp | |
534 | ||
535 | (hfy-box @var{box}) | |
536 | @end lisp | |
537 | ||
b55349fb | 538 | Derive CSS border-* attributes from the Emacs @code{:box} attribute. |
7fca93e2 VD |
539 | |
540 | @item hfy-box-to-style | |
541 | @findex hfy-box-to-style | |
542 | @anchor{hfy-box-to-style} | |
543 | ||
544 | @lisp | |
545 | ||
546 | (hfy-box-to-style @var{spec}) | |
547 | @end lisp | |
548 | ||
b55349fb GM |
549 | Convert a complex @code{:box} Emacs font attribute set to a list of |
550 | CSS border-* attributes. Don't call this directly---it is called by | |
551 | @ref{hfy-box} when necessary. | |
7fca93e2 VD |
552 | |
553 | @item hfy-html-enkludge-buffer | |
554 | @findex hfy-html-enkludge-buffer | |
555 | @anchor{hfy-html-enkludge-buffer} | |
556 | ||
557 | @lisp | |
558 | ||
559 | (hfy-html-enkludge-buffer) | |
560 | @end lisp | |
561 | ||
b55349fb | 562 | Mark dangerous @samp{["<>]} characters with the @code{hfy-quoteme} property. |
7fca93e2 VD |
563 | |
564 | See also @ref{hfy-html-dekludge-buffer}. | |
565 | ||
566 | @item hfy-buffer | |
567 | @findex hfy-buffer | |
568 | @anchor{hfy-buffer} | |
569 | ||
570 | @lisp | |
571 | ||
572 | (hfy-buffer) | |
573 | @end lisp | |
574 | ||
b55349fb GM |
575 | Generate and return an Htmlfontify html output buffer for the current |
576 | buffer. May trample an existing buffer. | |
7fca93e2 VD |
577 | |
578 | @item hfy-fontified-p | |
579 | @findex hfy-fontified-p | |
580 | @anchor{hfy-fontified-p} | |
581 | ||
582 | @lisp | |
583 | ||
584 | (hfy-fontified-p) | |
585 | @end lisp | |
586 | ||
b55349fb GM |
587 | @code{font-lock} doesn't like to say a buffer's been fontified when in |
588 | batch mode, but we want to know if we should fontify or raw copy, so in | |
589 | batch mode we check for non-default face properties. Otherwise we test | |
7fca93e2 VD |
590 | @code{font-lock-mode} and @code{font-lock-fontified} for truth. |
591 | ||
592 | @item hfy-lookup | |
593 | @findex hfy-lookup | |
594 | @anchor{hfy-lookup} | |
595 | ||
596 | @lisp | |
597 | ||
598 | (hfy-lookup @var{face} @var{style}) | |
599 | @end lisp | |
600 | ||
b55349fb | 601 | Where @var{style} is a @ref{hfy-sheet-assoc} and @var{face} is an Emacs face, |
7fca93e2 VD |
602 | return the relevant @var{css} style name. |
603 | ||
604 | @item hfy-fontify-buffer | |
605 | @findex hfy-fontify-buffer | |
606 | @anchor{hfy-fontify-buffer} | |
607 | ||
608 | @lisp | |
609 | ||
610 | (hfy-fontify-buffer &optional @var{srcdir} @var{file}) | |
611 | @end lisp | |
612 | ||
b55349fb | 613 | Implement the guts of @ref{htmlfontify-buffer}. |
7fca93e2 | 614 | |
b55349fb GM |
615 | @item hfy-color |
616 | @findex hfy-color | |
617 | @anchor{hfy-color} | |
7fca93e2 VD |
618 | |
619 | @lisp | |
620 | ||
b55349fb | 621 | (hfy-color @var{color}) |
7fca93e2 VD |
622 | @end lisp |
623 | ||
b55349fb | 624 | Convert an Emacs :foreground property to a CSS color property. |
7fca93e2 VD |
625 | |
626 | @item hfy-flatten-style | |
627 | @findex hfy-flatten-style | |
628 | @anchor{hfy-flatten-style} | |
629 | ||
630 | @lisp | |
631 | ||
632 | (hfy-flatten-style @var{style}) | |
633 | @end lisp | |
634 | ||
b55349fb GM |
635 | Take @var{style} (see @ref{hfy-face-to-style-i}, @ref{hfy-face-to-style}) |
636 | and merge any multiple attributes appropriately. Currently only font-size is | |
637 | merged down to a single occurrence---others may need special handling, but I | |
638 | haven't encountered them yet. Returns a @ref{hfy-style-assoc}. | |
7fca93e2 VD |
639 | |
640 | @item hfy-size-to-int | |
641 | @findex hfy-size-to-int | |
642 | @anchor{hfy-size-to-int} | |
643 | ||
644 | @lisp | |
645 | ||
646 | (hfy-size-to-int @var{spec}) | |
647 | @end lisp | |
648 | ||
b55349fb GM |
649 | Convert @var{spec}, a CSS font-size specifier, back to an Emacs |
650 | @code{:height} attribute value. Used while merging multiple font-size | |
651 | attributes. | |
7fca93e2 VD |
652 | |
653 | @item hfy-sprintf-stylesheet | |
654 | @findex hfy-sprintf-stylesheet | |
655 | @anchor{hfy-sprintf-stylesheet} | |
656 | ||
657 | @lisp | |
658 | ||
659 | (hfy-sprintf-stylesheet @var{css} @var{file}) | |
660 | @end lisp | |
661 | ||
b55349fb GM |
662 | Generates a header, via @ref{hfy-page-header}, for @var{file}, containing the |
663 | stylesheet derived from @var{css}, which is a @ref{hfy-sheet-assoc}. Returns a | |
7fca93e2 VD |
664 | string containing the same. |
665 | ||
666 | @item hfy-relstub | |
667 | @findex hfy-relstub | |
668 | @anchor{hfy-relstub} | |
669 | ||
670 | @lisp | |
671 | ||
672 | (hfy-relstub @var{file} &optional @var{start}) | |
673 | @end lisp | |
674 | ||
b55349fb GM |
675 | Return a @samp{../} stub of the appropriate length for the current source |
676 | tree depth (as determined from @var{file}). @c iyswim. | |
7fca93e2 VD |
677 | |
678 | @item hfy-compile-face-map | |
679 | @findex hfy-compile-face-map | |
680 | @anchor{hfy-compile-face-map} | |
681 | ||
682 | @lisp | |
683 | ||
684 | (hfy-compile-face-map) | |
685 | @end lisp | |
686 | ||
687 | Compile and return a @ref{hfy-facemap-assoc} for the current buffer. | |
688 | ||
689 | @item hfy-prepare-index | |
690 | @findex hfy-prepare-index | |
691 | @anchor{hfy-prepare-index} | |
692 | ||
693 | @lisp | |
694 | ||
695 | (hfy-prepare-index @var{srcdir} @var{dstdir}) | |
696 | @end lisp | |
697 | ||
698 | Return as list of index buffer(s), as determined by @ref{hfy-split-index}. | |
699 | Uses @ref{hfy-prepare-index-i} to do this. | |
700 | ||
701 | @item hfy-prepare-tag-map | |
702 | @findex hfy-prepare-tag-map | |
703 | @anchor{hfy-prepare-tag-map} | |
704 | ||
705 | @lisp | |
706 | ||
707 | (hfy-prepare-tag-map @var{srcdir} @var{dstdir}) | |
708 | @end lisp | |
709 | ||
b55349fb GM |
710 | Prepare the counterpart(s) to the index buffer(s)---a list of buffers with |
711 | the same structure, but listing (and linking to) instances of tags (as | |
712 | opposed to their definitions). | |
7fca93e2 VD |
713 | |
714 | See also: @ref{hfy-prepare-index}, @ref{hfy-split-index} | |
715 | ||
716 | @item hfy-subtract-maps | |
717 | @findex hfy-subtract-maps | |
718 | @anchor{hfy-subtract-maps} | |
719 | ||
720 | @lisp | |
721 | ||
722 | (hfy-subtract-maps @var{srcdir}) | |
723 | @end lisp | |
724 | ||
b55349fb | 725 | Internal function---strips definitions of tags from the instance map. |
7fca93e2 VD |
726 | See: @ref{hfy-tags-cache} and @ref{hfy-tags-rmap} |
727 | ||
728 | @item hfy-face-to-style-i | |
729 | @findex hfy-face-to-style-i | |
730 | @anchor{hfy-face-to-style-i} | |
731 | ||
732 | @lisp | |
733 | ||
734 | (hfy-face-to-style-i @var{fn}) | |
735 | @end lisp | |
736 | ||
b55349fb GM |
737 | The guts of @ref{hfy-face-to-style}. @var{fn} should be a @code{defface} |
738 | font specification, as returned by @code{face-attr-construct} or | |
739 | @ref{hfy-face-attr-for-class}. Note that this function does not get | |
740 | font-sizes right if they are based on inherited modifiers (via the | |
741 | :inherit) attribute, and any other modifiers that are cumulative if they | |
742 | appear multiple times need to be merged by the user---@ref{hfy-flatten-style} | |
7fca93e2 VD |
743 | should do this. |
744 | ||
745 | @item hfy-face-to-css | |
746 | @findex hfy-face-to-css | |
747 | @anchor{hfy-face-to-css} | |
748 | ||
749 | @lisp | |
750 | ||
751 | (hfy-face-to-css @var{fn}) | |
752 | @end lisp | |
753 | ||
b55349fb | 754 | Take @var{fn}, a font or @code{defface} specification (c.f. |
7fca93e2 VD |
755 | @code{face-attr-construct}) and return a CSS style specification. |
756 | ||
757 | See also: @ref{hfy-face-to-style} | |
758 | ||
759 | @item hfy-html-quote | |
760 | @findex hfy-html-quote | |
761 | @anchor{hfy-html-quote} | |
762 | ||
763 | @lisp | |
764 | ||
765 | (hfy-html-quote @var{char-string}) | |
766 | @end lisp | |
767 | ||
b55349fb GM |
768 | Map a string (usually 1 character long) to an html safe string |
769 | (entity) if need be. | |
7fca93e2 VD |
770 | |
771 | @item hfy-link-style | |
772 | @findex hfy-link-style | |
773 | @anchor{hfy-link-style} | |
774 | ||
775 | @lisp | |
776 | ||
777 | (hfy-link-style @var{style-string}) | |
778 | @end lisp | |
779 | ||
b55349fb | 780 | Convert the CSS style spec @var{style-string} to its equivalent |
7fca93e2 VD |
781 | hyperlink style. |
782 | ||
783 | See: @ref{hfy-link-style-fun}. | |
784 | ||
785 | @item hfy-p-to-face | |
786 | @findex hfy-p-to-face | |
787 | @anchor{hfy-p-to-face} | |
788 | ||
789 | @lisp | |
790 | ||
791 | (hfy-p-to-face @var{props}) | |
792 | @end lisp | |
793 | ||
b55349fb | 794 | Given @var{props}, a list of text-properties, return the value of the |
7fca93e2 VD |
795 | face property, or nil. |
796 | ||
797 | @item hfy-box-to-border-assoc | |
798 | @findex hfy-box-to-border-assoc | |
799 | @anchor{hfy-box-to-border-assoc} | |
800 | ||
801 | @lisp | |
802 | ||
803 | (hfy-box-to-border-assoc @var{spec}) | |
804 | @end lisp | |
805 | ||
806 | Helper function for @ref{hfy-box-to-style}. | |
807 | ||
808 | @item hfy-face-attr-for-class | |
809 | @findex hfy-face-attr-for-class | |
810 | @anchor{hfy-face-attr-for-class} | |
811 | ||
812 | @lisp | |
813 | ||
814 | (hfy-face-attr-for-class @var{face} &optional @var{class}) | |
815 | @end lisp | |
816 | ||
b55349fb GM |
817 | Return the face attributes for @var{face}. If @var{class} is set, it |
818 | must be a @code{defface} alist key [see below]. Prior to version 0.18, | |
819 | the first face specification returned by @ref{hfy-combined-face-spec} | |
820 | which @emph{didn't} clash with @var{class} was returned. In versions | |
821 | from 0.18 onwards, each font attribute list is scored, and the | |
822 | non-conflicting list with the highest score is returned. (A specification | |
823 | with a class of @code{t} is considered to match any class you specify. | |
da5ecfa9 | 824 | This matches Emacs's behavior when deciding on which face attributes to |
7fca93e2 VD |
825 | use, to the best of my understanding ). |
826 | ||
b55349fb GM |
827 | If @var{class} is nil, then you just get get whatever |
828 | @code{face-attr-construct} returns; i.e., the current specification in | |
7fca93e2 VD |
829 | effect for @var{face}. |
830 | ||
831 | See @ref{hfy-display-class} for details of valid values for @var{class}. | |
832 | ||
833 | @item hfy-face-at | |
834 | @findex hfy-face-at | |
835 | @anchor{hfy-face-at} | |
836 | ||
837 | @lisp | |
838 | ||
839 | (hfy-face-at P) | |
840 | @end lisp | |
841 | ||
b55349fb | 842 | Find face in effect at point P. If overlays are to be considered |
7fca93e2 VD |
843 | (see @ref{hfy-optimisations}) then this may return a @code{defface} style |
844 | list of face properties instead of a face symbol. | |
845 | ||
846 | @item hfy-bgcol | |
847 | @findex hfy-bgcol | |
848 | @anchor{hfy-bgcol} | |
849 | ||
850 | @lisp | |
851 | ||
b55349fb | 852 | (hfy-bgcol @var{color}) |
7fca93e2 VD |
853 | @end lisp |
854 | ||
b55349fb | 855 | As per @ref{hfy-color} but for background colors. |
7fca93e2 VD |
856 | |
857 | @item hfy-kludge-cperl-mode | |
858 | @findex hfy-kludge-cperl-mode | |
859 | @anchor{hfy-kludge-cperl-mode} | |
860 | ||
861 | @lisp | |
862 | ||
863 | (hfy-kludge-cperl-mode) | |
864 | @end lisp | |
865 | ||
677d5c92 | 866 | cperl mode does its best to not do some of its fontification when not |
b55349fb | 867 | in a windowing system---we try to trick it@dots{} |
7fca93e2 VD |
868 | |
869 | @item hfy-href | |
870 | @findex hfy-href | |
871 | @anchor{hfy-href} | |
872 | ||
873 | @lisp | |
874 | ||
875 | (hfy-href @var{this-file} @var{def-files} @var{tag} @var{tag-map}) | |
876 | @end lisp | |
877 | ||
878 | Return a relative href to the tag in question, based on | |
879 | ||
880 | @var{this-file} @ref{hfy-link-extn} @ref{hfy-extn} @var{def-files} @var{tag} and @var{tag-map} | |
881 | ||
882 | @var{this-file} is the current source file | |
883 | @var{def-files} is a list of file containing possible link endpoints for @var{tag} | |
884 | @var{tag} is the @var{tag} in question | |
885 | @var{tag-map} is the entry in @ref{hfy-tags-cache}. | |
886 | ||
887 | @item hfy-shell | |
888 | @findex hfy-shell | |
889 | @anchor{hfy-shell} | |
890 | ||
891 | @lisp | |
892 | ||
893 | (hfy-shell) | |
894 | @end lisp | |
895 | ||
b55349fb | 896 | Returns a best guess at a Bourne compatible shell to use: If the current |
7fca93e2 VD |
897 | shell doesn't look promising, fall back to @ref{hfy-shell-file-name}. |
898 | ||
899 | @item hfy-load-tags-cache | |
900 | @findex hfy-load-tags-cache | |
901 | @anchor{hfy-load-tags-cache} | |
902 | ||
903 | @lisp | |
904 | ||
905 | (hfy-load-tags-cache @var{srcdir}) | |
906 | @end lisp | |
907 | ||
908 | Run @ref{hfy-etags-cmd} on @var{srcdir}: load @ref{hfy-tags-cache} and @ref{hfy-tags-sortl}. | |
909 | ||
910 | @item hfy-parse-tags-buffer | |
911 | @findex hfy-parse-tags-buffer | |
912 | @anchor{hfy-parse-tags-buffer} | |
913 | ||
914 | @lisp | |
915 | ||
916 | (hfy-parse-tags-buffer @var{srcdir} @var{buffer}) | |
917 | @end lisp | |
918 | ||
919 | Parse a @var{buffer} containing etags formatted output, loading the | |
920 | @ref{hfy-tags-cache} and @ref{hfy-tags-sortl} entries for @var{srcdir}. | |
921 | ||
922 | @item hfy-interq | |
923 | @findex hfy-interq | |
924 | @anchor{hfy-interq} | |
925 | ||
926 | @lisp | |
927 | ||
928 | (hfy-interq @var{set-a} @var{set-b}) | |
929 | @end lisp | |
930 | ||
b55349fb | 931 | Return the intersection (using @code{eq}) of 2 lists. |
7fca93e2 VD |
932 | |
933 | @item hfy-text-p | |
934 | @findex hfy-text-p | |
935 | @anchor{hfy-text-p} | |
936 | ||
937 | @lisp | |
938 | ||
939 | (hfy-text-p @var{srcdir} @var{file}) | |
940 | @end lisp | |
941 | ||
b55349fb | 942 | Is @var{srcdir}/@var{file} text? Uses @ref{hfy-istext-command} to determine this. |
7fca93e2 VD |
943 | |
944 | @item hfy-opt | |
945 | @findex hfy-opt | |
946 | @anchor{hfy-opt} | |
947 | ||
948 | @lisp | |
949 | ||
950 | (hfy-opt @var{symbol}) | |
951 | @end lisp | |
952 | ||
953 | Is @ref{hfy-optimisations} member @var{symbol} set or not? | |
954 | ||
955 | @item hfy-dirname | |
956 | @findex hfy-dirname | |
957 | @anchor{hfy-dirname} | |
958 | ||
959 | @lisp | |
960 | ||
961 | (hfy-dirname @var{file}) | |
962 | @end lisp | |
963 | ||
b55349fb GM |
964 | Return everything preceding the last @samp{/} from a relative filename, |
965 | on the assumption that this will produce a relative directory name. Hardly | |
7fca93e2 VD |
966 | bombproof, but good enough in the context in which it is being used. |
967 | ||
968 | @item hfy-html-dekludge-buffer | |
969 | @findex hfy-html-dekludge-buffer | |
970 | @anchor{hfy-html-dekludge-buffer} | |
971 | ||
972 | @lisp | |
973 | ||
974 | (hfy-html-dekludge-buffer) | |
975 | @end lisp | |
976 | ||
b55349fb | 977 | Transform all dangerous characters marked with the @code{hfy-quoteme} property |
7fca93e2 VD |
978 | using @ref{hfy-html-quote} |
979 | ||
980 | See also @ref{hfy-html-enkludge-buffer}. | |
981 | ||
982 | @item hfy-copy-and-fontify-file | |
983 | @findex hfy-copy-and-fontify-file | |
984 | @anchor{hfy-copy-and-fontify-file} | |
985 | ||
986 | @lisp | |
987 | ||
988 | (hfy-copy-and-fontify-file @var{srcdir} @var{dstdir} @var{file}) | |
989 | @end lisp | |
990 | ||
b55349fb GM |
991 | Open @var{file} in @var{srcdir}---if fontified, write a fontified copy to @var{dstdir} |
992 | adding an extension of @ref{hfy-extn}. Fontification is actually done by | |
993 | @ref{htmlfontify-buffer}. If the buffer is not fontified, just copy it. | |
7fca93e2 VD |
994 | |
995 | @item hfy-decor | |
996 | @findex hfy-decor | |
997 | @anchor{hfy-decor} | |
998 | ||
999 | @lisp | |
1000 | ||
1001 | (hfy-decor @var{tag} @var{val}) | |
1002 | @end lisp | |
1003 | ||
b55349fb | 1004 | Derive CSS text-decoration specifiers from various Emacs font attributes. |
7fca93e2 VD |
1005 | |
1006 | @item hfy-slant | |
1007 | @findex hfy-slant | |
1008 | @anchor{hfy-slant} | |
1009 | ||
1010 | @lisp | |
1011 | ||
1012 | (hfy-slant @var{slant}) | |
1013 | @end lisp | |
1014 | ||
b55349fb GM |
1015 | Derive a font-style CSS specifier from the Emacs :slant |
1016 | attribute---CSS does not define the reverse-* styles, so just maps | |
1017 | those to the regular specifiers. | |
7fca93e2 VD |
1018 | |
1019 | @item hfy-tags-for-file | |
1020 | @findex hfy-tags-for-file | |
1021 | @anchor{hfy-tags-for-file} | |
1022 | ||
1023 | @lisp | |
1024 | ||
1025 | (hfy-tags-for-file @var{srcdir} @var{file}) | |
1026 | @end lisp | |
1027 | ||
b55349fb | 1028 | List of etags tags that have definitions in this @var{file}. Looks up |
7fca93e2 VD |
1029 | the tags cache in @ref{hfy-tags-cache} using @var{srcdir} as the key. |
1030 | ||
1031 | @item hfy-width | |
1032 | @findex hfy-width | |
1033 | @anchor{hfy-width} | |
1034 | ||
1035 | @lisp | |
1036 | ||
1037 | (hfy-width @var{width}) | |
1038 | @end lisp | |
1039 | ||
b55349fb | 1040 | Convert an Emacs @code{:width} attribute to a CSS font-stretch attribute. |
7fca93e2 VD |
1041 | |
1042 | @comment /AUTOGENERATED BLOCK | |
1043 | @end table | |
1044 | ||
b55349fb | 1045 | @node Variables |
7fca93e2 VD |
1046 | @section Variables |
1047 | @cindex variables | |
1048 | ||
677d5c92 | 1049 | Important variables that are not customization items: |
7fca93e2 VD |
1050 | |
1051 | @table @code | |
1052 | ||
1053 | @item hfy-tags-cache | |
1054 | @vindex hfy-tags-cache | |
1055 | @anchor{hfy-tags-cache} | |
1056 | ||
1057 | This is an alist of the form: | |
1058 | ||
1059 | @example | |
b55349fb | 1060 | (("/src/dir/0" . tag-hash0) ("/src/dir/1" tag-hash1) @dots{} ) |
7fca93e2 VD |
1061 | @end example |
1062 | ||
1063 | Each tag hash entry then contains entries of the form: | |
1064 | ||
1065 | @example | |
b55349fb | 1066 | "tag_string" => (("file/name.ext" line char) @dots{} ) |
7fca93e2 VD |
1067 | @end example |
1068 | ||
b55349fb | 1069 | i.e., an alist mapping (relative) file paths to line and character offsets. |
7fca93e2 VD |
1070 | |
1071 | See @ref{hfy-load-tags-cache}. | |
1072 | ||
1073 | @item hfy-tags-rmap | |
1074 | @vindex hfy-tags-rmap | |
1075 | @anchor{hfy-tags-rmap} | |
1076 | ||
1077 | @code{hfy-tags-rmap} is an alist of the form: | |
1078 | ||
1079 | @lisp | |
1080 | (("/src/dir" . tag-rmap-hash)) | |
1081 | @end lisp | |
1082 | ||
1083 | Where tag-rmap-hash has entries of the form: | |
1084 | ||
1085 | @example | |
1086 | "tag_string" => ( "file/name.ext" line char ) | |
1087 | @end example | |
1088 | ||
1089 | Unlike @ref{hfy-tags-cache} these are the locations of occurrences of | |
1090 | tagged items, not the locations of their definitions. | |
1091 | ||
1092 | @item hfy-tags-sortl | |
1093 | @vindex hfy-tags-sortl | |
1094 | @anchor{hfy-tags-sortl} | |
1095 | ||
1096 | @code{hfy-tags-sortl} is an alist of the form: | |
1097 | ||
1098 | @example | |
b55349fb | 1099 | (("/src/dir" . (tag0 tag1 tag2)) @dots{} ) |
7fca93e2 VD |
1100 | @end example |
1101 | ||
1102 | Where the tags are stored in descending order of length. | |
1103 | ||
1104 | See: @ref{hfy-load-tags-cache}. | |
1105 | ||
1106 | @end table | |
1107 | ||
b55349fb | 1108 | @node Data Structures |
7fca93e2 VD |
1109 | @section Data Structures |
1110 | @cindex Data Structures | |
1111 | ||
1112 | Some of the (informal) data structures used in Htmlfontify are detailed here: | |
1113 | ||
1114 | @table @code | |
1115 | ||
1116 | @item hfy-style-assoc | |
1117 | @cindex hfy-style-assoc | |
1118 | @anchor{hfy-style-assoc} | |
1119 | ||
b55349fb GM |
1120 | An assoc representing/describing an Emacs face. Properties may be repeated, |
1121 | in which case later properties should be treated as if they were inherited | |
1122 | from a ``parent'' font. (For some properties, only the first encountered value | |
7fca93e2 | 1123 | is of any importance, for others the values might be cumulative, and for |
b55349fb | 1124 | others they might be cumulative in a complex way.) |
7fca93e2 VD |
1125 | |
1126 | Some examples: | |
1127 | ||
1128 | @lisp | |
1129 | (hfy-face-to-style 'default) => | |
1130 | ||
1131 | (("background" . "rgb(0, 0, 0)" ) | |
1132 | ("color" . "rgb(255, 255, 255)") | |
1133 | ("font-style" . "normal" ) | |
1134 | ("font-weight" . "500" ) | |
1135 | ("font-stretch" . "normal" ) | |
1136 | ("font-family" . "misc-fixed" ) | |
1137 | ("font-size" . "13pt" ) | |
1138 | ("text-decoration" . "none" )) | |
1139 | ||
1140 | (hfy-face-to-style 'Info-title-3-face) => | |
1141 | ||
1142 | (("font-weight" . "700" ) | |
1143 | ("font-family" . "helv" ) | |
1144 | ("font-size" . "120%" ) | |
1145 | ("text-decoration" . "none") ) | |
1146 | @end lisp | |
1147 | ||
1148 | @item hfy-sheet-assoc | |
1149 | @cindex hfy-sheet-assoc | |
1150 | @anchor{hfy-sheet-assoc} | |
1151 | ||
b55349fb | 1152 | An assoc with elements of the form @samp{(face-name style-name . style-string)}. |
7fca93e2 VD |
1153 | The actual stylesheet for each page is derived from one of these. |
1154 | ||
1155 | @lisp | |
1156 | '((default "default" . "@{ background: black; color: white@}") | |
1157 | (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}")) | |
1158 | @end lisp | |
1159 | ||
b55349fb | 1160 | @item hfy-facemap-assoc |
7fca93e2 VD |
1161 | @cindex hfy-facemap-assoc |
1162 | @anchor{hfy-facemap-assoc} | |
1163 | ||
b55349fb GM |
1164 | An assoc of @code{(point . @var{face-symbol})} or |
1165 | @code{(point . @code{defface} attribute list)} and @code{(point | |
1166 | . end)} elements, in descending order of point value (i.e., from the | |
1167 | file's end to its beginning). The map is in reverse order because | |
1168 | inserting a @samp{<style>} tag (or any other string) at @var{point} | |
1169 | invalidates the map for all entries with a greater value of point. By | |
1170 | traversing the map from greatest to least @var{point}, we still | |
1171 | invalidate the map as we go, but only those points we have already | |
1172 | dealt with (and therefore no longer care about) will be invalid at any | |
7fca93e2 VD |
1173 | time. |
1174 | ||
1175 | @lisp | |
1176 | '((64820 . end) | |
1177 | (64744 . font-lock-comment-face) | |
1178 | (64736 . end) | |
1179 | (64722 . font-lock-string-face) | |
1180 | (64630 . end) | |
1181 | (64623 . font-lock-string-face) | |
1182 | (64449 . end) | |
b55349fb | 1183 | ;; Big similar section elided. You get the idea. |
7fca93e2 VD |
1184 | (5459 . end) |
1185 | (5431 . (:inherit font-lock-keyword-face :background "7e7e7e")) | |
1186 | (5431 . end) | |
1187 | (4285 . font-lock-constant-face) | |
1188 | (4285 . end) | |
1189 | (4221 . font-lock-comment-face) | |
1190 | (4221 . end) | |
1191 | (4197 . font-lock-constant-face) | |
1192 | (4197 . end) | |
1193 | (1 . font-lock-comment-face)) | |
1194 | @end lisp | |
1195 | ||
1196 | @end table | |
1197 | ||
b55349fb | 1198 | @node Examples |
7fca93e2 VD |
1199 | @section Examples |
1200 | @cindex Examples | |
1201 | ||
b55349fb GM |
1202 | The following is a lump of code I use to fontify source code on my |
1203 | site, @url{http://rtfm.etla.org/} (which was the reason, incidentally, | |
1204 | that Htmlfontify was written in the first place). | |
7fca93e2 VD |
1205 | |
1206 | @lisp | |
1207 | (defvar rtfm-section nil) | |
1208 | ||
b55349fb | 1209 | ;; Constructs an appropriate header string to fit in with rtfm's |
7fca93e2 VD |
1210 | ;; templating system, based on the file and the stylesheet string |
1211 | (defun rtfm-build-page-header (file style) | |
1212 | (format "#define TEMPLATE red+black.html | |
1213 | #define DEBUG 1 | |
1214 | #include <build/menu-dirlist|>\n | |
1215 | html-css-url := /css/red+black.css | |
1216 | title := rtfm.etla.org ( %s / src/%s ) | |
b55349fb | 1217 | bodytag := |
7fca93e2 VD |
1218 | head <=STYLESHEET;\n |
1219 | %s | |
1220 | STYLESHEET | |
1221 | main-title := rtfm / %s / src/%s\n | |
1222 | main-content <=MAIN_CONTENT;\n" rtfm-section file style rtfm-section file)) | |
1223 | ||
1224 | ;; the footer: | |
1225 | (defun rtfm-build-page-footer (file) "\nMAIN_CONTENT\n") | |
1226 | ||
1227 | (defun rtfm-fontify-buffer (section) | |
1228 | (interactive "s section[eg- emacs / p4-blame]: ") | |
1229 | (require 'htmlfontify) | |
1230 | (let ((hfy-page-header 'rtfm-build-page-header) | |
1231 | (hfy-page-footer 'rtfm-build-page-footer) | |
1232 | (rtfm-section section)) | |
1233 | (htmlfontify-buffer) | |
1234 | ) | |
1235 | ) | |
1236 | ||
b55349fb | 1237 | ;; Here's the function I actually call---it asks me for a section label, |
7fca93e2 | 1238 | ;; and source and destination directories, and then binds a couple of |
677d5c92 | 1239 | ;; customization variable in a let before calling htmlfontify: |
7fca93e2 VD |
1240 | (defun rtfm-build-source-docs (section srcdir destdir) |
1241 | (interactive | |
1242 | "s section[eg- emacs / p4-blame]:\nD source-dir: \nD output-dir: ") | |
1243 | (require 'htmlfontify) | |
1244 | (hfy-load-tags-cache srcdir) | |
1245 | (let ((hfy-page-header 'rtfm-build-page-header) | |
1246 | (hfy-page-footer 'rtfm-build-page-footer) | |
1247 | (rtfm-section section) | |
1248 | (hfy-index-file "index") | |
1249 | (auto-mode-alist (append auto-mode-alist | |
1250 | '(("dbi\\(shell\\|gtk\\)$" . cperl-mode) | |
1251 | ("\\.xpm$" . c-mode )))) | |
1252 | ) | |
1253 | (htmlfontify-run-etags srcdir) | |
1254 | (htmlfontify-copy-and-link-dir srcdir destdir ".src" ".html"))) | |
1255 | @end lisp | |
1256 | ||
677d5c92 PE |
1257 | @node Customization |
1258 | @chapter Customization | |
1259 | @cindex variables (customization) | |
7fca93e2 | 1260 | |
677d5c92 | 1261 | Htmlfontify provides the following variable and customization entries: |
7fca93e2 VD |
1262 | |
1263 | @table @code | |
1264 | @comment AUTOGENERATED BLOCK | |
1265 | ||
1266 | @item hfy-link-style-fun | |
1267 | @vindex hfy-link-style-fun | |
1268 | @anchor{hfy-link-style-fun} | |
1269 | ||
1270 | Set this to a function, which will be called with one argument | |
b55349fb | 1271 | (a @samp{@{ foo: bar; @dots{}@}} CSS style-string)---it should return a copy of |
7fca93e2 VD |
1272 | its argument, altered so as to make any changes you want made for text which |
1273 | is a hyperlink, in addition to being in the class to which that style would | |
1274 | normally be applied. | |
1275 | ||
1276 | @item hfy-html-quote-regex | |
1277 | @vindex hfy-html-quote-regex | |
1278 | @anchor{hfy-html-quote-regex} | |
1279 | ||
353ca646 | 1280 | @c FIXME: the cross-reference below looks ugly |
7fca93e2 | 1281 | Regex to match (with a single back-reference per match) strings in HTML |
b55349fb | 1282 | which should be quoted with @ref{hfy-html-quote} |
7fca93e2 VD |
1283 | (and @pxref{hfy-html-quote-map}) to make them safe. |
1284 | ||
1285 | @item hfy-page-footer | |
1286 | @vindex hfy-page-footer | |
1287 | @anchor{hfy-page-footer} | |
1288 | ||
1289 | As @ref{hfy-page-header}, but generates the output footer | |
1290 | (and takes only 1 argument, the filename). | |
1291 | ||
1292 | @item hfy-display-class | |
1293 | @vindex hfy-display-class | |
1294 | @anchor{hfy-display-class} | |
1295 | ||
1296 | Display class to use to determine which display class to use when | |
b55349fb GM |
1297 | calculating a face's attributes. This is useful when, for example, you |
1298 | are running Emacs on a tty or in batch mode, and want Htmlfontify to have | |
7fca93e2 VD |
1299 | access to the face spec you would use if you were connected to an X display. |
1300 | ||
1301 | Some valid class specification elements are: | |
1302 | ||
1303 | @lisp | |
1304 | '(class color) | |
1305 | '(class grayscale) | |
1306 | '(background dark) | |
1307 | '(background light) | |
1308 | '(type x-toolkit) | |
1309 | '(type tty) | |
1310 | '(type motif) | |
1311 | '(type lucid) | |
1312 | @end lisp | |
1313 | ||
1314 | Multiple values for a tag may be combined, to indicate that any one or more | |
1315 | of these values in the specification key constitutes a match, eg: | |
1316 | ||
1317 | '((class color grayscale) (type tty)) would match any of: | |
1318 | @lisp | |
1319 | '((class color)) | |
1320 | '((class grayscale)) | |
1321 | '((class color grayscale))) | |
1322 | '((class color foo)) | |
1323 | '((type tty)) | |
1324 | '((type tty) (class color)) | |
1325 | @end lisp | |
1326 | and so on. | |
1327 | ||
1328 | @item hfy-page-header | |
1329 | @vindex hfy-page-header | |
1330 | @anchor{hfy-page-header} | |
1331 | ||
1332 | Function called with two arguments (the filename relative to the top | |
1333 | level source directory being etag'd and fontified), and a string containing | |
b55349fb GM |
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 | |
1336 | the source file. | |
7fca93e2 VD |
1337 | |
1338 | See also: @ref{hfy-page-footer} | |
1339 | ||
1340 | @item hfy-src-doc-link-style | |
1341 | @vindex hfy-src-doc-link-style | |
1342 | @anchor{hfy-src-doc-link-style} | |
1343 | ||
b55349fb | 1344 | String to add to the @samp{<style> a} variant of an Htmlfontify CSS class. |
7fca93e2 | 1345 | |
7fca93e2 VD |
1346 | @item hfy-split-index |
1347 | @vindex hfy-split-index | |
1348 | @anchor{hfy-split-index} | |
1349 | ||
1350 | Whether or not to split the index @ref{hfy-index-file} alphabetically | |
b55349fb | 1351 | on the first letter of each tag. Useful when the index would otherwise |
7fca93e2 VD |
1352 | be large and take a long time to render or be difficult to navigate. |
1353 | ||
1354 | @item hfy-find-cmd | |
1355 | @vindex hfy-find-cmd | |
1356 | @anchor{hfy-find-cmd} | |
1357 | ||
1358 | ``find'' command used to harvest a list of files to attempt to fontify. | |
1359 | ||
1360 | @item hfy-extn | |
1361 | @vindex hfy-extn | |
1362 | @anchor{hfy-extn} | |
1363 | ||
241de290 | 1364 | File extension used for output files. |
7fca93e2 VD |
1365 | |
1366 | @item hfy-default-face-def | |
1367 | @vindex hfy-default-face-def | |
1368 | @anchor{hfy-default-face-def} | |
1369 | ||
b55349fb GM |
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}). | |
7fca93e2 | 1374 | |
677d5c92 | 1375 | For example, I customize this to: |
7fca93e2 VD |
1376 | |
1377 | @lisp | |
1378 | ((t :background "black" :foreground "white" :family "misc-fixed")) | |
1379 | @end lisp | |
1380 | ||
1381 | @item hfy-init-kludge-hooks | |
1382 | @vindex hfy-init-kludge-hooks | |
1383 | @anchor{hfy-init-kludge-hooks} | |
1384 | ||
1385 | List of functions to call when starting htmlfontify-buffer to do any | |
677d5c92 | 1386 | kludging necessary to get highlighting modes to behave as you want, even |
7fca93e2 VD |
1387 | when not running under a window system. |
1388 | ||
1389 | @item hfy-shell-file-name | |
1390 | @vindex hfy-shell-file-name | |
1391 | @anchor{hfy-shell-file-name} | |
1392 | ||
b55349fb GM |
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 | |
7fca93e2 VD |
1396 | @ref{hfy-etags-cmd-alist} for details. |
1397 | ||
1398 | @item hfy-optimisations | |
1399 | @vindex hfy-optimisations | |
1400 | @anchor{hfy-optimisations} | |
1401 | ||
677d5c92 | 1402 | Optimizations to turn on. So far, the following have been implemented: |
7fca93e2 VD |
1403 | |
1404 | @table @option | |
1405 | @item merge-adjacent-tags | |
b55349fb | 1406 | If two (or more) span tags are adjacent, identical and separated by nothing |
7fca93e2 VD |
1407 | more than whitespace, they will be merged into one span. |
1408 | ||
1409 | @item zap-comment-links | |
1410 | Suppress hyperlinking of tags found in comments. | |
1411 | ||
1412 | @item zap-string-links | |
1413 | Suppress hyperlinking of tags found in strings. | |
1414 | ||
1415 | @item div-wrapper | |
b55349fb GM |
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.) | |
7fca93e2 VD |
1419 | |
1420 | @item keep-overlays | |
b55349fb GM |
1421 | Preserve overlay highlighting (c.f. @code{ediff} or @code{goo-font-lock}) |
1422 | as well as basic faces. Can result in extremely verbose highlighting | |
7fca93e2 VD |
1423 | if there are many overlays (as is the case with @code{goo-font-lock}). |
1424 | ||
1425 | @end table | |
1426 | ||
1427 | And the following are planned but not yet available: | |
1428 | ||
1429 | @table @option | |
1430 | @item kill-context-leak | |
1431 | Suppress hyperlinking between files highlighted by different modes. | |
1432 | ||
1433 | @end table | |
1434 | ||
677d5c92 PE |
1435 | Note: like compiler optimizations, these optimize the @emph{output} of |
1436 | the code, | |
7fca93e2 | 1437 | not the processing of the source itself, and are therefore likely to slow |
b55349fb | 1438 | Htmlfontify down, at least a little. Except for skip-refontification, |
7fca93e2 VD |
1439 | which can never slow you down, but may result in incomplete fontification. |
1440 | ||
1441 | @item hfy-src-doc-link-unstyle | |
1442 | @vindex hfy-src-doc-link-unstyle | |
1443 | @anchor{hfy-src-doc-link-unstyle} | |
1444 | ||
241de290 | 1445 | Regex to remove from the @samp{<style> a} variant of an Htmlfontify CSS class. |
7fca93e2 VD |
1446 | |
1447 | @item hfy-link-extn | |
1448 | @vindex hfy-link-extn | |
1449 | @anchor{hfy-link-extn} | |
1450 | ||
b55349fb | 1451 | File extension used for href links---useful where the Htmlfontify |
677d5c92 | 1452 | output files are going to be processed again, with a resulting change |
b55349fb | 1453 | in file extension. If @code{nil}, then any code using this should fall back |
7fca93e2 VD |
1454 | to @ref{hfy-extn}. |
1455 | ||
1456 | @item hfy-istext-command | |
1457 | @vindex hfy-istext-command | |
1458 | @anchor{hfy-istext-command} | |
1459 | ||
1460 | Command to run with the name of a file, to see whether it is a text file | |
b55349fb GM |
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. | |
7fca93e2 VD |
1463 | |
1464 | @item hfy-etags-cmd-alist | |
1465 | @vindex hfy-etags-cmd-alist | |
1466 | @anchor{hfy-etags-cmd-alist} | |
1467 | ||
1468 | An alist of possible shell commands that will generate etags output that | |
b55349fb | 1469 | Htmlfontify can use. @samp{%s} will be replaced by @ref{hfy-etags-bin}. |
7fca93e2 VD |
1470 | |
1471 | @item hfy-etags-bin | |
1472 | @vindex hfy-etags-bin | |
1473 | @anchor{hfy-etags-bin} | |
1474 | ||
b55349fb | 1475 | The location of the etags binary (we begin by assuming it's in your path). |
7fca93e2 VD |
1476 | |
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}. | |
1479 | ||
b55349fb GM |
1480 | [As of version 0.17, this requirement has been removed: it should |
1481 | all just work(tm).] | |
7fca93e2 VD |
1482 | |
1483 | @item hfy-etags-cmd | |
1484 | @vindex hfy-etags-cmd | |
1485 | @anchor{hfy-etags-cmd} | |
1486 | ||
1487 | An etags shell command to run in the source directory to generate a tags | |
b55349fb | 1488 | file for the whole source tree from there on down. The command should emit |
7fca93e2 VD |
1489 | the etags output on standard output. |
1490 | ||
b55349fb GM |
1491 | Two canned commands are provided---they drive Emacs's etags and |
1492 | exuberant-ctags's etags respectively. | |
7fca93e2 VD |
1493 | |
1494 | @item hfy-etag-regex | |
1495 | @vindex hfy-etag-regex | |
1496 | @anchor{hfy-etag-regex} | |
1497 | ||
1498 | Regex used to parse an etags entry: must have 3 subexps, corresponding, | |
1499 | in order, to: | |
1500 | ||
1501 | @enumerate | |
db671917 AS |
1502 | @item |
1503 | The tag | |
1504 | @item | |
1505 | The line | |
1506 | @item | |
1507 | The character (point) at which the tag occurs | |
7fca93e2 VD |
1508 | @end enumerate |
1509 | ||
1510 | @item hfy-index-file | |
1511 | @vindex hfy-index-file | |
1512 | @anchor{hfy-index-file} | |
1513 | ||
b55349fb | 1514 | Name (sans extension) of the index file produced during |
7fca93e2 VD |
1515 | fontification-and-hyperlinking. |
1516 | ||
1517 | @item hfy-instance-file | |
1518 | @vindex hfy-instance-file | |
1519 | @anchor{hfy-instance-file} | |
1520 | ||
1521 | Name (sans extension) of the tag usage index file produced during | |
1522 | fontification-and-hyperlinking. | |
1523 | ||
1524 | @item hfy-html-quote-map | |
1525 | @vindex hfy-html-quote-map | |
1526 | @anchor{hfy-html-quote-map} | |
1527 | ||
b55349fb | 1528 | An alist of character -> entity mappings used to make the text html-safe. |
7fca93e2 VD |
1529 | |
1530 | @comment /AUTOGENERATED BLOCK | |
1531 | @end table | |
1532 | ||
b55349fb | 1533 | @node Requirements |
7fca93e2 VD |
1534 | @chapter Requirements |
1535 | @cindex Requirements, Prerequisites | |
1536 | ||
1537 | Htmlfontify has a couple of external requirements: | |
1538 | ||
1539 | @itemize @bullet | |
1540 | ||
1541 | @item | |
1542 | GNU Emacs 20.7+ or 21.1+ | |
1543 | ||
b55349fb GM |
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 | |
7fca93e2 VD |
1548 | money are always welcome. |
1549 | ||
b55349fb GM |
1550 | @item |
1551 | A copy of etags (exuberant-ctags or GNU etags). Htmlfontify attempts | |
677d5c92 | 1552 | to autodetect the version you have and customize itself accordingly, |
b55349fb | 1553 | but you should be able to override this. |
7fca93e2 | 1554 | |
677d5c92 | 1555 | See: @ref{Customization} |
7fca93e2 VD |
1556 | |
1557 | @item | |
b55349fb | 1558 | A copy of find (e.g., GNU find) that provides the @code{-path} predicate. |
7fca93e2 VD |
1559 | |
1560 | You may be able to work around this with a suitable clever shell | |
677d5c92 | 1561 | command and the customization entry: @ref{hfy-find-cmd} |
7fca93e2 | 1562 | |
b55349fb GM |
1563 | @item |
1564 | A copy of sed (e.g., GNU sed). | |
7fca93e2 VD |
1565 | |
1566 | @item | |
1567 | A copy of the @code{file} command. | |
1568 | ||
1569 | @end itemize | |
1570 | ||
b55349fb GM |
1571 | @node GNU Free Documentation License |
1572 | @appendix GNU Free Documentation License | |
1573 | @include doclicense.texi | |
1574 | ||
1575 | @node Index | |
7fca93e2 VD |
1576 | @unnumbered Index |
1577 | ||
1578 | @table @var | |
1579 | @item Concepts | |
1580 | @printindex cp | |
1581 | ||
1582 | @item Functions | |
1583 | @printindex fn | |
1584 | ||
677d5c92 | 1585 | @item Variables & Customization |
7fca93e2 VD |
1586 | @printindex vr |
1587 | ||
1588 | @end table | |
1589 | ||
7fca93e2 | 1590 | @setchapternewpage odd |
7fca93e2 | 1591 | @bye |