* doc/misc/htmlfontify.texi: Miscellaneous fixes and updates.

[bpt/emacs.git] / doc / misc / htmlfontify.texi

\input texinfo
@comment %**start of header
@setfilename ../../info/htmlfontify
@settitle Htmlfontify User Manual
@exampleindent 2
@comment %**end of header

@copying
This manual documents Htmlfontify, a source code -> crosslinked +
formatted + syntax colorised html transformer.

Copyright @copyright{} 2002, 2003, 2013 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs misc features
@direntry
* Htmlfontify: (htmlfontify).    Convert source code to html.
@end direntry

@titlepage
@title Htmlfontify User Manual
@sp 4
@subtitle Htmlfontify version 0.20
@sp 1
@subtitle Jun 2002
@sp 5
@author Vivek Dasmohapatra
@page

@vskip 0pt plus 1filll
@noindent
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Htmlfontify

@insertcopying
@end ifnottex

@menu
* Introduction::                   About Htmlfontify.
* Usage & Examples::               How to use Htmlfontify.
* Customisation::                  Fine-tuning Htmlfontify's behaviour.
* Requirements::                   External programs used by Htmlfontify.
* GNU Free Documentation License:: The license for this documentation.
* Index::                          Index of contents.
@end menu

@node Introduction
@chapter Introduction
@cindex Introduction

Htmlfontify provides a means of converting individual Emacs buffers,
source files, or entire source trees to html, preserving formatting
and Emacs colorisation / 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).

@node Usage & Examples
@chapter Usage & Examples
@cindex Usage & Examples

Htmlfontify can be used both interactively and as part of another
elisp function.  If you're running it in a modern Emacs, it will also
run when attached to a terminal (i.e., without X) or even when in
batch mode.

@menu
* 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.
@end menu

@node Interactive
@section Interactive
@cindex Interactive
@cindex functions (interactive)

Htmlfontify provides the following interactive functions:

@table @code
@item htmlfontify-buffer
@findex htmlfontify-buffer
@anchor{htmlfontify-buffer}

@lisp

(htmlfontify-buffer &optional @var{srcdir} @var{file})
@end 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