2 @c documentation for htmlfontify
3 @c written by Vivek Dasmohapatra
5 @comment %**start of header (This is for running Texinfo on a region.)
7 @setfilename htmlfontify.info
8 @settitle Htmlfontify User Manual
12 * Htmlfontify: (htmlfontify). A source code -> linked html + css transformer
16 @comment %**end of header (This is for running Texinfo on a region.)
20 This file documents Htmlfontify, a source code -> crosslinked + formatted +
21 syntax colourised html transformer.
23 Copyright (c) 2002,2003 Vivek Dasmohapatra <vivek@@etla.org>
25 Permission is granted to copy, distribute and/or modify this
26 document under the terms of the GNU Free Documentation Licence,
27 Version 1.1 or any later version published by the Free Software
28 Foundation; with no Invariant Sections, no Front-Cover Texts and
29 no Back-Cover Texts. A copy of the licence is included in the
30 section entitled "GNU Free Documentation Licence".
35 @title Htmlfontify User Manual
37 @subtitle Htmlfontify version 0.20
41 @author Vivek Dasmohapatra
44 @vskip 0pt plus 1filll
46 Copyright @copyright{} 2002 Vivek Dasmohapatra <vivek@@etla.org>
48 Permission is granted to copy, distribute and/or modify this document
49 under the terms of the GNU Free Documentation Licence, Version 1.1 or
50 any later version published by the Free Software Foundation; with no
51 Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A
52 copy of the licence is included in the section entitled "GNU Free
53 Documentation Licence".
58 @node Top, Introduction, (dir), (dir)
61 * Introduction:: About Htmlfontify.
62 * Usage & Examples:: How to use Htmlfontify.
63 * Customisation:: Fine tuning Htmlfontify's behaviour.
64 * Requirements:: External programs used by Htmlfontify.
65 * Index:: Index of Contents.
66 * COPYING:: The GNU Free Documentation Licence.
69 @node Introduction, Usage & Examples, Top, Top
73 Htmlfontify provides a means of converting individual emacs buffers,
74 source files, or entire source trees to html, preserving formatting
75 and emacs colourisation / syntax highlighting as much as possible
76 through careful application of CSS stylesheets and html tags.
78 It can also turn instances of functions, methods and ( for some
79 languages ) variables and other constructs and items into links
80 to their definitions, and create an index file ( or files ) of
81 all such symbols, also linked to their points of definition.
83 Htmlfontify also provides several customisation items, which should
84 allow it to mesh more-or-less seamlessly with various templating or
85 publishing systems ( in the event, for instance, that you don't want
86 to produce the html pages directly ).
88 @node Usage & Examples, Customisation, Introduction, Top
89 @chapter Usage & Examples
90 @cindex Usage & Examples
92 Htmlfontify can be used both interactively and as part of another
93 elisp function. If you're running it in emacs21 ( its native land,
94 it were ), it will also run when attached to a terminal ( ie w/o X )
95 or even when in batch mode.
98 * Interactive:: Using htmlfontify interactively.
99 * Non-interactive:: Using htmlfontify from elisp.
100 * Variables:: Variables (other than customisation entries).
101 * Data Structures:: Important Data Structures.
102 * Examples:: Example(s) of htmlfontify in use.
105 @node Interactive, Non-interactive, , Usage & Examples
108 @cindex functions (interactive)
110 Htmlfontify provides the following interactive functions:
113 @item htmlfontify-buffer
114 @findex htmlfontify-buffer
115 @anchor{htmlfontify-buffer}
119 (htmlfontify-buffer &optional @var{srcdir} @var{file})
122 Create a new buffer, named for the current buffer + a .html extension,
123 containing an inline css-stylesheet and formatted css-markup html that
124 reproduces the look of the current emacs buffer as closely as possible.
126 ``Dangerous'' characters in the existing buffer are turned into html
127 entities, so you should even be able to do html-within-html fontified
130 You should, however, note that random control or eight-bit characters
131 such as ^L (\x0c) or ยค (\xa4) won't get mapped yet.
133 If the @var{srcdir} and @var{file} arguments are set, lookup etags
134 derived entries in the @ref{hfy-tags-cache} and add html anchors
135 and hyperlinks as appropriate.
137 @item htmlfontify-run-etags
138 @findex htmlfontify-run-etags
139 @anchor{htmlfontify-run-etags}
143 (htmlfontify-run-etags @var{srcdir})
146 Load the etags cache for @var{srcdir}. See @ref{hfy-load-tags-cache}.
148 @item htmlfontify-copy-and-link-dir
149 @findex htmlfontify-copy-and-link-dir
150 @anchor{htmlfontify-copy-and-link-dir}
154 (htmlfontify-copy-and-link-dir @var{srcdir} @var{dstdir} &optional @var{f-ext} @var{l-ext})
157 Trawl @var{srcdir} and write fontified-and-hyperlinked output in
158 @var{dstdir} @var{f-ext} and @var{l-ext} specify values for
159 @ref{hfy-extn} and @ref{hfy-link-extn}.
161 You may also want to set @ref{hfy-page-header} and @ref{hfy-page-footer}.
163 @item htmlfontify-load-rgb-file
164 @findex htmlfontify-load-rgb-file
165 @anchor{htmlfontify-load-rgb-file}
169 (htmlfontify-load-rgb-file &optional @var{file})
172 Load an X11 style rgb.txt file (search @code{hfy-rgb-load-path} if
173 @var{file} is not specified).
175 Note that this is not necessary if all you want is the standard X11
176 (XFree86 4.1.0) colour name -> rgb triplet mapping, htmlfontify has
177 a copy built in, for use when it cannot contact an X server.
179 Loads the variable @code{hfy-rgb-txt-colour-map}, which is used by
180 @ref{hfy-fallback-colour-values}.
182 @item htmlfontify-unload-rgb-file
183 @findex htmlfontify-unload-rgb-file
184 @anchor{htmlfontify-unload-rgb-file}
188 (htmlfontify-unload-rgb-file)
191 Unload the currently loaded X11 style rgb.txt file ( if any ).
194 @node Non-interactive, Variables, Interactive, Usage & Examples
195 @section Non-interactive
196 @cindex Noninteractive
197 @cindex functions (noninteractive)
199 In addition to the aforementioned interactive methods, htmlfontify
200 provides the following non-interactive ones:
203 @comment AUTOGENERATED BLOCK
205 @item hfy-face-to-style
206 @findex hfy-face-to-style
207 @anchor{hfy-face-to-style}
211 (hfy-face-to-style @var{fn})
214 Take @var{fn}, a font or @code{defface} style font specification,
215 (as returned by @code{face-attr-construct} or @ref{hfy-face-attr-for-class})
216 and return a @ref{hfy-style-assoc}.
218 See also: @ref{hfy-face-to-style-i}, @ref{hfy-flatten-style}.
220 @item hfy-fallback-colour-values
221 @findex hfy-fallback-colour-values
222 @anchor{hfy-fallback-colour-values}
226 (hfy-fallback-colour-values @var{colour-string})
229 Use a fallback method for obtaining the rgb values for a colour.
230 If @ref{htmlfontify-load-rgb-file} has been called, it uses the
231 colour map specified, otherwise it uses htmlfontify's built in map.
233 @item hfy-combined-face-spec
234 @findex hfy-combined-face-spec
235 @anchor{hfy-combined-face-spec}
239 (hfy-combined-face-spec @var{face})
242 Return a @code{defface} style alist of possible specifications for
243 @var{face}, with any entries resulting from user customisation
244 (@code{custom-set-faces}) taking precedence.
246 See also: @ref{hfy-default-face-def}
249 @findex hfy-word-regex
250 @anchor{hfy-word-regex}
254 (hfy-word-regex @var{string})
257 Return a regex that matches @var{string} as the first @code{match-string},
258 with non word characters on either side (vaguely emulating the perl @code{\b}
261 @item hfy-force-fontification
262 @findex hfy-force-fontification
263 @anchor{hfy-force-fontification}
267 (hfy-force-fontification)
270 Emacs' fontification is designed for interactive use. As such, it sometimes
271 does things like deferring fontification until a section of the buffer is
272 exposed and rendered, or until emacs is idle for a while. Sometimes, in
273 non-interactive circumstances, or if it can't see X, it doesn't bother
274 with some of the harder stuff. While this is all great from the perspective
275 of a user waiting for emacs to load a 20000 line file and colourise it,
276 it's a pain from the point of view from non-interactive code. This function
277 lies, cheats, steals and generally bullies emacs into fontifying a buffer
278 from start to finish, with all the extra frills, whether it thinks it nneds
279 to or not. Oh yes: it operates on the current buffer.
281 @item hfy-link-style-string
282 @findex hfy-link-style-string
283 @anchor{hfy-link-style-string}
287 (hfy-link-style-string @var{style-string})
290 Replace the end of a css style declaration @var{style-string} with the contents
291 of the variable @ref{hfy-src-doc-link-style}, removing text matching the
292 regex @ref{hfy-src-doc-link-unstyle} first, if necessary.
295 @item hfy-prepare-index-i
296 @findex hfy-prepare-index-i
297 @anchor{hfy-prepare-index-i}
301 (hfy-prepare-index-i @var{srcdir} @var{dstdir} @var{filename} &optional @var{stub} @var{map})
304 Prepare a tags index buffer for @var{srcdir}.
305 @ref{hfy-tags-cache} must already have an entry for @var{srcdir} for
306 this to work. @ref{hfy-page-header}, @ref{hfy-page-footer},
307 @ref{hfy-link-extn} and @ref{hfy-extn} all play a part here.
309 If @var{stub} is set, prepare an (appropriately named) index buffer
310 specifically for entries beginning with @var{stub}.
312 If @var{map} is set, use that instead of @ref{hfy-tags-cache}.
314 @item hfy-compile-stylesheet
315 @findex hfy-compile-stylesheet
316 @anchor{hfy-compile-stylesheet}
320 (hfy-compile-stylesheet)
323 Trawl the current buffer, construct and return a @ref{hfy-sheet-assoc}.
327 @anchor{hfy-css-name}
331 (hfy-css-name @var{fn})
334 Strip some of the boring bits from a font-name and return a css style
335 name. If @var{fn} is a @code{defface} attribute list, either construct
336 a name for it, store it in the cache, and return it, or just fetch it
337 from the cache if it's already there.
339 @item hfy-make-directory
340 @findex hfy-make-directory
341 @anchor{hfy-make-directory}
345 (hfy-make-directory @var{dir})
348 Approx equivalent of mkdir -p @var{dir}
356 (hfy-triplet @var{colour})
359 Takes a colour name (string) and return a CSS rgb(R, G, B) triplet string.
360 Uses the definition of "white" to map the numbers to the 0-255 range, so
361 if you've redefined white, (esp if you've redefined it to have a triplet
362 member lower than that of the colour you are processing, strange things
365 @item hfy-default-footer
366 @findex hfy-default-footer
367 @anchor{hfy-default-footer}
371 (hfy-default-footer @var{file})
374 Default value for @ref{hfy-page-footer}
377 @findex hfy-list-files
378 @anchor{hfy-list-files}
382 (hfy-list-files @var{directory})
385 Return a list of files under @var{directory}.
386 Strips any leading "./" from each filename.
388 @item hfy-colour-vals
389 @findex hfy-colour-vals
390 @anchor{hfy-colour-vals}
394 (hfy-colour-vals @var{colour})
397 Where @var{colour} is a colour name or #XXXXXX style triplet, return a list of
398 3 (16 bit) rgb values for said colour. If a window system is unavailable,
399 calls @ref{hfy-fallback-colour-values}.
402 @findex hfy-href-stub
403 @anchor{hfy-href-stub}
407 (hfy-href-stub @var{this-file} @var{def-files} @var{tag})
410 Return an href stub for a tag href: if @var{def-files} (list of files
411 containing definitions for the tag in question) contains only one entry,
412 the href should link straight to that file. Otherwise, the link should
413 be to the index file.
415 We are not yet concerned with the file extensions/tag line number and
418 If @ref{hfy-split-index} is set, and the href wil be to an index file
419 rather than a source file, append a .X to @ref{hfy-index-file}, where
420 X is the uppercased first character of @var{tag}.
422 See also: @ref{hfy-relstub}, @ref{hfy-index-file}.
424 @item hfy-line-number
425 @findex hfy-line-number
426 @anchor{hfy-line-number}
433 Returns the line number of the point in the current buffer.
435 @item hfy-merge-adjacent-spans
436 @findex hfy-merge-adjacent-spans
437 @anchor{hfy-merge-adjacent-spans}
441 (hfy-merge-adjacent-spans @var{face-map})
444 Where @var{face-map} is a @ref{hfy-facemap-assoc} for the current buffer,
445 this function merges adjacent style blocks which are of the same value
446 and are separated by nothing more interesting than whitespace.
448 @code{<span class="foo">narf</span> <span class="foo">brain</span>}
450 (as interpreted from @var{face-map}) would become:
452 @code{<span class="foo">narf brain</span>}
454 Returns a modified copy of @var{face-map} (also a @ref{hfy-facemap-assoc}).
456 @item hfy-mark-tag-names
457 @findex hfy-mark-tag-names
458 @anchor{hfy-mark-tag-names}
462 (hfy-mark-tag-names @var{srcdir} @var{file})
465 Mark tags in @var{file} (lookup @var{srcdir} in @ref{hfy-tags-cache}) with the
466 'hfy-anchor property, with a value of "tag.line-number".
474 (hfy-weight @var{weight})
477 Derive a font-weight css specifier from an emacs weight spec symbol.
485 (hfy-size @var{height})
488 Derive a css font-size specifier from an emacs font :height attribute.
489 Does not cope with the case where height is a function to be applied to
490 the height of the underlying font.
492 @item hfy-default-header
493 @findex hfy-default-header
494 @anchor{hfy-default-header}
498 (hfy-default-header @var{file} @var{style})
501 Default value for @ref{hfy-page-header}
509 (hfy-family @var{family})
512 Derives a css font-family specifier from an emacs :family attribute.
514 @item hfy-mark-tag-hrefs
515 @findex hfy-mark-tag-hrefs
516 @anchor{hfy-mark-tag-hrefs}
520 (hfy-mark-tag-hrefs @var{srcdir} @var{file})
523 Mark href start points with the 'hfy-link prop (value: href string)
525 Mark href end points with the 'hfy-endl prop (value t)
527 Avoid overlapping links, and mark links in descending length of
528 tag name in order to prevent subtags from usurping supertags,
529 (eg "term" for "terminal").
540 Derive CSS border-* attributes from the emacs :box attribute.
542 @item hfy-box-to-style
543 @findex hfy-box-to-style
544 @anchor{hfy-box-to-style}
548 (hfy-box-to-style @var{spec})
551 Convert a complex :box emacs font attribute set to a list of CSS border-*
552 attributes. Don't call this directly - it is called by @ref{hfy-box}
555 @item hfy-html-enkludge-buffer
556 @findex hfy-html-enkludge-buffer
557 @anchor{hfy-html-enkludge-buffer}
561 (hfy-html-enkludge-buffer)
564 Mark dangerous ["<>] characters with the 'hfy-quoteme property.
566 See also @ref{hfy-html-dekludge-buffer}.
577 Generate and return an htmlfontify html output buffer for the current
578 buffer. May trample an existing buffer.
580 @item hfy-fontified-p
581 @findex hfy-fontified-p
582 @anchor{hfy-fontified-p}
589 @code{font-lock} doesn't like to say a buffer's been fontified when in
590 batch mode, but we want to know if we should fontify or raw copy, so in
591 batch mode we check for non-default face properties. Otherwise we test
592 @code{font-lock-mode} and @code{font-lock-fontified} for truth.
600 (hfy-lookup @var{face} @var{style})
603 Where @var{style} is a @ref{hfy-sheet-assoc} and @var{face} is an emacs face,
604 return the relevant @var{css} style name.
606 @item hfy-fontify-buffer
607 @findex hfy-fontify-buffer
608 @anchor{hfy-fontify-buffer}
612 (hfy-fontify-buffer &optional @var{srcdir} @var{file})
615 Implement the guts of @ref{htmlfontify-buffer}
623 (hfy-colour @var{colour})
626 Convert an emacs :foreground property to a CSS colour property.
628 @item hfy-flatten-style
629 @findex hfy-flatten-style
630 @anchor{hfy-flatten-style}
634 (hfy-flatten-style @var{style})
637 Take @var{style} (see @ref{hfy-face-to-style-i}, @ref{hfy-face-to-style})
638 and merge any multiple attributes appropriately. Currently only font-size is
639 merged down to a single occurrence - others may need special handling, but I
640 haven't encountered them yet. Returns a @ref{hfy-style-assoc}.
642 @item hfy-size-to-int
643 @findex hfy-size-to-int
644 @anchor{hfy-size-to-int}
648 (hfy-size-to-int @var{spec})
651 Convert @var{spec}, a css font-size specifier, back to an emacs :height attribute
652 value. Used while merging multiple font-size attributes.
654 @item hfy-sprintf-stylesheet
655 @findex hfy-sprintf-stylesheet
656 @anchor{hfy-sprintf-stylesheet}
660 (hfy-sprintf-stylesheet @var{css} @var{file})
663 Generates a header, via @ref{hfy-page-header}, for @var{file}, containing the
664 stylesheet derived from @var{css}, which is a @ref{hfy-sheet-assoc}. Returns a
665 string containing the same.
673 (hfy-relstub @var{file} &optional @var{start})
676 Return a "../" stub of the appropriate length for the current source
677 tree depth (as determined from @var{file}). iyswim.
679 @item hfy-compile-face-map
680 @findex hfy-compile-face-map
681 @anchor{hfy-compile-face-map}
685 (hfy-compile-face-map)
688 Compile and return a @ref{hfy-facemap-assoc} for the current buffer.
690 @item hfy-prepare-index
691 @findex hfy-prepare-index
692 @anchor{hfy-prepare-index}
696 (hfy-prepare-index @var{srcdir} @var{dstdir})
699 Return as list of index buffer(s), as determined by @ref{hfy-split-index}.
700 Uses @ref{hfy-prepare-index-i} to do this.
702 @item hfy-prepare-tag-map
703 @findex hfy-prepare-tag-map
704 @anchor{hfy-prepare-tag-map}
708 (hfy-prepare-tag-map @var{srcdir} @var{dstdir})
711 Prepare the counterpart(s) to the index buffer(s) - a list of buffers with
712 the same structure, but listing ( and linking to ) instances of tags ( as
713 opposed to their definitions ).
715 See also: @ref{hfy-prepare-index}, @ref{hfy-split-index}
717 @item hfy-subtract-maps
718 @findex hfy-subtract-maps
719 @anchor{hfy-subtract-maps}
723 (hfy-subtract-maps @var{srcdir})
726 Internal function - strips definitions of tags from the instance map.
727 See: @ref{hfy-tags-cache} and @ref{hfy-tags-rmap}
729 @item hfy-face-to-style-i
730 @findex hfy-face-to-style-i
731 @anchor{hfy-face-to-style-i}
735 (hfy-face-to-style-i @var{fn})
738 The guts of @ref{hfy-face-to-style}: @var{fn} should be a @code{defface}
739 font specification, as returned by @code{face-attr-construct} or
740 @ref{hfy-face-attr-for-class}. Note that this function does not get
741 font-sizes right if they are based on inherited modifiers (via the
742 :inherit) attribute, and any other modifiers that are cumulative if they
743 appear multiple times need to be merged by the user - @ref{hfy-flatten-style}
746 @item hfy-face-to-css
747 @findex hfy-face-to-css
748 @anchor{hfy-face-to-css}
752 (hfy-face-to-css @var{fn})
755 Take @var{fn}, a font or @code{defface} specification (cf.
756 @code{face-attr-construct}) and return a CSS style specification.
758 See also: @ref{hfy-face-to-style}
761 @findex hfy-html-quote
762 @anchor{hfy-html-quote}
766 (hfy-html-quote @var{char-string})
769 Map a string (usu. 1 char long) to an html safe string (entity) if need be.
772 @findex hfy-link-style
773 @anchor{hfy-link-style}
777 (hfy-link-style @var{style-string})
780 Convert the CSS style spec @var{style-string} to it's equivalent
783 See: @ref{hfy-link-style-fun}.
786 @findex hfy-p-to-face
787 @anchor{hfy-p-to-face}
791 (hfy-p-to-face @var{props})
794 Given @var{props}, a list of text-properties, return the value of the
795 face property, or nil.
797 @item hfy-box-to-border-assoc
798 @findex hfy-box-to-border-assoc
799 @anchor{hfy-box-to-border-assoc}
803 (hfy-box-to-border-assoc @var{spec})
806 Helper function for @ref{hfy-box-to-style}.
808 @item hfy-face-attr-for-class
809 @findex hfy-face-attr-for-class
810 @anchor{hfy-face-attr-for-class}
814 (hfy-face-attr-for-class @var{face} &optional @var{class})
817 Return the face attributes for @var{face}. If @var{class} is set, it
818 must be a @code{defface} alist key [see below]. Prior to version 0.18,
819 the first face specification returned by @ref{hfy-combined-face-spec}
820 which @emph{didn't} clash with @var{class} was returned. In versions
821 from 0.18 onwards, each font attribute list is scored, and the
822 non-conflicting list with the highest score is returned. ( A specification
823 with a class of @code{t} is considered to match any class you specify:
824 This matches emacs' behaviour when deciding on which face attributes to
825 use, to the best of my understanding ).
827 If @var{class} is nil, then you just get get whatever
828 @code{face-attr-construct} returns, ie the current specification in
829 effect for @var{face}.
831 See @ref{hfy-display-class} for details of valid values for @var{class}.
842 Find face in effect at point P. If overlays are to be considered
843 (see @ref{hfy-optimisations}) then this may return a @code{defface} style
844 list of face properties instead of a face symbol.
852 (hfy-bgcol @var{colour})
855 As per @ref{hfy-colour} but for background colours.
857 @item hfy-kludge-cperl-mode
858 @findex hfy-kludge-cperl-mode
859 @anchor{hfy-kludge-cperl-mode}
863 (hfy-kludge-cperl-mode)
866 cperl mode does its damndest not to do some of its fontification when not
867 in a windowing system - we try to trick it...
875 (hfy-href @var{this-file} @var{def-files} @var{tag} @var{tag-map})
878 Return a relative href to the tag in question, based on
880 @var{this-file} @ref{hfy-link-extn} @ref{hfy-extn} @var{def-files} @var{tag} and @var{tag-map}
882 @var{this-file} is the current source file
883 @var{def-files} is a list of file containing possible link endpoints for @var{tag}
884 @var{tag} is the @var{tag} in question
885 @var{tag-map} is the entry in @ref{hfy-tags-cache}.
896 Returns a best guess at a bourne compatible shell to use: If the current
897 shell doesn't look promising, fall back to @ref{hfy-shell-file-name}.
899 @item hfy-load-tags-cache
900 @findex hfy-load-tags-cache
901 @anchor{hfy-load-tags-cache}
905 (hfy-load-tags-cache @var{srcdir})
908 Run @ref{hfy-etags-cmd} on @var{srcdir}: load @ref{hfy-tags-cache} and @ref{hfy-tags-sortl}.
910 @item hfy-parse-tags-buffer
911 @findex hfy-parse-tags-buffer
912 @anchor{hfy-parse-tags-buffer}
916 (hfy-parse-tags-buffer @var{srcdir} @var{buffer})
919 Parse a @var{buffer} containing etags formatted output, loading the
920 @ref{hfy-tags-cache} and @ref{hfy-tags-sortl} entries for @var{srcdir}.
928 (hfy-interq @var{set-a} @var{set-b})
931 Return the intersection ( using @code{eq} ) of 2 lists.
939 (hfy-text-p @var{srcdir} @var{file})
942 Is @var{srcdir}/@var{file} text? Uses @ref{hfy-istext-command} to determine this.
950 (hfy-opt @var{symbol})
953 Is @ref{hfy-optimisations} member @var{symbol} set or not?
961 (hfy-dirname @var{file})
964 Return everything preceding the last "/" from a relative filename,
965 on the assumption that this will produce a relative directory name. Hardly
966 bombproof, but good enough in the context in which it is being used.
968 @item hfy-html-dekludge-buffer
969 @findex hfy-html-dekludge-buffer
970 @anchor{hfy-html-dekludge-buffer}
974 (hfy-html-dekludge-buffer)
977 Transform all dangerous characters marked with the 'hfy-quoteme property
978 using @ref{hfy-html-quote}
980 See also @ref{hfy-html-enkludge-buffer}.
982 @item hfy-copy-and-fontify-file
983 @findex hfy-copy-and-fontify-file
984 @anchor{hfy-copy-and-fontify-file}
988 (hfy-copy-and-fontify-file @var{srcdir} @var{dstdir} @var{file})
991 open @var{file} in @var{srcdir} - if fontified, write a fontified copy to @var{dstdir}
992 adding an extension of @ref{hfy-extn}. Fontification is actually done by
993 @ref{htmlfontify-buffer}. If the buffer is not fontified, just copy it.
1001 (hfy-decor @var{tag} @var{val})
1004 Derive CSS text-decoration specifiers from various emacs font attributes.
1012 (hfy-slant @var{slant})
1015 Derive a font-style css specifier from the emacs :slant attribute -
1016 CSS does not define the reverse-* styles, so just maps those to the
1019 @item hfy-tags-for-file
1020 @findex hfy-tags-for-file
1021 @anchor{hfy-tags-for-file}
1025 (hfy-tags-for-file @var{srcdir} @var{file})
1028 List of etags tags that have definitions in this @var{file}. Looks up
1029 the tags cache in @ref{hfy-tags-cache} using @var{srcdir} as the key.
1037 (hfy-width @var{width})
1040 Convert an emacs :width attribute to a CSS font-stretch attribute.
1042 @comment /AUTOGENERATED BLOCK
1045 @node Variables, Data Structures, Non-interactive, Usage & Examples
1049 Important variables which are not customisation items:
1053 @item hfy-tags-cache
1054 @vindex hfy-tags-cache
1055 @anchor{hfy-tags-cache}
1057 This is an alist of the form:
1060 (("/src/dir/0" . tag-hash0) ("/src/dir/1" tag-hash1) ...)
1063 Each tag hash entry then contains entries of the form:
1066 "tag_string" => (("file/name.ext" line char) ... )
1069 ie an alist mapping (relative) file paths to line and character offsets.
1071 See @ref{hfy-load-tags-cache}.
1074 @vindex hfy-tags-rmap
1075 @anchor{hfy-tags-rmap}
1077 @code{hfy-tags-rmap} is an alist of the form:
1080 (("/src/dir" . tag-rmap-hash))
1083 Where tag-rmap-hash has entries of the form:
1086 "tag_string" => ( "file/name.ext" line char )
1089 Unlike @ref{hfy-tags-cache} these are the locations of occurrences of
1090 tagged items, not the locations of their definitions.
1092 @item hfy-tags-sortl
1093 @vindex hfy-tags-sortl
1094 @anchor{hfy-tags-sortl}
1096 @code{hfy-tags-sortl} is an alist of the form:
1099 (("/src/dir" . (tag0 tag1 tag2)) ... )
1102 Where the tags are stored in descending order of length.
1104 See: @ref{hfy-load-tags-cache}.
1108 @node Data Structures, Examples, Variables, Usage & Examples
1109 @section Data Structures
1110 @cindex Data Structures
1112 Some of the (informal) data structures used in Htmlfontify are detailed here:
1116 @item hfy-style-assoc
1117 @cindex hfy-style-assoc
1118 @anchor{hfy-style-assoc}
1120 An assoc representing/describing an emacs face. Properties may be repeated,
1121 In which case later properties should be treated as if they were inherited
1122 from a 'parent' font. (For some properties, only the first encountered value
1123 is of any importance, for others the values might be cumulative, and for
1124 others they might be cumulative in a complex way).
1129 (hfy-face-to-style 'default) =>
1131 (("background" . "rgb(0, 0, 0)" )
1132 ("color" . "rgb(255, 255, 255)")
1133 ("font-style" . "normal" )
1134 ("font-weight" . "500" )
1135 ("font-stretch" . "normal" )
1136 ("font-family" . "misc-fixed" )
1137 ("font-size" . "13pt" )
1138 ("text-decoration" . "none" ))
1140 (hfy-face-to-style 'Info-title-3-face) =>
1142 (("font-weight" . "700" )
1143 ("font-family" . "helv" )
1144 ("font-size" . "120%" )
1145 ("text-decoration" . "none") )
1148 @item hfy-sheet-assoc
1149 @cindex hfy-sheet-assoc
1150 @anchor{hfy-sheet-assoc}
1152 An assoc with elements of the form (face-name style-name . stlye-string):
1153 The actual stylesheet for each page is derived from one of these.
1156 '((default "default" . "@{ background: black; color: white@}")
1157 (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}"))
1160 @item hfy-facemap-assoc
1161 @cindex hfy-facemap-assoc
1162 @anchor{hfy-facemap-assoc}
1164 An assoc of (point . @var{face-symbol}) or
1165 (point . @code{defface} attribute list) and (point . 'end) elements, in
1166 descending order of point value (ie from the file's end to its beginning).
1167 The map is in reverse order because inserting a <style> tag (or any other
1168 string) at @var{point} invalidates the map for all entries with a greater
1169 value of point. By traversing the map from greatest to least @var{point},
1170 we still 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
1176 (64744 . font-lock-comment-face)
1178 (64722 . font-lock-string-face)
1180 (64623 . font-lock-string-face)
1182 ;; big similar section elided. You get the idea.
1184 (5431 . (:inherit font-lock-keyword-face :background "7e7e7e"))
1186 (4285 . font-lock-constant-face)
1188 (4221 . font-lock-comment-face)
1190 (4197 . font-lock-constant-face)
1192 (1 . font-lock-comment-face))
1197 @node Examples, , Data Structures, Usage & Examples
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 ).
1206 (defvar rtfm-section nil)
1208 ;; constructs an appropriate header string to fit in with rtfm's
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
1213 #include <build/menu-dirlist|>\n
1214 html-css-url := /css/red+black.css
1215 title := rtfm.etla.org ( %s / src/%s )
1217 head <=STYLESHEET;\n
1220 main-title := rtfm / %s / src/%s\n
1221 main-content <=MAIN_CONTENT;\n" rtfm-section file style rtfm-section file))
1224 (defun rtfm-build-page-footer (file) "\nMAIN_CONTENT\n")
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)
1236 ;; here's the function I catually call - it asks me for a section label,
1237 ;; and source and destination directories, and then binds a couple of
1238 ;; customisation variable in a let before calling htmlfontify:
1239 (defun rtfm-build-source-docs (section srcdir destdir)
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 ))))
1252 (htmlfontify-run-etags srcdir)
1253 (htmlfontify-copy-and-link-dir srcdir destdir ".src" ".html")))
1256 @node Customisation, Requirements, Usage & Examples, Top
1257 @chapter Customisation
1258 @cindex variables (customisation)
1260 Htmlfontify provides the following variable and customisation entries:
1263 @comment AUTOGENERATED BLOCK
1265 @item hfy-link-style-fun
1266 @vindex hfy-link-style-fun
1267 @anchor{hfy-link-style-fun}
1269 Set this to a function, which will be called with one argument
1270 (a "@{ foo: bar; ...@}" css style-string) - it should return a copy of
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.
1275 @item hfy-html-quote-regex
1276 @vindex hfy-html-quote-regex
1277 @anchor{hfy-html-quote-regex}
1279 Regex to match (with a single back-reference per match) strings in HTML
1280 which should be quoted with @ref{hfy-html-quote}
1281 (and @pxref{hfy-html-quote-map}) to make them safe.
1283 @item hfy-page-footer
1284 @vindex hfy-page-footer
1285 @anchor{hfy-page-footer}
1287 As @ref{hfy-page-header}, but generates the output footer
1288 (and takes only 1 argument, the filename).
1290 @item hfy-display-class
1291 @vindex hfy-display-class
1292 @anchor{hfy-display-class}
1294 Display class to use to determine which display class to use when
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
1297 access to the face spec you would use if you were connected to an X display.
1299 Some valid class specification elements are:
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:
1315 '((class color grayscale) (type tty)) would match any of:
1318 '((class grayscale))
1319 '((class color grayscale)))
1320 '((class color foo))
1322 '((type tty) (class color))
1326 @item hfy-page-header
1327 @vindex hfy-page-header
1328 @anchor{hfy-page-header}
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
1332 the <style>...</style> text to embed in the document- the string returned will
1333 be used as the header for the htmlfontified version of the source file.
1335 See also: @ref{hfy-page-footer}
1337 @item hfy-src-doc-link-style
1338 @vindex hfy-src-doc-link-style
1339 @anchor{hfy-src-doc-link-style}
1341 String to add to the '<style> a' variant of an htmlfontify css class.
1343 @item hfy-fast-lock-save
1344 @vindex hfy-fast-lock-save
1345 @anchor{hfy-fast-lock-save}
1347 Minimum size of a buffer for cached fontification.
1348 This value is temporarily assigned to @code{fast-lock-minimum-size} during
1351 Only buffers more than this can have associated Font Lock cache files saved.
1353 If nil, means cache files are never created.
1355 If a list, each element should be a cons pair of the form
1356 @code{(@var{major-mode} . @var{size})}, where @var{major-mode}
1357 is a symbol or t (meaning the default). For example:
1362 (rmail-mode . 1048576))
1365 means that the minimum size is 25K for buffers in C or C++ modes, one megabyte
1366 for buffers in Rmail mode, and size is irrelevant (ie no saves) otherwise.
1368 @item hfy-split-index
1369 @vindex hfy-split-index
1370 @anchor{hfy-split-index}
1372 Whether or not to split the index @ref{hfy-index-file} alphabetically
1373 on the first letter of each tag. Useful when the index would otherwise
1374 be large and take a long time to render or be difficult to navigate.
1377 @vindex hfy-find-cmd
1378 @anchor{hfy-find-cmd}
1380 ``find'' command used to harvest a list of files to attempt to fontify.
1386 File extension used for output files
1388 @item hfy-default-face-def
1389 @vindex hfy-default-face-def
1390 @anchor{hfy-default-face-def}
1392 Fallback @code{defface} specification for the face @code{default}, used
1393 when @ref{hfy-display-class} has been set ( the normal htmlfontify way of
1394 extracting potentially non-current face information doesn't necessarily
1395 work for @code{default} ).
1397 Example: I customise this to:
1400 ((t :background "black" :foreground "white" :family "misc-fixed"))
1403 @item hfy-init-kludge-hooks
1404 @vindex hfy-init-kludge-hooks
1405 @anchor{hfy-init-kludge-hooks}
1407 List of functions to call when starting htmlfontify-buffer to do any
1408 kludging necessary to get highlighting modes to bahave as you want, even
1409 when not running under a window system.
1411 @item hfy-shell-file-name
1412 @vindex hfy-shell-file-name
1413 @anchor{hfy-shell-file-name}
1415 Should be set to a bourne compatible shell, which will be invoked
1416 for the more complex shell interactions needed by htmlfontify.
1417 Currently this is only required/used when using GNU etags, see
1418 @ref{hfy-etags-cmd-alist} for details.
1420 @item hfy-optimisations
1421 @vindex hfy-optimisations
1422 @anchor{hfy-optimisations}
1424 Optimisations to turn on: So far, the following have been implemented:
1427 @item merge-adjacent-tags
1428 If two (or more) span tags are adjacent, identical and separated by nothing
1429 more than whitespace, they will be merged into one span.
1431 @item zap-comment-links
1432 Suppress hyperlinking of tags found in comments.
1434 @item zap-string-links
1435 Suppress hyperlinking of tags found in strings.
1438 Add <div class="default"> </div> tags around the fontified body.
1439 ( some people like this because they cut and paste the html into
1440 a page with different colours than the fontified code. )
1443 preserve overlay highlighting (cf @code{ediff} or @code{goo-font-lock})
1444 as well as basic faces. Can result in extremely verbose highlighting
1445 if there are many overlays (as is the case with @code{goo-font-lock}).
1449 And the following are planned but not yet available:
1452 @item kill-context-leak
1453 Suppress hyperlinking between files highlighted by different modes.
1457 Note: like compiler optimisations, these optimise the _output_ of the code,
1458 not the processing of the source itself, and are therefore likely to slow
1459 htmlfontify down, at least a little. Except for skip-refontification,
1460 which can never slow you down, but may result in incomplete fontification.
1462 @item hfy-src-doc-link-unstyle
1463 @vindex hfy-src-doc-link-unstyle
1464 @anchor{hfy-src-doc-link-unstyle}
1466 Regex to remove from the <style> a variant of an htmlfontify css class.
1469 @vindex hfy-link-extn
1470 @anchor{hfy-link-extn}
1472 File extension used for href links - Useful where the htmlfontify
1473 output files are going to be processed again, with a rersulting change
1474 in file extension. If @code{nil}, then any code using this should fall back
1477 @item hfy-istext-command
1478 @vindex hfy-istext-command
1479 @anchor{hfy-istext-command}
1481 Command to run with the name of a file, to see whether it is a text file
1482 or not. The command should emit a string containing the word 'text' if
1483 the file is a text file, and a string not containing 'text' otherwise.
1485 @item hfy-etags-cmd-alist
1486 @vindex hfy-etags-cmd-alist
1487 @anchor{hfy-etags-cmd-alist}
1489 An alist of possible shell commands that will generate etags output that
1490 Htmlfontify can use. '%s' will be replaced by @ref{hfy-etags-bin}.
1493 @vindex hfy-etags-bin
1494 @anchor{hfy-etags-bin}
1496 The Location of the etags binary (we begin by assuming it's in your path).
1498 Note that if etags is not in your path, you will need to alter the shell
1499 commands in @ref{hfy-etags-cmd-alist}.
1501 [ As of version 0.17, this requirement has been removed: It should
1505 @vindex hfy-etags-cmd
1506 @anchor{hfy-etags-cmd}
1508 An etags shell command to run in the source directory to generate a tags
1509 file for the whole source tree from there on down. The command should emit
1510 the etags output on standard output.
1512 Two canned commands are provided - they drive emacs' etags and
1513 exuberant-ctags' etags respectively.
1515 @item hfy-etag-regex
1516 @vindex hfy-etag-regex
1517 @anchor{hfy-etag-regex}
1519 Regex used to parse an etags entry: must have 3 subexps, corresponding,
1525 The char (point) at which the tag occurs
1528 @item hfy-index-file
1529 @vindex hfy-index-file
1530 @anchor{hfy-index-file}
1532 Name (sans extension) of the index file produced during
1533 fontification-and-hyperlinking.
1535 @item hfy-instance-file
1536 @vindex hfy-instance-file
1537 @anchor{hfy-instance-file}
1539 Name (sans extension) of the tag usage index file produced during
1540 fontification-and-hyperlinking.
1542 @item hfy-html-quote-map
1543 @vindex hfy-html-quote-map
1544 @anchor{hfy-html-quote-map}
1546 An alist of char -> entity mappings used to make the text html-safe.
1548 @comment /AUTOGENERATED BLOCK
1551 @node Requirements, Index, Customisation, Top
1552 @chapter Requirements
1553 @cindex Requirements, Prerequisites
1555 Htmlfontify has a couple of external requirements:
1560 GNU Emacs 20.7+ or 21.1+
1562 Other versions may work - these have been used successfully by the
1563 author. If you intend to use Htmlfontify in batch mode, 21.1+ is
1564 pretty much required. The author does not know if XEmacs, NTemacs,
1565 or J.Random Emacs will run Htmlfontify, but reports/patches/bags of
1566 money are always welcome.
1569 A copy of etags ( exuberant-ctags or GNU etags ). Htmlfontify attempts
1570 to autodetect the version you have and customise itself accordingly,
1571 but you should be able to override this.
1573 See: @ref{Customisation}
1576 A copy of find (eg GNU find) that provides the @code{-path} predicate.
1578 You may be able to work around this with a suitable clever shell
1579 command and the customisation entry: @ref{hfy-find-cmd}
1582 A copy of sed (eg GNU sed).
1585 A copy of the @code{file} command.
1589 @node Index, , Requirements, Top
1599 @item Variables & Customisation
1604 @node COPYING, , , Top
1605 @appendix GNU Free Documentation Licence
1607 @cindex FDL, GNU Free Documentation License
1608 @center Version 1.1, March 2000
1611 Copyright @copyright{} 2000 Free Software Foundation, Inc.
1612 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
1614 Everyone is permitted to copy and distribute verbatim copies
1615 of this license document, but changing it is not allowed.
1622 The purpose of this License is to make a manual, textbook, or other
1623 written document @dfn{free} in the sense of freedom: to assure everyone
1624 the effective freedom to copy and redistribute it, with or without
1625 modifying it, either commercially or noncommercially. Secondarily,
1626 this License preserves for the author and publisher a way to get
1627 credit for their work, while not being considered responsible for
1628 modifications made by others.
1630 This License is a kind of ``copyleft'', which means that derivative
1631 works of the document must themselves be free in the same sense. It
1632 complements the GNU General Public License, which is a copyleft
1633 license designed for free software.
1635 We have designed this License in order to use it for manuals for free
1636 software, because free software needs free documentation: a free
1637 program should come with manuals providing the same freedoms that the
1638 software does. But this License is not limited to software manuals;
1639 it can be used for any textual work, regardless of subject matter or
1640 whether it is published as a printed book. We recommend this License
1641 principally for works whose purpose is instruction or reference.
1644 APPLICABILITY AND DEFINITIONS
1646 This License applies to any manual or other work that contains a
1647 notice placed by the copyright holder saying it can be distributed
1648 under the terms of this License. The ``Document'', below, refers to any
1649 such manual or work. Any member of the public is a licensee, and is
1650 addressed as ``you''.
1652 A ``Modified Version'' of the Document means any work containing the
1653 Document or a portion of it, either copied verbatim, or with
1654 modifications and/or translated into another language.
1656 A ``Secondary Section'' is a named appendix or a front-matter section of
1657 the Document that deals exclusively with the relationship of the
1658 publishers or authors of the Document to the Document's overall subject
1659 (or to related matters) and contains nothing that could fall directly
1660 within that overall subject. (For example, if the Document is in part a
1661 textbook of mathematics, a Secondary Section may not explain any
1662 mathematics.) The relationship could be a matter of historical
1663 connection with the subject or with related matters, or of legal,
1664 commercial, philosophical, ethical or political position regarding
1667 The ``Invariant Sections'' are certain Secondary Sections whose titles
1668 are designated, as being those of Invariant Sections, in the notice
1669 that says that the Document is released under this License.
1671 The ``Cover Texts'' are certain short passages of text that are listed,
1672 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1673 the Document is released under this License.
1675 A ``Transparent'' copy of the Document means a machine-readable copy,
1676 represented in a format whose specification is available to the
1677 general public, whose contents can be viewed and edited directly and
1678 straightforwardly with generic text editors or (for images composed of
1679 pixels) generic paint programs or (for drawings) some widely available
1680 drawing editor, and that is suitable for input to text formatters or
1681 for automatic translation to a variety of formats suitable for input
1682 to text formatters. A copy made in an otherwise Transparent file
1683 format whose markup has been designed to thwart or discourage
1684 subsequent modification by readers is not Transparent. A copy that is
1685 not ``Transparent'' is called ``Opaque''.
1687 Examples of suitable formats for Transparent copies include plain
1688 @sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
1689 @acronym{SGML} or @acronym{XML} using a publicly available
1690 @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
1691 for human modification. Opaque formats include PostScript,
1692 @acronym{PDF}, proprietary formats that can be read and edited only by
1693 proprietary word processors, @acronym{SGML} or @acronym{XML} for which
1694 the @acronym{DTD} and/or processing tools are not generally available,
1695 and the machine-generated @acronym{HTML} produced by some word
1696 processors for output purposes only.
1698 The ``Title Page'' means, for a printed book, the title page itself,
1699 plus such following pages as are needed to hold, legibly, the material
1700 this License requires to appear in the title page. For works in
1701 formats which do not have any title page as such, ``Title Page'' means
1702 the text near the most prominent appearance of the work's title,
1703 preceding the beginning of the body of the text.
1708 You may copy and distribute the Document in any medium, either
1709 commercially or noncommercially, provided that this License, the
1710 copyright notices, and the license notice saying this License applies
1711 to the Document are reproduced in all copies, and that you add no other
1712 conditions whatsoever to those of this License. You may not use
1713 technical measures to obstruct or control the reading or further
1714 copying of the copies you make or distribute. However, you may accept
1715 compensation in exchange for copies. If you distribute a large enough
1716 number of copies you must also follow the conditions in section 3.
1718 You may also lend copies, under the same conditions stated above, and
1719 you may publicly display copies.
1724 If you publish printed copies of the Document numbering more than 100,
1725 and the Document's license notice requires Cover Texts, you must enclose
1726 the copies in covers that carry, clearly and legibly, all these Cover
1727 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1728 the back cover. Both covers must also clearly and legibly identify
1729 you as the publisher of these copies. The front cover must present
1730 the full title with all words of the title equally prominent and
1731 visible. You may add other material on the covers in addition.
1732 Copying with changes limited to the covers, as long as they preserve
1733 the title of the Document and satisfy these conditions, can be treated
1734 as verbatim copying in other respects.
1736 If the required texts for either cover are too voluminous to fit
1737 legibly, you should put the first ones listed (as many as fit
1738 reasonably) on the actual cover, and continue the rest onto adjacent
1741 If you publish or distribute Opaque copies of the Document numbering
1742 more than 100, you must either include a machine-readable Transparent
1743 copy along with each Opaque copy, or state in or with each Opaque copy
1744 a publicly-accessible computer-network location containing a complete
1745 Transparent copy of the Document, free of added material, which the
1746 general network-using public has access to download anonymously at no
1747 charge using public-standard network protocols. If you use the latter
1748 option, you must take reasonably prudent steps, when you begin
1749 distribution of Opaque copies in quantity, to ensure that this
1750 Transparent copy will remain thus accessible at the stated location
1751 until at least one year after the last time you distribute an Opaque
1752 copy (directly or through your agents or retailers) of that edition to
1755 It is requested, but not required, that you contact the authors of the
1756 Document well before redistributing any large number of copies, to give
1757 them a chance to provide you with an updated version of the Document.
1762 You may copy and distribute a Modified Version of the Document under
1763 the conditions of sections 2 and 3 above, provided that you release
1764 the Modified Version under precisely this License, with the Modified
1765 Version filling the role of the Document, thus licensing distribution
1766 and modification of the Modified Version to whoever possesses a copy
1767 of it. In addition, you must do these things in the Modified Version:
1771 Use in the Title Page (and on the covers, if any) a title distinct
1772 from that of the Document, and from those of previous versions
1773 (which should, if there were any, be listed in the History section
1774 of the Document). You may use the same title as a previous version
1775 if the original publisher of that version gives permission.
1778 List on the Title Page, as authors, one or more persons or entities
1779 responsible for authorship of the modifications in the Modified
1780 Version, together with at least five of the principal authors of the
1781 Document (all of its principal authors, if it has less than five).
1784 State on the Title page the name of the publisher of the
1785 Modified Version, as the publisher.
1788 Preserve all the copyright notices of the Document.
1791 Add an appropriate copyright notice for your modifications
1792 adjacent to the other copyright notices.
1795 Include, immediately after the copyright notices, a license notice
1796 giving the public permission to use the Modified Version under the
1797 terms of this License, in the form shown in the Addendum below.
1800 Preserve in that license notice the full lists of Invariant Sections
1801 and required Cover Texts given in the Document's license notice.
1804 Include an unaltered copy of this License.
1807 Preserve the section entitled ``History'', and its title, and add to
1808 it an item stating at least the title, year, new authors, and
1809 publisher of the Modified Version as given on the Title Page. If
1810 there is no section entitled ``History'' in the Document, create one
1811 stating the title, year, authors, and publisher of the Document as
1812 given on its Title Page, then add an item describing the Modified
1813 Version as stated in the previous sentence.
1816 Preserve the network location, if any, given in the Document for
1817 public access to a Transparent copy of the Document, and likewise
1818 the network locations given in the Document for previous versions
1819 it was based on. These may be placed in the ``History'' section.
1820 You may omit a network location for a work that was published at
1821 least four years before the Document itself, or if the original
1822 publisher of the version it refers to gives permission.
1825 In any section entitled ``Acknowledgments'' or ``Dedications'',
1826 preserve the section's title, and preserve in the section all the
1827 substance and tone of each of the contributor acknowledgments
1828 and/or dedications given therein.
1831 Preserve all the Invariant Sections of the Document,
1832 unaltered in their text and in their titles. Section numbers
1833 or the equivalent are not considered part of the section titles.
1836 Delete any section entitled ``Endorsements''. Such a section
1837 may not be included in the Modified Version.
1840 Do not retitle any existing section as ``Endorsements''
1841 or to conflict in title with any Invariant Section.
1844 If the Modified Version includes new front-matter sections or
1845 appendices that qualify as Secondary Sections and contain no material
1846 copied from the Document, you may at your option designate some or all
1847 of these sections as invariant. To do this, add their titles to the
1848 list of Invariant Sections in the Modified Version's license notice.
1849 These titles must be distinct from any other section titles.
1851 You may add a section entitled ``Endorsements'', provided it contains
1852 nothing but endorsements of your Modified Version by various
1853 parties---for example, statements of peer review or that the text has
1854 been approved by an organization as the authoritative definition of a
1857 You may add a passage of up to five words as a Front-Cover Text, and a
1858 passage of up to 25 words as a Back-Cover Text, to the end of the list
1859 of Cover Texts in the Modified Version. Only one passage of
1860 Front-Cover Text and one of Back-Cover Text may be added by (or
1861 through arrangements made by) any one entity. If the Document already
1862 includes a cover text for the same cover, previously added by you or
1863 by arrangement made by the same entity you are acting on behalf of,
1864 you may not add another; but you may replace the old one, on explicit
1865 permission from the previous publisher that added the old one.
1867 The author(s) and publisher(s) of the Document do not by this License
1868 give permission to use their names for publicity for or to assert or
1869 imply endorsement of any Modified Version.
1874 You may combine the Document with other documents released under this
1875 License, under the terms defined in section 4 above for modified
1876 versions, provided that you include in the combination all of the
1877 Invariant Sections of all of the original documents, unmodified, and
1878 list them all as Invariant Sections of your combined work in its
1881 The combined work need only contain one copy of this License, and
1882 multiple identical Invariant Sections may be replaced with a single
1883 copy. If there are multiple Invariant Sections with the same name but
1884 different contents, make the title of each such section unique by
1885 adding at the end of it, in parentheses, the name of the original
1886 author or publisher of that section if known, or else a unique number.
1887 Make the same adjustment to the section titles in the list of
1888 Invariant Sections in the license notice of the combined work.
1890 In the combination, you must combine any sections entitled ``History''
1891 in the various original documents, forming one section entitled
1892 ``History''; likewise combine any sections entitled ``Acknowledgments'',
1893 and any sections entitled ``Dedications''. You must delete all sections
1894 entitled ``Endorsements.''
1897 COLLECTIONS OF DOCUMENTS
1899 You may make a collection consisting of the Document and other documents
1900 released under this License, and replace the individual copies of this
1901 License in the various documents with a single copy that is included in
1902 the collection, provided that you follow the rules of this License for
1903 verbatim copying of each of the documents in all other respects.
1905 You may extract a single document from such a collection, and distribute
1906 it individually under this License, provided you insert a copy of this
1907 License into the extracted document, and follow this License in all
1908 other respects regarding verbatim copying of that document.
1911 AGGREGATION WITH INDEPENDENT WORKS
1913 A compilation of the Document or its derivatives with other separate
1914 and independent documents or works, in or on a volume of a storage or
1915 distribution medium, does not as a whole count as a Modified Version
1916 of the Document, provided no compilation copyright is claimed for the
1917 compilation. Such a compilation is called an ``aggregate'', and this
1918 License does not apply to the other self-contained works thus compiled
1919 with the Document, on account of their being thus compiled, if they
1920 are not themselves derivative works of the Document.
1922 If the Cover Text requirement of section 3 is applicable to these
1923 copies of the Document, then if the Document is less than one quarter
1924 of the entire aggregate, the Document's Cover Texts may be placed on
1925 covers that surround only the Document within the aggregate.
1926 Otherwise they must appear on covers around the whole aggregate.
1931 Translation is considered a kind of modification, so you may
1932 distribute translations of the Document under the terms of section 4.
1933 Replacing Invariant Sections with translations requires special
1934 permission from their copyright holders, but you may include
1935 translations of some or all Invariant Sections in addition to the
1936 original versions of these Invariant Sections. You may include a
1937 translation of this License provided that you also include the
1938 original English version of this License. In case of a disagreement
1939 between the translation and the original English version of this
1940 License, the original English version will prevail.
1945 You may not copy, modify, sublicense, or distribute the Document except
1946 as expressly provided for under this License. Any other attempt to
1947 copy, modify, sublicense or distribute the Document is void, and will
1948 automatically terminate your rights under this License. However,
1949 parties who have received copies, or rights, from you under this
1950 License will not have their licenses terminated so long as such
1951 parties remain in full compliance.
1954 FUTURE REVISIONS OF THIS LICENSE
1956 The Free Software Foundation may publish new, revised versions
1957 of the GNU Free Documentation License from time to time. Such new
1958 versions will be similar in spirit to the present version, but may
1959 differ in detail to address new problems or concerns. See
1960 @uref{http://www.gnu.org/copyleft/}.
1962 Each version of the License is given a distinguishing version number.
1963 If the Document specifies that a particular numbered version of this
1964 License ``or any later version'' applies to it, you have the option of
1965 following the terms and conditions either of that specified version or
1966 of any later version that has been published (not as a draft) by the
1967 Free Software Foundation. If the Document does not specify a version
1968 number of this License, you may choose any version ever published (not
1969 as a draft) by the Free Software Foundation.
1973 @appendixsubsec ADDENDUM: How to use this License for your documents
1975 To use this License in a document you have written, include a copy of
1976 the License in the document and put the following copyright and
1977 license notices just after the title page:
1981 Copyright (C) @var{year} @var{your name}.
1982 Permission is granted to copy, distribute and/or modify this document
1983 under the terms of the GNU Free Documentation License, Version 1.1
1984 or any later version published by the Free Software Foundation;
1985 with the Invariant Sections being @var{list their titles}, with the
1986 Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
1987 A copy of the license is included in the section entitled ``GNU
1988 Free Documentation License''.
1992 If you have no Invariant Sections, write ``with no Invariant Sections''
1993 instead of saying which ones are invariant. If you have no
1994 Front-Cover Texts, write ``no Front-Cover Texts'' instead of
1995 ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
1997 If your document contains nontrivial examples of program code, we
1998 recommend releasing these examples in parallel under your choice of
1999 free software license, such as the GNU General Public License,
2000 to permit their use in free software.
2002 @setchapternewpage odd