Html create replace package html html donald

Chapter 9 ■ DoCumenting

Programmers are four times as likely to use a component if they know it exists beforehand and they also know how to use it. That sounds like training, doesn’t it? Will your CFO or project manager tell you that you may not provide training; in other words, that you may not reuse your components? If not, then you’ll need documentation you can distribute freely. To that end, let’s look at the ability to create distributable documentation from a package or TYPE specification next.

An HTML-Based Documentation Formatting Tool

Listing 9-3 is the package specification for an HTML-based help tool. Working with the capabilities of SQL*Plus, I can use it to produce an HTML help file for each executable object, and then an index to all those documents.

14
15 PROCEDURE create_help(
16 aiv_object_name in varchar2);
17
18
19 -- Text-based help for this package. "set serveroutput on" in SQL*Plus.

20
21 PROCEDURE help;
22
23
24 PROCEDURE test;
25
26

•� create_index() creates an index to all the documents created using the next method, create_help().

•� create_help() creates an HTML-based document from the comments and method signatures in a specification.

Listing 9-4. A Package Body to Create HTML-Based Help, html_help.pkb

001 create or replace PACKAGE BODY HTML_HELP as
002 /*
003 html_help.pkb
004 by Donald J. Bales on 2014-10-20
005 Package to create HTML-based help files for packages
006 */
007
008 -- TYPES
009
010 TYPE spec_record is record (
011 line_type varchar2(1),
012 line_number number,
013 line_text varchar2(2000),
014 method_name varchar2(2000),
015 first_sentence varchar2(2000));
016
017 TYPE spec_table is table of spec_record index by binary_integer; 018
019 TYPE buffer_table is table of varchar2(2000) index by binary_integer; 020
021 -- CONSTANTS
022
023 v_LT_COMMENT constant varchar2(1) := 'C';
024 v_LT_METHOD constant varchar2(1) := 'M';
025 v_LT_OTHER constant varchar2(1) := 'O';
026
027 -- FORWARD DECLARATIONS
028