(SDM2HTM -\An SDML to HTML Converter) <COMMENT>(HTML/OFF) <LINE> <COMMENT>(HTML/ON) <COMMENT>(--------------------------------------------------------------------) <HEAD>(March 1998\sect_date) Supercedes: <CODE_EXAMPLE> July 1997 October 1994 <ENDCODE_EXAMPLE> <COMMENT>(--------------------------------------------------------------------) <HEAD>(Abstract\sect_abstract) 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. The utility is provided <EMPHASIS>(as-is). This document assumes a basic understanding of both HTML and SDML / VAX DOCUMENT. <COMMENT>(--------------------------------------------------------------------) <HEAD>(Author\sect_author) <INCLUDE>([-.CONFIG]DOC_AUTHOR.SDML) <COMMENT>(--------------------------------------------------------------------) <HEAD>(Online PDF\head_postscript) <COMMENT>(HTML= This document is also available in <A HREF="/ht_root/doc/sdm2htm/wasd_sdm2htm.pdf">PDF</A> for access and subsequent printing by suitable viewers (e.g. GhostScript), and from the location HT_ROOT:[DOC.SDM2HTM]WASD_SDM2HTM.PDF ) <COMMENT>(HTML/OFF) This book is available in PDF for access and subsequent printing by suitable viewers (e.g. GhostScript) from the location HT_ROOT:[DOC.SDM2HTM]WASD_SDM2HTM.PDF <COMMENT>(HTML/ON) <COMMENT>(HTML/OFF) 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) <ENDTITLE_PAGE> <COMMENT>(--------------------------------------------------------------------) <COPYRIGHT_PAGE> <COMMENT>(HTML= WASD VMS Hypertext Services, Copyright © 1996-1998 Mark G. Daniel. ) <COMMENT>(HTML/OFF) <EMPHASIS>(WASD VMS Hypertext Services, Copyright (C) 1996-1998 Mark G. Daniel. \BOLD) <COMMENT>(HTML/ON) 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 3 of the License, or any later version. 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. 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) 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. Special constructs allow the inclusion of content in only the HTML version of a document, or only in the printed/Bookreader versions. 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. 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) 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) 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. 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. 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). 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= 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>. 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) <BOX>(online demonstration) <BOX>(online document SDML source) <COMMENT>(HTML/ON) <COMMENT>(....................................................................) <COMMENT>(--------------------------------------------------------------------) <CHAPTER>(Content For Hypertext Only\chapter_hypertext_only) <HEAD>(<LITERAL>(<)COMMENT<LITERAL>(>)(HTML=)\sect_comment_html_equals) 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= 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= <PRE> <COMMENT>(HTML= 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) <BOX>(online demonstration) <COMMENT>(HTML/ON) <COMMENT>(....................................................................) <COMMENT>(--------------------------------------------------------------------) <HEAD>(<LITERAL>(<)COMMENT<LITERAL>(>)(HTML/POPUP=)\sect_comment_popup_equals) 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= Select the following link for an online demonstration: ) <COMMENT>(HTML/POPUP=An Online Demonstration) <COMMENT>(HTML= Note that the source after a <TT><COMMENT>(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> <COMMENT>(HTML/POPUP=An Online Demonstration) <COMMENT>(HTML= Note that the source after a <TT><COMMENT>(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> (This is bit like Russian Dolls, so I'll quit here!) </PRE> ) <COMMENT>(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) <BOX>(online demonstration) <COMMENT>(HTML/ON) <COMMENT>(....................................................................) <HEAD>(Suggestion\sect_hypertext_only_suggestion) 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. For an online demonstration include: <CODE_EXAMPLE> <LITERAL> <COMMENT>(HTML/OFF) <BOX>(online demonstration) <COMMENT>(HTML/ON) <ENDLITERAL><ENDCODE_EXAMPLE> For a reference include: <CODE_EXAMPLE> <LITERAL> <COMMENT>(HTML/OFF) <BOX>(online hypertext reference) <COMMENT>(HTML/ON) <ENDLITERAL><ENDCODE_EXAMPLE> For referenced hypertext documentation include: <CODE_EXAMPLE> <LITERAL> <COMMENT>(HTML/OFF) <BOX>(online hypertext documentation) <COMMENT>(HTML/ON) <ENDLITERAL><ENDCODE_EXAMPLE> 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) 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. 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= The paragraph appeared to printed or Bookreader users as: This is demonstated in this paragraph where Hypertext users cannot see the remainder of this sentence. It was produced using the following syntax: <PRE> This is demonstated in this paragraph <COMMENT>(HTML/OFF) where Hypertext users cannot see the remainder of this sentence <COMMENT>(HTML/ON). </PRE> ) <COMMENT>(HTML/ENDPOPUP) <COMMENT>(--------------------------------------------------------------------) <CHAPTER>(Usage\chapter_usage) 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\sect_parameters) <EMPHASIS>(/BODY [=string]\BOLD) <LINE> HTML <LITERAL>(<BODY>) tag attributes can be specified. Default is no attributes. For example, /BODY="BGCOLOR=""#ff0000""". <EMPHASIS>(/COMMENTS\BOLD) <LINE> <EMPHASIS>(/NOCOMMENTS\BOLD) (default) <LINE> SDML <LITERAL>(<COMMENT>)s are included in the HTML source (between <LITERAL>()). <EMPHASIS>(/DIRECTORY\BOLD) <LINE> Directory into which to place the generated HTML files. <EMPHASIS>(/FLAG_UNKNOWN_TAGS\BOLD) <LINE> <EMPHASIS>(/NOFLAG_UNKNOWN_TAGS\BOLD) (default) <LINE> SDML tags unknown to SDM2HTM are displayed as they are encountered. <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. <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. <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. <EMPHASIS>(/SOURCE\BOLD) <LINE> When a buffer overflow occurs provides additional information useful for the developer to analyse any problem. <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. <EMPHASIS>(/VERBOSE\BOLD) (default) <LINE> <EMPHASIS>(/NOVERBOSE\BOLD) <LINE> Display progress messages. <COMMENT>(--------------------------------------------------------------------)

(--------------------------------------------------------------------) (SDM2HTM -\An SDML to HTML Converter) <COMMENT>(HTML/OFF) <LINE> <COMMENT>(HTML/ON) <COMMENT>(--------------------------------------------------------------------) <HEAD>(March 1998\sect_date) Supercedes: <CODE_EXAMPLE> July 1997 October 1994 <ENDCODE_EXAMPLE> <COMMENT>(--------------------------------------------------------------------) <HEAD>(Abstract\sect_abstract) 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. The utility is provided <EMPHASIS>(as-is). This document assumes a basic understanding of both HTML and SDML / VAX DOCUMENT. <COMMENT>(--------------------------------------------------------------------) <HEAD>(Author\sect_author) <INCLUDE>([-.CONFIG]DOC_AUTHOR.SDML) <COMMENT>(--------------------------------------------------------------------) <HEAD>(Online PDF\head_postscript) <COMMENT>(HTML= This document is also available in <A HREF="/ht_root/doc/sdm2htm/wasd_sdm2htm.pdf">PDF</A> for access and subsequent printing by suitable viewers (e.g. GhostScript), and from the location HT_ROOT:[DOC.SDM2HTM]WASD_SDM2HTM.PDF ) <COMMENT>(HTML/OFF) This book is available in PDF for access and subsequent printing by suitable viewers (e.g. GhostScript) from the location HT_ROOT:[DOC.SDM2HTM]WASD_SDM2HTM.PDF <COMMENT>(HTML/ON) <COMMENT>(HTML/OFF) 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) <ENDTITLE_PAGE> <COMMENT>(--------------------------------------------------------------------) <COPYRIGHT_PAGE> <COMMENT>(HTML= WASD VMS Hypertext Services, Copyright © 1996-1998 Mark G. Daniel. ) <COMMENT>(HTML/OFF) <EMPHASIS>(WASD VMS Hypertext Services, Copyright (C) 1996-1998 Mark G. Daniel. \BOLD) <COMMENT>(HTML/ON) 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 3 of the License, or any later version. 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. 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) 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. Special constructs allow the inclusion of content in only the HTML version of a document, or only in the printed/Bookreader versions. 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. 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) 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) 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. 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. 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). 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= 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>. 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) <BOX>(online demonstration) <BOX>(online document SDML source) <COMMENT>(HTML/ON) <COMMENT>(....................................................................) <COMMENT>(--------------------------------------------------------------------) <CHAPTER>(Content For Hypertext Only\chapter_hypertext_only) <HEAD>(<LITERAL>(<)COMMENT<LITERAL>(>)(HTML=)\sect_comment_html_equals) 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= 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= <PRE> <COMMENT>(HTML= 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) <BOX>(online demonstration) <COMMENT>(HTML/ON) <COMMENT>(....................................................................) <COMMENT>(--------------------------------------------------------------------) <HEAD>(<LITERAL>(<)COMMENT<LITERAL>(>)(HTML/POPUP=)\sect_comment_popup_equals) 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= Select the following link for an online demonstration: ) <COMMENT>(HTML/POPUP=An Online Demonstration) <COMMENT>(HTML= Note that the source after a <TT><COMMENT>(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> <COMMENT>(HTML/POPUP=An Online Demonstration) <COMMENT>(HTML= Note that the source after a <TT><COMMENT>(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> (This is bit like Russian Dolls, so I'll quit here!) </PRE> ) <COMMENT>(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) <BOX>(online demonstration) <COMMENT>(HTML/ON) <COMMENT>(....................................................................) <HEAD>(Suggestion\sect_hypertext_only_suggestion) 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. For an online demonstration include: <CODE_EXAMPLE> <LITERAL> <COMMENT>(HTML/OFF) <BOX>(online demonstration) <COMMENT>(HTML/ON) <ENDLITERAL><ENDCODE_EXAMPLE> For a reference include: <CODE_EXAMPLE> <LITERAL> <COMMENT>(HTML/OFF) <BOX>(online hypertext reference) <COMMENT>(HTML/ON) <ENDLITERAL><ENDCODE_EXAMPLE> For referenced hypertext documentation include: <CODE_EXAMPLE> <LITERAL> <COMMENT>(HTML/OFF) <BOX>(online hypertext documentation) <COMMENT>(HTML/ON) <ENDLITERAL><ENDCODE_EXAMPLE> 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) 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. 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= The paragraph appeared to printed or Bookreader users as: This is demonstated in this paragraph where Hypertext users cannot see the remainder of this sentence. It was produced using the following syntax: <PRE> This is demonstated in this paragraph <COMMENT>(HTML/OFF) where Hypertext users cannot see the remainder of this sentence <COMMENT>(HTML/ON). </PRE> ) <COMMENT>(HTML/ENDPOPUP) <COMMENT>(--------------------------------------------------------------------) <CHAPTER>(Usage\chapter_usage) 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\sect_parameters) <EMPHASIS>(/BODY [=string]\BOLD) <LINE> HTML <LITERAL>(<BODY>) tag attributes can be specified. Default is no attributes. For example, /BODY="BGCOLOR=""#ff0000""". <EMPHASIS>(/COMMENTS\BOLD) <LINE> <EMPHASIS>(/NOCOMMENTS\BOLD) (default) <LINE> SDML <LITERAL>(<COMMENT>)s are included in the HTML source (between <LITERAL>()). <EMPHASIS>(/DIRECTORY\BOLD) <LINE> Directory into which to place the generated HTML files. <EMPHASIS>(/FLAG_UNKNOWN_TAGS\BOLD) <LINE> <EMPHASIS>(/NOFLAG_UNKNOWN_TAGS\BOLD) (default) <LINE> SDML tags unknown to SDM2HTM are displayed as they are encountered. <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. <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. <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. <EMPHASIS>(/SOURCE\BOLD) <LINE> When a buffer overflow occurs provides additional information useful for the developer to analyse any problem. <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. <EMPHASIS>(/VERBOSE\BOLD) (default) <LINE> <EMPHASIS>(/NOVERBOSE\BOLD) <LINE> Display progress messages. <COMMENT>(--------------------------------------------------------------------)