english
version "1.0"
identify "xyz"

#: Copyright (c) 2001 by Wayne C. Gramlich.
#, All rights reserved.
#, 
#, Permission to use, copy, modify, distribute, and sell this software
#, for any purpose is hereby granted without fee provided that the above
#, copyright notice and this permission are retained.  The author makes
#, no representations about the suitability of this software for any purpose.
#, It is provided "as is" without express or implied warranty.

#: This module is the plain text markup language module.

module ptml

define ptml				#: PTML object
    record
	file_name string		#: File name for PTML object
	indents vector[unsigned]	#: List of indentation levels
	lines vector[line]		#: Lines making up PTML object
	paragraph paragraph		#: Paragraph object
	tags vector[string]		#: Current indentation tag
    generate allocate, erase, identical, print



#: {ptml} routines:

procedure convert@ptml
    takes
	ptml ptml
	output_file_name string
	table_of_contents logical
    returns_nothing

    #: This procedure will covert {ptml} to HTML and output the
    #, result to {output_file_name}.


procedure create@ptml
    takes
	file_name string
    returns ptml
	
    #: This procedure will create and return an empty {ptml} object.


procedure description_list_process@ptml
    takes
	ptml ptml
	index unsigned
	out_stream out_stream
    returns logical

    #: This procedure will determine if the lines at {index} and {index} + 1
    #, are part of a description list.  If necessary, the enclosing <DL>
    #, is output to {out_stream}.


procedure file_append@ptml
    takes
	ptml ptml
	file_name string
    returns logical

    #: This procedure will append the contents of {file_name} to {ptml}. 
    #, If any errors occur, {true} is returned; otherwise, {false is returned.


procedure file_read@ptml
    takes
	file_name string
    returns ptml

    #: This procedure will read in the contents of {file_name}
    #, and return it as a PTML object.  If {file_name} can not
    #, be opened, ?? is returned.


procedure indent@ptml
    takes
	ptml ptml
	out_stream out_stream
    returns_nothing

    #: This procedure will output a stream of spaces for the
    #, current indentation level of {ptml} to {out_stream}.


procedure indents_close@ptml
    takes
	ptml ptml
	out_stream out_stream
    returns_nothing

    #: This procedure will close off any indentation levels.


procedure indents_open@ptml
    takes
	ptml ptml
	desired_indent unsigned
	desired_tag string
	out_stream out_stream
    returns_nothing

    #: This procedure will pop off enough indentation levels in {ptml}
    #, to get to {desired_indent}.


procedure list_item_adjust@ptml
    takes
	ptml ptml
	start_index unsigned
	end_index unsigned
    returns unsigned

    #: This procedure will notice whether the current line at {start_index}
    #, in {ptml} looks like an list item paragraph.  The new value for
    #, {end_index} is returned if the paragraph is a list item.

    #, for the item list is:
    #, paragraph to include any following lines at the same indentation level:


procedure list_item_process@ptml
    takes
	ptml ptml
	start_index unsigned
	paragraph paragraph
	out_stream out_stream
    returns logical

    #: This procedure will return {true} if {paragraph} is a list item.
    #, If it is a list item, {start_index} is used to fetch the first
    #, line to figure out the indentation level.  If this is the first
    #, list item, a "<UL>" or "<OL>" is output.


procedure paragraph_convert@ptml
    takes
	ptml ptml
	start_index unsigned
	end_index unsigned
	table_of_contents logical
	out_stream out_stream
    returns_nothing

    #: This procedure will convert the lines from {start_index} to {end_index}
    #, in {ptml} to HTML and output them to {out_stream}.


procedure paragraph_fill@ptml
    takes
	ptml ptml
	start_index unsigned
	end_index unsigned
    returns paragraph

    #: This procedure will fill the {paragraph} object in {ptml}
    #, with the words from lines {start_index} to {end_index} inclusive.


procedure plain_write@ptml
    takes
	ptml ptml
	output_file_name string
    returns_nothing

    #: This procedure will output {ptml} to {output_file_name}.


procedure table_of_contents_generate@ptml
    takes
	ptml ptml
	out_stream out_stream
    returns_nothing

    #: This procedure will output the table of contents for {ptml}
    #, to {out_stream}.


procedure tag_pop@ptml
    takes
	ptml ptml
	out_stream out_stream
    returns_nothing

    #: This procedure will output {tag} to {out_stream} indented by {indent}.


procedure tag_push@ptml
    takes
	ptml ptml
	indent unsigned
	tag string
	out_stream out_stream
    returns_nothing

    #: This procedure will output {tag} to {out_stream} indented by {indent}.


procedure title@ptml
    takes
	ptml ptml
    returns string

    #: This procedure will return the title associated with {ptml}