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

<FRONT_MATTER>
<TITLE_PAGE>

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

<LINE>

<HEAD>(3rd October 1994\head_date)

<P>
This is a new document. 

<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 HFRD 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.

<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>(....................................................................)

<HEAD>(Contact\head_contact)

<P>
M.G.Daniel 

<HEAD>(Printed Copy\head_printed_copy)

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

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

<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>(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>
This book is available for printing to a PostScript printer.  At the VMS 
command line enter <QUOTE>(PrintBook), the facility is menu driven.  For 
multiple copies it is better to print once, then <EMPHASIS>(photo-copy). 
<COMMENT>(HTML/ON)

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

<LINE>

<ENDTITLE_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. 

<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>(<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 hypertext 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 hypertext 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 hypertext 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 hypertext 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 sdm2htm.sdml
  %SDM2HTM-I-FILE, HYPERDATA:[HTML.SDM2HTM]SDM2HTM.SDML
  %SDM2HTM-I-PASS, 1
  [Processing HYPERDATA:[HTML.SDM2HTM]SDM2HTM.SDML]
  %SDM2HTM-I-PASS, 2
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0000.HTML]
  [Processing HYPERDATA:[HTML.SDM2HTM]SDM2HTM.SDML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0001.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0100.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0200.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0300.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0301.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0302.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0400.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0401.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0500.HTML]
  [Created HYPERDATA:[HTML.SDM2HTM]SDM2HTM_0600.HTML]
  $
<ENDCODE_EXAMPLE>

<HEAD>(Parameters and Qualifiers\head_parameters)

<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>(/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>(/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>(--------------------------------------------------------------------)

<CHAPTER>(References\chapter_references)

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

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

<COMMENT>(HTML=
<P>
Available online within HFRD:

<UL>
<LI> <A HREF="/hyperdata/html/html-primer/html-primer.html">A Beginner's Guide
to HTML</A>
<LI> <A HREF="/hyperdata/html/url/url_guide.html">Beginner's Buide to URLs</A>
<LI> <A HREF="/hyperdata/html/uri/uri-spec.html">URI Specification</A>
<LI> VAX DOCUMENT Guides (on Bookreader <HELLIPSIS> sorry, no 
<EMPHASIS>(gateway) yet!)
</UL>
)

<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>
The following Hypertext documents can be found online within HFRD:

<LIST>(UNNUMBERED)
<LE> A beginner's Guide to HTML
<LE> Beginner's Guide to URLs
<LE> URI Specification
<LE> VAX DOCUMENT Guides (online on Bookreader)
<ENDLIST>

<P><BOX>(online hypertext documentation)

<COMMENT>(HTML/ON)

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

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

