                                    DDF2Html
                                    ~~~~~~~~

  ..                
  |.  /'/ |      
  |  |_\/ / | |      vsn 150 6th July 2003
  |==  | / _/ |.     
  |= = |/_/   |     |          
  |=== /     |     V          Converts Impression
  '/.    Publisher DDF files
       |      |   =====   |    (Save text story
       |      |_ ---------|     with styles)  to
       '>|*. ======|    an HTML document.
              |**\ =====|    
              |***| ====|    Please read instructions!
              ''    

  ============================================================================

                                C o n t e n t s
                                ~~~~~~~~~~~~~~~

           Purpose of program

           Creating DDF files

           The main window:  saving out HTML files
             Mapping characters to specific entities
             Progress window

           Conversion of standard styles/effects
             HTML tags recognised
             DDF2Html and Impression lists

           Mapping styles to specific HTML tags
             Mappings menu
               Mappings files
             Special styles which affect DDF2Html

             History

             
  ============================================================================

                                Purpose of program
                                ~~~~~~~~~~~~~~~~~~

       DDF2Html is a program to make it easy to convert Impression documents
        into HTML format, either for use as Web pages or simply in order to
        send them to PC-owning friends.   Simply use the 'Save text with
        styles' option from within Impression and run the resulting output
        through DDF2Html  to translate Impression styles/effects into HTML
        mark-up.
       The program also incorporates the features of John Alldred's
        Text2Html, importing plain text files, converting any characters
        which are illegal in HTML, and making a spirited attempt to preserve
        any paragraph formatting present in the original  again, useful as a
        way of circumventing different character set/line-ending conventions
        when sending files to Mac/PC owners.
       Finally, it can be used to 'tidy-up' existing HTML files by
        converting any illegal characters it finds which ought to be entities
        but aren't!   (Note that it assumes the [RISC OS default] Latin-1
        character set, however, so can't be used to fix files using
        Windows-specific quote characters.)

    DDF2Html should run as supplied on all computers with RISC OS 31 to RISC
    OS 5 (it may well work under RISC OS 2, but I have been unable to test
    whether this is still the case!), and requires about 128K of free RAM.
    It can be run from a read-only medium such as CD-ROM without errors.

    Impression owners may find Mike Williams' /UnHTML/ (available on the
    Datafile's PDCD4 and from the Internet) a useful companion program.
    This performs a similar process in reverse, allowing the import of basic
    HTML formatting into Impression.
    ==========================================================================


                                Creating DDF files
                                ~~~~~~~~~~~~~~~~~~

    DDF2Html will attempt to convert any file that can be saved out as DDF
    from Impression.   Note that the DDF format does *not* include frame
    information nor embedded graphics, so these will not appear in the output
    HTML.
 
    To create a DDF file, make sure the cursor is in the main frame of your
    Impression document and press CTRL-F3 (Ctrl-Shift-T in Impression II),
    or Adjust-click on the Save icon.
 
    The 'With styles' icon should be selected;  the 'Linefeeds' and 'Returns'
    icons should be *clear*. (You should not need to alter the default
    settings as provided by Impression.)
 
    Save the file to disc or directly into DDF2Html.
    ==========================================================================

                     The main window:  saving out HTML files
                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    When you drag a DDF file to the DDF2Html iconbar icon, the main window
    will open, allowing you to set various options before saving out the
    corresponding HTML file.

    The Input section gives details on the file that has just been loaded
     filename, size and type (DDF, HTML or plain Text).
    The Output section allows you to edit the text that will be
    displayed in the titlebar of the browser window (if processing an
    existing HTML file, the currently-defined page title will
    be supplied here;  otherwise it defaults to 'Untitled').

    A pair of radio icons allow you to select which set of entities will
    be used to translate characters outside the basic ASCII set.

    The suggested save leafname is based on six characters of the
    input leafname plus the extension '/html' (automatically truncated to
    '/htm' on filing systems not supporting long filenames).   Edit
    it as required, then drag the file icon to save out the converted file.
    
   The progress window will then open, allowing you to abort the conversion.
    ==========================================================================

                      Mapping characters to specific entities
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

      All reserved characters and top-bit-set characters in the original text
      are replaced by entities (such as &lt; for < and &copy for ).   These
      substitutions are defined by two configuration files, Glyphs3 and
      Glyphs4, which are used to look up the entity names and/or what to
      substitute for illegal characters.

      The setting of the radio icons on the main window controls which set of
      entities will be used for a given input file   the old HTML 32 set,
      as supplied with original versions of DDF2Html, or the new HTML 4 set,
      which adds 'smart' quotes and characters such as the bullet point, long
      em-dash and ellipsis.  (Note that the majority of browsers currently
      support only a subset of the HTML 4 entities.)

      These radio icons take the place of the 'Bullet' settings panel in
      earlier versions of the program, since HTML 4 defines a specific
      "&bull;" character!   The default now used to represent bullet points
      under the HTML 32 setting is the bold asterisk, "<B>*</B>":   to alter
      this, edit the string at character position 143 in the Glyphs3 file.

      The setting of these icons will also affect which <DOCTYPE is declared
      at the head of the output page.   Their default setting is read from
      the system variable <DDF2Html$HTMLver>, defined in the application's
      !Boot file.
    ========================================================================

                                  Progress window
                                  ~~~~~~~~~~~~~~~

      Depending on the speed of your computer, what other background
      processes are going on, and the size of the source file, it can take
      DDF2Html a relatively long time to save out an HTML file.

      The program displays a progress window while multitasking to indicate
      how the conversion is progressing.   The green bar shows what point in
      the file it has currently reached.   (In the case of DDF files, which
      contain a large 'prologue' defining the various styles, the progress
      window may open with the green bar apparently indicating that it has
      started converting halfway through the file.   This is quite normal!)

      A small menu can be brought up from this window with the single entry
      'Cancel'.   Selecting this will abort the process, leaving you with a
      truncated (but if possible still valid) HTML file.
      ========================================================================

                               What gets converted
                               ~~~~~~~~~~~~~~~~~~~

    Global definitions
    ~~~~~~~~~~~~~~~~~~
       Base text size and colour
       Heading alignment
       Paragraphing

    Style conversions
    ~~~~~~~~~~~~~~~~~
       Standard Impression styles
       Styles corresponding to HTML tag names
       Mapping other styles to specific HTML tags
       Special styles which affect DDF2Html

    Effects conversions
    ~~~~~~~~~~~~~~~~~~~
       Tab characters
       Font size\/colour
       Other font effects
       Alignment
       Nextframe


       Styles whose names correspond to a suitable HTML tag become the tag
        of that name, i.e. a region to which a "Blockquote" style has been
        applied will be enclosed in <BLOCKQUOTE> tags.

       A horizontal ruleoff will be inserted at the *start* of any "HR"
        region.

       Support for nested lists - any styles starting <UL_1>, <OL_2>, <UL_3>
        etc will be recognised and treated as occurrences of <UL> or <OL>.
        This allows you to work around the problem that identical occurrences
        of an Impression style cannot be nested.

    The 'standard' styles (as found in the default Impression document) are
    converted as follows:

       "Main Heading" and "Sub-Heading" become <H1> and <H2>

       "1in indent" becomes <BLOCKQUOTE>

       "Hanging indent" becomes <DL>, but not very successfully (better
        results will often be obtained by using Impression's own
        numbered\/bulleted list handling)

       "Table" becomes <TABLE>

       "Bold" and "Italic" (ImpressionII) become <STRONG> and <EM>

    The point size and colour of text in Normal/BaseStyle *only* are noted.

    The colour is used to set the base colour in the document's BODY tag, and
    the size is used to translate any subsequent {fontsize} effects into BIG
    or SMALL according to whether they are larger or smaller than this 'base'
    size.

    The alignment (right/left/centre) of any 'heading' styles ("Main Heading",
    "Sub-Heading", plus styles "H1""H6", if present) are noted, and
    reproduced
    thereafter throughout the document using the <H1 ALIGN="CENTER"> syntax.

    If the Normal/BaseStyle has the 'space above' and/or 'space below'
    paragraph attributes set, then all Impression paragraphs become <P>
    save for list items.    Otherwise the program assumes that you are
    using blank lines to indicate separation between paragraphs;  single
    newlines become <BR> and double newlines become <P>.

    {tab} becomes <TD> if within a 'Table' style, <DD> if within a 'DL'
    style, or "&nbsp; &nbsp;" otherwise.

       {fontsize} becomes <BIG> or <SMALL>, relative to the 'base' size.

       {fontcolour} becomes <FONTCOLOR=...>.

       {font} is ignored unless it specifies Corpus.* or *.Monospaced or
        *.Fixed, when it inserts either <TT> or <PRE> according to whim.

       {bold} and {italic} (Impression Publisher/Style)
        become <B> and <I>

       {superscript} and {subscript} become <SUP> and <SUB>

    "justify left/centre/right" becomes <DIVALIGN=LEFT/CENTER/RIGHT>.

    {nextframe} (often indicating the end of a column/section) becomes <HR>.
    ==========================================================================

                                HTML tags recognised
                                ~~~~~~~~~~~~~~~~~~~~

      The style-names currently recognised as tags, upper or lower case, with
      or without <>, are:

      B           CENTER  EM  H3  H6  OL     STRIKE  SUP  UL 
      BIG         CITE    H1  H4  HR  PRE    STRONG  TT   VAR
      BLOCKQUOTE  CODE    H2  H5  I   SMALL  SUB     U       

      Two other styles, shown in blue on the tags menu in the Style map
      window, are also recognised by DDF2Html, but these have a slightly more
      drastic effect:

         Within a region defined as a <TABLE> style, tab characters will be
          replaced by <TD> and <TR> be placed at the start of every line.
         Within a region defined as a <DL> (definition list) style, the
          first part of the line will receive a <DT> tag, and any section
          following a tab will receive a <DD> tag.
      ========================================================================

                           DDF2Html and Impression lists
                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

      Later versions of Impression contain support for auto-numbered/bulleted
      lists, where if you add or delete entries the remaining numbers will
      adjust.   DDF2Html can recognise and convert these lists into HTML list
      entries of the relevant type, although you will still need to apply a
      <UL> or <OL> style to the list as a whole.   (Numbered lists are often
      indented from the main text using a special ruler style in any case.)

      In order to create a numbered list in Impression, either
         select a region of text and choose Insert=>Number region
          (Ctrl-Shift-F10) from the menu, specifying the correct number
          sequence (1,2,3;a,b,c;i,ii,iii;,,;A,B,C;I,II,III), which will
          assign consecutive numbers to each paragraph
         or choose Insert=>Initial number from the menu to insert the start
          of a new sequence, and Insert=>Subsequent number (Ctrl-Shift-F9)
          every time you want the next number in the sequence.

      To create a nested sub-list:
       A. 1)           Use Insert=>Initial number again with a different
                       numbering type, when
          2)           a new sequence will be started.
          3)   
       B.              To resume the old sequence, use Insert=>Subsequent
                       number but specify
       C. 1)           the previous numbering type, and Impression will
                       insert the next number
          2)           in /that/ sequence.
       D. 

      Note that Impression does not allow you to overlay more than one
      occurrence of the same style  for example, a second instance of an
      <OL> style to signify a sub-list  so DDF2Html checks OL and UL tags in
      a special way.   It will treat any occurrence of a tag whose name
      consists of "OL_" or "UL_" plus a number as if it were a plain OL or UL
      tag.

      You can thus define UL_1, UL_2, etc., with successive degrees of
      indentation, and apply UL_1 to the whole list, UL_2 to each subsection,
      and UL_3 (for example) to a sub-list of points within that, and obtain
      a similar appearance to that desired within the Web browser.
      ------------------------------------------------------------------------
      (This last feature has been somewhat superseded in versions 1.50+ by a
      more generalised facility for converting multiple similar styles of
      *any* name to a single output tag - see Style mapping)
      ========================================================================

                       Mapping styles to specific HTML tags
                       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    When converting an existing Impression document, it is often not
    practical or desirable to edit the names of all your styles in order to
    match them with the tag names to which you wish them to be converted.

    As of DDF2Html version 150, there is a new facility to 'map' specific
    styles present in a given DDF file to HTML tags  either via the menus
    provided, or, by typing them into the writable menu entry, from *any*
    style to *any* tag.

    Select 'Styles...' from the iconbar menu to open the style map window.
    By default, this window will be empty.   If you click on the pop-up menu
    icon attached to an icon in the right-hand column, you can select from a
    menu of HTML tags;  if you click on a menu icon attached to the left-hand
    column, you can select from the currently-available DDF styles.

    Unless you have already loaded a DDF file, this menu will initially
    contain only the two default entries, 'delete line' followed by a
    writable menu item at the bottom of the menu.  You may type any style
    name you choose here  but if you drag a DDF file directly to the window,
    or if one has already been loaded for conversion, you will instead be
    presented with a menu of all the styles available in that document.
    Dragging a different DDF file to this window will alter the contents of
    the menu rather than converting that file, but will not affect the
    contents of any icons that have already been defined.   Case is not
    significant.

    Any style name appearing in the left-hand column will be converted into
    the corresponding tag name on the same row.   You may enter style and tag
    names either by selecting them from the menu or by typing them into their
    respective writable menu entries.    The window will enlarge as necessary
    up to a maximum of 60 rows.   Selecting the 'delete row' entry from the
    DDF style menu will blank out that entire row, removing the definition 
    blank rows are ignored when translating files.

    Clicking MENU over this window will bring up the Mappings menu, allowing
    you to control the contents of the window as a whole.

    Note that the 'default' Impression styles  'Main heading',
    'Sub-Heading', '1in indent', 'Hanging indent' and 'Table'  are already
    mapped by default to <H1>, <H2>, <BLOCKQUOTE>, <DL> and <TABLE>
    respectively.   If you specify a different mapping in this window, this
    will replace the default.

    Styles with the 'reserved' names 'Tag', 'Link', 'Name' and 'Comment' are
    interpreted as special cases by DDF2Html.   They cannot be remapped, and
    even if present in the document will not appear on this menu.


    By convention, DDF styles are displayed 'as defined' in the style menu
    and in lowercase with a leading capital letter in the display icons,
    while HTML tags are displayed in uppercase in the tag menu and all in
    lowercase in the display icons (to avoid the need for an enormously wide
    window!)

    However, all style/tag data is stored in uppercase internally for
    comparison purposes, and appears as such in the output.
    ==========================================================================

                                   Mappings menu
                                   ~~~~~~~~~~~~~

      It can be convenient to have separate sets of style->tag mappings
      defined for use with different documents, and it is certainly
      convenient not to have to re-enter your mappings every time you run the
      program!   DDF2Html allows you to save sets of mappings, either as the
      default setting (within Boot\:Choices or inside the program) or as
      separate files, which can be stored alongside the documents to which
      they refer and reloaded at a later stage.


         'Save' leads to a savebox which can be used to save out the current
          mappings as a mappings file to any convenient location.
         'Save as default' will overwrite the old default mappings (if any)
          with the current settings, after asking for confirmation.

      The other two entries allow you to change the contents of the whole
      window without redefining each icon one by one:
         'Reload default' reloads the saved default from disc (useful if you
          have been customising it for a specific purpose and wish to revert
          without restarting the program)
         'Delete all' deletes *all* current mappings and leaves you with a
          blank window ready for new entries.
      ========================================================================

                                    Mappings files
                                    ~~~~~~~~~~~~~~

        Mappings files consist of a single line reading "!Mappings", followed
        by one or more lines containing a DDF style name, followed by a tab
        character and then an HTML tag name.
        Example:

            !Mappings
            ATTRIBUTION|--|CITE
            QUOTES|-------|BLOCKQUOTE
            SUPERSCRIPT|--|SUP

        The case of the entries is not significant.

        DDF2Html checks the initial line of any text file dragged to one of
        its windows;  if it appears to be a mappings file, instead of
        offering to convert it to HTML it will use the mappings defined there
        to replace any style mappings currently present, and then open the
        Style map window to show the contents of the file.
        ======================================================================


                        Special styles which affect DDF2Html
                        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

      Four /special/ styles have significance to DDF2Html, although they do
      not correspond literally to HTML tags:

         Tag  Any section of text to which a style called "Tag" has been
               applied will be inserted *verbatim*, save that 'smart quotes'
               will be converted into plain ones. This allows you to maintain
               a few literal HTML tags in your Impression document,
               *provided* you know what you are doing!
         Link If you apply a style called "Link" to text that looks like an
               absolute URL, an HTML link will be generated.
         Name      Any text to which a style "Name" is applied will be
                    converted into an "<A name=" tag, allowing you to
                    reference subsections of your document from other pages.
         Comment   Text in a "Comment" style will be inserted as an HTML
                    comment.

      Examples

      The *Tag* style allows you to type literal HTML tags as necessary.
      The typed string <BR clear=left>  in Impression, with this style
      applied, would be exported as DDF in the form
       {"Tag" on}<BR clear={\148}left{\149}>{"Tag" off}
      and converted back into <BR clear="left"> in the output HTML file.

      The *Link* style applied to the string http://news.fornost.com would
      produce the output
       <AHREF="http://news.fornost.com">http://news.fornost.com</A>
      However, applying the Link style to the string Norbury Times would produce
       <A HREF="">Norbury Times</A>, with the URL left blank.

      The *Name* style applied to the last word of The Wild Bunch would produce
       The Wild <A name="Bunch">Bunch</A>

      Finally, the *Comment* style, if detected, will simply enclose the
      relevant text in "<!-- -->"
       <!--This is a comment-->
      ========================================================================

                                    Version 1.50
                                    ~~~~~~~~~~~~

      17th June 2003  v150 *MAJOR UPGRADE*
         Added Style mapping - facility to 'map' a given Impression DDF
          style to a given HTML tag without having to rename it in the
          original document, including mapping to TABLE and DL styles.   Took
          advantage of this to remove the special-case handling for default
          mappings ("Main Heading", "Sub-heading", "1in indent", "Hanging
          indent", "Table", "Bold" and "Italic") :-)
         Removed recognition by default for some of the more obscure tags -
          ACRONYM, ADDRESS, DEL, DFN, INS, KBD, S - in order to make the
          pop-up menu more manageable!
         Removed old radio icons giving a choice of fake bullet styles from
          main window (far less of an issue since DDF2Html started supporting
          the native Impression list format), and replaced with radio icons
          giving a choice between mapping to HTML 3.2 entities or to HTML 4
          entities (which include a true "&bull;" character!).   Provided
          *two* Glyphs files corresponding to the two mappings.   The
          selection is reflected in the DOCTYPE header.   (The default 3.2
          'fake bullet' is now the asterisk -- edit Glyphs3 to change
          this....)
         Glyphs and Mappings files will be searched for in and saved to
          Choices:DDF2Html, if Choices$Path exists.
         Fixed message handling somewhat;  DDF2Html can now save directly
          into other applications, although most Web browsers don't seem to
          support this....
         Added Sliding Heap support, to make possible dynamically resizing
          number of icons in Style map window and entries in DDF style menu.
          Much data moved into sliding blocks from static DIMs.
         Detection for special treatment of the "Main Heading",
          "Sub-heading", "1in indent", "Hanging indent", "Table", "Bold" and
          "Italic" Impression default styles is no longer case-sensitive.
         Rationalised window creation code somewhat (removed duplicated
          procedures, unnecessary use of global variables to pass parameters)
         Dragging file icons from the Pinboard could crash the program - the
          Pinboard gives an estimated size of 1 instead of -1 for "unknown",
          and DDF2Html was mindlessly believing this!


    +----------------------------------------------------------------------+
    |                                                                      |
    | This text file was converted from a StrongHelp manual on 3 Jul 2003  |
    |                                                                      |
    |             using !StHlp2Txt version 1.10 (8 June 2001)              |
    |                           by Chris Morison                           |
    |                                                                      |
    |               email: organizer@morison.net                           |
    |                 web: http://www.organizer.morison.net/               |
    |                                                                      |
    +----------------------------------------------------------------------+

