[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111131: Import the htmlfontify ma
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111131: Import the htmlfontify manual |
|
Date: |
Fri, 04 Jan 2013 01:38:18 -0800 |
|
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 111131
author: Vivek Dasmohapatra <address@hidden>
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Fri 2013-01-04 01:38:18 -0800
message:
Import the htmlfontify manual
added:
doc/misc/htmlfontify.texi
modified:
doc/misc/ChangeLog
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2013-01-01 09:11:05 +0000
+++ b/doc/misc/ChangeLog 2013-01-04 09:38:18 +0000
@@ -1,3 +1,7 @@
+2013-01-04 Vivek Dasmohapatra <address@hidden>
+
+ * htmlfontify.texi: New file.
+
2012-12-22 Glenn Morris <address@hidden>
* viper.texi (Rudimentary Changes, Key Bindings, Key Bindings):
=== added file 'doc/misc/htmlfontify.texi'
--- a/doc/misc/htmlfontify.texi 1970-01-01 00:00:00 +0000
+++ b/doc/misc/htmlfontify.texi 2013-01-04 09:38:18 +0000
@@ -0,0 +1,2004 @@
+\input texinfo
address@hidden documentation for htmlfontify
address@hidden written by Vivek Dasmohapatra
+
address@hidden %**start of header (This is for running Texinfo on a region.)
+
address@hidden htmlfontify.info
address@hidden Htmlfontify User Manual
+
address@hidden Emacs
address@hidden
+* Htmlfontify: (htmlfontify). A source code -> linked html + css transformer
address@hidden direntry
+
address@hidden 2
address@hidden %**end of header (This is for running Texinfo on a region.)
+
address@hidden
+
+This file documents Htmlfontify, a source code -> crosslinked + formatted +
+syntax colourised html transformer.
+
+Copyright (c) 2002,2003 Vivek Dasmohapatra <vivek@@etla.org>
+
+Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation Licence,
+Version 1.1 or any later version published by the Free Software
+Foundation; with no Invariant Sections, no Front-Cover Texts and
+no Back-Cover Texts. A copy of the licence is included in the
+section entitled "GNU Free Documentation Licence".
+
address@hidden ifinfo
+
address@hidden
address@hidden Htmlfontify User Manual
address@hidden 4
address@hidden Htmlfontify version 0.20
address@hidden 1
address@hidden Jun 2002
address@hidden 5
address@hidden Vivek Dasmohapatra
address@hidden
+
address@hidden 0pt plus 1filll
address@hidden
+Copyright @copyright{} 2002 Vivek Dasmohapatra <vivek@@etla.org>
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation Licence, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A
+copy of the licence is included in the section entitled "GNU Free
+Documentation Licence".
+
address@hidden titlepage
address@hidden
+
address@hidden Top, Introduction, (dir), (dir)
+
address@hidden
+* Introduction:: About Htmlfontify.
+* Usage & Examples:: How to use Htmlfontify.
+* Customisation:: Fine tuning Htmlfontify's behaviour.
+* Requirements:: External programs used by Htmlfontify.
+* Index:: Index of Contents.
+* COPYING:: The GNU Free Documentation Licence.
address@hidden menu
+
address@hidden Introduction, Usage & Examples, Top, Top
address@hidden Introduction
address@hidden Introduction
+
+Htmlfontify provides a means of converting individual emacs buffers,
+source files, or entire source trees to html, preserving formatting
+and emacs colourisation / syntax highlighting as much as possible
+through careful application of CSS stylesheets and html tags.
+
+It can also turn instances of functions, methods and ( for some
+languages ) variables and other constructs and items into links
+to their definitions, and create an index file ( or files ) of
+all such symbols, also linked to their points of definition.
+
+Htmlfontify also provides several customisation items, which should
+allow it to mesh more-or-less seamlessly with various templating or
+publishing systems ( in the event, for instance, that you don't want
+to produce the html pages directly ).
+
address@hidden Usage & Examples, Customisation, Introduction, Top
address@hidden Usage & Examples
address@hidden Usage & Examples
+
+Htmlfontify can be used both interactively and as part of another
+elisp function. If you're running it in emacs21 ( its native land,
+it were ), it will also run when attached to a terminal ( ie w/o X )
+or even when in batch mode.
+
address@hidden
+* Interactive:: Using htmlfontify interactively.
+* Non-interactive:: Using htmlfontify from elisp.
+* Variables:: Variables (other than customisation entries).
+* Data Structures:: Important Data Structures.
+* Examples:: Example(s) of htmlfontify in use.
address@hidden menu
+
address@hidden Interactive, Non-interactive, , Usage & Examples
address@hidden Interactive
address@hidden Interactive
address@hidden functions (interactive)
+
+Htmlfontify provides the following interactive functions:
+
address@hidden @code
address@hidden htmlfontify-buffer
address@hidden htmlfontify-buffer
address@hidden
+
address@hidden
+
+(htmlfontify-buffer &optional @var{srcdir} @var{file})
address@hidden lisp
+
+Create a new buffer, named for the current buffer + a .html extension,
+containing an inline css-stylesheet and formatted css-markup html that
+reproduces the look of the current emacs buffer as closely as possible.
+
+``Dangerous'' characters in the existing buffer are turned into html
+entities, so you should even be able to do html-within-html fontified
+display.
+
+You should, however, note that random control or eight-bit characters
+such as ^L (\x0c) or ? (\xa4) won't get mapped yet.
+
+If the @var{srcdir} and @var{file} arguments are set, lookup etags
+derived entries in the @ref{hfy-tags-cache} and add html anchors
+and hyperlinks as appropriate.
+
address@hidden htmlfontify-run-etags
address@hidden htmlfontify-run-etags
address@hidden
+
address@hidden
+
+(htmlfontify-run-etags @var{srcdir})
address@hidden lisp
+
+Load the etags cache for @var{srcdir}. See @ref{hfy-load-tags-cache}.
+
address@hidden htmlfontify-copy-and-link-dir
address@hidden htmlfontify-copy-and-link-dir
address@hidden
+
address@hidden
+
+(htmlfontify-copy-and-link-dir @var{srcdir} @var{dstdir} &optional @var{f-ext}
@var{l-ext})
address@hidden lisp
+
+Trawl @var{srcdir} and write fontified-and-hyperlinked output in
address@hidden @var{f-ext} and @var{l-ext} specify values for
address@hidden and @ref{hfy-link-extn}.
+
+You may also want to set @ref{hfy-page-header} and @ref{hfy-page-footer}.
+
address@hidden htmlfontify-load-rgb-file
address@hidden htmlfontify-load-rgb-file
address@hidden
+
address@hidden
+
+(htmlfontify-load-rgb-file &optional @var{file})
address@hidden lisp
+
+Load an X11 style rgb.txt file (search @code{hfy-rgb-load-path} if
address@hidden is not specified).
+
+Note that this is not necessary if all you want is the standard X11
+(XFree86 4.1.0) colour name -> rgb triplet mapping, htmlfontify has
+a copy built in, for use when it cannot contact an X server.
+
+Loads the variable @code{hfy-rgb-txt-colour-map}, which is used by
address@hidden
+
address@hidden htmlfontify-unload-rgb-file
address@hidden htmlfontify-unload-rgb-file
address@hidden
+
address@hidden
+
+(htmlfontify-unload-rgb-file)
address@hidden lisp
+
+Unload the currently loaded X11 style rgb.txt file ( if any ).
address@hidden table
+
address@hidden Non-interactive, Variables, Interactive, Usage & Examples
address@hidden Non-interactive
address@hidden Noninteractive
address@hidden functions (noninteractive)
+
+In addition to the aforementioned interactive methods, htmlfontify
+provides the following non-interactive ones:
+
address@hidden @code
address@hidden AUTOGENERATED BLOCK
+
address@hidden hfy-face-to-style
address@hidden hfy-face-to-style
address@hidden
+
address@hidden
+
+(hfy-face-to-style @var{fn})
address@hidden lisp
+
+Take @var{fn}, a font or @code{defface} style font specification,
+(as returned by @code{face-attr-construct} or @ref{hfy-face-attr-for-class})
+and return a @ref{hfy-style-assoc}.
+
+See also: @ref{hfy-face-to-style-i}, @ref{hfy-flatten-style}.
+
address@hidden hfy-fallback-colour-values
address@hidden hfy-fallback-colour-values
address@hidden
+
address@hidden
+
+(hfy-fallback-colour-values @var{colour-string})
address@hidden lisp
+
+Use a fallback method for obtaining the rgb values for a colour.
+If @ref{htmlfontify-load-rgb-file} has been called, it uses the
+colour map specified, otherwise it uses htmlfontify's built in map.
+
address@hidden hfy-combined-face-spec
address@hidden hfy-combined-face-spec
address@hidden
+
address@hidden
+
+(hfy-combined-face-spec @var{face})
address@hidden lisp
+
+Return a @code{defface} style alist of possible specifications for
address@hidden, with any entries resulting from user customisation
+(@code{custom-set-faces}) taking precedence.
+
+See also: @ref{hfy-default-face-def}
+
address@hidden hfy-word-regex
address@hidden hfy-word-regex
address@hidden
+
address@hidden
+
+(hfy-word-regex @var{string})
address@hidden lisp
+
+Return a regex that matches @var{string} as the first @code{match-string},
+with non word characters on either side (vaguely emulating the perl @code{\b}
+regex atom).
+
address@hidden hfy-force-fontification
address@hidden hfy-force-fontification
address@hidden
+
address@hidden
+
+(hfy-force-fontification)
address@hidden lisp
+
+Emacs' fontification is designed for interactive use. As such, it sometimes
+does things like deferring fontification until a section of the buffer is
+exposed and rendered, or until emacs is idle for a while. Sometimes, in
+non-interactive circumstances, or if it can't see X, it doesn't bother
+with some of the harder stuff. While this is all great from the perspective
+of a user waiting for emacs to load a 20000 line file and colourise it,
+it's a pain from the point of view from non-interactive code. This function
+lies, cheats, steals and generally bullies emacs into fontifying a buffer
+from start to finish, with all the extra frills, whether it thinks it nneds
+to or not. Oh yes: it operates on the current buffer.
+
address@hidden hfy-link-style-string
address@hidden hfy-link-style-string
address@hidden
+
address@hidden
+
+(hfy-link-style-string @var{style-string})
address@hidden lisp
+
+Replace the end of a css style declaration @var{style-string} with the contents
+of the variable @ref{hfy-src-doc-link-style}, removing text matching the
+regex @ref{hfy-src-doc-link-unstyle} first, if necessary.
+
+
address@hidden hfy-prepare-index-i
address@hidden hfy-prepare-index-i
address@hidden
+
address@hidden
+
+(hfy-prepare-index-i @var{srcdir} @var{dstdir} @var{filename} &optional
@var{stub} @var{map})
address@hidden lisp
+
+Prepare a tags index buffer for @var{srcdir}.
address@hidden must already have an entry for @var{srcdir} for
+this to work. @ref{hfy-page-header}, @ref{hfy-page-footer},
address@hidden and @ref{hfy-extn} all play a part here.
+
+If @var{stub} is set, prepare an (appropriately named) index buffer
+specifically for entries beginning with @var{stub}.
+
+If @var{map} is set, use that instead of @ref{hfy-tags-cache}.
+
address@hidden hfy-compile-stylesheet
address@hidden hfy-compile-stylesheet
address@hidden
+
address@hidden
+
+(hfy-compile-stylesheet)
address@hidden lisp
+
+Trawl the current buffer, construct and return a @ref{hfy-sheet-assoc}.
+
address@hidden hfy-css-name
address@hidden hfy-css-name
address@hidden
+
address@hidden
+
+(hfy-css-name @var{fn})
address@hidden lisp
+
+Strip some of the boring bits from a font-name and return a css style
+name. If @var{fn} is a @code{defface} attribute list, either construct
+a name for it, store it in the cache, and return it, or just fetch it
+from the cache if it's already there.
+
address@hidden hfy-make-directory
address@hidden hfy-make-directory
address@hidden
+
address@hidden
+
+(hfy-make-directory @var{dir})
address@hidden lisp
+
+Approx equivalent of mkdir -p @var{dir}
+
address@hidden hfy-triplet
address@hidden hfy-triplet
address@hidden
+
address@hidden
+
+(hfy-triplet @var{colour})
address@hidden lisp
+
+Takes a colour name (string) and return a CSS rgb(R, G, B) triplet string.
+Uses the definition of "white" to map the numbers to the 0-255 range, so
+if you've redefined white, (esp if you've redefined it to have a triplet
+member lower than that of the colour you are processing, strange things
+may happen).
+
address@hidden hfy-default-footer
address@hidden hfy-default-footer
address@hidden
+
address@hidden
+
+(hfy-default-footer @var{file})
address@hidden lisp
+
+Default value for @ref{hfy-page-footer}
+
address@hidden hfy-list-files
address@hidden hfy-list-files
address@hidden
+
address@hidden
+
+(hfy-list-files @var{directory})
address@hidden lisp
+
+Return a list of files under @var{directory}.
+Strips any leading "./" from each filename.
+
address@hidden hfy-colour-vals
address@hidden hfy-colour-vals
address@hidden
+
address@hidden
+
+(hfy-colour-vals @var{colour})
address@hidden lisp
+
+Where @var{colour} is a colour name or #XXXXXX style triplet, return a list of
+3 (16 bit) rgb values for said colour. If a window system is unavailable,
+calls @ref{hfy-fallback-colour-values}.
+
address@hidden hfy-href-stub
address@hidden hfy-href-stub
address@hidden
+
address@hidden
+
+(hfy-href-stub @var{this-file} @var{def-files} @var{tag})
address@hidden lisp
+
+Return an href stub for a tag href: if @var{def-files} (list of files
+containing definitions for the tag in question) contains only one entry,
+the href should link straight to that file. Otherwise, the link should
+be to the index file.
+
+We are not yet concerned with the file extensions/tag line number and
+so on at this point.
+
+If @ref{hfy-split-index} is set, and the href wil be to an index file
+rather than a source file, append a .X to @ref{hfy-index-file}, where
+X is the uppercased first character of @var{tag}.
+
+See also: @ref{hfy-relstub}, @ref{hfy-index-file}.
+
address@hidden hfy-line-number
address@hidden hfy-line-number
address@hidden
+
address@hidden
+
+(hfy-line-number)
address@hidden lisp
+
+Returns the line number of the point in the current buffer.
+
address@hidden hfy-merge-adjacent-spans
address@hidden hfy-merge-adjacent-spans
address@hidden
+
address@hidden
+
+(hfy-merge-adjacent-spans @var{face-map})
address@hidden lisp
+
+Where @var{face-map} is a @ref{hfy-facemap-assoc} for the current buffer,
+this function merges adjacent style blocks which are of the same value
+and are separated by nothing more interesting than whitespace.
+
address@hidden<span class="foo">narf</span> <span class="foo">brain</span>}
+
+(as interpreted from @var{face-map}) would become:
+
address@hidden<span class="foo">narf brain</span>}
+
+Returns a modified copy of @var{face-map} (also a @ref{hfy-facemap-assoc}).
+
address@hidden hfy-mark-tag-names
address@hidden hfy-mark-tag-names
address@hidden
+
address@hidden
+
+(hfy-mark-tag-names @var{srcdir} @var{file})
address@hidden lisp
+
+Mark tags in @var{file} (lookup @var{srcdir} in @ref{hfy-tags-cache}) with the
+'hfy-anchor property, with a value of "tag.line-number".
+
address@hidden hfy-weight
address@hidden hfy-weight
address@hidden
+
address@hidden
+
+(hfy-weight @var{weight})
address@hidden lisp
+
+Derive a font-weight css specifier from an emacs weight spec symbol.
+
address@hidden hfy-size
address@hidden hfy-size
address@hidden
+
address@hidden
+
+(hfy-size @var{height})
address@hidden lisp
+
+Derive a css font-size specifier from an emacs font :height attribute.
+Does not cope with the case where height is a function to be applied to
+the height of the underlying font.
+
address@hidden hfy-default-header
address@hidden hfy-default-header
address@hidden
+
address@hidden
+
+(hfy-default-header @var{file} @var{style})
address@hidden lisp
+
+Default value for @ref{hfy-page-header}
+
address@hidden hfy-family
address@hidden hfy-family
address@hidden
+
address@hidden
+
+(hfy-family @var{family})
address@hidden lisp
+
+Derives a css font-family specifier from an emacs :family attribute.
+
address@hidden hfy-mark-tag-hrefs
address@hidden hfy-mark-tag-hrefs
address@hidden
+
address@hidden
+
+(hfy-mark-tag-hrefs @var{srcdir} @var{file})
address@hidden lisp
+
+Mark href start points with the 'hfy-link prop (value: href string)
+
+Mark href end points with the 'hfy-endl prop (value t)
+
+Avoid overlapping links, and mark links in descending length of
+tag name in order to prevent subtags from usurping supertags,
+(eg "term" for "terminal").
+
address@hidden hfy-box
address@hidden hfy-box
address@hidden
+
address@hidden
+
+(hfy-box @var{box})
address@hidden lisp
+
+Derive CSS border-* attributes from the emacs :box attribute.
+
address@hidden hfy-box-to-style
address@hidden hfy-box-to-style
address@hidden
+
address@hidden
+
+(hfy-box-to-style @var{spec})
address@hidden lisp
+
+Convert a complex :box emacs font attribute set to a list of CSS border-*
+attributes. Don't call this directly - it is called by @ref{hfy-box}
+when necessary.
+
address@hidden hfy-html-enkludge-buffer
address@hidden hfy-html-enkludge-buffer
address@hidden
+
address@hidden
+
+(hfy-html-enkludge-buffer)
address@hidden lisp
+
+Mark dangerous ["<>] characters with the 'hfy-quoteme property.
+
+See also @ref{hfy-html-dekludge-buffer}.
+
address@hidden hfy-buffer
address@hidden hfy-buffer
address@hidden
+
address@hidden
+
+(hfy-buffer)
address@hidden lisp
+
+Generate and return an htmlfontify html output buffer for the current
+buffer. May trample an existing buffer.
+
address@hidden hfy-fontified-p
address@hidden hfy-fontified-p
address@hidden
+
address@hidden
+
+(hfy-fontified-p)
address@hidden lisp
+
address@hidden doesn't like to say a buffer's been fontified when in
+batch mode, but we want to know if we should fontify or raw copy, so in
+batch mode we check for non-default face properties. Otherwise we test
address@hidden and @code{font-lock-fontified} for truth.
+
address@hidden hfy-lookup
address@hidden hfy-lookup
address@hidden
+
address@hidden
+
+(hfy-lookup @var{face} @var{style})
address@hidden lisp
+
+Where @var{style} is a @ref{hfy-sheet-assoc} and @var{face} is an emacs face,
+return the relevant @var{css} style name.
+
address@hidden hfy-fontify-buffer
address@hidden hfy-fontify-buffer
address@hidden
+
address@hidden
+
+(hfy-fontify-buffer &optional @var{srcdir} @var{file})
address@hidden lisp
+
+Implement the guts of @ref{htmlfontify-buffer}
+
address@hidden hfy-colour
address@hidden hfy-colour
address@hidden
+
address@hidden
+
+(hfy-colour @var{colour})
address@hidden lisp
+
+Convert an emacs :foreground property to a CSS colour property.
+
address@hidden hfy-flatten-style
address@hidden hfy-flatten-style
address@hidden
+
address@hidden
+
+(hfy-flatten-style @var{style})
address@hidden lisp
+
+Take @var{style} (see @ref{hfy-face-to-style-i}, @ref{hfy-face-to-style})
+and merge any multiple attributes appropriately. Currently only font-size is
+merged down to a single occurrence - others may need special handling, but I
+haven't encountered them yet. Returns a @ref{hfy-style-assoc}.
+
address@hidden hfy-size-to-int
address@hidden hfy-size-to-int
address@hidden
+
address@hidden
+
+(hfy-size-to-int @var{spec})
address@hidden lisp
+
+Convert @var{spec}, a css font-size specifier, back to an emacs :height
attribute
+value. Used while merging multiple font-size attributes.
+
address@hidden hfy-sprintf-stylesheet
address@hidden hfy-sprintf-stylesheet
address@hidden
+
address@hidden
+
+(hfy-sprintf-stylesheet @var{css} @var{file})
address@hidden lisp
+
+Generates a header, via @ref{hfy-page-header}, for @var{file}, containing the
+stylesheet derived from @var{css}, which is a @ref{hfy-sheet-assoc}. Returns a
+string containing the same.
+
address@hidden hfy-relstub
address@hidden hfy-relstub
address@hidden
+
address@hidden
+
+(hfy-relstub @var{file} &optional @var{start})
address@hidden lisp
+
+Return a "../" stub of the appropriate length for the current source
+tree depth (as determined from @var{file}). iyswim.
+
address@hidden hfy-compile-face-map
address@hidden hfy-compile-face-map
address@hidden
+
address@hidden
+
+(hfy-compile-face-map)
address@hidden lisp
+
+Compile and return a @ref{hfy-facemap-assoc} for the current buffer.
+
address@hidden hfy-prepare-index
address@hidden hfy-prepare-index
address@hidden
+
address@hidden
+
+(hfy-prepare-index @var{srcdir} @var{dstdir})
address@hidden lisp
+
+Return as list of index buffer(s), as determined by @ref{hfy-split-index}.
+Uses @ref{hfy-prepare-index-i} to do this.
+
address@hidden hfy-prepare-tag-map
address@hidden hfy-prepare-tag-map
address@hidden
+
address@hidden
+
+(hfy-prepare-tag-map @var{srcdir} @var{dstdir})
address@hidden lisp
+
+Prepare the counterpart(s) to the index buffer(s) - a list of buffers with
+the same structure, but listing ( and linking to ) instances of tags ( as
+opposed to their definitions ).
+
+See also: @ref{hfy-prepare-index}, @ref{hfy-split-index}
+
address@hidden hfy-subtract-maps
address@hidden hfy-subtract-maps
address@hidden
+
address@hidden
+
+(hfy-subtract-maps @var{srcdir})
address@hidden lisp
+
+Internal function - strips definitions of tags from the instance map.
+See: @ref{hfy-tags-cache} and @ref{hfy-tags-rmap}
+
address@hidden hfy-face-to-style-i
address@hidden hfy-face-to-style-i
address@hidden
+
address@hidden
+
+(hfy-face-to-style-i @var{fn})
address@hidden lisp
+
+The guts of @ref{hfy-face-to-style}: @var{fn} should be a @code{defface}
+font specification, as returned by @code{face-attr-construct} or
address@hidden Note that this function does not get
+font-sizes right if they are based on inherited modifiers (via the
+:inherit) attribute, and any other modifiers that are cumulative if they
+appear multiple times need to be merged by the user - @ref{hfy-flatten-style}
+should do this.
+
address@hidden hfy-face-to-css
address@hidden hfy-face-to-css
address@hidden
+
address@hidden
+
+(hfy-face-to-css @var{fn})
address@hidden lisp
+
+Take @var{fn}, a font or @code{defface} specification (cf.
address@hidden) and return a CSS style specification.
+
+See also: @ref{hfy-face-to-style}
+
address@hidden hfy-html-quote
address@hidden hfy-html-quote
address@hidden
+
address@hidden
+
+(hfy-html-quote @var{char-string})
address@hidden lisp
+
+Map a string (usu. 1 char long) to an html safe string (entity) if need be.
+
address@hidden hfy-link-style
address@hidden hfy-link-style
address@hidden
+
address@hidden
+
+(hfy-link-style @var{style-string})
address@hidden lisp
+
+Convert the CSS style spec @var{style-string} to it's equivalent
+hyperlink style.
+
+See: @ref{hfy-link-style-fun}.
+
address@hidden hfy-p-to-face
address@hidden hfy-p-to-face
address@hidden
+
address@hidden
+
+(hfy-p-to-face @var{props})
address@hidden lisp
+
+Given @var{props}, a list of text-properties, return the value of the
+face property, or nil.
+
address@hidden hfy-box-to-border-assoc
address@hidden hfy-box-to-border-assoc
address@hidden
+
address@hidden
+
+(hfy-box-to-border-assoc @var{spec})
address@hidden lisp
+
+Helper function for @ref{hfy-box-to-style}.
+
address@hidden hfy-face-attr-for-class
address@hidden hfy-face-attr-for-class
address@hidden
+
address@hidden
+
+(hfy-face-attr-for-class @var{face} &optional @var{class})
address@hidden lisp
+
+Return the face attributes for @var{face}. If @var{class} is set, it
+must be a @code{defface} alist key [see below]. Prior to version 0.18,
+the first face specification returned by @ref{hfy-combined-face-spec}
+which @emph{didn't} clash with @var{class} was returned. In versions
+from 0.18 onwards, each font attribute list is scored, and the
+non-conflicting list with the highest score is returned. ( A specification
+with a class of @code{t} is considered to match any class you specify:
+This matches emacs' behaviour when deciding on which face attributes to
+use, to the best of my understanding ).
+
+If @var{class} is nil, then you just get get whatever
address@hidden returns, ie the current specification in
+effect for @var{face}.
+
+See @ref{hfy-display-class} for details of valid values for @var{class}.
+
address@hidden hfy-face-at
address@hidden hfy-face-at
address@hidden
+
address@hidden
+
+(hfy-face-at P)
address@hidden lisp
+
+Find face in effect at point P. If overlays are to be considered
+(see @ref{hfy-optimisations}) then this may return a @code{defface} style
+list of face properties instead of a face symbol.
+
address@hidden hfy-bgcol
address@hidden hfy-bgcol
address@hidden
+
address@hidden
+
+(hfy-bgcol @var{colour})
address@hidden lisp
+
+As per @ref{hfy-colour} but for background colours.
+
address@hidden hfy-kludge-cperl-mode
address@hidden hfy-kludge-cperl-mode
address@hidden
+
address@hidden
+
+(hfy-kludge-cperl-mode)
address@hidden lisp
+
+cperl mode does its damndest not to do some of its fontification when not
+in a windowing system - we try to trick it...
+
address@hidden hfy-href
address@hidden hfy-href
address@hidden
+
address@hidden
+
+(hfy-href @var{this-file} @var{def-files} @var{tag} @var{tag-map})
address@hidden lisp
+
+Return a relative href to the tag in question, based on
+
address@hidden @ref{hfy-link-extn} @ref{hfy-extn} @var{def-files} @var{tag} and
@var{tag-map}
+
address@hidden is the current source file
address@hidden is a list of file containing possible link endpoints for
@var{tag}
address@hidden is the @var{tag} in question
address@hidden is the entry in @ref{hfy-tags-cache}.
+
address@hidden hfy-shell
address@hidden hfy-shell
address@hidden
+
address@hidden
+
+(hfy-shell)
address@hidden lisp
+
+Returns a best guess at a bourne compatible shell to use: If the current
+shell doesn't look promising, fall back to @ref{hfy-shell-file-name}.
+
address@hidden hfy-load-tags-cache
address@hidden hfy-load-tags-cache
address@hidden
+
address@hidden
+
+(hfy-load-tags-cache @var{srcdir})
address@hidden lisp
+
+Run @ref{hfy-etags-cmd} on @var{srcdir}: load @ref{hfy-tags-cache} and
@ref{hfy-tags-sortl}.
+
address@hidden hfy-parse-tags-buffer
address@hidden hfy-parse-tags-buffer
address@hidden
+
address@hidden
+
+(hfy-parse-tags-buffer @var{srcdir} @var{buffer})
address@hidden lisp
+
+Parse a @var{buffer} containing etags formatted output, loading the
address@hidden and @ref{hfy-tags-sortl} entries for @var{srcdir}.
+
address@hidden hfy-interq
address@hidden hfy-interq
address@hidden
+
address@hidden
+
+(hfy-interq @var{set-a} @var{set-b})
address@hidden lisp
+
+Return the intersection ( using @code{eq} ) of 2 lists.
+
address@hidden hfy-text-p
address@hidden hfy-text-p
address@hidden
+
address@hidden
+
+(hfy-text-p @var{srcdir} @var{file})
address@hidden lisp
+
+Is @var{srcdir}/@var{file} text? Uses @ref{hfy-istext-command} to determine
this.
+
address@hidden hfy-opt
address@hidden hfy-opt
address@hidden
+
address@hidden
+
+(hfy-opt @var{symbol})
address@hidden lisp
+
+Is @ref{hfy-optimisations} member @var{symbol} set or not?
+
address@hidden hfy-dirname
address@hidden hfy-dirname
address@hidden
+
address@hidden
+
+(hfy-dirname @var{file})
address@hidden lisp
+
+Return everything preceding the last "/" from a relative filename,
+on the assumption that this will produce a relative directory name. Hardly
+bombproof, but good enough in the context in which it is being used.
+
address@hidden hfy-html-dekludge-buffer
address@hidden hfy-html-dekludge-buffer
address@hidden
+
address@hidden
+
+(hfy-html-dekludge-buffer)
address@hidden lisp
+
+Transform all dangerous characters marked with the 'hfy-quoteme property
+using @ref{hfy-html-quote}
+
+See also @ref{hfy-html-enkludge-buffer}.
+
address@hidden hfy-copy-and-fontify-file
address@hidden hfy-copy-and-fontify-file
address@hidden
+
address@hidden
+
+(hfy-copy-and-fontify-file @var{srcdir} @var{dstdir} @var{file})
address@hidden lisp
+
+open @var{file} in @var{srcdir} - if fontified, write a fontified copy to
@var{dstdir}
+adding an extension of @ref{hfy-extn}. Fontification is actually done by
address@hidden If the buffer is not fontified, just copy it.
+
address@hidden hfy-decor
address@hidden hfy-decor
address@hidden
+
address@hidden
+
+(hfy-decor @var{tag} @var{val})
address@hidden lisp
+
+Derive CSS text-decoration specifiers from various emacs font attributes.
+
address@hidden hfy-slant
address@hidden hfy-slant
address@hidden
+
address@hidden
+
+(hfy-slant @var{slant})
address@hidden lisp
+
+Derive a font-style css specifier from the emacs :slant attribute -
+CSS does not define the reverse-* styles, so just maps those to the
+regular specifiers.
+
address@hidden hfy-tags-for-file
address@hidden hfy-tags-for-file
address@hidden
+
address@hidden
+
+(hfy-tags-for-file @var{srcdir} @var{file})
address@hidden lisp
+
+List of etags tags that have definitions in this @var{file}. Looks up
+the tags cache in @ref{hfy-tags-cache} using @var{srcdir} as the key.
+
address@hidden hfy-width
address@hidden hfy-width
address@hidden
+
address@hidden
+
+(hfy-width @var{width})
address@hidden lisp
+
+Convert an emacs :width attribute to a CSS font-stretch attribute.
+
address@hidden /AUTOGENERATED BLOCK
address@hidden table
+
address@hidden Variables, Data Structures, Non-interactive, Usage & Examples
address@hidden Variables
address@hidden variables
+
+Important variables which are not customisation items:
+
address@hidden @code
+
address@hidden hfy-tags-cache
address@hidden hfy-tags-cache
address@hidden
+
+This is an alist of the form:
+
address@hidden
+(("/src/dir/0" . tag-hash0) ("/src/dir/1" tag-hash1) ...)
address@hidden example
+
+Each tag hash entry then contains entries of the form:
+
address@hidden
+"tag_string" => (("file/name.ext" line char) ... )
address@hidden example
+
+ie an alist mapping (relative) file paths to line and character offsets.
+
+See @ref{hfy-load-tags-cache}.
+
address@hidden hfy-tags-rmap
address@hidden hfy-tags-rmap
address@hidden
+
address@hidden is an alist of the form:
+
address@hidden
+(("/src/dir" . tag-rmap-hash))
address@hidden lisp
+
+Where tag-rmap-hash has entries of the form:
+
address@hidden
+"tag_string" => ( "file/name.ext" line char )
address@hidden example
+
+Unlike @ref{hfy-tags-cache} these are the locations of occurrences of
+tagged items, not the locations of their definitions.
+
address@hidden hfy-tags-sortl
address@hidden hfy-tags-sortl
address@hidden
+
address@hidden is an alist of the form:
+
address@hidden
+(("/src/dir" . (tag0 tag1 tag2)) ... )
address@hidden example
+
+Where the tags are stored in descending order of length.
+
+See: @ref{hfy-load-tags-cache}.
+
address@hidden table
+
address@hidden Data Structures, Examples, Variables, Usage & Examples
address@hidden Data Structures
address@hidden Data Structures
+
+Some of the (informal) data structures used in Htmlfontify are detailed here:
+
address@hidden @code
+
address@hidden hfy-style-assoc
address@hidden hfy-style-assoc
address@hidden
+
+An assoc representing/describing an emacs face. Properties may be repeated,
+In which case later properties should be treated as if they were inherited
+from a 'parent' font. (For some properties, only the first encountered value
+is of any importance, for others the values might be cumulative, and for
+others they might be cumulative in a complex way).
+
+Some examples:
+
address@hidden
+(hfy-face-to-style 'default) =>
+
+ (("background" . "rgb(0, 0, 0)" )
+ ("color" . "rgb(255, 255, 255)")
+ ("font-style" . "normal" )
+ ("font-weight" . "500" )
+ ("font-stretch" . "normal" )
+ ("font-family" . "misc-fixed" )
+ ("font-size" . "13pt" )
+ ("text-decoration" . "none" ))
+
+(hfy-face-to-style 'Info-title-3-face) =>
+
+ (("font-weight" . "700" )
+ ("font-family" . "helv" )
+ ("font-size" . "120%" )
+ ("text-decoration" . "none") )
address@hidden lisp
+
address@hidden hfy-sheet-assoc
address@hidden hfy-sheet-assoc
address@hidden
+
+An assoc with elements of the form (face-name style-name . stlye-string):
+The actual stylesheet for each page is derived from one of these.
+
address@hidden
+'((default "default" . "@{ background: black; color: address@hidden")
+ (font-lock-string-face "string" . "@{ color: rgb(64,224,208) @}"))
address@hidden lisp
+
address@hidden hfy-facemap-assoc
address@hidden hfy-facemap-assoc
address@hidden
+
+An assoc of (point . @var{face-symbol}) or
+(point . @code{defface} attribute list) and (point . 'end) elements, in
+descending order of point value (ie from the file's end to its beginning).
+The map is in reverse order because inserting a <style> tag (or any other
+string) at @var{point} invalidates the map for all entries with a greater
+value of point. By traversing the map from greatest to least @var{point},
+we still invalidate the map as we go, but only those points we have already
+dealt with ( and therefore no longer care about ) will be invalid at any
+time.
+
address@hidden
+'((64820 . end)
+ (64744 . font-lock-comment-face)
+ (64736 . end)
+ (64722 . font-lock-string-face)
+ (64630 . end)
+ (64623 . font-lock-string-face)
+ (64449 . end)
+ ;; big similar section elided. You get the idea.
+ (5459 . end)
+ (5431 . (:inherit font-lock-keyword-face :background "7e7e7e"))
+ (5431 . end)
+ (4285 . font-lock-constant-face)
+ (4285 . end)
+ (4221 . font-lock-comment-face)
+ (4221 . end)
+ (4197 . font-lock-constant-face)
+ (4197 . end)
+ (1 . font-lock-comment-face))
address@hidden lisp
+
address@hidden table
+
address@hidden Examples, , Data Structures, Usage & Examples
address@hidden Examples
address@hidden Examples
+
+The following is a lump of code I use to fontify source code on my
+site, @url{http://rtfm.etla.org/} ( which was the reason, incidentally,
+that htmlfontify was written in the first place ).
+
address@hidden
+(defvar rtfm-section nil)
+
+;; constructs an appropriate header string to fit in with rtfm's
+;; templating system, based on the file and the stylesheet string
+(defun rtfm-build-page-header (file style)
+ (format "#define TEMPLATE red+black.html
+#define DEBUG 1
+#include <build/menu-dirlist|>\n
+html-css-url := /css/red+black.css
+title := rtfm.etla.org ( %s / src/%s )
+bodytag :=
+head <=STYLESHEET;\n
+%s
+STYLESHEET
+main-title := rtfm / %s / src/%s\n
+main-content <=MAIN_CONTENT;\n" rtfm-section file style rtfm-section file))
+
+;; the footer:
+(defun rtfm-build-page-footer (file) "\nMAIN_CONTENT\n")
+
+(defun rtfm-fontify-buffer (section)
+ (interactive "s section[eg- emacs / p4-blame]: ")
+ (require 'htmlfontify)
+ (let ((hfy-page-header 'rtfm-build-page-header)
+ (hfy-page-footer 'rtfm-build-page-footer)
+ (rtfm-section section))
+ (htmlfontify-buffer)
+ )
+ )
+
+;; here's the function I catually call - it asks me for a section label,
+;; and source and destination directories, and then binds a couple of
+;; customisation variable in a let before calling htmlfontify:
+(defun rtfm-build-source-docs (section srcdir destdir)
+ (interactive
+ "s section[eg- emacs / p4-blame]:\nD source-dir: \nD output-dir: ")
+ (require 'htmlfontify)
+ (hfy-load-tags-cache srcdir)
+ (let ((hfy-page-header 'rtfm-build-page-header)
+ (hfy-page-footer 'rtfm-build-page-footer)
+ (rtfm-section section)
+ (hfy-index-file "index")
+ (auto-mode-alist (append auto-mode-alist
+ '(("dbi\\(shell\\|gtk\\)$" . cperl-mode)
+ ("\\.xpm$" . c-mode ))))
+ )
+ (htmlfontify-run-etags srcdir)
+ (htmlfontify-copy-and-link-dir srcdir destdir ".src" ".html")))
address@hidden lisp
+
address@hidden Customisation, Requirements, Usage & Examples, Top
address@hidden Customisation
address@hidden variables (customisation)
+
+Htmlfontify provides the following variable and customisation entries:
+
address@hidden @code
address@hidden AUTOGENERATED BLOCK
+
address@hidden hfy-link-style-fun
address@hidden hfy-link-style-fun
address@hidden
+
+Set this to a function, which will be called with one argument
+(a "@{ foo: bar; address@hidden" css style-string) - it should return a copy of
+its argument, altered so as to make any changes you want made for text which
+is a hyperlink, in addition to being in the class to which that style would
+normally be applied.
+
address@hidden hfy-html-quote-regex
address@hidden hfy-html-quote-regex
address@hidden
+
+Regex to match (with a single back-reference per match) strings in HTML
+which should be quoted with @ref{hfy-html-quote}
+(and @pxref{hfy-html-quote-map}) to make them safe.
+
address@hidden hfy-page-footer
address@hidden hfy-page-footer
address@hidden
+
+As @ref{hfy-page-header}, but generates the output footer
+(and takes only 1 argument, the filename).
+
address@hidden hfy-display-class
address@hidden hfy-display-class
address@hidden
+
+Display class to use to determine which display class to use when
+calculating a face's attributes. This is useful when, for example, you
+are running emacs on a tty or in batch mode, and want htmlfontify to have
+access to the face spec you would use if you were connected to an X display.
+
+Some valid class specification elements are:
+
address@hidden
+ '(class color)
+ '(class grayscale)
+ '(background dark)
+ '(background light)
+ '(type x-toolkit)
+ '(type tty)
+ '(type motif)
+ '(type lucid)
address@hidden lisp
+
+Multiple values for a tag may be combined, to indicate that any one or more
+of these values in the specification key constitutes a match, eg:
+
+'((class color grayscale) (type tty)) would match any of:
address@hidden
+ '((class color))
+ '((class grayscale))
+ '((class color grayscale)))
+ '((class color foo))
+ '((type tty))
+ '((type tty) (class color))
address@hidden lisp
+and so on.
+
address@hidden hfy-page-header
address@hidden hfy-page-header
address@hidden
+
+Function called with two arguments (the filename relative to the top
+level source directory being etag'd and fontified), and a string containing
+the <style>...</style> text to embed in the document- the string returned will
+be used as the header for the htmlfontified version of the source file.
+
+See also: @ref{hfy-page-footer}
+
address@hidden hfy-src-doc-link-style
address@hidden hfy-src-doc-link-style
address@hidden
+
+String to add to the '<style> a' variant of an htmlfontify css class.
+
address@hidden hfy-fast-lock-save
address@hidden hfy-fast-lock-save
address@hidden
+
+Minimum size of a buffer for cached fontification.
+This value is temporarily assigned to @code{fast-lock-minimum-size} during
+html-fontification.
+
+Only buffers more than this can have associated Font Lock cache files saved.
+
+If nil, means cache files are never created.
+
+If a list, each element should be a cons pair of the form
address@hidden(@var{major-mode} . @var{size})}, where @var{major-mode}
+is a symbol or t (meaning the default). For example:
+
address@hidden
+ ((c-mode . 25600 )
+ (c++-mode . 25600 )
+ (rmail-mode . 1048576))
address@hidden lisp
+
+means that the minimum size is 25K for buffers in C or C++ modes, one megabyte
+for buffers in Rmail mode, and size is irrelevant (ie no saves) otherwise.
+
address@hidden hfy-split-index
address@hidden hfy-split-index
address@hidden
+
+Whether or not to split the index @ref{hfy-index-file} alphabetically
+on the first letter of each tag. Useful when the index would otherwise
+be large and take a long time to render or be difficult to navigate.
+
address@hidden hfy-find-cmd
address@hidden hfy-find-cmd
address@hidden
+
+``find'' command used to harvest a list of files to attempt to fontify.
+
address@hidden hfy-extn
address@hidden hfy-extn
address@hidden
+
+File extension used for output files
+
address@hidden hfy-default-face-def
address@hidden hfy-default-face-def
address@hidden
+
+Fallback @code{defface} specification for the face @code{default}, used
+when @ref{hfy-display-class} has been set ( the normal htmlfontify way of
+extracting potentially non-current face information doesn't necessarily
+work for @code{default} ).
+
+Example: I customise this to:
+
address@hidden
+((t :background "black" :foreground "white" :family "misc-fixed"))
address@hidden lisp
+
address@hidden hfy-init-kludge-hooks
address@hidden hfy-init-kludge-hooks
address@hidden
+
+List of functions to call when starting htmlfontify-buffer to do any
+kludging necessary to get highlighting modes to bahave as you want, even
+when not running under a window system.
+
address@hidden hfy-shell-file-name
address@hidden hfy-shell-file-name
address@hidden
+
+Should be set to a bourne compatible shell, which will be invoked
+for the more complex shell interactions needed by htmlfontify.
+Currently this is only required/used when using GNU etags, see
address@hidden for details.
+
address@hidden hfy-optimisations
address@hidden hfy-optimisations
address@hidden
+
+Optimisations to turn on: So far, the following have been implemented:
+
address@hidden @option
address@hidden merge-adjacent-tags
+If two (or more) span tags are adjacent, identical and separated by nothing
+more than whitespace, they will be merged into one span.
+
address@hidden zap-comment-links
+Suppress hyperlinking of tags found in comments.
+
address@hidden zap-string-links
+Suppress hyperlinking of tags found in strings.
+
address@hidden div-wrapper
+Add <div class="default"> </div> tags around the fontified body.
+( some people like this because they cut and paste the html into
+ a page with different colours than the fontified code. )
+
address@hidden keep-overlays
+preserve overlay highlighting (cf @code{ediff} or @code{goo-font-lock})
+as well as basic faces. Can result in extremely verbose highlighting
+if there are many overlays (as is the case with @code{goo-font-lock}).
+
address@hidden table
+
+And the following are planned but not yet available:
+
address@hidden @option
address@hidden kill-context-leak
+Suppress hyperlinking between files highlighted by different modes.
+
address@hidden table
+
+Note: like compiler optimisations, these optimise the _output_ of the code,
+not the processing of the source itself, and are therefore likely to slow
+htmlfontify down, at least a little. Except for skip-refontification,
+which can never slow you down, but may result in incomplete fontification.
+
address@hidden hfy-src-doc-link-unstyle
address@hidden hfy-src-doc-link-unstyle
address@hidden
+
+Regex to remove from the <style> a variant of an htmlfontify css class.
+
address@hidden hfy-link-extn
address@hidden hfy-link-extn
address@hidden
+
+File extension used for href links - Useful where the htmlfontify
+output files are going to be processed again, with a rersulting change
+in file extension. If @code{nil}, then any code using this should fall back
+to @ref{hfy-extn}.
+
address@hidden hfy-istext-command
address@hidden hfy-istext-command
address@hidden
+
+Command to run with the name of a file, to see whether it is a text file
+or not. The command should emit a string containing the word 'text' if
+the file is a text file, and a string not containing 'text' otherwise.
+
address@hidden hfy-etags-cmd-alist
address@hidden hfy-etags-cmd-alist
address@hidden
+
+An alist of possible shell commands that will generate etags output that
+Htmlfontify can use. '%s' will be replaced by @ref{hfy-etags-bin}.
+
address@hidden hfy-etags-bin
address@hidden hfy-etags-bin
address@hidden
+
+The Location of the etags binary (we begin by assuming it's in your path).
+
+Note that if etags is not in your path, you will need to alter the shell
+commands in @ref{hfy-etags-cmd-alist}.
+
+[ As of version 0.17, this requirement has been removed: It should
+ all just work(tm) ]
+
address@hidden hfy-etags-cmd
address@hidden hfy-etags-cmd
address@hidden
+
+An etags shell command to run in the source directory to generate a tags
+file for the whole source tree from there on down. The command should emit
+the etags output on standard output.
+
+Two canned commands are provided - they drive emacs' etags and
+exuberant-ctags' etags respectively.
+
address@hidden hfy-etag-regex
address@hidden hfy-etag-regex
address@hidden
+
+Regex used to parse an etags entry: must have 3 subexps, corresponding,
+in order, to:
+
address@hidden
+ The tag
+ The line
+ The char (point) at which the tag occurs
address@hidden enumerate
+
address@hidden hfy-index-file
address@hidden hfy-index-file
address@hidden
+
+Name (sans extension) of the index file produced during
+fontification-and-hyperlinking.
+
address@hidden hfy-instance-file
address@hidden hfy-instance-file
address@hidden
+
+Name (sans extension) of the tag usage index file produced during
+fontification-and-hyperlinking.
+
address@hidden hfy-html-quote-map
address@hidden hfy-html-quote-map
address@hidden
+
+An alist of char -> entity mappings used to make the text html-safe.
+
address@hidden /AUTOGENERATED BLOCK
address@hidden table
+
address@hidden Requirements, Index, Customisation, Top
address@hidden Requirements
address@hidden Requirements, Prerequisites
+
+Htmlfontify has a couple of external requirements:
+
address@hidden @bullet
+
address@hidden
+GNU Emacs 20.7+ or 21.1+
+
+Other versions may work - these have been used successfully by the
+author. If you intend to use Htmlfontify in batch mode, 21.1+ is
+pretty much required. The author does not know if XEmacs, NTemacs,
+or J.Random Emacs will run Htmlfontify, but reports/patches/bags of
+money are always welcome.
+
address@hidden
+A copy of etags ( exuberant-ctags or GNU etags ). Htmlfontify attempts
+to autodetect the version you have and customise itself accordingly,
+but you should be able to override this.
+
+See: @ref{Customisation}
+
address@hidden
+A copy of find (eg GNU find) that provides the @code{-path} predicate.
+
+You may be able to work around this with a suitable clever shell
+command and the customisation entry: @ref{hfy-find-cmd}
+
address@hidden
+A copy of sed (eg GNU sed).
+
address@hidden
+A copy of the @code{file} command.
+
address@hidden itemize
+
address@hidden Index, , Requirements, Top
address@hidden Index
+
address@hidden @var
address@hidden Concepts
address@hidden cp
+
address@hidden Functions
address@hidden fn
+
address@hidden Variables & Customisation
address@hidden vr
+
address@hidden table
+
address@hidden COPYING, , , Top
address@hidden GNU Free Documentation Licence
+
address@hidden FDL, GNU Free Documentation License
address@hidden Version 1.1, March 2000
+
address@hidden
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
address@hidden display
+
address@hidden 0
address@hidden
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
address@hidden
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
address@hidden without markup, Texinfo input format, address@hidden input
format,
address@hidden or @acronym{XML} using a publicly available
address@hidden, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
address@hidden, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
address@hidden
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
address@hidden
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
address@hidden
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
address@hidden A
address@hidden
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
address@hidden
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
address@hidden
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
address@hidden
+Preserve all the copyright notices of the Document.
+
address@hidden
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
address@hidden
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
address@hidden
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
address@hidden
+Include an unaltered copy of this License.
+
address@hidden
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
address@hidden
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
address@hidden
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
address@hidden
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
address@hidden
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
address@hidden
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
address@hidden enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
address@hidden
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
address@hidden
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
address@hidden
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
address@hidden
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
address@hidden
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
address@hidden
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
address@hidden://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
address@hidden enumerate
+
address@hidden
address@hidden ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
address@hidden
address@hidden
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
address@hidden group
address@hidden smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
address@hidden odd
address@hidden
address@hidden
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/emacs-24 r111131: Import the htmlfontify manual,
Glenn Morris <=