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