NAME

  htmlbook - HTML-Dateien für ein Buch-Äquivalent

AUFRUF

  htmlbook [<Optionen>] <Projekt>

BESCHREIBUNG

Das Programm erzeugt HTML-Dateien, die Struktur des erzeugten Webangebotes
ähnelt einem Buch. Der Autor kann sich auf den Inhalt konzentrieren,
das Programm htmlbook übernimmt die Erstellung von Navigationsmenü,
Navigationsblock mit Icons, Inhaltsverzeichnis und Stichwortverzeichnis.

OPTIONEN

-i <encoding>
--input-encoding=<encoding>
				gibt das Encoding für die Projektdatei an.

-o Name[,Name...]
				aktiviert optionale Abschnitte der
				Projektdatei.

-s Name=Wert
--set=Name=Wert
				setzt eine Variable, überschreibt
				Variablen, die im options-Abschnitt der
				Projektdatei gesetzt wurden.

-h
--help
				zeigt diesen Hilfetext an.

-v
--version
				zeigt die Versionsnummer an.

-L
--license
				zeigt die Lizenzbedingungen an.

RÜCKGABEWERT

Das Programm gibt bei Erfolg 0 zurück, alle anderen (positiven) Exit-Codes
weisen auf Fehler hin.

DATEIEN

Die Projektdatei ist der Startpunkt von htmlbook. Sie gibt an, welche
Textdateien unter Zuhilfename welcher Templates benutzt werden.

Projektdatei
------------
Die Projektdatei besteht aus den Abschnitten "[options]", "[files]"
und "[contents]".
Weiterhin sind optionale Abschnitte der Form "[options:<Name>]",
"[files:<Name>]" und "[contents:<Name>]" möglich, diese Abschnitt werden
nur dann verarbeitet, wenn sie beim Programmstart mit der Option -o
aktiviert wurden. Auf Windows-Systemen werden optionale Abschnitte mit dem
Namen "windows" immer verarbeitet, auf Nicht-Windows-Systemen
optionale Abschnitte mit dem Namen "non-windows".

Der options-Abschnitt enthält Zeilen der Form "Schlüssel=Wert", folgende
Schlüssel können verwendet werden:

  output directory		Verzeichnis für die Ausgabedateien, muss leer
				sein, wird bei jedem Aufruf des output script
				gelöscht und neu angelegt.

  output script			Ausgabescript, legt das Ausgabeverzeichnis neu
				an und kopiert die Daten dorthin.

  title				Titel-Angabe.

  url				URL unter der das Webangebot online steht.

  index file			Dateiname für Text auf Startseite.

  html charset			Zeichensatz für HTML-Dateien, "us-ascii",
  				"utf-8" oder "ascii".

  template			Dateiname für das Standard-Template ("web.hbt").

  style				Dateiname für die Standard-Style-Datei
				("style.css").

  page toc			Flag: Seiteninternes Inhaltsverzeichnis anlegen.

  create toc			Flag: Inhaltsverzeichnis anlegen (über alle
				Seiten).

  create index			Flag: Stichwortverzeichnis (Index) anlegen.

  section numbers in index	Flag: Abschnittsnummer in Index anzeigen.

  replace ampersand		Flag: Zeichen & ersetzen (Standard: aus).

  tidy				Flag: tidy zur Kontrolle und Korrektur
				verwenden.

  ln				Flag: ln anstelle von cp verwenden.

  author			Autor-Angabe.

  location			Ortsangabe.

  write position		Flag: Positionsangabe schreiben.

  section numbers in position	Flag: Abschnittsnummer in Positionsangabe.

  shortcut icon			URL zu favicon.

  icon toc			Dateinamen für Icons in Navigationsleiste
  icon previous			(Inhaltsverzeichnis, vorheriger Abschnitt,
  icon next			nächster Abschnitt, Index).
  icon index

  impressum link		URL zu Impressum.

  impressum page		Text-Knoten für Impressum.
  				Es kann entweder ein Impressum-Link oder ein
				Impressum-Knoten verwendet werden.

  chm				Flag: HTML erzeugen, aus dem später eine
				CHM-Datei erstellt wird.

  chm language			Sprachangabe für CHM-Projekt
  				(Standard: "0x409 English (USA)").

  js file			Dateiname für JavaScript-Datei.

  inherit js			Flag: JavaScript-Dateien von Eltern... erben.

  var				Variable setzen (das erste Textwort auf der
				rechten Seite ist der Variablenname, der Rest
				der Zeile ist der Wert der Variablen).

Der Abschnitt "[files]" listet die Namen zusätzlich zu kopierender
Dateien, eine per Zeile.

Der Abschnitt "[contents]" enthält die Baumstruktur für die Navigation.
Jeder Unterabschnitt für einen Knoten beginnt mit dem Titel.
Die Baumstruktur ergibt sich aus den Einrückungen. Gleich weit eingerückte
Titel bezeichnen benachbarte Knoten innerhalb derselben Kollektion.
Der Elternknoten eines jeden Knotens ist der letzte oberhalb befindliche
Knoten, der weniger weit eingerückt ist.

Auf einen Knoten-Titel können ein oder mehrere Zeilen folgen, die mit
@ beginnen. Diese Zeilen enthalten Konfigurationsangaben zum Knoten:

  file = Datei			Dateiname der Textdatei.
  input encoding = Encoding	Encoding, falls kein BOM in Eingabedatei.
  suffix = String		Dateinamen-Endung für Ausgabedatei.
  short = Kurztitel		Kurzfassung des Titels für Navigationsmenü.

Weiterhin sind die options-Angaben "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" und "shortcut icon" erlaubt.

Blätter (Knoten ohne weitere Unterknoten) müssen eine Angabe zur
Textdatei haben, für andere Knoten ist dies optional.

Template
--------
Das Template gibt an, was zwischen den Tags <BODY> und </BODY> steht.
Über Spezial-Kommandos der Form %%Kommando%% können u.a. der Text eingebunden
werden, das Navigationsmenü bzw Navigationsblöcke eingefügt werden.
Folgende Spezial-Kommandos können verwendet werden:

  %%contents%%			fügt den Inhalt der Textdatei an dieser
  				Stelle ein.

  %%title%%			fügt den Titel des aktuellen Dokumentes ein.

  %%img <Optionen>%%		fügt ein Bild ein. Folgende Optionen
  				können verwendet werden:
    div[=Bool]			div-Tag um img-Tag
    centered[=Bool]		Bild zentriert zeigen, nicht linksbündig
    src=Datei			Dateiname für Bilddatei
    alt="Text"			Beschreibungstext
    title[="Text"]		Titel (Standard: alt)
    caption[="Text"]		Bildunterschrift (aktiviert div)
    longdesc=Datei		URL der ausführlichen Bildbeschreibung
    border=Breite		Bildrahmenbreite
    height=Höhe			Bildhöhe
    width=Breite		Bildbreite
    svg=Datei			URL der Vektorgraphik (SVG-Format)
    svgwh[=Bool]		Für SVG Abmessungen aus PNG/JPEG nutzen
    object[=Bool]		SVG-Objekt erzeugen
    pdf=Datei			URL der Vektorgraphik (PDF-Format)
    larger=Datei		URL einer hochauflösenden Bildvariante
    ismap[=Bool]		Flag: Bild ist eine Map
    usemap=Datei		URL der Map
    name=name			Name für das Bild
    id=ID			ID für CSS-Styling
    class=Klasse		Klasse für CSS-Styling
    align=Ausrichtung		Ausrichtung des Bildes
    vspace=Abstand		Vertikaler Abstand
    hspace=Abstand		Horizontaler Abstand
    download[=Bool]		Download-Links für Vektorgraphiken erzeugen
    cache			Bildgröße in Cache zwischenspeichern für
    				mehrmalige Verwendung desselben Bildes.
				Automatisch aktiv, wenn %%img%% in Template
				verwendet wird.

  %%menu <Optionen>%%		fügt das Navigationsmenü ein.
  				Folgende Optionen können verwendet werden:
    style=Stil			Menü-Stil, "reverse" (Standard), "full",
    				"current" oder "top".
    sub[=Bool]			Flag: Kind-Knoten der aktuellen Seite anzeigen.

  %%navigation <Optionen>%%	fügt einen Navigationsblock mit anklickbaren
  				Navigationsicons ein. Folgende Optionen
				können verwendet werden:
    itop=Datei			Icon für Inhaltsverzeichnis ("toc.png").
    iprev=Datei			Icon für vorherigen Abschnitt ("prev.png").
    inext=Datei			Icon für nächsten Abschnitt ("next.png").
    ikind=Datei			Icon für Stichwortverzeichnis ("index.png").

  %%author%%			fügt die Angabe zum Autor ein.

  %%location%%			fügt die Angabe zum Ort ein.

  %%date <Optionen>%%		fügt das aktuelle Datum ein.
  				Folgende Optionen können verwendet werden:
    style=Stil			Datums-Stil (derzeit nur "german" unterstützt).

  %%var <Name> <Optionen>%%	fügt den Wert der angegebenen Variable ein.
  				Folgende Optionen können verwendet werden:
    url[=Bool]			Der Wert wird in einer Codierung passend
    				für URLs ausgegeben.

  %%code <Optionen>%%		schaltet das Code-Verhalten um.
  				Folgende Optionen können verwendet werden:
    enable[=Bool]		schaltet Code-Verarbeitung ein.
    on[=Bool]			schaltet Code-Verarbeitung ein.
    disable[=Bool]		schaltet Code-Verarbeitung aus.
    off[=Bool]			schaltet Code-Verarbeitung aus.
    toggle			schaltet Code-Verarbeitung um.

  %%a <Optionen>%%		fügt einen Link ein.
  				Folgende Optionen können verwendet werden:
    href=URL			Ziel-URL des Links.
    name=Name			Anker-Name (entweder href oder name erlaubt).
    text="Text"			Link-Text (Standard: href-Angabe).
    title="Text"		Link-Titel, wenn Maus über Link.
    target=Ziel			Zielfenster oder -frame.
    type=Typ			MIME-Typ.
    external[=Bool]		Flag: Externer Link, überschreibt die
				automatische Erkennung.
    id=ID			ID für CSS-Styling.
    class=Klasse		Klasse für CSS-Styling.
    style=Stilangabe		Direkte Stil-Angaben.
    hreflang=Sprache		Sprache für die href-Angabe.
    charset=Zeichensatz		Zeichensatz des Links.
    onblur=Script		Script wenn Link den Fokus verliert.
    onfocus=Script		Script, wenn Link den Fokus erhält.
    accesskey=Key		Hotkey für den Link.
    tabindex=Index		Tabulator-Reihenfolge durch Zahlenangabe.
    shape=Form			Verweis-sensitiver Bereich bei Objekten.
    coords=Koordinaten		Verweis-sensitiver Bereich bei Objekten.
    rel=Relation		Vorwärts-Verknüpfung.
    rev=Revision		Rückwärts-Verknüpfung.

  %%menuentry <Optionen>%%	fügt die Darstellung eines Menüeintrages ein.
  				Folgende Optionen können verwendet werden:
    item="Text"			Mehrfach verwendbar bei hierarchischen
    				Menüs.

  %%sourcefile <Optionen>%%	stellt eine Datei in <PRE></PRE>-Umgebung
  				dar und bietet einen Download-Link an.
				Folgende Optionen können verwendet werden:
    file=Datei			Darzustellende Datei, Pflichtangabe.
    type=Typ			MIME-Typ der Datei.
    title="Text"		Titel für Link.

Textdatei
---------
Textdateien enthalten den eigentlichen Seiteninhalt.
Zur Strukturierung können Überschriften der Form
  .1	@name@	Überschrift
verwendet werden mit den Tiefen 1, 2, 3, 4 und 5. Aus diesen Tiefenangaben
wird dann <h2>...<h6> erzeugt.
Die Namensangabe ist optional. Ist sie vorhanden, wird ein mit Namen
versehener Anker
  <a name="name"></a>
vor der Überschrift angelegt. Ohne die Namensangabe wird automatisch ein
Anker-Name gebildet.

Text-Dateien können ebenfalls die unter "Template" aufgeführten
Spezial-Kommandos enthalten, mit Ausnahme von %%contents%%. Zusätzlich
ist in Textdateien noch das folgende Spezialkommando erlaubt:

  %%index <Optionen>%%		fügt einen Eintrag zum Stichwortverzeichnis
  				hinzu. Folgende Optionen sind möglich:
    text="Text"			Text (Pflichtangabe).
    name=Name			Anker-Name (optional).
    reference[=Bool]		Flag: Index-Eintrag bezieht sich auf einen
    				bereits vorhandenen Anker (z.B. eine
				mit Namen versehene Überschrift oder einen
				explizit gesetzten Anker).

HINWEISE

Alle Textdateien, Templates, Style-Dateien und Bilder müssen lokale
Dateien im aktuellen Verzeichnis sein.

SIEHE AUCH

  http://dktools.sourceforge.net

AUTOR

  Dirk Krause

LIZENZ

Mit dem Kommando

  htmlbook -L

werden die Lizenzbedingungen angezeigt.