################################################################################
#
# Project     : UDO manual
# Chapter     : Formats: HTML (Hypertext Markup Language)
# Language    : German
# Initial Date: 2009-06-05
# Author      : Dirk Hagedorn
# Co-author(s): Ulf Dunkel (fd)
# Write-access: fd
#
# ------------------------------------------------------------------------------
# 
# History
# -------
# 2009:
#   fd  Jun 05: file introduced (extracted from formats.ui)
#   fd  Jun 09: 'file' -> 'Datei'
#   fd  Jun 09: 'lediglich' -> 'nur'
#   fd  Jun 09: ', so ' -> ', ' (old-style fill word, not required)
#   fd  Jun 08: 'Homepage' -> 'Website'
#   fd  Jun 09: 'Endung' -> 'Suffix' (following German Mac OS X nomenclature)
#   fd  Jun 09: macro (!file) introduced
#   fd  Jun 10: using macro (!file [])
#   fd  Jun 10: using macro (!code [])
#   fd  Jun 10: using EXAMPLE_... macros
#   fd  Jun 16: great review session #1
# 2010:
#   fd  Mar 05: old environment attribute short changed: -> !compressed
#   fd  May 26: 'man' -> 'Sie' (Golden Rule #2)
# 2013:
#   fd  Oct 25: subchapter 'HTML markup with CSS' added
# 2014:
#   fd  Jun 20: FAQ item added: 'How to navigate in HTML pages using the keyboard'
#
################################################################################

!begin_node HTML (Hypertext Markup Language)
!html_name format_html
!label HTML

HTML ist eines der meistgenutzten Zielformate, die mit UDO erzeugt werden. 
Es ist zudem eines der meistgenutzten Formate für Online-Dokumentationen. 
Logischerweise gibt es zum HTML-Ausgabeformat auch die meisten Fragen. 
Hier sind die häufigsten als FAQ zusammengefasst.

!begin_description !not_compressed

##################################################

!index Kann ich per Tastatur in den HTML-Seiten blättern?
!item [Kann ich per Tastatur in den HTML-Seiten blättern?]
Normalerweise werden bei der HTML-Ausgabe pro Seite in den Kopf- und Fußzeilen anklickbare Navigationsbuttons erzeugt.
Diese Buttons zeigen die Hierarchie des Dokuments mit einem Home-Button und einigen Pfeil-Buttons.

Ab Version 7.04 schreibt UDO in die Anker-Tags dieser anklickbaren Buttons IDs:
!begin_blist !compressed
!item [UDO_nav_hm_HEAD] Home-Button: Er führt zurück auf die Startseite des HTML-Dokuments.
!item [UDO_nav_lf_HEAD] Nach links: Dieser Button führt zurück auf die logisch vorige Dokumentseite.
!item [UDO_nav_up_HEAD] Nach oben: Dieser Button führt eine Kapitelhierarchiestufe zurück.
!item [UDO_nav_rg_HEAD] Nach rechts: Dieser Button führt zurück auf die logisch folgende Dokumentseite.
!end_blist

Um diese Navigationsbuttons per Tastatur ansprechen zu können, sollten Sie JavaScript einsetzen.
Das HTML-Attribut ""accesskey"" benötigt je nach Browser unterschiedliche Zusatztasten und spricht z.B. keine Pfeiltasten an.
Achten Sie darauf, daß Sie die Navigationsbuttons nicht mittels (!KW [no_headlines]) und (!KW [no_footers]) im Vorspann abgeschaltet haben.
Binden Sie dann mit (!KW [html_script_name]) ein JavaScript-Skript ein, das Tastendrücke auswertet.

##################################################

!index Aufteilung
!index HTML !! Aufteilung
!item [Wie kann man die Aufteilung in mehrere Dateien unterbinden?]
Im Gegensatz zu den anderen Formaten erzeugt UDO standardmäßig
mehrere Dateien, die miteinander verknüpft sind. Für jedes
Kapitel, jeden Abschnitt und Unterabschnitt wird eine eigene
Datei mit der Endung (!file [.htm[l!]]) angelegt. Die Namen der einzelnen
Dateien richten sich nach der Nummer und der Position des
jeweiligen Kapitel. Inhaltsverzeichnis und Titelseite gelangen in
die Datei, die Sie UDO per Kommandozeile als (!code [(--!)outfile]) übergeben.

!index !html_merge_nodes
!index !html_merge_subnodes
!index !html_merge_subsubnodes
!index !html_merge_subsubsubnodes
!index !html_merge_subsubsubsubnodes
Mit den Schaltern (!KW [html_merge_nodes]), (!KW [html_merge_subnodes]),
(!KW [html_merge_subsubnodes]), (!KW [html_merge_subsubsubnodes]) oder (!KW [html_merge_subsubsubsubnodes]) können
Sie die Aufteilung in mehrere Dateien unterbinden.

Wird im Vorspann (!KW [html_merge_nodes]) benutzt, wird das gesamte
Dokument in einer Datei gesichert. Dies empfiehlt sich lediglich
bei kleinen Dokumenten, die kleiner als 16~KB sind.

(!KW [html_merge_subnodes]) sorgt dafür, daß alle Abschnitte eines
Kapitels in der Datei angegeben werden, in dem sich auch das
Kapitel selbst befindet.

Der Schalter (!KW [html_merge_subsubnodes]) sorgt dafür, daß alle
Unterabschnitte in der gleichen Datei wie der übergeordnete Abschnitt
untergebracht werden.

Der Schalter (!KW [html_merge_subsubsubnodes]) schließlich sorgt dafür,
daß alle Paragraphen in der gleichen Datei wie der übergeordnete
Unterabschnitt untergebracht werden.

Der Schalter (!KW [html_merge_subsubsubsubnodes]) schließlich sorgt dafür,
daß alle Unterparagraphen in der gleichen Datei wie der übergeordnete
Paragraph untergebracht werden.

##################################################

!index Dateinamen
!index HTML !! Dateinamen
!index !html_name
!item [Mir gefallen die Dateinamen bei der HTML-Ausgabe nicht!/]
Durch den Befehl (!KW [html_name]) können Sie einem Kapitel einen
bestimmten Namen zuweisen, den UDO für die jeweilige Datei
anstelle der etwas kryptischen Namen wie etwa ""(!file [0a1009.htm])""
benutzt.

##################################################

!index HTML !! Kopfzeile
!index udo_lf.gif
!index udo_rg.gif
!index udo_up.gif
!item [Wie bekomme ich diese scheußlichen Kopfzeilen weg?]
UDO erzeugt standardmäßig auf jeder HTML-Seite eine Kopfzeile,
anhand derer Sie das Thema (gebildet aus den Daten von (!KW [docinfo] [[title!!]]) und
(!KW [docinfo] [[program!!]])) des Hypertextes erkennen können. Desweiteren werden Links
zu der vorgehenden, nachfolgenden und/oder übergeordneten Seite
angelegt. Dazu werden GIFs benutzt, die UDO automatisch erzeugt.
Die Dateinamen dieser GIFs lauten (!file [udo_lf.gif]), (!file [udo_rg.gif]) und
(!file [udo_up.gif]).

!index !no_headlines
Durch den Schalter (!KW [no_headlines] [[html!!]]) kann die Ausgabe der
Kopfzeilen und der Grafiken unterbunden werden.

##################################################

!item [Wie kann ich bequem eigene Kopf- und Fußzeilen erzeugen?]
Um eigene (!idx [Kopfzeilen]) und (!idx [Fußzeilen]) zu erzeugen, können Sie Makros
benutzen, die Sie jeweils am Anfang und Ende eines Kapitels
angeben. Der Inhalt dieser Kapitel erscheint dabei jedoch
unterhalb der Überschrift. Auf folgende Art und Weise wurden
beispielsweise Kopf- und Fußzeilen meiner Website angelegt,
in der es Kapitel namens ""Software"", ""Kontaktadressen"" und
""Links"" gibt:

!begin_description
!item [Hauptdatei:]
(!EXAMPLE_BEGIN)
!vinclude (!EXAMPLES)html/headfoot.ui
(!EXAMPLE_END)

!item [software.ui:]
(!EXAMPLE_BEGIN)
!vinclude (!EXAMPLES)html/software.ui
(!EXAMPLE_END)
!end_description

Wird nun nach HTML umgewandelt, werden die jeweiligen Kopf- und
Fußzeilen ausgegeben. Durch die Referenzierung von UDO werden
automatisch Links auf die anderen Kapitel angelegt.

Wandeln Sie nicht nach HTML um, werden leere Definitionen und
Makros erzeugt, wodurch keine Kopf- und Fußzeilen ausgegeben
werden.

Eine andere Möglichkeit, Kopf- bzw. Fußzeilen zu erzeugen, ist die
Verwendung von (!KW [use_raw_header]) bzw. (!KW [use_raw_footer]).

##################################################

!index HTML !! Tabellen
!index Umrahmung
!index Rahmen
!index Tabelle
!item [Mal wird eine Tabelle umrahmt dargestellt, mal nicht!?]
Bei HTML können Sie leider nur angeben, ob die gesamte Tabelle
umrahmt werden soll oder ob sie gar nicht mit einem Rahmen
dargestellt werden soll.

Um eine Tabelle mit Rahmen darzustellen, müssen Sie bei
(!KW [begin_table]) den Befehle (!KW [hline]) angeben. Fehlt (!KW [hline]) bei diesem
Befehl, wird die Tabelle ohne Rahmen dargestellt.

##################################################

!index HTML !! Dateiendungen
!item [Wie legt UDO die Endungen der Dateien fest?]
UDO benutzt als Endung für die HTML-Dateien immer die Endung des
in der Kommandozeile mit der Option (!code [(--!)outfile]) bzw. (!code [-o]) übergebenen
Dateinamens:

!begin_tlist [-o INDEX.HTML] !compressed
!item [-o index.htm]  (!file [.htm])
!item [-o index.html] (!file [.html])
!item [-o INDEX.HTML] (!file [.HTML])
!end_tlist

Wenn Sie stattdessen die Option (!code [-o~!/]) verwenden, benutzt UDO für
8+3-Dateisysteme immer die Endung (!file [.htm]), bei Dateisystemen, die
lange Namen erlauben, hingegen immer die Endung (!file [.html]).

##################################################

!item [Die Dateinamen bei den Querverweisen stimmen nicht!?]
Falls Sie HTML-Dateien auf einem Betriebssystem erstellen, das
keine langen Namen zulässt, Sie als Endung (!file [.html]) vorgegeben haben
und Sie diese Dateien dann auf einem Web-Server ablegen, so
müssen Sie folgendes beachten:

!begin_enumerate !compressed
!item UDO versucht zwar, (!file [foo.html]) zu sichern, TOS und DOS sichern
die Datei jedoch nur als (!file [foo.htm]).

!item UDO benutzt für alle Querverweise die Endung (!file [.html]). Wenn nun
ein HTML-Browser unter TOS und DOS versucht, (!file [foo.html]) zu
öffnen, öffnet dieser anstandslos (!file [foo.htm]).

!item Nach dem Kopieren der Dateien auf den Web-Server (!B)müssen(!b)
die Endungen der Dateien von (!file [.htm]) auf (!file [.html]) angepaßt werden.
Hier wird (!file [foo.htm]) nicht geöffnet, wenn auf (!file [foo.html])
zugegriffen werden soll!
!end_enumerate

##################################################

!index Hintergrundmusik
!index HTML !! Hintergrundmusik
!item [Wie kann ich Hintergrundmusik einbinden?]
Hierfür steht das Kommando (!KW [html_bgsound]) zur Verfügung.

##################################################

!end_description

# = = =

!begin_node HTML-Auszeichnung mit CSS
!html_name  format_html_css

Seit UDO~7 werden bei der HTML-Ausgabe mehr Attribute ausgegeben, die über CSS formatierbar sind.

!label CSS-Klassen für HTML allgemein
!begin_description
!item [CSS-Klassen für HTML allgemein]
!label UDO_index_list
!begin_blist
!item [UDO_index_list]
Dieser Klassenname wird für eine <div>-Umgebung verwendet, mit
der die Sprungmarkenleiste (A-Z) in der (!B)indexudo(!b)-Seite
formatiert wird.

!label UDO_index_group
!item [UDO_index_group]
Dieser Klassenname wird für eine <p>-Umgebung verwendet, die alle Index-Einträge für eine Sprungmarke, also für einen Buchstaben enthält.
So können Sie z.B. einen Buchstaben-Gruppe in einem langen Index mit einem größeren Abstand zum nächsten Abschnitt versehen oder die Gruppen farbig hervorheben.

!label UDO_index_name
!item [UDO_index_name]
Dieser Klassenname wird für eine <span>-Umgebung verwendet, in der eine Sprungmarke (also ein Buchstabe aus der Sprungmarkenleiste) formatiert werden kann.
So können Sie z.B. einen Buchstaben-Abschnitt in einem langen Index größer oder farbig unterlegt hervorheben.

!label UDO_nav_index
!item [UDO_nav_index]
Die Navigationsleiste hat jetzt immer einen Link zur Index-Seite.
Der Link wird in einem Span namens ""UDO_nav_index"" ausgegeben und kann bequem per CSS z.B. rechtsbündig auf der Seite platziert werden.

!label UDO_nav_line
!item [UDO_nav_line]
Wenn Sie mit (!KW [html_navigation]) [line] eine Navigationszeile nutzen, wird sie in einer <div>-Umgebung mit diesem Klassennamen ausgegeben.
!end_blist
!end_description

!label CSS-IDs für HTML allgemein
!begin_description !not_compressed
!item [CSS-IDs für HTML allgemein]
!label UDO_menu
!begin_blist
!item [UDO_menu]
Beim ""Modern Layout"" wird die Tabelle in der linken Spalte, die das Menü zeigt, mit einer ID namens ""UDO_menu"" versehen, 
so dass das Menü beim Drucken mittels CSS ausgeblendet werden kann.

!item [UDOTOC]
Dieser Name wird als Sprungmarke zum Anfang des Inhaltsverzeichnisses verwendet.
Bei Ausgabe in HTML~5 wird er als ID verwendet.
!end_blist
!end_description

Seit UDO~7.03 wird HTML~5 unterstützt, das auf viele früher übliche HTML-Formatierungsangaben verzichtet und erwartet, dass diese über CSS gelöst werden.
Die von UDO zur Zeit unterstützten CSS-Attribute werden nachfolgend aufgeführt:

!label CSS-Klassen für HTML~5
!begin_description !not_compressed
!item [CSS-Klassen für HTML~5]
Die nachfolgend aufgeführten Attribute werden immer als entsprechende Klassennamen verwendet und sollten selbsterklärend sein.
Alle Klassen beginnen mit ""UDO_"", um Namenskonflikte mit evtl. schon bestehenden CSS-Klassennamen in Ihren Dokumenten zu vermeiden.
Anschließend kommen der Tag-Name, das Attribut und die Eigenschaft, jeweils durch Unterstrich getrennt.

!label UDO_caption_valign_bottom
!begin_blist
!item [UDO_caption_valign_bottom]
!label UDO_div_align_center
!item [UDO_div_align_center]
!label UDO_div_align_left
!item [UDO_div_align_left]
!label UDO_div_align_right
!item [UDO_div_align_right]
!label UDO_h1_align_center
!item [UDO_h1_align_center]
!label UDO_h2_align_center
!item [UDO_h2_align_center]
!label UDO_p_align_center
!item [UDO_p_align_center]
!label UDO_p_align_right
!item [UDO_p_align_right]
!label UDO_span_tt
!item [UDO_span_tt]
Da HTML~5 das <tt>-Tag nicht mehr unterstützt, wird es mit einer <span>-Umgebung nachgebildet. 
Die Formatierung geschieht über CSS.
!label UDO_td_align_center
!item [UDO_td_align_center]
!label UDO_td_align_right
!item [UDO_td_align_right]
!label UDO_td_nowrap
!item [UDO_td_nowrap]
!label UDO_td_valign_top
!item [UDO_td_valign_top]
!end_blist

!label CSS-IDs
!item [CSS-IDs]
HTML~5 unterstützt bei Ankern nicht mehr das ""name""-Attribut.
Daher werden alle Sprungmarken in HTML~5 über IDs erzeugt.
Achten Sie darauf, dass Sie eigene IDs in Ihrer CSS-Datei mit den von UDO automatisch vergebenen abgleichen, damit es keine ID-Namenskonflikte gibt.
      
      (!EXAMPLE)
      (!EXAMPLE_BEFORE) (!nl)
      <a name="einName">
      (!EXAMPLE_AFTER) (!nl)
      <a id="einName">
      (!EXAMPLE_END)

!label CSS-Beispiel für HTML~5
!item [CSS-Beispiel für HTML~5]
!begin_quote
!begin_verbatim
/* UDO HTML5 classes */
.UDO_caption_valign_bottom {
   /* <http://www.w3.org/wiki/CSS/Properties/vertical-align>
    * baseline, sub, super, top, text-top, middle,
    * bottom, text-bottom, length, or a value in percentage
    */
    vertical-align:text-bottom;
}

.UDO_div_align_left {}

.UDO_div_align_center {
   margin-left:auto;
   margin-right:auto;
   text-align:center;
}

.UDO_div_align_right {
   text-align:right;
}

.UDO_span_tt {
   font-size: 16px;
   font-family: Courier, monospace;
   color: #2E4793;
}

.UDO_h1_align_center,
.UDO_h2_align_center,
.UDO_p_align_center,
.UDO_td_align_center {
   /* <http://www.w3.org/wiki/CSS/Properties/text-align>
    * left, right, center, justify, inherit
    */
   text-align:center;
}

.UDO_p_align_right,
.UDO_td_align_right {
   /* <http://www.w3.org/wiki/CSS/Properties/text-align>
    * left, right, center, justify, inherit
    */
   text-align:right;
}

.UDO_td_nowrap {
   white-space:nowrap;
}

.UDO_td_valign_top {
   /* <http://www.w3.org/wiki/CSS/Properties/vertical-align>
    * baseline, sub, super, top, text-top, middle,
    * bottom, text-bottom, length, or a value in percentage
    */
    vertical-align: top;
}
!end_verbatim
!end_quote
!end_description

!end_node # HTML-Auszeichnung mit CSS

# = = =

!end_node
