<%- #
    # This template belongs to the package Web::DataService, and contains
    # default definitions for generating documentation pages.
    # 
    # You can edit this in order to modify the look of your documentation pages.
    #
    # ===========================

    USE dumper;
    SET block_done = { };
    
    # Edit the following definitions to modify the labels used for navigation
    # -----------------------------------------------------------------------
    
    PROCESS doc_strings.tt;
    
    IF ds.version; SET main_doc_label = "$main_doc_label (v. $ds.version)"; END;
        
    msgval = {
    	format_param = ds.special_param('format')
	vocab_param = ds.special_param('vocab')
	show_param = ds.special_param('show')
    };
    
    MACRO sub_message(text) IF message.$text; message.$text; ELSE; text; "\n"; END;
    MACRO sub_value(msg, value) GET message.$msg FILTER replace('%s', value);
    
    # 
    # DOCSTRING : Include the documentation string for this node, if any.
    # -------------------------------------------------------------------
        
    BLOCK DOCSTRING; GET request.document_node or sub_message("MSG_DOCSTRING_MISSING"); END;
    
    MACRO DOCSTRING PROCESS DOCSTRING;
    
    #
    # USAGE: Display usage examples for this URL path
    # -----------------------------------------------
    
    BLOCK USAGE;
        IF block_done.usage; RETURN; ELSE; SET block_done.usage = 1; END;
        SET usage_doc = request.document_usage;
	IF usage_doc;
	    IF opt_noheader; "\n";
	    ELSE; "\n=head2 $section_label.usage\n\n";
            END;
	    IF content; GET content FILTER trim; "\n\n";
	    ELSE; sub_message("MSG_USAGE_HEADER_OP"); "\n\n";
            END;
	    usage_doc;
        END;
    END;
    
    MACRO USAGE INCLUDE USAGE;
    
    #
    # PARAMETERS: Document the parameters corresponding to this URL path
    # ------------------------------------------------------------------
    
    BLOCK PARAMETERS;
        IF block_done.params; RETURN; ELSE; SET block_done.params = 1; END;
    	"\n=head2 $section_label.params\n\n";
	SET param_doc = request.document_params(ruleset);
	IF content; GET content FILTER trim; "\n\n"; sub_message(param_doc);
	ELSIF param_doc; sub_message("MSG_PARAM_HEADER_OP"); "\n\n"; param_doc;
	ELSE; sub_message("MSG_PARAM_NONE_DEFINED");
	END;
    END;
    
    MACRO PARAMETERS(ruleset) INCLUDE PARAMETERS;
    
    #
    # METHODS: Document the HTTP methods accepted by this URL path
    # ------------------------------------------------------------
    
    BLOCK METHODS;
        IF block_done.methods; RETURN; ELSE; SET block_done.methods = 1; END;
        SET method_list = request.document_http_methods or sub_method("MSG_METHOD_NONE_DEFINED");
        "\n=head2 $section_label.methods\n\n";
	IF content; GET content FILTER trim;
        ELSIF request.node_has_operation; sub_message("MSG_METHOD_HEADER_OP");
        ELSE; sub_message("MSG_METHOD_HEADER_NODE");
        END;
	GET " $method_list";
    END;
    
    MACRO METHODS INCLUDE METHODS;
    
    #
    # FORMATS: Document the formats allowed by this URL path
    # ------------------------------------------------------
    
    BLOCK FORMATS;
        IF block_done.formats; RETURN; ELSE; SET block_done.formats = 1; END;
        SET options = { };
        IF opt_extended; options.extended = 1; END;
	IF opt_all; options.path = '/'; END;
	IF request.node_path == '/'; opt_all = 1; END;
	SET format_doc = request.document_formats(options);
	"\n=head2 $section_label.formats\n\n";
  	IF format_doc.match('^MSG_'); sub_message(format_doc);
	ELSIF content; GET content FILTER trim; "\n\n$format_doc";
	ELSIF opt_all;
	    sub_message("MSG_FORMAT_HEADER_ALL");
	    sub_message("MSG_FORMAT_HEADER_SUFFIX") IF ds.has_feature('format_suffix');
	    sub_message("MSG_FORMAT_HEADER_PARAM") IF ds.special_param('format');
	    "\n\n$format_doc";
	ELSE;
	    sub_message("MSG_FORMAT_HEADER_SOME");
	    sub_message("MSG_FORMAT_HEADER_SUFFIX") IF ds.has_feature('format_suffix');
	    sub_message("MSG_FORMAT_HEADER_PARAM") IF ds.special_param('format');
	    IF not ds.has_feature('format_suffix');
	        default_value = request.default_format;
	        sub_value("MSG_FORMAT_HEADER_DEFAULT", default_value) IF default_value;
	    END;
	    "\n\n$format_doc";
	END;
    END;
    
    MACRO FORMATS INCLUDE FORMATS;
    
    #
    # VOCABULARIES: Document the vocabularies allowed by this URL path
    # ----------------------------------------------------------------
    
    BLOCK VOCABULARIES;
        IF block_done.vocabs; RETURN; ELSE; SET block_done.vocabs = 1; END;
	SET options = { };
        IF opt_extended; options.extended = 1; END;
	IF opt_all; options.path = '/'; END;
	IF request.node_path == '/'; opt_all = 1; END;
	SET vocab_doc = request.document_vocabs(options);
	IF vocab_doc;
	    "\n=head2 $section_label.vocabs\n\n";
	    IF content;
	        GET content FILTER trim; "\n\n$vocab_doc";
	    ELSIF opt_all;
	        sub_message("MSG_VOCAB_HEADER_ALL");
	        sub_message("MSG_VOCAB_HEADER_PARAM") IF ds.special_param('vocab');
	        "\n\n$vocab_doc";
	    ELSE;
	        sub_message("MSG_VOCAB_HEADER_SOME");
	        sub_message("MSG_VOCAB_HEADER_PARAM") IF ds.special_param('vocab');
	        "\n\n$vocab_doc";
            END;
	END;
    END;
    
    MACRO VOCABULARIES INCLUDE VOCABULARIES;
    
    # 
    # RESPONSE: Document the response fields returned by this URL path
    # ----------------------------------------------------------------

    BLOCK RESPONSE;
        IF block_done.response; RETURN; ELSE; SET block_done.response = 1; END;
        "\n=head2 $section_label.response\n\n";
	SET response_doc = request.document_response;
	SET fixed = request.output_label;
	SET optional = request.optional_output;
	IF response_doc;
	    IF content; GET content FILTER trim;
	    ELSE;
	        sub_message("MSG_RESPONSE_HEADER");
	    	IF fixed && optional;
	            sub_value("MSG_RESPONSE_HEADER_FIXED", fixed);
	    	    sub_message("MSG_RESPONSE_HEADER_OPT");
	    	ELSIF optional;
	            sub_message("MSG_RESPONSE_HEADER_OPT_ONLY");
	    	END;
		"\n\n";
	    END;
	    GET response_doc;
	    INCLUDE FORMATS;
	    INCLUDE VOCABULARIES;
	ELSE;
	    sub_message("MSG_RESPONSE_NONE_DEFINED");
	END;
    END;
    
    MACRO RESPONSE INCLUDE RESPONSE;
    
    #
    # STANDARD: Include all of the standard blocks for an "operation" page
    # --------------------------------------------------------------------
    
    BLOCK STANDARD;
        INCLUDE PARAMETERS;
	INCLUDE METHODS;
	INCLUDE RESPONSE;
    END;
    
    MACRO STANDARD INCLUDE STANDARD;
    
    # 
    # TRAIL: Add a navigation trail to the page
    # -----------------------------------------
    
    BLOCK NAVTRAIL;
        IF block_done.trail; RETURN; ELSE; SET block_done.trail = 1; END;
	SET navtrail = "";
        FOREACH item IN request.list_navtrail(main_doc_label);
	    IF navtrail; SET navtrail = "$navtrail E<GT> $item";
	    ELSE; SET navtrail = item; END;
        END;
        "\n=for wds_nav =head3 $main_doc_prefix$navtrail\n";
    END;
    
    MACRO NAVTRAIL INCLUDE NAVTRAIL;
    
    # 
    # URL: Generate an example URL
    # ----------------------------
    
    BLOCK URL;
        SET args = { };
	args.operation = operation;
	IF documentation; args.documentation = documentation; END;
    	IF format; args.format = format; END;
	IF params; args.params = params; END;
	IF fragment; args.fragment = fragment; END;
	IF type; args.type = type; END;
	dumper.dump(args);
	# ds.generate_url(args);
    END;
    
    MACRO URL INCLUDE URL;
    
    BLOCK DOC_URL;
        SET args = { documentation = path };
        IF format; args.format = format; END;
        IF fragment; args.fragment = fragment; END;
        IF type; args.type = type; END;
        SET url = ds.generate_url(args);
        IF title; "L<$title|$url>";
        ELSE; "L<$url>"; END;
    END;
    
    MACRO DOC_URL(path) INCLUDE DOC_URL;

-%>
