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