Menu ▾ ▴

htmlbook manual

Dirk Krause
← Previous ↑ Home ↑ Programs → Next

htmlbook — Write HTML like a book

Synopsis

htmlbook [_options_] _project_

Description

The htmlbook program creates a HTML book structure in a specified output directory.

Main features

  • Page design controlled by templates
    All pages or groups of pages use the same design controlled by a template.
     
  • Navigation buttons
    Navigation buttons on page top and bottom link to the start page with table of contents, previous page, next page, table of contents page and keyword index page.
     
  • Current position
    The current position in the book (list of parent nodes headers) is shown below the top navigation buttons.
     
  • Navigation menu
    In the right top of the page there is the navigation menu with several sections:
    • Childen of the current node (if any).
    • Current node and neighbours.
    • Parent node and neighbours.
    • Further ancestor nodes and neighbours.

Options

Option Purpose
-i encoding
--input-encoding=encoding		 Expected input encoding for project file.
-s name=value Override a variable setting (var =) from project file. May be used multiple times.
-o name[,name…]
‑‑optional‑sections=name[,name…]		 Activate optional sections in the project file, see Required and optional sections below. On Windows systems optional sections named "windows" are activated automatically. Optional sections named "non-windows" are activated automatically on all other systems.
-h
--help		 Show help text.
-v
--version		 Show version information.
-L
--license		 Show license information.

Exit status

0 on success, all other status codes indicate an error.

Project file

The project file is the starting point for the htmlbook program.

Required and optional sections

2 sections are required:

  • [options]
    This section is used for project setup.
     
  • [contents]
    This option configures the book structure and specifies the text files to use.

Other sections are optional:

  • [files]
    This section configures additional files to include in the project.
     
  • [options:name]
    These sections contain conditional project setup.

The [options] section

The options section is used for setup. It consists of key=value pairs, each pair in one line.
The following keys are available:

Group Key Type Purpose
Output output directory Absolute path name Output directory to produce. The output directory is removed completely and re-created each time the output script is run. Do not use any directory already containing data used for other purposes.
output script Short path name File name of script producing the output directory. The htmlbook program creates this script to copy all files for your web contents into an output directory. Execute this script after running htmlbook.
ln Boolean Use the ln program instead of cp when building the output directory.
url URL URL where your contents is visible on the Web.
tidy Boolean The output script runs tidy to check and correct the HTML files.
Impressum impressum link URL URL of existing page containing your impressum.
impressum page Short path name File containing your impressum, included in the book you create. The options "impressum link" and "impressum page" are mutually exclusive.
privacy link URL URL of existing page containing your privacy statement.
privacy page Short path name File containing your privacy statement, included in the book you create. The options "privacy link" and "privacy page" are mutually exclusive.
Book style index file Short path name Text file containing text for start page.
mark external links Boolean Use special symbol (a globe) in the title text of external links shown when the mouse is moved over the link.
external link marker symbol Hexadecimal Unicode position of the glyph to use as marker for external links.
create toc Boolean Build a table of contents on the start page.
create index Boolean Build keyword index on the start page.
section numbers in index Boolean Show section numbers in keyword index links.
table summaries Boolean Produce summary attributes in tables (default: off).
Node metadata title Text Title of the project.
author Text Authors name.
location Text Location where author lives.
Node appearance template Short path name Template file to use.
style Short path name CSS style file (default: style.css).
shortcut icon URL Shortcut icon to use in HTML files (default: favicon.ico).
write position Boolean Write position on top of page.
section numbers in position Boolean Write section numbers before section name in position list.
section numbers in page header Boolean Write section number in page header.
code line numbers Boolean Preceed code lines with line numbers in "sourcefile" and "code" special commands.
page toc Boolean Write a page table of contents.
Navigation bar icon home Short path name Icon for "Go to start page" link.
icon previous Short path name Icon for "Go to previous page" link.
icon next Short path name Icon for "Go to next page"link.
icon toc Short path name Icon for "Go to table of contents" link.
icon index Short path name Icon for "Go to keyword index" link.
Web or CHM chm Boolean Produce HTML output for CHM file creation.
chm language Text Language setup for CHM project file (default: "0x409 English (USA)"
chm full text search Boolean Active full text search in CHM file.
HTML version html doctype Text HTML-Version, one from: `none" (do not write a DOCTYPE line), "html-5", "html-4.01-strict", "html-4.01-transitional", "html-4.01-frameset", "xhtml-1.0-strict", "xhtml-1.0-transitional", "xhtml-1.0-frameset", or "xhtml-1.1". The most recent HTML version - "html-5" at this time - is assumed if the html doctype specification is missing.
Text encoding input encoding String Input encoding to use if no BOM (byte order marker) is found at start of file.
html charset String Character set for HTML files, either "us-ascii" or "utf-8".
replace ampersand Boolean Replace & by &. This flag is ignored in a number of special commands. When using & as parameter separator in URLs, you always have to encode it as &.
SVG svg wh Boolean Default for the "svgwh" option in "img" special commands (default: on).
JavaScript js file Short path name File containing JavaScript to include in HTML file.
inherit js Boolean Can be used to stop inheritance of JavaScript files.
chm close li Boolean Write optional closing li tag to hhk and hhc files.
Variables var Text Set variable. At least two words, the first word is the variable name, the remaining text is the variables value.

Some of the settings above can be overwritten per node by adding a @key=value line to a node in the contents section or by writing a ".key value" line in the nodes text file:

Option @ in contents . in file
tidy ✓ —
title ✓ ✓
author ✓ ✓
location ✓ ✓
template ✓ —
style ✓ —
shortcut icon ✓ ✓
write position ✓ ✓
page toc ✓ ✓
icon home ✓ —
icon previous ✓ —
icon next ✓ —
icon toc ✓ —
icon index ✓ —
html doctype ✓ —
input encoding ✓ —
html charset ✓ —
replace ampersand ✓ ✓
js file ✓ ✓
inherit js ✓ ✓
var ✓ —

The [files] section

This section contains a list of additional files to copy for your project, one file name per line. Use short path names in the current directory.

The [contents] section

The contents section contains the tree structure for your documents.

Each node description is started by a title line. This line contains the full title of a node.

The tree structure is based upon the indent.
Title lines with same indent level represent neighbours (sub-nodes of the same parent node). A nodes parent node is the next node above the current node having smaller indent.

After the title line you can use lines started by "@" to configure the node. The following key=value settings are available:

Key Type Purpose
file Short path name File name of the text file containing the page contents, required
title Text Title of the nodes page.
suffix File name suffix File name suffix for output file (default: ".html").
short Text Short title for page, used in the navigation menu.
context number Integer Context number, used when building a CHM file. An application may use the context number to open online help at a specific position.

Additionally you can overwrite some settings from the [options] section per node:

  • 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

Leaf nodes (nodes without further subnodes) are required to have a text file configured, for other nodes it's optional.

The [options:name] sections

Additional options sections can be activated using command line argument

-o name

when running the htmlbook program.

A section [options:windows] is always activated automatically when htmlbook is running on a Windows system. A section [options:non-windows] is always activated automatically when htmlbook is running on a non-Windows system.

Template files

The template file specifies the text between the <BODY> and </BODY> tags. Special commands can be used to insert the contents text, the navigation menu or navigation blocks with hyperlinked icons.
The following special commands (with key=value options) are available:

Command Option name Type Purpose
%%contents%% Insert the page contents.
%%title%% Insert the page title.
%%img …%% Insert an image.
src Short path name File name for image. Must be specified without path and without CGI parameters.
alt Text Alternative text for image.
title Text Title (tooltip text), shown when mouse is over image.
longdesc URL URL of file containing a long description of the image.
border Integer Border width.
height Integer Image height in pixels.
width Integer Image width in pixels.
svg Short path name SVG version of image. Must be specified without path and without CGI parameters.
object Boolean Create SVG object. If this option is turned off, the SVG file is simply added to the download link list. Default: on.
svgwh Boolean Use width and height of src file for SVG image.
Although the SVG file contains the real size of the image and the browser can use this information and the screen resolution to find a suitable width and height in pixels not all browsers do so. Guess, which one doesn't.
The default value for the svgwh option is controled by the "svg wh" option in the [options] section of the project file. Default: on.
pdf Short path name PDF version of image. Must be specified without path and without CGI parameters.
larger Short path name Larger version of image (higher resolution). Must be specified without path and without CGI parameters. The options "pdf" and "larger" are mutually exclusive.
ismap Boolean Set ismap attribute for img tag.
usemap Short path name File to use as a map.
name Identifier Set name attribute for img tag.
id Identifier Object ID for CSS styling.
class Identifier Class name for CSS styling.
align Text Image alignment.
hspace Integer Horizontal space.
vspace Integer Vertical space.
cache Boolean Cache image dimension. Use this option for images used multiple times. The flag is enabled automatically for images included from templates.
table Boolean Use a <table> to separate image and links beside.
div Boolean Create a <div> around the image to ensure vertical space between image and other contents. Inside the outer <div> tag we can use either a table or a sequence of further divs to align the downloads links beside the image. The "table" and "div" options are mutually exclusive.
caption Text Caption text for image. Automatically activates table if div is not used.
download Boolean Provide download links to open vector graphics or high-resolution in separated browser windows or tab. Automatically activates table if div is not used.
centered Boolean Image is shown centered in the available space, not left-aligned.
no-vspace Boolean Use the div.hb_image_div_no_vspace class without the margin-top and margin-bottom setting instead of div.hb_image_div_outer.
%%img.suffix file=basename.suffix …%% Shortcut for
%%img with src=basename.png svg=basename.svg pdf=basename.pdf table title download%%.
%%img.tex file=basename.tex …%% Shortcut for
%%img src=basename.png svg=basename.svg pdf=basename.pdf no-vspace table title download …%%
(no vertical space for formulas).
%%a …%% Hyperlink or named anchor.
href URL Link destination.
text Text Hyperlink text. The default text is to show the URL specified in href.
title Text Title text (tooltip text) shown when mouse is over hyperlink. If no text is specified, the hyperlink text is shown.
target Identifier Destination windows, frame or tag.
type Text MIME type.
external Boolean Override result of internal/external link inspection.
id Identifier ID for CSS styling.
class Identifier Class name for CSS styling.
style text Direct CSS style information.
hreflang Text Language for href= specification.
charset Text Character set for link.
onfocus Text Script to execute when link gets focus.
onblur Text Script to execute when link looses focus.
accesskey Text Hotkey to activate link.
tabindex Integer Tabulator index.
shape Text Link shape type.
coords Active coordinates.
rel URL Link to next page.
rev URL Link to previous page.
name Identifier Create a named anchor.
%%menu …%% Insert the navigation menu.
style Text Menu style, one from
  • full
    List collection for all hierarchy levels, starting at the root node, ending for the current node's parent.
     
  • reverse
    List collection for all hierarchy levels in reverse order, starting at the current node's parent, ending at the root node. This is the default as it shows the subnodes (if sub is enabled) and the neighbours of the current node at the top of the menu.
     
  • top
    Only top level nodes are shown.
     
  • current
    Only neighbours of the current node are shown.
sub Boolean Show subnodes of current node. Enabled by default.
%%navigation …%% Insert a navigation block (navigation icons with hyperlinks).
home Short path name Icon file to go to start page. Default: "home.png".
previous Short path name Icon file for previous section. Default: "prev.png".
next Short path name Icon file for next section. Default: "next.png".
toc Short path name Icon file to go to top (start page, table of contents). Default: "toc.png".
index Short path name Icon file for keyword index. Default: "index.png".
%%author%% Insert author's name.
%%location%% Insert author's location (city).
%%date …%% Insert current date.
style Text Date style, "german" for german date style "dd.mm.yyyy". By default the universal date style "yyyy-mm-dd" is used.
%%var name …%% Insert variable value.
url Boolean Switch from normal text encoding for HTML to URL encoding.
%%code …%% Switch between normal processing and code processing. In normal processing our input is text with HTML tags and encoded characters. This means, "<", ">" and "&" (if ampersand conversion is turned off) are passed to HTML output as is. If we process source code, these characters are not correctly encoded yet, we have to correct them.
The %%code%% special command is typically used in <PRE>…</PRE> sections.
on Boolean Turn code mode on.
off Boolean Turn code mode off.
toggle Boolean Toggle code mode.
lineno Boolean Create line numbers.
%%sourcefile …%% Show a file contents and provide a download hyperlink.
file Short path name Source file to show, required.
type text MIME type of file.
title Text Title text (tooltip text) for hyperlink, shown when mouse is over link.
lineno Boolean Create line numbers, default: on.
%%menuentry …%% Visualize a menu entry.
item Text Text for menu entry. This option may be used multiple times for a nested menu entry.
%%htmlname%% Replaced by the name of the HTML output file.
%%hint …% Hint (some text with tooltip text attached).
text Text Normal text.
title Text Tooltip text to show when mouse is over text.

Text files

Text files contain the page contents for a node.

Metadata in text files

The notation

.name value

is used to store metadata in the text file.

Metadata lines must be placed at the beginning of the file before any other (non-metadata) line.

Description

Use a

.meta-description       This is a page description

line to produce

<meta name="description" content="This is a page description">

tag in the output file header.

Keywords

Use a

.meta-keywords  some, words, to, search, for

line to produce a

<meta name="keywords" content="some, words, to, search, for">

tag in the output file header.

Headings in text files

Use headings like

.number [@name@] Text

i.e.

.1 @files@ File types used by this program

to structure your document. The .1, .2, .3, .4, and .5 header depths are converted to <h2>…<h6> HTML headers (<h1> is used for the page title).
If you omit the anchor name specification an anchor name is created automatically.

Special commands in text files

In text files you can use the special commands listed in the Template files section, except %%contents%% (when processing a text file, you are already handling the contents).
Additionally you can use the following special command:

Command Option name Type Purpose
%%index …%% Add an entry to the keyword index.
text Text Keyword.
name Text Anchor name, optional. An anchor name is constructed automatically if this option is omitted.
reference Boolean Do not create an anchor, reference an existing one. A name is required. Intended to reference anchors from headings.

Backslashes as escape characters

Occurances of "%%" in text lines (not headings) are recognized as start or end of a special command by htmlbook. If you need a "%%" in HTML output, escape the percent characters by a backslash:

\%\%

Style file style.css

The style.css file contains the style definitions.
The following tags and classes are set up:

Htmlbook CSS style classes
Class name Purpose
body Body of the HTML file
White background assigned.
h1
h2
h3
h4
h5
h6		 Headings in different levels.
pre Show code.
pre > i Italic text in pre tag.
For some reason it does not inherit the font from pre sometimes, inheritance is set up explicitly.
div.header The header division
div.headerleft
div.headercenter
div.headerright		 Left/centered/right sub-division of header
span.title Title text, typically shown in the div.headercenter
div.navicon Division for navigation and contents
div.naviheader Navigation menu division
div.hb_nm_div Division for navigation menu
ul.hb_um_ul Unnumbered list for navigation menu
li.hb_nm_li Navigation menu item
a.hb_nm_a Navigation menu link (normal)
a.hb_nm_a_parent Navigation menu link (to a parent node)
li.hb_nm_c Current navigation menu item (no link assigned)
li.hb_nm_sep Navigation menu separator
div.hb_navigation Navigation bar division
a.hb_navi_a Navigation bar link
img.hb_navi_img Navigation bar icon image
div.hb_pos_div Division to show position
table.hb_pos_ta Position table
tr.hb_pos_tr Row in position table
td.hb_pos_td_arrow Table field in position table to show arrow
td.hb_pos_td_text Table field in position table to show text
div.contents_from_text Division for contents from text file
div.contents Contents division
table.hb_ptoc_ta Table to show page-internal table of contents
tr.hb_ptoc_tr Table row in page-internal table of contents
td.hb_ptoc_td_empty Table field for space in page-internal table of contents
td.hb_ptoc_td_data Table field for link in page-internal table of contents
a.hb_ptoc_a Link in page-internal table of contents
a.hb_a_i Internal link
a.hb_a_e External link
span.hb_link_number Link number for external links, shown only in print
div.hb_img_div_outer Outer division around image division or image table
div.hb_img_div_no_vspace Outer division around image division or image table not requiring additional space (i.e. images to show a mathematical formula)
table.hb_img_ta Table for image
tr.hb_img_tr Row in image table
td.hb_img_td_img Table field to show image in image table
td.hb_img_td_empty Table field for distance between image and download links in image table
td.hb_img_td_a Table field for download links in image table
div.hb_img_div_inner_img Inner image division, contains image
div.hb_img_div_inner_img_centered Inner image division, contains image, centered
p.hb_img_p_download Paragraph to show download links if no table used
span.hb_img_caption Caption for image
a.hb_img_a_larger Download link for image in image table
table.hb_me_ta Table to show a menu entry
tr.hb_me_tr Table row in a menu entry table
td.hb_me_td_text Table field to show menu entry text
td.hb_me_td_arrow Table field to show arrow for menu entry
div.hb_file_div Division to show a text file
a.hb_file_a Link to download a text file from a text file division
div.hb_file_div pre Code range of division to show a text file
div.hb_file_div pre > i Italic text in code range of division to show a text file
.topleft
.topcenter
.topright
.middleleft
.middlecenter
.middleright
.bottomleft
.bottomcenter
.bottomright
.paddedtopleft
.paddedtopcenter
.paddedtopright
.paddedmiddleleft
.paddedmiddlecenter
.paddedmiddleright
.paddedbottomleft
.paddedbottomcenter
.paddedbottomright 		Easier alignment for th and td
.floatleft Floating on the left side, allows text flow on the right side
.marginfloatleft Floating on the left side, allows text flow on the right side, requires space
.floatright Floating on the right side, allows text flow on the left side
.clearboth Clear both horizontal and vertical flow
div.hb_link_div Division for external links table
table.hb_link_ta Table for external links
td.hb_link_td_number Table field for external link number
td.hb_link_td_url Table field for external link URL
div.hb_dtoc_div Division for document table of contents
table.hb_dtoc_ta Table for document table of contents
tr.hb_dtoc_tr Table row in document table of contents
td.hb_dtoc_td_space Table field for spaces in document table of contents
td.hb_dtoc_td_entry Table field for entry in document table of contents
a.hb_dtoc_a Link in document table of contents
div.hb_ki_div Division for keyword index
h2.hb_ki_h2 Heading for keywod index
dl.hb_ki_dl List for keyword index
dt.hb_ki_dt Title for item in keyword index
dd.hb_ki_dd Description for item in keyword index
ul.hb_ki_ul URL list in keyword index
li.hb_ki_li List item in keyword index URL list
a.hb_ki_a Link in keyword index
div.footer Footer division
div.footerleft
div.footercenter
div.footerright		 Left/centered/right footer sub-division

Restrictions

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

Use only the following characters in file names: "a"…"z", "A"…"Z", "0"…"9", "_", ".", and "-". The minus ("-") must not be the first character in the file name.
You must not use the following characters:

  • "?" (used in URLs to separate file name and CGI parameters),
  • "&" (used in URL to separate CGI parameters one from another),
  • "#" (used in URLs to separate file name and anchor name),
  • "%" (special meaning in URLs, starts encoded sequence),
  • space and tabulator,
  • all characters above 0x7F.

Escape characters are needed in some situations:

  • if a %% sequence is needed in a template file or text file, use \%\% instead.
  • if a line is started by a leading dot in a text file, use . instead.
  • As the backslash is used for escaping, you have to write two backslashes in the *.txt file to produce one backslash in HTML output.

Notes

This program uses DK libraries version 3.

FAQ

What's the purpose of the program?

The htmlbook program helps you to publish web contents "like a book".

The logical structure of your contents is specified in a project file.
An initial logical structure description might look like this:

[contents]
Overview
Legal stuff
Installation
  Installation on Linux/Unix
    RPM installation
    Installation from source
  Installation on Windows
    Executable setup
    Installation from source

As you can see the indent level corresponds to the hierarchical chapter/section/subsection… structure.
Leaf nodes (nodes without further subnodes) must have text assigned, for other nodes text assignment is optional.

A "@file = " instruction is used to assign a text file to a node, i.e.:

    Installation from Source
                @file = instwsrc.txt

Templates are used for an equal appearance of all pages or groups of pages.

In the templates there are special commands to place a navigation icon block and a navigation menu.

Htmlbook creates a navigation menu.

Htmlbook creates a navigation icon bar.

Htmlbook creates a position information.

Htmlbook creates a page internal table of contents if configured to do so.

Htmlbook creates a table of contents on the start page if configured to do so.

Htmlbook creates a keyword index on the start page if configured to do so.

For images and links you can use the %%img …%% and %%a …%% commands, resource files are added to the list of files to copy automatically.

GNU make
GNU make provides a "wildcard" and a "patsubst" feature. So it is relatively easy to require PNG, SVG and PDF files for all FIG files:

FIGIMAGES := \
    $(patsubst %.fig,%.png,$(wildcard *.fig)) \
    $(patsubst %.fig,%.pdf,$(wildcard *.fig)) \
    $(patsubst %.fig,%.svg,$(wildcard *.fig))

gxhconvert
The Graphics conversion hints contains the gxhconvert script.
The download is available on the project page in the "Files" section, navigate into the directory indicating the most recent (highest) version number.
After installing gxhints itself, run

gxhconvert --check

to check for software required by gxhconvert. If some of the required programs are missing, gxhconvert prints hints where to find the software and how to install it.

pdflatex
Install a LaTeX distribution to have the pdflatex command available.

Where can I find an example for a web page created by htmlbook?

See "html" directory in the user documentation package dktools-x.y.z.tar.gz available in the "Files" section of the DK tools project at SourceForge.

How do I start a htmlbook based project?

Create a directory structure for sources and HTML output, i.e.

mkdir -p /home/joe/mybook
mkdir -p /home/joe/mybook/src
mkdir -p /home/joe/mybook/html

The /home/joe/mybook/src directory contains the sources you write, the /home/joe/mybook/html will contain all the files you need to transfer to your web server.

Copy initial files to /home/joe/mybook/src.

cd /home/joe/mybook/src
cp /usr/share/dktools/htmlbook/* .

Edit the index.prj file
At least change the output directory to

output directory = /home/joe/mybook/html

Inspect the file, customize it to fit your project's needs. The settings you most likely want to change are collected at the start of the file.

Edit the style.css file.
To follow your corporate identity design you can change colors.
Replace all occurances of "yellow" by your CI policies main color. This color is used as background color in the header bar, in the navigation menu, and in the footer bar.
Replace all occurances of color "red" by your CI policies second color.
Note: Make sure to replace only color "red", not the "red" in class names and positions like "centered"!
It should be a color in contrast to the color before as it is used as text color in the navigation menu.
In the original file we did not specify a "color:" entry for "div.footer" as the background color was a bright color. If you replaced "yellow" by a dark color, change the text color to "white" or a bright color.

How do I write a GNUmakefile for a htmlbook based project?

Here is a starting point:

TEXTFILES := $(wildcard *.txt)
HBTFILES  := $(wildcard *.hbt)
PRJFILES  := $(wildcard *.prj)

htmlbook.sh:  $(TEXTFILES) $(HBTFILES) $(PRJFILES)
      -[ ! -f htmlbook.sh ] || rm -f htmlbook.sh
      htmlbook index.prj
      chmod 755 htmlbook.sh

install:      htmlbook.sh
      ./htmlbook.sh

How do I write good HTML?

  • Learn about HTML and CSS.
    Visit http://de.selfhtml.org/ or another HTML introduction/tutorial in your preferred language.
     
  • Let the user choose font and size for texts on screen.
    Modern web browsers allow the user to choose a font family and size for convenient reading.
    You should respect the users choice and not force readers to fonts or font sizes hard to read.
     
  • Avoid the following stupidities:
    • Font sizes in px:
      A text size of 9px will result in a real text size of 0.153 inches (3.89 mm) on a 17 inch tube screen with 800x600 pixels resolution and in a real text size of 0.09 inches (2.29 mm) on a 20 inch LCD screen with 1600x1200 pixels resolution. On better screens with higher resolutions your text will be harder and harder to read.
    • Width and height of texts specified in px
      This typically goes hand in hand with font sizes in px, as some people do not know about width specifications in em or are unable to calculate percents.
      If a user has set up the browser to enforce minimum font sizes, width and height specifications in px will result in texts overlapping other texts.
    • Large parts of the screen left white
      Some brain-dead web designers (let's call them "px counters") want their work to look fine and equal on all screens, so they pack the entire design into a table of 640px width (in memory to VGA resolution of 640x480) or 800px which is shown centered on the screen. Today I have a 1920x1080 screen both at work and at home, this "design masterpiece" leaves 66 percents or 58 percents of my screen blank, typically I can not read any text in the contents.
       
  • Use tidy and the W3C validation service.
    The tidy program inspects HTML files and suggests/applies corrections to deliver valid HTML. You can also use the W3C Markup Validation Service to validate your web site.
     
  • Place time and/or product version information on each page.
    In the distributed web.hbt template the %%date%% instruction near the end places the current date (when htmlbook was run) at the bottom of each page. Visitors like to know whether they are reading an up-to-date page or a 15 years old one. In web pages about a software product mention the version you are talking about. If you write "In the current Debian GNU/Linux version do …" people do not know whether "potato" (2.2, released in july 2002) or "jessie" (8, released in april 2015) was the current version while you were writing the text. Better write "In Debian GNU/Linux, versions Jessie and Stretch, do …".

Classes for CSS styling added automatically, different for internal and external links.
Htmlbook inspects the value of the "href" attribute and decides whether the link is external or internal and assigns a class to the link.

Files for internal links are added to the list of files to copy.
For internal links to a file in the current working directory the link destination is added to the list of resource files to copy.
So there is no need to mention the file in the "[files]" section of the project.

External links section maintained automatically.
Htmlbook keeps track of all external links for a node and appends an "External links" section to the end of text.
CSS styling is used to hide this section when viewing the file on screen and to print it when printing the file.

Write a %%a…%% special command, i.e.

View the
%%a href="http://sourceforge.net/projects/dktools/" text="DK tools project page at SourceForge.net" title%%
for more information.

This results in HTML code:

View the
<a href="http://sourceforge.net/projects/dktools/" target="_blank" class="hb_a_e" title="DK tools project at SourceForge.net">DK tools at SourceForge.net</a><span class="hb_link_number">&nbsp;&#9001;2&#9002;</span>
for more information.
  • The text specified in the text attribute is the text for the hyperlink.
  • The href attribute of the %%a…%% special command is used directly as the href attribute in the link.
  • The title attribute in the %%a…%% special command is specified without the value. So the value from the text attribute is used as default text.
  • The value of the href attribute is started by a protocol specification so the link is recognized as external link:
    • The class hb_a_e is used for the link.
    • The link is opened in a new browser window or browser tab.
    • A link number is appended in a class hb_link_number span. The CSS definitions for that class don't show the link number on screen, only when printing. There is a special table listing all external links sorted by number at the end of the page. Due to CSS definitions this table is not shown on screen, only when printing.

    For an internal link htmlbook would use the hb_a_i class, no link number and no new browser window or tab.

For external hyperlinks you should configure a symbol to mark the link as external in the title attribute. By default a globe with meridians is used. For web page links use text like "Visit xxx: homepage" or "Visit _xxx project". For downloads use text like "Download xxx file".

For navigation links to other pages within the same book you can prepend arrowheads to the link.

Symbol HTML code Purpose
← &#x2190; Link to a previous page
↑ &#x2191 Link to a previous section on the same page
↓ &#x2193 Link to a section below on the same page
→ &#x2192 Link to a later in the book

For file download links use text like "C file x1.c".

Which image types can I use in HTML?

Vector graphics
Recent browser versions can show SVG (*.svg) objects. For PDF files there are plugins available.

Bitmap graphics
You can use PNG (*.png), GIF (*.gif) and JPEG files (*.jpg, *.jpeg) in HTML.
For "artificial" images (logos, drawings…) you should prefer PNG, for "natural" images (photograms) you should use JPEG.

How can I embed images into a page?

  • Just an <img> tag, text can float around the image.
  • Place the image in a <div> tag to leave some space between the image and the text before and after the image. Optionally you can configure an image title.

For images drawn in a vector graphics drawing application export your image to SVG, PDF and PNG. Optionally export to SVG and PDF, convert one of them to PNG.
We create a tag for an SVG object. In the SVG object tag we produce an img tag as fallback for browsers not capable to show the SVG.
We can add hyperlinks to open the SVG, PDF or PNG file in a new browser tab. So users can open just the graphics and zoom in to view details if necessary.

How do I produce a simple img tag image with text floating around it?

To show a screenshot from a dialog box and add text explaining the screenshot use

%%img src=screenshot.png alt="Screenshot" class="marginfloatleft"%%

to add the image.

Use

<p>Some text explaining the image.<br class="clearboth">
</p>

for the text. Note the the class="clearboth" in the final <br> tag.

The example code

%%img src=testimg.png alt="A test image" class=marginfloatleft%%<p>Some
text shown right beside the image.<br class="clearboth">
</p>

results in HTML code:

<img src="testimg.png" alt="A test image" width="192" height="96" border="0" class="marginfloatleft"><p>Some text shown right beside the image.<br class="clearboth">
</p>

How do I produce a normal image?

Use

%%img.fig file=image.fig alt="Alternative text"%%

if you have image.svg, image.pdf and image.png available.
This is a shortcut for

%%img src=image.png svg=image.svg pdf=image.pdf alt="Alternative text" div title download%%

Although "img.fig" was intended for *.fig files from XFig, jFig and WinFIG first, you can use it with whatever source file type, you just have to convert/export the source file to SVG, PDF, and PNG.

The example code

%%img.fig file=testimg.fig alt="A test image" caption%%

results in HTML code like:

<div class="hb_img_div_outer">
<table class="hb_img_ta">
<tr class="hb_img_tr">
<td class="hb_img_td_img">
<object type="image/svg+xml" data="testimg.svg">
<param name="src" value="testimg.svg">
<img src="testimg.png" alt="A test image" title="A test image" width="192" height="96" border="0">
</object>
<br>
<span class="hb_img_caption">A test image</span></td>
<td class="hb_img_td_empty">&nbsp;</td>
<td class="hb_img_td_a">
<a class="hb_img_a_larger" href="testimg.svg" target="_blank" type="image/svg+xml">SVG</a><br>
<a class="hb_img_a_larger" href="testimg.pdf" target="_blank" type="application/pdf">PDF</a><br>
<a class="hb_img_a_larger" href="testimg.png" target="_blank">Image</a></td>
</tr>
</table>
</div>

How do I convert *.fig files automatically using GNU make?

Change your GNUmakefile to:

FIGPNGRES=96

TEXTFILES := $(wildcard *.txt)
HBTFILES  := $(wildcard *.hbt)
PRJFILES  := $(wildcard *.prj)

IMAGES    := \
    $(patsubst %.fig,%.png,$(wildcard *.fig)) \
    $(patsubst %.fig,%.svg,$(wildcard *.fig)) \
    $(patsubst %.fig,%.pdf,$(wildcard *.fig))

%.svg:  %.fig
    gxhconvert -o=svg $<

%.pdf:  %.fig
    gxhconvert -o=pdf $<

%.png:  %.fig
    gxhconvert -o=png -r=$(FIGPNGRES) $<
    optipng -q -i1 -zc1-9 -zm1-9 -zs0-3 -f0-5 $@

htmlbook.sh:    $(TEXTFILES) $(HBTFILES) $(PRJFILES) $(IMAGES)
    -[ ! -f htmlbook.sh ] || rm -f htmlbook.sh
    htmlbook index.prj
    chmod 755 htmlbook.sh

install:    htmlbook.sh
    ./htmlbook.sh

So GNU make knows it has to produce a *.svg, *.pdf, and *.png file for each *.fig file.

How do I use Gnuplot files with htmlbook?

Prepare the Gnuplot file
In the Gnuplot source file — i.e. sinus.gp — omit the "set terminal" and "set output" instructions:

set xrange[0:2*pi]
plot sin(x) notitle

Convert to *.svg, *.pdf and *.png

gxhconvert -o=svg sinus.gp
gxhconvert -o=pdf sinus.gp
gxhconvert -o=png sinus.gp

Use images in HTML book text file

%%img.gp file=sinus.gp alt="Sinus"%%

How do I convert *.gp files automatically using GNU make?

Extend your GNUmakefile to:

FIGPNGRES=96

TEXTFILES := $(wildcard *.txt)
HBTFILES  := $(wildcard *.hbt)
PRJFILES  := $(wildcard *.prj)

IMAGES    := \
    $(patsubst %.fig,%.png,$(wildcard *.fig)) \
    $(patsubst %.fig,%.svg,$(wildcard *.fig)) \
    $(patsubst %.fig,%.pdf,$(wildcard *.fig)) \
    $(patsubst %.gp,%.png,$(wildcard *.gp)) \
    $(patsubst %.gp,%.svg,$(wildcard *.gp)) \
    $(patsubst %.gp,%.pdf,$(wildcard *.gp))

%.svg:  %.fig
    gxhconvert -o=svg $<

%.pdf:  %.fig
    gxhconvert -o=pdf $<

%.png:  %.fig
    gxhconvert -o=png -r=$(FIGPNGRES) $<
    optipng -q -i1 -zc1-9 -zm1-9 -zs0-3 -f0-5 $@

%.svg:  %.gp
    gxhconvert -o=svg $<

%.pdf:  %.gp
    gxhconvert -o=pdf $<

%.png:  %.gp
    gxhconvert -o=png -r=$(FIGPNGRES) $<
    optipng -q -i1 -zc1-9 -zm1-9 -zs0-3 -f0-5 $@

htmlbook.sh:    $(TEXTFILES) $(HBTFILES) $(PRJFILES) $(IMAGES)
    -[ ! -f htmlbook.sh ] || rm -f htmlbook.sh
    htmlbook index.prj
    chmod 755 htmlbook.sh

install:    htmlbook.sh
    ./htmlbook.sh

So GNU make knows it has to produce a *.svg, *.pdf, and *.png file for each *.gp file.

How do I typeset formulas in htmlbook?

The recommended method to typeset formulas in HTML is the use of MathML Core.
The example formula

A = 1 4 ⁢ 2 ⁢ ( a 2 ⁢ b 2 + a 2 ⁢ c 2 + b 2 ⁢ c 2 ) - a 4 - b 4 - c 4

is produced by the following code:

<math display="block" style="text-align: left; font-size: 120%;">
<mrow>
  <mi>A</mi>
  <mo>=</mo>
  <mfrac>
    <mn>1</mn>
    <mn>4</mn>
  </mfrac>
  <mo>&#x2062;</mo>
  <msqrt>
    <mrow>
      <mn>2</mn>
      <mo>&#x2062;</mo>
      <mo>(</mo>
      <msup>
        <mi>a</mi>
        <mn>2</mn>
      </msup>
      <mo>&#x2062;</mo>
      <msup>
        <mi>b</mi>
        <mn>2</mn>
      </msup>
      <mo>+</mo>
      <msup>
        <mi>a</mi>
        <mn>2</mn>
      </msup>
      <mo>&#x2062;</mo>
      <msup>
        <mi>c</mi>
        <mn>2</mn>
      </msup>
      <mo>+</mo>
      <msup>
        <mi>b</mi>
        <mn>2</mn>
      </msup>
      <mo>&#x2062;</mo>
      <msup>
        <mi>c</mi>
        <mn>2</mn>
      </msup>
      <mo>)</mo>
      <mo>-</mo>
      <msup>
        <mi>a</mi>
        <mn>4</mn>
      </msup>
      <mo>-</mo>
      <msup>
        <mi>b</mi>
        <mn>4</mn>
      </msup>
      <mo>-</mo>
      <msup>
        <mi>c</mi>
        <mn>4</mn>
      </msup>
    </mrow>
  </msqrt>
</mrow>
</math>

See Rendering Math in HTML: MathML, MathML Core, and AsciiMath for a short introduction and/or MathML Core W3C Recommendation snapshot for a complete description of MathML Core.

Experienced LaTeX users can use the latexmlmath program (for Debian available in the latexml package) to get suggestions how to translate LaTeX math to MathML Core.
Example: type

latexmlmath 'a_b^c'

to see the suggestion

<math xmlns="http://www.w3.org/1998/Math/MathML" alttext="a_{b}^{c}" display="block">
  <msubsup>
    <mi>a</mi>
    <mi>b</mi>
    <mi>c</mi>
  </msubsup>
</math>

Old way: Create vector graphics images

Formulas in HTML pages created by htmlbook are images. These images are available as *.svg, *.pdf and *.png files.

To typeset the formula you can use any method you want to produce these files. The preferred method is to use pdfLaTeX.

Copy the template file to the current directory, save it i.e. as "math-triangle.tex" In dktools 3.8.4 the template file is available as /usr/share/dktools/htmlbook/math-img.tex.

\documentclass[12pt]{article}
% begin font setup
\usepackage[T1]{fontenc}
\usepackage{mathptmx}
\usepackage[scaled=.92]{helvet}
\usepackage{courier}
% end font setup
% begin other packages
\usepackage{textcomp}
\usepackage[intlimits]{amsmath}
% end other packages
\usepackage{color}
\setlength{\paperwidth}{20cm}
\setlength{\paperheight}{20cm}
\pagestyle{empty}
\setlength{\voffset}{-0.9in}
\setlength{\topmargin}{0bp}
\setlength{\headheight}{0bp}
\setlength{\headsep}{0bp}
\setlength{\topskip}{0bp}
\setlength{\hoffset}{-0.9in}
\setlength{\oddsidemargin}{0bp}
\setlength{\evensidemargin}{0bp}
\setlength{\marginparwidth}{0bp}
\setlength{\marginparsep}{0bp}
\setlength{\textwidth}{\paperwidth}
\setlength{\textheight}{\paperheight}
\setlength{\parskip}{0bp}
\setlength{\parindent}{0bp}
\setlength{\pdfpagewidth}{\paperwidth}
\setlength{\pdfpageheight}{\paperheight}
\begin{document}% FORMULA GOES INTO NEXT LINE, REPLACE EXISTING ONE
\(a^2+b^2=c^2\)
\end{document}

Edit the file, insert your formula, save as math-triangle.tex file:

\documentclass[12pt]{article}
% begin font setup
\usepackage[T1]{fontenc}
\usepackage{mathptmx}
\usepackage[scaled=.92]{helvet}
\usepackage{courier}
% end font setup
% begin other packages
\usepackage{textcomp}
\usepackage[intlimits]{amsmath}
% end other packages
\usepackage{color}
\setlength{\paperwidth}{8cm}
\setlength{\paperheight}{2cm}
\pagestyle{empty}
\setlength{\voffset}{-0.9in}
\setlength{\topmargin}{0bp}
\setlength{\headheight}{0bp}
\setlength{\headsep}{0bp}
\setlength{\topskip}{0bp}
\setlength{\hoffset}{-0.9in}
\setlength{\oddsidemargin}{0bp}
\setlength{\evensidemargin}{0bp}
\setlength{\marginparwidth}{0bp}
\setlength{\marginparsep}{0bp}
\setlength{\textwidth}{\paperwidth}
\setlength{\textheight}{\paperheight}
\setlength{\parskip}{0bp}
\setlength{\parindent}{0bp}
\setlength{\pdfpagewidth}{\paperwidth}
\setlength{\pdfpageheight}{\paperheight}
\begin{document}% FORMULA GOES INTO NEXT LINE, REPLACE EXISTING ONE
\(A=\tfrac{1}{4}\sqrt{2(a^2b^2+a^2c^2+b^2c^2)-a^4-b^4-c^4}\)
\end{document}

Run pdflatex:

pdflatex -interaction=nonstopmode math-triangle

Open the math-triangle.pdf file for inspection. You might want to change paper size and height in the math-triangle.tex file an do another iteration step to run pdflatex and view the image again.

Now produce the *.svg and *.png files:

gxhconvert -o=svg math-triangle.pdf
gxhconvert -o=png math-triangle.pdf

In the text file write:

%%img.tex file=math-triangle.tex alt="Area of a triangle"%%

Consider using the same paper width for all formulas used in the same page.

How do I convert the *.tex files automatically using GNU make?

Extend your GNUmakefile to:

FIGPNGRES=96

TEXTFILES := $(wildcard *.txt)
HBTFILES  := $(wildcard *.hbt)
PRJFILES  := $(wildcard *.prj)

IMAGES    := \
    $(patsubst %.fig,%.png,$(wildcard *.fig)) \
    $(patsubst %.fig,%.svg,$(wildcard *.fig)) \
    $(patsubst %.fig,%.pdf,$(wildcard *.fig)) \
    $(patsubst %.gp,%.png,$(wildcard *.gp)) \
    $(patsubst %.gp,%.svg,$(wildcard *.gp)) \
    $(patsubst %.gp,%.pdf,$(wildcard *.gp)) \
    $(patsubst %.tex,%.png,$(wildcard math-*.tex)) \
    $(patsubst %.tex,%.svg,$(wildcard math-*.tex)) \
    $(patsubst %.tex,%.pdf,$(wildcard math-*.tex))

%.svg:  %.fig
    gxhconvert -o=svg $<

%.pdf:  %.fig
    gxhconvert -o=pdf $<

%.png:  %.fig
    gxhconvert -o=png -r=$(FIGPNGRES) $<
    optipng -q -i1 -zc1-9 -zm1-9 -zs0-3 -f0-5 $@

%.svg:  %.tex
    gxhconvert -o=svg $<

%.pdf:  %.tex
    gxhconvert -o=pdf $<

%.png:  %.tex
    gxhconvert -o=png -r=$(FIGPNGRES) $<
    optipng -q -i1 -zc1-9 -zm1-9 -zs0-3 -f0-5 $@

htmlbook.sh:    $(TEXTFILES) $(HBTFILES) $(PRJFILES) $(IMAGES)
    -[ ! -f htmlbook.sh ] || rm -f htmlbook.sh
    htmlbook index.prj
    chmod 755 htmlbook.sh

install:    htmlbook.sh
    ./htmlbook.sh

So GNU make knows it has to produce a *.svg, *.pdf, and *.png file for each math-*.tex file.

How do I show a source code section?

Use:

<pre>%%code on%%
...place source code here...
%%code off%%</pre>

In the source code replace each backslash by a sequence of two backslashes.

In the source code replace each sequence of two percent signs by backslash-percent-backslash-percent.

How do I show an entire source file?

Use the %%sourcefile…%% special command, i.e. to show file example1.c:

%%sourcefile file=example1.c%%

How can I produce a keyword index?

In index.prj use

create index = yes

in the [options] section.

In text files use the %%index…%% special command, i.e.:

<p>%%index text="Toolbar"%%There are several buttons
in the toolbar. Click on a button to start an action.</p>

How do I place a keyword index entry for a header?

You can not use special commands in a header line. Use

.1      @toolbarheader@ Toolbar
%%index text="Toolbar" name=toolbarheader reference%%
<p>There are several buttons in the toolbar.
Click on a button to start an action.</p>

to create an index entry for a header.

Can I use htmlbook to create web pages and online help?

In theory: yes. Practically there are some limitations as you should provide different HTML for web browsers and online help (HTML files used to create *.chm and/or *.htb files).
See the questions below.

Which options should I set in index.prj to create HTML for online help?

chm             =       yes
template        =       chm.hbt
html charset    =       us-ascii
create index    =       yes

When creating online help in different languages, you have multiple source directories and multiple output directories (one for each language). Use the same file names for *.txt files in each directory.
For pages opened by numeric id, use the same id for corresponding files in different language directories.

Where can I find an example for htmlbook sources to create online help?

The sources for the *.htb and *.chm files used by DK tools GUI applications are in the "help-src" subdirectory of the source archive.
Before building the archive to distribute, my script runs the "build-help.sh" script which in turn runs the htmlbook program for all application/language subdirectories, runs chmcmd and zip to produce the *.chm and *.htb files.

How does HTML for web pages differ from HTML for online help?

Users visiting web sites typically use a browser. Recent browsers support large parts of HTML and CSS standards, have support for SVG graphics and can launch external viewers for PDF files.
Online help viewers differ. Some of them use leightweight HTML rendering components supporting only parts of the HTML and CSS standards, having no support for SVG…
Some help viewers seem to ignore CSS style information completely.

So when producing HTML for online help you should not use any CSS styling.

Use &nbsp; to create horizontal distances, empty lines to create vertical distances.

Manually add line breaks and space between text paragraphs and images or tables.

How does image support differ between browsers and online help viewers?

Browsers typically support SVG, PNG, JPEG and can launch an external viewer for PDF files. If you have an image available as *.svg, *.pdf and *.png file you should use:

<p>Text paragraph before the image.</p>
%%img.fig file=image.fig alt="Some text" title%%
<p>Text paragraph after the image.</p>

Leightweight HTML rendering components used in online help viewers sometimes do not automatically create the line breaks and distances between paragraphs and images.
To produce HTML for online help, you should use:

<p>Text paragraph before the image.<br>&nbsp;<br></p>
%%img src=image.png alt="Some text" title%%
<p><br>&nbsp;<br>Text paragraph after the image.</p>

How does table support differ between browsers and online help viewers?

Leightweight HTML rendering components used in online help viewers sometimes do not automatically create the line breaks and distances between paragraphs and tables.
So you should add

<br>&nbsp;<br>

at the end of the paragraph before the table and the start of the paragraph after the table (same as suggested for images above).

How can I produce a *.htb file?

After running htmlbook to produce the HTML and other files, change to the HTML output directory and run:

if [ -f index.chm ]
then
  rm -fr index.chm
fi
zip -r -9 ../index.zip *
mv ../index.zip ../index.htb

If we did build a *.chm file before we do not want to include it in the *.htb file.

How can I preview a *.htb file?

Use wxdkhtb:

wxdkhtb file.htb > /dev/null 2>&1 &

How can I produce a *.chm file on a Linux system?

Install Free Pascal 2.6.4 or newer. You can find it on http://freepascal.org. On Linux systems you can install it via package management.

After running htmlbook to produce the HTML and other files, change to the HTML output directory and run:

chmcmd --verbosity 5 --html-scan project.hhp
chmod 644 index.chm
mv index.chm ..

How can I preview a *.chm file on a Linux system?

Install the xchm package.
Run:

xchm file.chm > /dev/null 2>&1 &
← Previous ↑ Home ↑ Programs → Next

Related

Wiki: htmlbook