NAME

htmlbook - Create HTML book structure

SYNOPSIS

  htmlbook [<option>] <file>
  htmlbook -h
  htmlbook -v
  htmlbook -L

DESCRIPTION

The program creates a HTML book structure in a specified output directory.
Configuration is read from a project file read on th command line.

OPTIONS

-i <encoding> | --input-encoding=<encoding>
		specify input encoding for project file to process.

-o name[,name...]
		activates optional project file sections.

-s name=value | --set=name=value
		set variables (overwrite variables from options section).

-h | --help
		print help text.

-v | --version
		print version information.

-L | --license
		print license terms.

RETURN VALUE

The program returns exit status code 0 on success, any other value
indicates an error.

FILES

The project file contains project settings and information about the
document structure (text files and used template files).

Project file
------------
A project file consists of three sections: ``[options]'', ``[files]'', and
``[contents]''. A project file can contain optional sections
``[options:<name>]'', ``[files:<name>]'', and ``[contents:<name>]''. Optional
sections are only processed when activated by the -o command line option.
On Windows systems optional sections named ``windows'' are activated
automatically, on non-Windows systems sections named ``non-windows'' are
activated automatically.

The options section contains ``key=value'' lines for the following keys:

  output directory		Name of output directory. This directory is
  				removed completely and created again each
				time the output script is run.

  output script			Script to re-create the output directory and
  				copy files into it.

  title				Document or collection title.

  url				URL to access the document collection via web.

  index file			Name of file containing text for start page.

  html charset			Character set for output HTML files
				(``us-ascii'', ``ascii'', or ``utf-8'').

  template			Name of default template file (``web.hbt'').

  style				Name of default style file (``style.css'').

  page toc			Flag: Create an intra-page table of contents.

  create toc			Flag: Create table of contents.

  create index			Flag: Create keyword index.

  section numbers in index	Flag: Write section numbers in index.

  replace ampersand		Flag: Replace ampersand in texts (no).

  tidy				Flag: Use tidy for inspection and correction
				of HTML output files.

  ln				Flag: Use ln command instead of cp to save
				disk space.

  author			Author name.

  location			Location of author.

  write position		Flag: Write position within the collection at
  				start of page.

  section numbers in position	Flag: Write section number in position.

  shortcut icon			URL to shortcut icon.

  icon toc			File names for icons in navigation bar.
  icon previous
  icon next
  icon index

  impressum link		URL to impressum.

  impressum page		Name of text file for impressum (you can use
				either impressum link or impressum page).

  chm				Flag: Create HTML to produce a CHM file later.

  chm language			Language setting for CHM project
  				(``0x409 English (USA)'').

  js file			File name of JavaScript file.

  inherit js			Flag: Inherit JavaScript files from parents.

  var				Set variable (the first text word on the
				right side is the variable name, the
				remainder of the line is the variable value).

The ``[files]'' section lists the name of additional files to copy,
one per line.

The ``[contents]'' section contains the tree structure for navigation.
Each subsection for a node is started by a title line.
The indent level corresponds to the tree structure.
Title lines with same indent level are neighbours (sub-nodes of the same
parent node). A nodes parent node is the next node above the node with
smaller indent.
After the node title there are lines started by @ to configure the node:

  file = <File>			Text file for the nodes contents.
  input encoding = <Encoding>	Default encoding to use if no BOM is found.
  suffix = <String>		File name suffix for output file.
  short = <Short title>		Short title for use in the navigation menu.

Additionally you can use the ``html charset'', ``template'', ``style'',
``page toc'', ``write position'', ``replace ampersand'', ``tidy'', ``ln'',
``author'', ``location'', ``js file'', ``inherit js'', ``var'',
``icon toc'', ``icon previous'', ``icon next'', ``icon index'', and
``shortcut icon'' settings as shown for the options section.

Leafs (nodes without further subnodes) must have a text file configured,
for other nodes it's optional.

Template file
-------------
The template file specifies the text between <BODY> and </BODY>.
Special commands %%command%% can be used to insert the text, the navigation
menu, navigation blocks with clickable icons.
The following special commands are available:

  \%%contents%%			inserts the text file contents.

  \%%title%%			inserts the node title.

  \%%img <options>%%		inserts an image. The following options
  				are available:
    div[=Bool]			Create <div> around <img>
    centered[=Bool]		Show image centered, not left-aligned.
    src=file			File name for image.
    alt=``text''		Alternative text for image.
    title[=``text'']		Title text (alt= is used as default).
    caption[=``text'']		Image caption.
    longdesc=URL		File containing long description of image.
    border=width		Border width.
    height=height		Image height.
    width=width			Image width.
    svg=file			SVG version of image.
    svgwh[=Bool]		Apply PNG/JPEG dimensions to SVG object.
    object[=Bool]		Create object for SVG.
    pdf=file			PDF version of image.
    larger=file			Larger version of image.
    ismap[=bool]		Set ismap attribute.
    usemap=file			Image map file.
    name=name			Item name.
    id=name			ID for CSS styling.
    class=name			Class name for CSS styling.
    align=name			Alignment.
    vspace=distance		Vertical space.
    hspace=distance		Horizontal space.
    downloads[=Bool]		Provide links to download vector graphics
    cache			Cache image dimensions for images used multiple
    				times. Image dimensions for images used in
				a template are cached automatically.

  \%%menu <options>%%		inserts the navigation menu.
  				The following options are available:
    style=...			One from ``reverse'' (full menu in reverse
				order), ``full'' (full menu), ``top'' (show
				only first hierarchy level) or ``current''
				(show only current hierarchy level).
    sub[=bool]			Flag: Show subnodes of current node.

  \%%navigation <options>%%	inserts a navigation block.
  				The following options are available:
    itop=file			Icon for table of contents (``toc.png'').
    iprev=file			Icon for previous section (``prev.png'').
    inext=file			Icon for next section (``next.png'').
    ikind=file			Icon for keyword index (``index.png'').

  \%%author%%			inserts the author name.

  \%%location%%			inserts the authors location.

  \%%date <options>%%		inserts the current node.
  				The following options are available:
    style=name			Date style, currently only ``german'' is
				allowed to switch from the default
				``yyyy-mm-dd'' to ``dd.mm.yyyy''.

  \%%var <name> <options>%%	inserts a variable value.
  				The following options are available:
    url[=bool]			Flag: Encode as URL, not as text.

  \%%code <options>%%		controls output encoding. By default the
  				``<'', ``>'' are not replaced by ``&lt;'', and
				``&gt;'' as we expect to get correct HTML 
				from the text files. Replacement of ``&''
				by ``&amp;'' is controlled by the
				``replace ampersand'' setting in the options
				section.
				In code mode our text comes from a source
				code file, so we have to encode these
				characters for HTML output.
				The following options are available:
    enable[=bool]		turns code mode on.
    on[=bool]			turns code mode on.
    disable[=bool]		turns code mode off.
    off[=bool]			turns code mode off.
    toggle			toggles code mode.

  \%%a <options>%%		inserts a named anchor or a hyperlink.
  				The following options are available:
    name=name			Anchor name.
    href=URL			Link destination.
    title=``text''		Text to show when mouse is over link.
    text=``text''		Text for hyperlink.
    target=destination		Destination windows or frame, i.e. ``_blank''.
    type=text			MIME type.
    external[=bool]		Override result of internal/external test.
    id=text			ID for CSS styling.
    class=text			Class name for CSS styling.
    style=text			Direct style information.
    hreflang=text		Language for href text.
    charset=text		Character set.
    onblur=text			Script to execute when link looses focus.
    onfocus=text		Script to execute when link gets focus.
    accesskey=text		Hotkey for link.
    tabindex=number		Tabulator index.
    shape=text			Link shape form.
    coords=text			Coordinates.
    rel=text			Information for link to next element.
    rev=text			Information for link to previous element.

  \%%menuentry <options>%%	inserts code to visualize a menu entry.
  				The following options are available:
    item=``text''		Text of the menu entry, can be used
    				multiple times for hierarchical menus.

  \%%sourcefile <options>%%	shows a file contents in a <PRE></PRE>
  				environment and provides a download
				hyperlink. The following options are available:
    file=file			File name.
    type=text			MIME type.
    title=``text''		Text shown when mouse is over hyperlink.

Text file
---------
Text files contain the page contents.
You can use headings like
  .1	@name@	Heading text
for a structural document. Depths 1, 2, 3, 4, or 5 are converted to
<h2>...<h6> headers. A <h1> header is used for the page title.
The @name@ specification is optional, it results in a named anchor
  <a name="name"></a>
before the heading. If the name specification is omitted, an anchor name
is generated automatically.

Text files can use the special commands listed in ``Template file'', execpt
\%%contents%%. Additionally the following special command can be used
in text files:

  \%%index <options>%%		adds an entry to the keyword index.
  				The following options can be used:
    text=``text''		Keyword.
    name=``text''		Name of a named anchor.
    reference[=bool]		Flag: Use existing named anchor, do not
    				create an anchor.
NOTES

All text files, style files and images must be local files
in the current working directory.

AUTHOR

Dipl.-Ing. Dirk krause

HISTORY

2013-11-30 work on program was started.

COPYRIGHT AND LICENSE

Run
  htmlbook --license
to see the license conditions.

SEE ALSO

tidy