MODULE sca$report_format_document
IDENT "T4.0-2"
!*************************************************************************
!									 *
!	      © 2000 BY							 *
!	      COMPAQ COMPUTER CORPORATION                                *
!	      © 2000 BY							 *
!	      ELECTRONIC DATA SYSTEMS LIMITED                            *
!									 *
! THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND  COPIED *
! ONLY  IN  ACCORDANCE  WITH  THE  TERMS  OF  SUCH  LICENSE AND WITH THE *
! INCLUSION OF THE ABOVE COPYRIGHT NOTICE.  THIS SOFTWARE OR  ANY  OTHER *
! COPIES  THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY *
! OTHER  PERSON.  NO  TITLE TO OR OWNERSHIP OF THE  SOFTWARE  IS  HEREBY *
! TRANSFERRED.                                                           *
!									 *
! THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE  WITHOUT  NOTICE *
! AND  SHOULD  NOT  BE  CONSTRUED  AS  A COMMITMENT  BY  COMPAQ COMPUTER *
! CORPORATION OR EDS.                                                    *
!									 *
! NEITHER  COMPAQ  NOR  EDS  ASSUME ANY RESPONSIBILITY FOR  THE  USE  OR *
! RELIABILITY  OF  THIS SOFTWARE ON EQUIPMENT WHICH IS NOT  SUPPLIED  BY *
! COMPAQ.                                                                *
!									 *
!*************************************************************************

!+
! Facility:
!   SCA - Source Code Analyzer
!	REPORT - Report Subfacility
!
! Abstract:
!   This module contains routines that deal with the formatting of VAX Document
!   (.SDML) source files.
!
!   All of the dependencies on VAX Document are isolated into this module.
!-

PROCEDURE sca$report_add_table_item_document (item_name; item_description)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure adds an entry to a table.  All of our tables are two columns,
!   consisting of an item and the description of the item.
!
! FORMAL PARAMETERS:
!
!   item_name
!
!	The name of the item to put into the table.  This must be a string.
!
!   item_description
!
!	The description of the item, as a TPU string.  Optional IN parameter.
!--
    LOCAL
	output_string;

    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_ADD_TABLE_ITEM_DOCUMENT');
    ENDON_ERROR;

    !  If the item_description is provided, write the item_name in the first
    !  column and the item description in the second column.
    !
    IF GET_INFO(item_description,'TYPE') = STRING
    THEN
	output_string :=
	    '<TABLE_ROW>(' + item_name + '\' + item_description + ')'
    ELSE
	!  Only the item_name was specified - write the item_name in the first
	!  column only.
	!
	output_string := '<TABLE_ROW>(' + item_name + '\)';
    ENDIF;
    sca$report_append_text (output_string, TRUE);
    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_appendix_document (appendix_title)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This routine writes an appendix heading in SDML format.
!
! FORMAL PARAMETERS:
!
!   appendix_title
!
!	The name of the appendix, as a string.  IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_APPENDIX_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('<APPENDIX>(' + appendix_title + ')', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_chapter_document (chapter_title, decl_class)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This routine writes a chapter heading in SDML format.
!
! FORMAL PARAMETERS:
!
!   chapter_title
!
!	The name of the chapter, as a TPU string value.  IN parameter.
!
!   decl_class
!
!	The declaration class of the object that the chapter describes, as a
!	TPU string value.  IN parameter.
!--
    LOCAL
	full_chapter_title;

    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_CHAPTER_DOCUMENT');
    ENDON_ERROR;

    ! Construct the chapter title, including declaration class information if
    ! it is enabled.
    !
    IF sca$report_option_decl_class_modules AND (decl_class <> '')
    THEN
    	full_chapter_title := chapter_title + ' (' + decl_class + ')';
    ELSE
    	full_chapter_title := chapter_title;
    ENDIF;

    ! Write the <CHAPTER> tag, followed by a new paragraph tag to insure
    ! proper alignment of the paragraph text.
    !
    sca$report_append_text ('<CHAPTER>(' + full_chapter_title + ')', TRUE);
    sca$report_append_text ('<P>', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_end_fragment_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the SDML commands necessary to end a code fragment.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_FRAGMENT_DOCUMENT');
    ENDON_ERROR;

    !  Write out the <ENDCODE_EXAMPLE> and <ENDCALLOUTS> tags to close the
    !  previous <CODE_EXAMPLE> and <CALLOUTS> tags.
    !
    sca$report_append_text ('<ENDCODE_EXAMPLE>', TRUE);
    sca$report_append_text ('<ENDCALLOUTS>', TRUE);
    sca$report_blank_line;
    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_end_list_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the SDML tags necessary to end a list.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_LIST_DOCUMENT');
    ENDON_ERROR;

    !  Write the <ENDLIST> tag to close the current list.
    !
    sca$report_append_text ('<ENDLIST>', TRUE);
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_end_parameter_section_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the formatting information necessary for ending
!   the description of the parameter list in a routine section.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_PARAMETER_SECTION_DOCUMENT');
    ENDON_ERROR;

    !  Write the <ENDARGDEFLIST> tag to close the <ARGDEFLIST> tag used in
    !  formatting the parameter section.
    !
    sca$report_append_text ('<ENDARGDEFLIST>', TRUE);
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_end_routine_section_document (routine_name)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the formatting information necessary for ending
!   a routine section.
!
! FORMAL PARAMETERS:
!
!   routine_name
!
!	The name of the current routine being processed, as a TPU string.
!	IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_ROUTINE_SECTION_DOCUMENT');
    ENDON_ERROR;

    !  If the routine name is specified and not blank, then write the closing
    !  index tag to close the open index range.
    !
    IF routine_name <> tpu$k_unspecified
    THEN
	IF routine_name <> ''
	THEN
	    sca$report_append_text ('<X>(' + routine_name + '\END)', TRUE);
	ENDIF;
    ENDIF;

    !  Write the <ENDROUTINE_SECTION> tag to close the routine section.
    !
    sca$report_append_text ('<ENDROUTINE_SECTION>', TRUE);
    sca$report_append_text (ASCII(12), TRUE);

ENDPROCEDURE

PROCEDURE sca$report_end_routine_subsection_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to end a subsection of a
!   routine section.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_ROUTINE_SUBSECTION_DOCUMENT');
    ENDON_ERROR;

    !  Write the <ENDDESCRIPTION> tag to close a description block.
    !
    sca$report_append_text ('<ENDDESCRIPTION>', TRUE);
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_end_section_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to end a section.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_SECTION_DOCUMENT');
    ENDON_ERROR;

    !  Nothing special is required to mark the end of a section.  Just write a
    !  blank line to make the source file easier to read.
    !
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_end_subsection_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to end a subsection.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_SUBSECTION_DOCUMENT');
    ENDON_ERROR;

    !  Nothing special is required to mark the end of a subsection.  Just write
    !  a blank line to make the source file easier to read
    !
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_end_table_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure terminates a table.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_END_TABLE_DOCUMENT');
    ENDON_ERROR;

    !  Write the <ENDTABLE> tag to close the current table.
    !
    sca$report_append_text ('<ENDTABLE>', TRUE);
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_format_tag_document (tag_value_range)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure does target-specific processing of tag value text.
!   That consists of surrounding text that has the format of an SDML tag
!   (text enclosed in angle brackets) with <LITERAL>(...).
!
! FORMAL PARAMETERS:
!
!   tag_value_range
!
!	The text of the tag value, as a TPU range. IN parameter.
!--
    LOCAL
	close_paren,
	open_paren,
	saved_position,
	this_line;

    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('sca$report_format_tag_document');
    ENDON_ERROR;

    ! Don't add any LITERAL<...> tags if the user doesn't want them (based on
    ! the literal_angle_brackets option).
    !
    IF GET_INFO (sca$report_option_literal_angle_brackets, 'TYPE') = UNSPECIFIED
    THEN
	sca$report_option_literal_angle_brackets := TRUE;
    ENDIF;

    IF NOT sca$report_option_literal_angle_brackets
    THEN
	RETURN;
    ENDIF;

    saved_position := MARK(FREE_CURSOR);
    POSITION (BEGINNING_OF ( tag_value_range));
    LOOP
	open_paren := SEARCH_QUIETLY( '<', FORWARD, EXACT);
	EXITIF open_paren = 0;
	POSITION (open_paren);
	this_line := CREATE_RANGE (MARK(NONE), LINE_END, NONE);
	close_paren := SEARCH_QUIETLY( '>', FORWARD, EXACT, this_line);
	IF close_paren <> 0
	THEN
	    ! We found <...> - surround it with <LITERAL>(...)
	    !
	    POSITION (open_paren);
	    COPY_TEXT ( '<LITERAL>(' );
	    POSITION (close_paren);
	    MOVE_HORIZONTAL(1);
	    COPY_TEXT ( ')' );
	ELSE
	    ! We found < without a matching > on the same line.  Move past
	    ! the < so that we don't find it again on the next SEARCH operation.
	    !
	    MOVE_HORIZONTAL(1);
	ENDIF;
    ENDLOOP;

    POSITION (saved_position);
ENDPROCEDURE

PROCEDURE sca$report_include_file_document (file_name)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes an <INCLUDE> tag.
!
! FORMAL PARAMETERS:
!
!   file_name
!
!	The name of the file to be included.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_INCLUDE_FILE_DOCUMENT');
    ENDON_ERROR;

    !  Write the <INCLUDE> tag to instruct DOCUMENT to include a file
    !  containing SDML tags.
    !
    sca$report_append_text ('<INCLUDE>(' + file_name + ')', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_list_element_document (element_text)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes a single list element.
!
! FORMAL PARAMETERS:
!
!   element_text
!
!	The text of the element.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_LIST_ELEMENT_DOCUMENT');
    ENDON_ERROR;

    !  Use the <LE> tag to indicate a list element.
    !
    sca$report_append_text ('<LE>', TRUE);

    !  Write the text using sca$report_paragraph_document, since it may contain
    !  multiple lines.  Suppress the leading paragraph character in order to
    !  properly format the text.
    !
    sca$report_paragraph_document (element_text, FALSE);

ENDPROCEDURE

PROCEDURE sca$report_paragraph_document (text_block; initial_paragraph)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes one or more paragraphs of text in SDML format.  It
!   searches for blank lines in the text, and inserts paragraph breaks (i. e.,
!   <P> tags, as appropriate.
!
! FORMAL PARAMETERS:
!
!   text_block
!
!	The text of the paragraph, as a TPU string or range value.  It must
!	contain at least one paragraph.  IN parameter.
!
!   initial_paragraph
!
!	A boolean flag to indicate whether to write an initial paragraph.  TRUE
!	means write '<P>' tag, FALSE means not to write the '<P>' tag the
!	initial time through.  If omitted, the default is TRUE.
!
! IMPLICIT INPUTS:
!
!   sca$report_option_fill
!--
    LOCAL
	end_paragraph,
	end_paragraph_pattern,
	individual_paragraph_range,
	local_text_block,
	local_flag,
	saved_position,
	search_range,
	start_paragraph;

    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_PARAGRAPH_DOCUMENT');
    ENDON_ERROR;

    local_flag := initial_paragraph;
    saved_position := MARK(FREE_CURSOR);

    ! If the value of the flag to suppress the writing of an initial paragraph
    ! was not specified, then default to writing the initial paragraph tag.
    !
    IF local_flag = tpu$k_unspecified
    THEN
	local_flag := TRUE;
    ENDIF;

    ! We define the end of a paragraph to be an empty line, as defined by
    ! the pattern eve$pattern_empty_line.
    !
    end_paragraph_pattern := eve$pattern_empty_line;

    ! If the text block is a string, we convert it into a range by copying it
    ! into a scratch buffer.
    !
    IF GET_INFO(text_block,'TYPE') = STRING
    THEN
	POSITION(sca$report_scratch_buffer);
	ERASE(sca$report_scratch_buffer);
	COPY_TEXT(text_block);
	local_text_block :=
	    CREATE_RANGE(
		BEGINNING_OF(sca$report_scratch_buffer),
		END_OF(sca$report_scratch_buffer),
		NONE);
    ELSE
	local_text_block := text_block;
    ENDIF;

    POSITION(BEGINNING_OF(local_text_block));

    ! Strip leading blank lines from the text block, by moving the beginning
    ! point of the range.
    !
    start_paragraph :=
	SEARCH_QUIETLY (
	    NOTANY(eve$kt_whitespace + ASCII(12) + ASCII(0)),
	    FORWARD,
	    EXACT,
	    local_text_block);
    IF start_paragraph = 0
    THEN
	! There is no text associated with this tag.
	!
	IF local_flag = TRUE
	THEN
	    sca$report_append_text('<P>', TRUE);
	ENDIF;
        POSITION(saved_position);
	ERASE(sca$report_scratch_buffer);
	RETURN
    ELSE
	! Start at the line containing the first non-blank character.
	!
	POSITION(BEGINNING_OF(start_paragraph));
	POSITION(LINE_BEGIN);
	start_paragraph := MARK(FREE_CURSOR)
    ENDIF;
    local_text_block :=
	CREATE_RANGE (start_paragraph, END_OF(local_text_block), NONE);

    IF GET_INFO (sca$report_option_fill, 'TYPE') = UNSPECIFIED
    THEN
	sca$report_option_fill := sca$report_fill;
    ENDIF;

    IF sca$report_option_fill = 1
    THEN
	! /FILL is in effect.  Divide the text into individual paragraphs,
	! separated by <P> tags.
	! This algorithm assumes there is always at least one paragraph.
	!
	POSITION(BEGINNING_OF(local_text_block));
	LOOP
	    ! Find the paragraph boundaries
	    !
	    start_paragraph := MARK(FREE_CURSOR);

	    ! Search for end of paragraph
	    !
	    search_range :=
		CREATE_RANGE (start_paragraph, END_OF(local_text_block), NONE);
	    end_paragraph :=
		SEARCH_QUIETLY (
		    end_paragraph_pattern,
		    FORWARD,
		    NO_EXACT,
		    search_range);
	    IF end_paragraph = 0
	    THEN
		end_paragraph := END_OF(local_text_block)
	    ELSE
		! Position to the end of the paragraph (the LINE_END of the last
		! line of the paragraph).
		!
		POSITION(BEGINNING_OF(end_paragraph));
		end_paragraph := MARK(FREE_CURSOR)
	    ENDIF;
	    individual_paragraph_range :=
		CREATE_RANGE (start_paragraph, end_paragraph, NONE);

	    ! Write the current paragraph
	    !
	    IF local_flag = TRUE
	    THEN
		sca$report_append_text('<P>', TRUE);
	    ENDIF;

	    local_flag := TRUE;
	    sca$report_append_text(individual_paragraph_range, TRUE);
	    sca$report_blank_line;

	    ! Search for the start of the next paragraph.
	    !
	    POSITION(end_paragraph);
	    EXITIF MARK(FREE_CURSOR) >= END_OF(local_text_block);
	    search_range :=
		CREATE_RANGE (end_paragraph, END_OF(local_text_block), NONE);
	    start_paragraph :=
		SEARCH_QUIETLY(
		    NOTANY(eve$kt_whitespace + ASCII(12) + ASCII(0)),
		    FORWARD,
		    EXACT,
		    search_range);
	    EXITIF start_paragraph = 0;
	    POSITION(start_paragraph);

	ENDLOOP;

    ELSE
	! Write the text block line by line, using the <LINE> tag to preserve
	! line breaks and indentation from the source.
	!
	sca$report_append_text('<P>', TRUE);
	POSITION (BEGINNING_OF (local_text_block));
        LOOP
	    EXITIF MARK(FREE_CURSOR) >= END_OF(local_text_block);

	    !*** add code here to calculate INDENT(xxx) value
	    sca$report_append_text('<LINE>' + current_line, TRUE);
	    lse$move_vertical(1);
	ENDLOOP;

	sca$report_blank_line;
    ENDIF;
    ERASE(sca$report_scratch_buffer);
    POSITION(saved_position);
    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_placeholder_document (placeholder_name)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes a placeholder to the output file.  It always writes an
!   optional placeholder.
!
! FORMAL PARAMETERS:
!
!   placeholder_name
!
!	The name of the placeholder, as a string.  Placeholder brackets should
!	not be included in the string.  IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_PLACEHOLDER_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('[' + placeholder_name + ']', FALSE);
    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_start_2167A_design_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure initializes a 2167A design document.  It writes introductory
!   formatting commands for the report.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_2167a_DESIGN_DOCUMENT');
    ENDON_ERROR;

    !  Write the <DOCTYPE> tag to inform the user of the proper doctype to
    !  use when processing the report through VAX DOCUMENT.
    !
    sca$report_append_text ('<DOCTYPE>(MILSPEC)', TRUE);

    !  Include a comment indicating how the file was generated and on what date.
    !
    sca$report_append_text (
	FAO ('<COMMENT>(Generated by the LSE/SCA Report Tool, ' +
	     sca$report_2167a_design_module_ident + ', !%D)', 0),
	TRUE);

    ! VAX Document requires that when you do a book-build (i. e. you use a
    ! profile file containing <PROFILE> and <ELEMENT> tags), the chapter tag for
    ! each element must have a symbol name.  Write the same name that VAX
    ! Document uses in the template for this report.
    !
    sca$report_chapter_document (
	sca$report_section_detailed_design + '\det_design_section', '');

ENDPROCEDURE

PROCEDURE sca$report_start_fragment_document (fragment_number, id_text_size)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to start a new code fragment.
!
! FORMAL PARAMETERS:
!
!   fragment_number
!
!	The number to assign to the fragment, as a TPU integer value.  IN
!	parameter.
!
!   id_text_size
!
!	The number of columns required to display the fragment number.  OUT
!	parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_FRAGMENT_DOCUMENT');
    ENDON_ERROR;

    !  Write the <CALLOUTS> tag and <CODE_EXAMPLE> to start the code fragment.
    !
    sca$report_append_text ('<CALLOUTS>(\prefix)', TRUE);
    sca$report_append_text ('<CODE_EXAMPLE>(WIDE\MAXIMUM)', TRUE);
    sca$report_append_text ('<CO>(' + STR(fragment_number) + ')', FALSE);

    ! We don't need to reserve any columns for the fragment number, because in
    ! SDML format it is pushed to the left of the left margin.
    !
    id_text_size := 0;
    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_start_header_document (level, section_title)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the <HEADx> tag for a given level.
!
! FORMAL PARAMETERS:
!
!   level
!
!	The level for the header.  This should be an integer value.  IN
!	parameter.
!
!   section_title
!
!	The title to use for the header.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_HEADER_DOCUMEN');
    ENDON_ERROR;

    sca$report_append_text ('<HEAD' + STR(level) + '>(' + section_title + ')',
			    TRUE);
    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_start_list_document  (;list_style)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the tags necessary to start a list.
!
! FORMAL PARAMETERS:
!
!   list_style
!
!	The type of list to be created.  If unspecified, the list type will
!	default to SCA$REPORT_K_LIST_NUMBERED.  The list styles available
!	are:
!
!	    sca$report_k_list_simple
!	    sca$report_k_list_unnumbered
!	    sca$report_k_list_numbered
!	    sca$report_k_list_lower_alpha
!	    sca$report_k_list_upper_alpha
!	    sca$report_k_list_lower_roman
!	    sca$report_k_list_upper_roman
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_LIST_DOCUMENT');
    ENDON_ERROR;

    !  If the list_style was not passed to the procedure, then default
    !  to using a numbered list.
    !
    IF list_style = tpu$k_unspecified
    THEN
	list_style := sca$report_k_list_numbered;
    ENDIF;

    !  Depending upon the list style, write the appropriate SDML code to set up
    !  the list.
    !
    CASE list_style
        FROM sca$report_k_first_list_index TO sca$report_k_last_list_index
        [sca$report_k_list_simple] :
	    sca$report_append_text ('<LIST>(SIMPLE)', TRUE);

        [sca$report_k_list_unnumbered] :
	    sca$report_append_text ('<LIST>(UNNUMBERED)', TRUE);

        [sca$report_k_list_numbered] :
	    sca$report_append_text ('<LIST>(NUMBERED)', TRUE);

        [sca$report_k_list_lower_alpha] :
	    sca$report_append_text ('<LIST>(ALPHABETIC)', TRUE);

        [sca$report_k_list_upper_alpha] :
	    sca$report_append_text ('<LIST>(ALPHABETIC\UPPERCASE)', TRUE);

        [sca$report_k_list_lower_roman] :
	    sca$report_append_text ('<LIST>(ROMAN)', TRUE);

        [sca$report_k_list_upper_roman] :
	    sca$report_append_text ('<LIST>(ROMAN\UPPERCASE)', TRUE);

	[INRANGE, OUTRANGE] :
	    sca$report_bad_target (list_style);
	    RETURN;
    ENDCASE;

ENDPROCEDURE

PROCEDURE sca$report_start_parameter_document (parameter_name)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the formatting information necessary for starting
!   the description of a single parameter in the parameter list description of
!   a routine section.
!
! FORMAL PARAMETERS:
!
!   parameter_name
!
!	The name of the parameter, as a TPU string.  IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_PARAMETER_DOCUMENT');
    ENDON_ERROR;

    !  Use the <ARGITEM> tag to format a parameter name.
    !
    sca$report_append_text ('<ARGITEM>(' + parameter_name + ')', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_start_parameter_section_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the formatting information necessary for starting
!   the description of the parameter list in a routine section.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_PARAMETER_SECTION_DOCUMENT');
    ENDON_ERROR;

    !  The argument section is started by using the <ARGDEFLIST> tag.
    !
    sca$report_append_text ('<ARGDEFLIST>', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_start_routine_section_document (module_name, routine_name,
						     routine_decl_class)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to start a new routine section. A
!   routine section is a highly stylized section that describes a given routine,
!   such as used by the VMS documentation.
!
! FORMAL PARAMETERS:
!
!   module_name
!
!	The name of the module in which this routine is declared, as a TPU
!	string value.  IN parameter.
!
!   routine_name
!
!	The name of the routine, as a TPU string value.  IN parameter.
!
!   routine_decl_class
!
!	The declaration class of the routine, as a TPU string.  IN parameter.
!--
    LOCAL
	full_routine_title;

    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_ROUTINE_SECTION_DOCUMENT');
    ENDON_ERROR;

    ! Construct the routine title, including declaration class information if
    ! it is enabled.
    !
    IF sca$report_option_decl_class_routines
    THEN
    	full_routine_title := routine_name + ' (' + routine_decl_class + ')';
    ELSE
    	full_routine_title := routine_name;
    ENDIF;

    !  Start a routine section by writing the <ROUTINE_SECTION> and
    !  <ROUTINE_DECL> tags.
    !
    sca$report_append_text ('<ROUTINE_SECTION>(' + module_name + '\\NEWPAGE)',
			    TRUE);
    sca$report_append_text ('<ROUTINE_DECL>(' + full_routine_title + ')', TRUE);

    ! If the routine name is not blank, write the indexing tags to include the
    ! routine in the index.
    !
    IF routine_name <> tpu$k_unspecified
    THEN
	IF routine_name <> ''
	THEN
	    sca$report_append_text ('<X>('+ routine_name + '\BEGIN)', TRUE);
	    sca$report_append_text ('<X>('+ module_name + '<XS>' +
				    routine_name + ')', TRUE);
	    sca$report_append_text ('<Y>('+ routine_name + '<XS>See Also ' +
				    module_name + ')', TRUE);
	ENDIF;
    ENDIF;

ENDPROCEDURE

PROCEDURE sca$report_start_routine_subsection_document (heading)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to start a new subsection of a
!   routine section.
!
!   We implement this by using the <DESCRIPTION> tag, with an explicit
!   alternate heading as the tag parameter.  This forces all generic subsections
!   to have the same format as the DESCRIPTION subsection.  This is a fairly
!   general text format - special cases will require separate routines that
!   exploit the <SET_TEMPLATE_xxx> tags.
!
! FORMAL PARAMETERS:
!
!   heading
!
!	The heading to use for the subsection.  This must be a TPU string
!	value.  IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_ROUTINE_SUBSECTION_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('<DESCRIPTION>(' + heading + ')', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_start_section_document (section_title)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to start a new section.
!
! FORMAL PARAMETERS:
!
!   section_title
!
!	The name of the section, as a TPU string value.  IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_SECTION_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('<HEAD1>(' + section_title + ')', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_start_subsection_document (subsection_title)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the commands needed to start a new subsection.
!
! FORMAL PARAMETERS:
!
!   subsection_title
!
!	The name of the subsection, as a TPU string value.  IN parameter.
!
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_SUBSECTION_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('<HEAD2>(' + subsection_title + ')', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_start_software_specification_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure initializes a software specification report.  It writes
!   introductory formatting commands to the report.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_SOFTWARE_SPECIFICATION_DOCUMENT');
    ENDON_ERROR;

    ! Write the <DOCTYPE> tag to inform the user of the proper doctype to use
    ! when processing the report with VAX DOCUMENT.
    !
    sca$report_append_text ('<DOCTYPE>(SOFTWARE.REFERENCE)', TRUE);

    ! Include a comment indicating how the file was generated and on what date.
    !
    sca$report_append_text (
	FAO ('<COMMENT>(Generated by the LSE/SCA Report Tool, ' +
	     sca$report_internals_module_ident + ', !%D)', 0),
	TRUE);

    ! Write a dummy routine section so that the tags <ROUTINE_DECL> and <BODY>
    ! can be defined.
    !
    sca$report_blank_line;
    sca$report_append_text ('<ROUTINE_SECTION>(\\)', TRUE);
    sca$report_append_text (
	'<SET_TEMPLATE_ROUTINE>(ROUTINE_DECL\doublerunningheads)', TRUE);
    sca$report_append_text ('<SET_TEMPLATE_PARA>(BODY\Code Body\1)', TRUE);
    sca$report_append_text ('<ENDROUTINE_SECTION>', TRUE);
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_start_table_document (heading)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure sets things up for a table.
!
! FORMAL PARAMETERS:
!
!   heading
!
!	The heading to use for the table, as a TPU string.  IN parameter.
!
! IMPLICIT INPUTS:
!
!   sca$report_option_description_indent_width
!
!	The width of the first column of the table
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_START_TABLE_DOCUMENT');
    ENDON_ERROR;

    ! If the heading is null, set up an informal table.
    !
    IF heading = ''
    THEN
	sca$report_append_text ('<TABLE>', TRUE);
    ELSE
	! Set up a formal table with the specified heading.
	!
	sca$report_append_text ('<TABLE>(' + heading + ')', TRUE);
    ENDIF;

    ! Set up the table for 2 columns, using
    ! sca$report_option_description_indent_width as the width of the first
    ! column.
    !
    sca$report_append_text (
	  '<TABLE_SETUP>(2\' +
	      STR(sca$report_option_description_indent_width) + ')',
	  TRUE);

ENDPROCEDURE

PROCEDURE sca$report_unnumbered_heading_document (heading_text)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes an unnumbered heading.
!
! FORMAL PARAMETERS:
!
!   heading_text
!
!	The text of the heading.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_UNNUMBERED_HEADING_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('<SUBHEAD1>(' + heading_text + ')', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_write_cross_reference_document (cross_reference)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure adds a cross reference number to a previously written
!   overview line in the output buffer.
!
! FORMAL PARAMETERS:
!
!   cross_reference
!
!	The cross reference number to write, as an integer.  IN parameter.
!
! IMPLICIT INPUTS:
!
!   The current position is assumed to be the location to add the cross
!   reference number.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_WRITE_CROSS_REFERENCE_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text(' <CALLOUT_REF>(' + STR(cross_reference) + ')',
			   FALSE);
    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_write_line_break_document
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes a line break.
!
! FORMAL PARAMETERS:
!
!   None
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_WRITE_LINE_BREAK_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('<LINE>', TRUE);

ENDPROCEDURE

PROCEDURE sca$report_write_parameter_description_document (
	parameter_description)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the description of a single parameter.
!
! FORMAL PARAMETERS:
!
!   parameter_description
!
!	The description of the parameter, as a TPU range.  IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_WRITE_PARAMETER_DESCRIPTION_DOCUMENT');
    ENDON_ERROR;

    ! Write the <ARGDEF> tag to start the argument definition.
    !
    sca$report_append_text ('<ARGDEF>', TRUE);

    ! Write the description text.  Suppress the initial paragraph tag to
    ! perform proper alignment of the text.
    !
    sca$report_paragraph_document(parameter_description, FALSE);

    RETURN;

ENDPROCEDURE

PROCEDURE sca$report_write_return_value_document (routine_type,return_value)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the return value portion of the routine section.
!
! FORMAL PARAMETERS:
!
!   routine_type
!
!	The type of the routine, as a TPU string.  IN parameter.
!
!   return_value
!
!	A description of the return value, as a TPU string or range.  IN
!	parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_WRITE_RETURN_VALUE_DOCUMENT');
    ENDON_ERROR;

    ! Write the return value section if there is either a return type or return
    ! description text.
    !
    IF (routine_type <> '') OR (return_value <> '')
    THEN
	! Write the RETURNS header.
	!
	sca$report_append_text ('<RETURNS>(HEADONLY)', TRUE);

	! Write the return value type, if any.
	!
	IF routine_type <> ''
	THEN
	    sca$report_append_text ('<P>', TRUE);
	    sca$report_append_text (sca$report_item_type + ': ' + routine_type,
				   TRUE);
	    sca$report_blank_line;
	ENDIF;

	! Write the return value description text, if any.
	!
	IF return_value <> ''
	THEN
	    sca$report_append_text ('<RETTEXT>', TRUE);
	    sca$report_paragraph_document (return_value, TRUE);
	    sca$report_append_text ('<ENDRETTEXT>', TRUE);
	ENDIF;

	sca$report_blank_line;
    ENDIF;

ENDPROCEDURE

PROCEDURE sca$report_write_routine_format_document (routine_name, routine_type,
						    parameter_names)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the Format section of the routine description.  This
!   section shows the calling sequence for the routine.
!
! FORMAL PARAMETERS:
!
!   routine_name
!
!	The name of the routine, as a string.  IN parameter.
!
!   routine_type
!
!	The type of the routine return value (or '' if it has no return value),
!	as a string.  IN parameter.
!
!   parameter_names
!
!	The names of the parameters of the routine, as an array of strings, or
!	0 if the routine has no parameters.  IN parameter.
!--
    LOCAL
	i;

    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_WRITE_ROUTINE_FORMAT_DOCUMENT');
    ENDON_ERROR;

    ! Start the format section by writing the <FORMAT> and <FRTN> tags.
    !
    sca$report_append_text ('<FORMAT>', TRUE);
    sca$report_append_text ('<FRTN>(', FALSE);

    ! If there is a return value, then write the routine type followed by the
    ! routine name.  The arguments will be part of this tag.
    !
    IF routine_type <> ''
    THEN
	sca$report_append_text (routine_type + ' = \' + routine_name + '\',
			        FALSE);
    ELSE
	! If no return value, then write the routine name and close the <FRTN>
	! tag.  The arguments will be processed by the <FARGS> tag.
	!
	sca$report_append_text (routine_name + ')<FARGS>(', FALSE);
    ENDIF;

    ! Write the parameters (if any).
    !
    IF parameter_names <> 0
    THEN
	i := 1;
        LOOP
            EXITIF i > parameter_names{0};
	    IF i < parameter_names{0}
	    THEN
		sca$report_append_text (STR(parameter_names{i}) + ',', TRUE);
	    ELSE
		! This is the last parameter - don't follow it with a comma.
		!
		sca$report_append_text (parameter_names{i}, FALSE);
	    ENDIF;

	    i := i + 1;
        ENDLOOP;
    ENDIF;

    ! Write the closing parenthesis for the <FRTN> or <FARGS> tag and then
    ! write the <ENDFORMAT> tag to close the format section.
    !
    sca$report_append_text (')', TRUE);
    sca$report_append_text ('<ENDFORMAT>', TRUE);
    sca$report_blank_line;

ENDPROCEDURE

PROCEDURE sca$report_write_routine_remark_document (remark_string)
!++
! FUNCTIONAL DESCRIPTION:
!
!   This procedure writes the remark string of a routine to a routine section.
!
! FORMAL PARAMETERS:
!
!   remark_string
!
!	The remark string to write, as a TPU string.  IN parameter.
!--
    ON_ERROR
	[OTHERWISE] :
	    sca$report_common_error_cleanup('SCA$REPORT_WRITE_ROUTINE_REMARK_DOCUMENT');
    ENDON_ERROR;

    sca$report_append_text ('<OVERVIEW>', TRUE);
    sca$report_append_text (remark_string, TRUE);
    sca$report_append_text ('<ENDOVERVIEW>', TRUE);
    sca$report_blank_line;

ENDPROCEDURE
ENDMODULE