<COMMENT>(--------------------------------------------------------------------)

<FRONT_MATTER>
<TITLE_PAGE>

<TITLE>(SDM2HTM -\An SDML to HTML Converter)

<COMMENT>(HTML/OFF)
<LINE>
<COMMENT>(HTML/ON)

<HEAD>(March 1998\head_date)

<P> Supercedes: 

<CODE_EXAMPLE>
     July 1997
     October 1994
<ENDCODE_EXAMPLE>

<HEAD>(Abstract\head_abstract)

<P>
This document is a guide to the use of the SDML to HTML converter.  SDML is 
the Standard Digital Markup Language used as source for <EMPHASIS>(VAX 
DOCUMENT\SMALLCAPS).  Much of WASD systems documentation is written using 
SDML.  It allows the production of printed and Bookreader documents, and now 
Hypertext, from the one source. 

<P>
The utility is provided <EMPHASIS>(as-is).

<P>
This document assumes a basic understanding of both HTML and SDML / VAX 
DOCUMENT.

<HEAD>(Author\head_author)

<P> Mark G. Daniel
<LINE> Intelligence, Surveillance & Reconnaissance Division
<LINE> Defence Science and Technology Organisation

<P> For WASD-related email please use

<COMMENT>(HTML=
<A HREF="mailto:Mark.Daniel@vsm.com.au">Mark.Daniel@vsm.com.au</A>
)

<COMMENT>(HTML/OFF)
<UNDERLINE>(Mark.Daniel@vsm.com.au)
<COMMENT>(HTML/ON)

<P> Should the above address present problems or provide no response for an
extended period then use

<UNDERLINE>(Mark.Daniel@dsto.defence.gov.au)

<P> <EMPHASIS>(A pox on the houses of all SPAMers.  Make that two poxes.)

<P> +61 (8) 82596189 (bus) 
<LINE> +61 (8) 82596673 (fax)

<P> PO Box 1500
<LINE> Edinburgh
<LINE> South Australia 5108

<HEAD>(Printed Copy\head_printed_copy)

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P>
For Hypertext browsers a <I>PostScript</I>version of this document is 
available for 
 <A HREF="/ht_root/doc/sdm2htm/sdm2htm.ps">viewing</A>
 and 
 <A HREF="/print/ht_root/doc/sdm2htm/sdm2htm.ps">printing</A>.
)

<COMMENT>(....................................................................)

<COMMENT>(HTML/OFF)
<P>
It is strongly suggested those using printed versions of this document also
access the Hypertext version.  It provides online demonstrations of some
concepts.
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<ENDTITLE_PAGE>

<COMMENT>(--------------------------------------------------------------------)

<COPYRIGHT_PAGE>

<P>
<COMMENT>(HTML=
<B>
WASD VMS Hypertext Services,
Copyright &copy; 1996-1998
Mark G. Daniel.
</B> 
)

<COMMENT>(HTML/OFF)
<EMPHASIS>(WASD VMS Hypertext Services,
Copyright (C) 1996-1998
Mark G. Daniel.
\BOLD) 
<COMMENT>(HTML/ON) 

<P> This package is free software; you can redistribute it and/or modify it 
under the terms of the GNU General Public License as published by the Free 
Software Foundation; version 2 of the License, or any later version. 

<P> This package is distributed in the hope that it will be useful, but 
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more 
details. 

<P> You should have received a copy of the GNU General Public License along 
with this package; if not, write to the Free Software Foundation, Inc., 675 
Mass Ave, Cambridge, MA 02139, USA. 

<ENDCOPYRIGHT_PAGE>

<CONTENTS_FILE>

<ENDFRONT_MATTER>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Introduction\chapter_introduction)

<P>
The SDM2HTM utility converts SDML documents into HTML documents.  SDML is the 
Standard Digital Markup Language used as source for <EMPHASIS>(VAX 
DOCUMENT\SMALLCAPS).  HTML is the HyperText Markup Language used as the native 
<EMPHASIS>(rich text) of the Hypertext environment.  Hypertext documents 
produced by this utility look and behave very much like their Bookreader 
cousins. It is not an exhaustive implementation, basically just enough to
support the simple documents of the WASD server environment, although it may
provide enough for other purposes.

<P>
Special constructs allow the inclusion of content in only the HTML version of 
a document, or only in the printed/Bookreader versions.

<P>
The utility contains no syntax checks in itself, and relies on a syntactically 
correct SDML source.  It has worked well on all documents syntactically 
verified by prior formatting against VAX DOCUMENT.  It contains fixed-size 
buffers making it vulnerable to atypically large 
<EMPHASIS>(<LITERAL>(<tag>)(...)\SMALLCAPS) constructs (tags with parameters),
and syntax errors not closing certain constructs.

<P>
A <EMPHASIS>(buffer overflow) error is generated if buffer space is exhausted. 

<COMMENT>(....................................................................)

<COMMENT>(the "<COMMENT>(HTML/OFF)...<COMMENT>(HTML/ON)" construct cause this 
section to appear in printed and Bookreader but not Hypertext documents) 

<COMMENT>(HTML/OFF)
<P>
It is strongly suggested those using printed versions of this document also
access the Hypertext version.  It provides online demonstrations of some
concepts.
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Generated HTML Documents\chapter_html_documents)

<P>
The HTML generated is designed to make the browsed HTML document look and 
behave much like the equivalent Bookreader document.  It generates a 
<EMPHASIS>(title page) and <EMPHASIS>(table of contents) from which 
<EMPHASIS>(chapters) and <EMPHASIS>(headings) may be selected and moved to.  
<EMPHASIS>(References) to other sections of the document are supported, as 
are <EMPHASIS>(formal examples) and <EMPHASIS>(formal tables).  It does not 
support the generation of an index. 

<P>
SDM2HTM control statements allow the embedding of <EMPHASIS>(raw) HTML for 
inclusion in the HTML documents only.  This allows functionality only 
belonging to the Hypertext environment to be employed (e.g. extra-document 
referencing).  HTML output can be turned on and off allowing content to be 
included in printed/Bookreader documents only.

<P>
SDM2HTM generates a separate file for the table of contents, the title page, 
each chapter, and each formal example and formal table.  It also generates a 
file for the SDM2HTM <EMPHASIS>(HTML/POPUP=\SMALLCAPS) directive, see 
<REFERENCE>(chapter_hypertext_only).

<P>
Commentary inserted at the beginning of each generated HTML file includes the 
name of the file it was generated from, the utility and version used, and the 
date. 

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
<P>
The following <A HREF="*.HTML">directory listing</A> of the files comprising 
this current document illustrates the file naming schema.  The 
<TT>*_0000.HTML</TT> is the table-of-contents file, <TT>*_0100.HTML</TT> is 
chapter one, <TT>*_0200.HTML</TT> is chapter two, etc.  Sub-Chapters (formal 
examples, etc.), if present, number <TT>*_0101.HTML</TT>, etc.  The title page 
is <TT>*_0001.HTML</TT>. 

<P>
The <A HREF="SDM2HTM.SDML">SDML source</A> for this current document is also 
available for viewing.
) 
 
<COMMENT>(....................................................................)

<COMMENT>(the "<COMMENT>(HTML/OFF)...<COMMENT>(HTML/ON)" construct cause this 
section to appear in printed and Bookreader but not Hypertext documents) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<P><BOX>(online document SDML source)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Content For Hypertext Only\chapter_hypertext_only)

<HEAD>(<LITERAL>(<)COMMENT<LITERAL>(>)(HTML=)\head_comment_html_equals)

<P>
To allow the inclusion of text in Hypertext-available documents 
only (i.e. to exclude it from the printed and Bookreader documents) the 
following construct is provided: 

<CODE_EXAMPLE>
  <LITERAL>(<COMMENT>)(HTML=
  <EMPHASIS>(intervening HTML)
  )
<ENDCODE_EXAMPLE>

<CP>
The embedding of the HTML within the comment statement effectively hides it 
from processing by DOCUMENT.  SDM2HTM will detect it however and outputs the 
HTML enclosed by the statement.

<COMMENT>(HTML=
<P>
This statement does not appear within the printed or Bookreader document.
)

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML/POPUP=Select this link to see how it was produced)
<COMMENT>(HTML=
<P>
<PRE>  &lt;COMMENT&gt;(HTML=
  &lt;P&gt;
  This statement does not appear within the printed or Bookreader document.
  )
</PRE> 
)
<COMMENT>(HTML/ENDPOPUP) 
 
<COMMENT>(....................................................................)

<COMMENT>(the "<COMMENT>(HTML/OFF)...<COMMENT>(HTML/ON)" construct cause this 
section to appear in printed and Bookreader but not Hypertext documents) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD>(<LITERAL>(<)COMMENT<LITERAL>(>)(HTML/POPUP=)\head_comment_popup_equals)

<P>
This allows a separate section of document to be created that does not appear 
in the flow of current text, but contains a reference (HTML link) that must be 
selected, in much the same way as the DOCUMENT 
<EMPHASIS>(<LITERAL>(<POPUP>)) 
tag used for online documents.  It is implemented by creating a separate HTML 
file. 

<CODE_EXAMPLE>
  <LITERAL>(<COMMENT>(HTML/POPUP=descriptive text appearing in link))
  <EMPHASIS>(intervening SDML)
  <LITERAL>(<COMMENT>(HTML/ENDPOPUP))
<ENDCODE_EXAMPLE>

<CP>
The embedding of the HTML within the comment statement effectively hides it 
from processing by DOCUMENT.  SDM2HTM will detect it however and creates the 
popup HTML.

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML=
<P>
Select the following link for an online demonstration:
)

<COMMENT>(HTML/POPUP=An Online Demonstration)
<COMMENT>(HTML=
Note that the source after a <TT>&lt;COMMENT&gt;(HTML/POPUP=...)</TT> 
directive is still SDML.  The text following the <TT>/POPUP=</TT> is the 
description of the link.  This popup was produced using: 

<PRE>  &lt;COMMENT&gt;(HTML/POPUP=An Online Demonstration)
  &lt;COMMENT&gt;(HTML=
  Note that the source after a &lt;TT&gt;&lt;COMMENT&gt;(HTML/POPUP=...)&lt;/TT&gt; 
  directive is still SDML.  The text following the &lt;TT&gt;/POPUP=&lt;/TT&gt; is the 
  description of the link.  This popup was produced using: 

  &lt;PRE&gt;
    <I>(This is bit like Russian Dolls, so I'll quit here!)</I>
  &lt;/PRE&gt;
  )
  &lt;COMMENT&gt;(HTML/ENDPOPUP) 
</PRE>
)
<COMMENT>(HTML/ENDPOPUP) 

<COMMENT>(....................................................................)

<COMMENT>(the "<COMMENT>(HTML/OFF)...<COMMENT>(HTML/ON)" construct cause this 
section to appear in printed and Bookreader but not Hypertext documents) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<HEAD>(Suggestion\head_hypertext_only_suggestion)

<P>
When hypertext-only portions of a document contain links to other documents or
online demonstrations, information documenting this should be placed in any
printable/Bookreader versions.  This can be accomplished using constructs
described in <REFERENCE>(chapter_printed_only).  The essential details are
presented here. 

<P>
For an online demonstration include:

<CODE_EXAMPLE>
<LITERAL>  <COMMENT>(HTML/OFF)
  <P><BOX>(online demonstration)
  <COMMENT>(HTML/ON)
<ENDLITERAL><ENDCODE_EXAMPLE>

<P>
For a reference include:

<CODE_EXAMPLE>
<LITERAL>  <COMMENT>(HTML/OFF)
  <P><BOX>(online hypertext reference)
  <COMMENT>(HTML/ON)
<ENDLITERAL><ENDCODE_EXAMPLE>

<P>
For referenced hypertext documentation include:

<CODE_EXAMPLE>
<LITERAL>  <COMMENT>(HTML/OFF)
  <P><BOX>(online hypertext documentation)
  <COMMENT>(HTML/ON)
<ENDLITERAL><ENDCODE_EXAMPLE>

<P>
Etcetera.

<NOTE>
The <EMPHASIS>(<LITERAL>(<COMMENT>(HTML=...))\SMALLCAPS) construct is one of 
the most likely to cause SDM2HTM buffers to overflow.  Be very careful to 
terminate the <EMPHASIS>(<LITERAL>(<COMMENT>)\SMALLCAPS) statement with a  
closing parenthesis.  If parentheses are included within the HTML they must be 
<EMPHASIS>(balanced\BOLD), as this is how the end-of-comment is detected.  If 
a buffer overflow occurs check the above considerations and if this is not the 
problem reduce the quantity of HTML within the construct or break it into 
multiple constructs.
<ENDNOTE> 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Content For Printed/Bookreader Only\chapter_printed_only)

<P>
To allow the inclusion of text for printed and Bookreader available documents 
only (i.e. to exclude it from the Hypertext document) the following construct 
is provided:

<CODE_EXAMPLE>
  <LITERAL>(<COMMENT>(HTML/OFF))
  <EMPHASIS>(intervening SDML)
  <LITERAL>(<COMMENT>(HTML/ON))
<ENDCODE_EXAMPLE>

<CP>
The embedding of the HTML control statements 
<QUOTE>(<EMPHASIS>(HTML/OFF\SMALLCAPS)) and 
<QUOTE>(<EMPHASIS>(HTML/ON\SMALLCAPS)) inside the SDML comment statements 
hides it from processing by DOCUMENT.  SDM2HTM will detect it however and 
controls HTML output according to the directive.  Anything between the OFF and 
ON controls does not appear in the HTML source.

<P>
This is demonstated in this paragraph 
<COMMENT>(HTML/OFF) where Hypertext users cannot see the remainder of this 
sentence <COMMENT>(HTML/ON).

<COMMENT>(....................................................................)

<COMMENT>(this next "<COMMENT>(HTML=...)" construct causes only the Hypertext 
document to contain this text) 

<COMMENT>(HTML/POPUP=Select this link to see what you missed)

<COMMENT>(HTML=
<P>
The paragraph appeared to printed or Bookreader users as:

<P>
This is demonstated in this paragraph where Hypertext users cannot see the 
remainder of this sentence.

<P>
It was produced using the following syntax:

<PRE>  &lt;P&gt;
  This is demonstated in this paragraph &lt;COMMENT&gt;(HTML/OFF) where 
  Hypertext users cannot see the remainder of this sentence 
  &lt;COMMENT&gt;(HTML/ON).
</PRE> 
)

<COMMENT>(HTML/ENDPOPUP) 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Usage\chapter_usage)

<P>
The SDM2HTM utility accepts a single parameter, the source SDML file (a file 
type of <EMPHASIS>(.SDML\SMALLCAPS) is assumed if not supplied.  Qualifiers 
control other behaviour.  Default values are usually acceptable.  Example 
usage:

<CODE_EXAMPLE>
  $ sdm2htm /framed /index sdm2htm.sdml
  %SDM2HTM-I-FILE, HT_ROOT:[DOC.SDM2HTM]SDM2HTM.SDML
  %SDM2HTM-I-PASS, 1
  [Processing HT_ROOT:[DOC.SDM2HTM]SDM2HTM.SDML]
  %SDM2HTM-I-PASS, 2
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0000.HTML]
  [Processing HT_ROOT:[DOC.SDM2HTM]SDM2HTM.SDML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0001.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0002.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0100.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0200.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0300.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0301.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0302.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0400.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0401.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0500.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]SDM2HTM_0600.HTML]
  [Created HT_ROOT:[DOC.SDM2HTM]INDEX.HTML]
  $
<ENDCODE_EXAMPLE>

<HEAD>(Parameters and Qualifiers\head_parameters)

<P>
<EMPHASIS>(/BODY [=string]\BOLD)
<LINE>
HTML <LITERAL>(<BODY>) tag attributes can be specified.  Default is no
attributes.  For example, /BODY="BGCOLOR=""#ff0000""".

<P>
<EMPHASIS>(/COMMENTS\BOLD)
<LINE>
<EMPHASIS>(/NOCOMMENTS\BOLD) (default)
<LINE>
SDML <LITERAL>(<COMMENT>)s are included in the HTML source (between 
<LITERAL>(<!--) and <LITERAL>(-->)).

<P>
<EMPHASIS>(/DIRECTORY\BOLD)
<LINE>
Directory into which to place the generated HTML files.

<P>
<EMPHASIS>(/FLAG_UNKNOWN_TAGS\BOLD)
<LINE>
<EMPHASIS>(/NOFLAG_UNKNOWN_TAGS\BOLD) (default)
<LINE>
SDML tags unknown to SDM2HTM are displayed as they are encountered.

<P>
<EMPHASIS>(/FRAMED\BOLD)
<LINE>
<EMPHASIS>(/NOFRAMED\BOLD) (default)
<LINE>
The generated document uses <EMPHASIS>(frames) technology, dividing the page
into a table-of-contents on the left and a document page on the right.

<P>
<EMPHASIS>(/HTML\BOLD) (default)
<LINE>
<EMPHASIS>(/NOHTML\BOLD)
<LINE>
HTML files are produced as output.  The <EMPHASIS>(/NOHTML\SMALLCAPS) allows 
a pass of the source without generating any new files.

<P>
<EMPHASIS>(/INDEX [=name]\BOLD) (default)
<LINE>
By default the base document is <QUOTE>(<EMPHASIS>(name)_0000.HTML).  If the
/INDEX qualifier is used an additional file <QUOTE>(INDEX.HTML), a copy of the
base document, is generated providing a <EMPHASIS>(home page) for the
directory.  An alternative name to the the default <QUOTE>(INDEX.HTML) may be
supplied if desired.

<P>
<EMPHASIS>(/SOURCE\BOLD)
<LINE>
When a buffer overflow occurs provides additional information useful for the 
developer to analyse any problem.

<P>
<EMPHASIS>(/UNKNOWN_TAGS\BOLD)
<LINE>
<EMPHASIS>(/NOUNKNOWN_TAGS\BOLD) (default)
<LINE>
SDML tags unknown to SDM2HTM are included as comments in the HTML output 
files.

<P>
<EMPHASIS>(/VERBOSE\BOLD) (default)
<LINE>
<EMPHASIS>(/NOVERBOSE\BOLD)
<LINE>
Display progress messages.

<COMMENT>(--------------------------------------------------------------------)

