################################################################################
#
# Project     : UDO manual
# Chapter     : Formats: HTML (Hypertext Markup Language)
# Language    : English
# 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 08: quotation changed
#   fd  Jun 09: macro (!file) introduced
#   fd  Jun 10: using macro (!file [])
#   fd  Jun 10: using macro (!code [])
#   fd  Jun 16: great review session #1
# 2010:
#   fd  Mar 05: old environment attribute short changed: -> !compressed
# 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 is one of the most used target formats being created by UDO. It is
also one of the most used formats for online documentations. Therefore,
HTML output format generates the most questions, too. Here is the FAQ
collection:

!begin_description !not_compressed

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

!item [How to navigate in HTML pages using the keyboard?]
Basically, the HTML output creates clickable navigation buttons in the headlines and footers of each page.
These buttons reflect the hierarchy of the document with a Home button and some arrow buttons.
      
As of version 7.04, UDO adds IDs to the anchor tags of these buttons:
!begin_blist !compressed
!item [UDO_nav_hm_HEAD] Home: this one brings you back to the homepage of the HTML document.
!item [UDO_nav_lf_HEAD] Left: this button brings you to the previous document page in logical order.
!item [UDO_nav_up_HEAD] Up: this button brings you back one chapter hierarchy level.
!item [UDO_nav_rg_HEAD] Right: this button forwards you to the next document page in logical order.
!end_blist
      
In order to be able and access these buttons using the keyboard, we recommend to use JavaScript.
The HTML attribute ""accesskey"" requires various additional function keys, depending on the browser, and doesn't access e.g. arrow keys.
Keep in mind to not switch off the navigation buttons using (!KW [no_headlines]) and (!KW [no_footers]) in the preamble.
Then include a JavaScript file which evaluates key presses, using (!KW [html_script_name]).

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

!item [How can I tell UDO not to make files for each chapter?]
In contrast to the other formats UDO saves a separate HTML file for each
chapter by default. UDO names these files by using the chapter numbers. The
title page and the table of contents will be saved in the file you passed in
the command line.

!index !/html_merge_nodes
!index !/html_merge_subnodes
!index !/html_merge_subsubnodes
!index !/html_merge_subsubsubnodes
!index !/html_merge_subsubsubsubnodes

Using the switches
(!KW [html_merge_nodes]),
(!KW [html_merge_subnodes]),
(!KW [html_merge_subsubnodes]),
(!KW [html_merge_subsubsubnodes]) or
(!KW [html_merge_subsubsubsubnodes])
you can tell UDO not to save a file for each chapter.

If you use (!KW [html_merge_nodes]) inside the preamble UDO will save only
one HTML file that contains the whole text. You should use this option only
for small source files.

If you use (!KW [html_merge_subnodes]) UDO will save separate files only
for chapters. All sections, subsections and paragraphs of a chapter will be
saved inside this file, too.

If you use (!KW [html_merge_subsubnodes]) UDO will save separate files for
chapters and sections. The subsections and paragraphs of a section will be
saved in the file that contains the text of the superior section.

Finally if you use (!KW [html_merge_subsubsubnodes]) the paragraphs of a
subsection will be saved in the file that contains the text of the
subsection. UDO will save separate files for chapters, sections and
subsections.

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

!index !/html_name
!index HTML !! Filenames
!item [I don't like the names of the HTML files! ]
Using the command (!KW [html_name]) inside a chapter, section, subsection
or paragraph you can tell UDO which filename it shall use instead of using
a filename like "01020304.html".

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

!index udo_rg.gif
!index udo_lf.gif
!index udo_up.gif
!index HTML !! Headlines
!item [How can I suppress these ugly headlines?]
UDO will print on every HTML page a headline that contains the title of the
documentation and hypertext links to the previous, next and upper page.
UDO uses GIF files for these links that are saved by UDO automatically. The
filenames of these GIF files are (!file [udo_lf.gif]), (!file [udo_rg.gif]) and
(!file [udo_up.gif]).

!index (!kw [no_headlines])

Using the switch (!KW [no_headlines] [[html!!]]) inside the preamble you can
tell UDO not to generate these headlines.

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

!index Headlines
!index Bottomlines
!item [How can I easily make my own headlines or bottomlines?]
If you want to make your own headlines or bottomlines you can use macros
at the beginning of each chapter. The following example shows how I added
bottomlines to my WWW pages. These pages contain links to the chapters that
contain my address, the descriptions of my software and links to other web
sites.

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

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

If you convert the source file to HTML, UDO expands the macros that contain
the text of the headlines and bottomlines. Because UDO insert links
automatically you can jump to the other pages by clicking the entries of the
bottomline.

If you don't convert to HTML empty macros are used so that nothing will
appear when using (!code [(!/HEAD!)]) or (!code [(!/FOOT!)]).

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

!index HTML !! Table frames
!item [Sometimes a table has a frame, sometimes it hasn't!?]
Unfortunately HTML only allows to use tables with or without frames. You
cannot use table lines where you want to.

To print a table with a frame you have to add (!I)!/hline(!i) to the line
that contains (!KW [begin_table]). If you don't want a frame don't use
(!KW [hline]). That's all.

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

!index HTML !! Suffixes
!item [Which suffixes does UDO use for HTML files?]
By default UDO uses the suffix of the (!code [(--!)outfile]) you used in the
command line:

!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

If you use the option (!code [-o~!/]) UDO uses ''(!file [.htm])'' on operating
systems with 8+3-filenames and ''(!file [.html])'' on operating systems with
long filenames.

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

!item [The filenames of the URL's are wrong!?]
If you use UDO on an operating system that doesn't support long filenames
but you have used ""(!code [(--!)outfile index.html])"" and you copy the saved
''(!file [.htm])'' files to a web server, remember this:

!begin_enumerate
!item UDO will try to save ''(!file [index.html])'' but TOS and DOS will
name it ''(!file [index.htm])''.

!item UDO will use for all hypertext links the suffix ''(!file [.html])''
because of the suffix of the ""outfile"". If you use a HTML browser for TOS
or DOS this browser will open ''(!file [index.html])'' without any problems
even if there's only a file named ''(!file [index.htm])''.

!item When copying the files to a web server you have to change the
suffixes from ''(!file [.htm])'' to ''(!file [.html])''. If you will forget this
all links will be wrong.
!end_enumerate

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

!index Background music
!index HTML !! background !! music
!item [How can I include background music?]
Use the command (!KW [html_bgsound]).

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

!end_description

# = = =

!begin_node HTML markup with CSS
!html_name format_html_css

Since UDO~7 more attributes are written in the HTML output, which can be formatted via CSS.

!label CSS classes for HTML in general
!begin_description
!item [CSS classes for HTML in general]
!label UDO_index_list
!begin_blist
!item [UDO_index_list]
This class name is used in a <div> environment which formats the jump marks bar (A-Z) in the (!B)indexudo(!b) page.

!label UDO_index_group
!item [UDO_index_group]
This class name is used in a <p> environment which contains all index entries for a jump mark, which stands for a letter or character.
This way you can e.g. separate a letter's group in a long index page to the next section, or you can mark up the groups with color.

!label UDO_index_name
!item [UDO_index_name]
This class name is used in a <span> environment in which the jump mark (i.e. a letter or character from the jump marks bar) can be formatted.
This way you can e.g. enlarge a letter in front of a letter's group or add a colored background.

!label UDO_nav_index
!item [UDO_nav_index]
The navigation bar now always has a link to the index page.
The link is output in a <span> environment with the class name ""UDO_nav_index"" and therefore can be easily right-adjusted on the page via CSS.

!label UDO_nav_line
!item [UDO_nav_line]
When you use a navigation bar with (!KW [html_navigation]) [line], it will be output in a <div> environment with this class name.
!end_blist
!end_description

!label CSS IDs for HTML in general
!begin_description !not_compressed
!item [CSS IDs for HTML in general]
!label UDO_menu
!begin_blist
!item [UDO_menu]
The table which shows the menu in the left column of ""Modern Layout"", now has an ID named ""UDO_menu"". 
You might e.g. want to hide it via CSS for print output, etc.

!item [UDOTOC]
This name is used as jump mark to the start of the table of contents .
When output into HTML~5, it will be used as an ID.
!end_blist
!end_description

Since UDO~7.03, HTML~5 is supported, which no longer supports some formerly usual HTML formattings and expects to rebuild these in CSS.
The CSS attributes which are currently supported by UDO, are listed below:

!label CSS classes for HTML~5
!begin_description !not_compressed
!item [CSS classes for HTML~5]
The following attributes are always used as class names and should be self-explanatory.
All classes start with ""UDO_"" in order to avoid name conflicts with eventually already existing CSS class names in your documents.
Then follows the tag name, the attribute and the property, each of them separated by an underscore.

!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]
Because HTML~5 no longer supports the <tt> tag, we rebuild it with a <span> environment. 
Formatting is done via 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 no longer supports the ""name"" attribute for anchors.
Therefore all jump marks in HTML~5 are realized with IDs.
Please control that your own IDs in your CSS file do not cause any conflict with those which are automatically generated by UDO.
      
      (!EXAMPLE)
      (!EXAMPLE_BEFORE) (!nl)
      <a name="aName">
      (!EXAMPLE_AFTER) (!nl)
      <a id="aName">
      (!EXAMPLE_END)

!label CSS example for HTML~5
!item [CSS example for 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 markup with CSS

# = = =

!end_node
