ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/PROG/MISC/ADA_LRM3.ZIP/LR7VT.SRC

Text File | 1989-03-30 | 50.8 KB | 1,512 lines

--                ON-LINE Ada LANGUAGE REFERENCE MANUAL
--        Developed at Nofolk State University
--        Development funded by a grant from the U. S. Army
--        Project ReDTEA
--        Version 1.0 released December 1988
--        Programmer:        Esther M. Lumsdon
--        Project Director:  George C. Harrison, PhD



with TEXT_IO; use TEXT_IO;
with MACHINE_SPECIFIC; use MACHINE_SPECIFIC;
with LRM_TYPES; use LRM_TYPES;
with LRM_GLOBAL; use LRM_GLOBAL;
with STARLET; use STARLET;
with SMG; use SMG;

package LRM_SMG is



  ANNEX_MENU_DISPLAY   : LONGWORD_UNSIGNED;
  CHAPTER_MENU_DISPLAY : LONGWORD_UNSIGNED;
  KB_ID                : LONGWORD_UNSIGNED;
  LEFT_MOST            : NATURAL;
  -- X coordinate of where to paste virtual displays
  --  dependent on whether they have borders or not.
  LIMITED_BORDERS      : BOOLEAN;
  -- true if user doesn't want border on every window.

  MAIN_MENU_CHOICE     : STRING(1 .. 4);

  MAIN_MENU_DISPLAY    : LONGWORD_UNSIGNED;
  RESULTANT_FILE       : STRING(1 .. 10);
  SIZE_COLUMNS         : LONGWORD_SIGNED;
  SIZE_ROWS            : LONGWORD_SIGNED;
  -- # of rows and columns available on user's terminal
  TERM_ID              : LONGWORD_UNSIGNED;
  -- id assigned to user's terminal (pasteboard)
  TEXT_SCREEN_DISPLAY  : LONGWORD_UNSIGNED;
  TOP_MOST             : NATURAL;
  -- X coordinate of where to paste virtual displays
  --  dependent on whether they have borders or not.
  USING_DEC_TERMINAL   : BOOLEAN;
  -- true if using DEC or compatible terminal (capable of obeying SMG$
  --   VAX VMS system calls); false otherwise.
  VD_2_ID              : LONGWORD_UNSIGNED;
  -- prompt and error message box


  procedure INITIALIZE;

  procedure WELCOME(IN_FILE_NAME : in STRING);

  procedure DISPLAY_EXPLAIN(IN_FILE_NAME : in STRING);

  procedure DISPLAY_MAIN_MENU(IN_FILE_NAME : in STRING);

  procedure SELECT_FROM_MAIN_MENU(MAIN_MENU_CHOICE : out STRING);

  procedure SCROLL_TEXT(IN_FILE_NAME : in STRING;
                        SAVE_TITLE   : in STRING;
                        SAVE_FILE    : in out FILE_TYPE);

  procedure DO_CHAPTER_MENU(SAVE_FILE : in out FILE_TYPE);

  procedure DO_ANNEX_MENU(SAVE_FILE : in out FILE_TYPE);

  procedure CREDITS(SAVE_FILE : in out FILE_TYPE);

  procedure TERMINATE_LRM;


end LRM_SMG;

-----------------------------------------------------------------

with TEXT_IO; use TEXT_IO;
with LRM_TYPES; use LRM_TYPES;
with LRM_GLOBAL; use LRM_GLOBAL;
with STARLET; use STARLET;
with SMG; use SMG;
with INT_IO; use INT_IO;

package body LRM_SMG is




  procedure DISPLAY_MENU(IN_FILE_NAME : in STRING;
                         DISPLAY_ID   : in LONGWORD_UNSIGNED) is



  -- read menu text from file, and put entire file on screen.

    EMPTY_STRING_80 : STRING(1 .. 80);
    LAST_CHAR       : NATURAL := 0;
    READ_IN_FILE    : FILE_TYPE;
    READ_IN_LINE    : STRING(1 .. 80);


  begin
    for I in 1 .. 80 loop
      EMPTY_STRING_80 := (others => ' ');
    end loop;

    OPEN(READ_IN_FILE, IN_FILE, IN_FILE_NAME);
    while not END_OF_FILE(READ_IN_FILE) loop
      READ_IN_LINE := EMPTY_STRING_80;
      GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
      PUT_LINE(DISPLAY_ID => DISPLAY_ID, TEXT => READ_IN_LINE);
    end loop;

  end DISPLAY_MENU;


------------------------------------------------------------------------------


  procedure DISPLAY_CHAPTER_MENU(IN_FILE_NAME : in STRING) is



  -- read menu text from file, and put entire file on screen.

    EMPTY_STRING_80 : STRING(1 .. 80);
    LAST_CHAR       : NATURAL := 0;
    READ_IN_FILE    : FILE_TYPE;
    READ_IN_LINE    : STRING(1 .. 80);


  begin
    EMPTY_STRING_80 := (others => ' ');

    OPEN(READ_IN_FILE, IN_FILE, IN_FILE_NAME);
    SET_CURSOR_ABS(CHAPTER_MENU_DISPLAY, 3, 1);

    while not END_OF_FILE(READ_IN_FILE) loop
      READ_IN_LINE := EMPTY_STRING_80;
      GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
      PUT_LINE(DISPLAY_ID => CHAPTER_MENU_DISPLAY, TEXT => READ_IN_LINE);

    -- VMS 5.0  put_line (display_id => chapter_menu_display, text
    --  => read_in_line, flags => smg$m_wrap_word);
    end loop;

  end DISPLAY_CHAPTER_MENU;






------------------------------------------------------------------------------
  procedure INITIALIZE is

  --    Initialization for on-line Ada Language Reference Manual
  --      using SMG$ virtual terminal driver
  --
  --
  --LOGIC:
  --
  -- Decide terminal category
  -- Prompt user for value of limited_borders
  -- create pasteboard
  -- create bordered box for prompts ( 1 rows x 78 columns @20,2), the
  --     annex_menu_display, chapter_menu_display, main_menu_display;
  --     most of these are 18 rows x 78 columns, paste @2,2.
  --
  -- create virtual keyboard for user input
  -- attach virtual keyboard to user device
  --


    BORDER_CHOICE : CHARACTER := 'y';
    OD            : CHAR_STRING(1 .. 10);  -- output device
    PSF           : MASK_LONGWORD;  -- Preserve Screen Flag (in SMG$)

  ----------------------------------------------------------------------------
    procedure DECIDE_TERM_CATEGORY(USING_DEC_TERMINAL : out BOOLEAN) is

      CHOSE_TERMINAL_CATEGORY : BOOLEAN;
      TERM_CATEGORY           : CHARACTER;


    begin

      loop
        CLS;
        PUT_LINE("  The following terminals are available for your use at NSU:")
          ;
        PUT_LINE("Category A terminals:");
        PUT_LINE("    VISUAL brand terminals");
        PUT_LINE("    TeleVideo brand terminals");
        PUT_LINE("    DEC terminals");
        NEW_LINE;
        PUT_LINE("Category B terminals:");
        PUT_LINE("    ADM brand terminals");
        PUT_LINE("    Adds-Viewpoint terminals");
        PUT_LINE("    Hazeltine brand terminals");
        NEW_LINE(2);
        PUT(
          "Please enter A or B for the category of terminal that you are using: "
          );
        GET(TERM_CATEGORY);
        CHOSE_TERMINAL_CATEGORY := TRUE;
        case TERM_CATEGORY is
          when 'A' | ASCII.LC_A =>
            USING_DEC_TERMINAL := TRUE;
          when 'B' | ASCII.LC_B =>
            USING_DEC_TERMINAL := FALSE;
          when others =>
            CHOSE_TERMINAL_CATEGORY := FALSE;
        end case;
        exit when CHOSE_TERMINAL_CATEGORY;
      end loop;

    end DECIDE_TERM_CATEGORY;

    -----------------------------------------------------------------

  begin

    -- create annex_menu_display, chapter_menu_display, main_menu_display,
    -- text_screen_display
    CLS;
    USING_DEC_TERMINAL := TRUE;
    if USING_DEC_TERMINAL then
      NEW_LINE(2);
      PUT_LINE("Do you want windows with borders, or without borders?");
      PUT(
        "If you are accessing this system at slower than 4800 baud, your screen"
        );
      NEW_LINE;
      PUT_LINE("  will update much faster without borders.");
      NEW_LINE;
      PUT("Do you want borders (y/n) ? ");
      GET(BORDER_CHOICE);
      if (BORDER_CHOICE = 'n' or BORDER_CHOICE = 'N') then
        LIMITED_BORDERS := TRUE;
        SCREEN_HEIGHT := 19;
      else
        LIMITED_BORDERS := FALSE;
        SCREEN_WIDTH := SCREEN_WIDTH - 2;
        SCREEN_HEIGHT := 18;
      end if;
      OD := "SYS$OUTPUT";

      --  set psf=0
      PSF := 0;
      CREATE_PASTEBOARD(TERM_ID, OD, SIZE_ROWS, SIZE_COLUMNS, PSF);
      CREATE_VIRTUAL_KEYBOARD(NEW_KEYBOARD_ID => KB_ID, RESULTANT_FILESPEC =>
        RESULTANT_FILE);
      if LIMITED_BORDERS then
        TOP_MOST := 1;
        LEFT_MOST := 1;
      else
        TOP_MOST := 2;
        LEFT_MOST := 2;
      end if;
      if LIMITED_BORDERS then
        CREATE_VIRTUAL_DISPLAY(NUM_ROWS => 25, NUM_COLUMNS => 80, NEW_DISPLAY_ID
          => CHAPTER_MENU_DISPLAY);
      else
        CREATE_VIRTUAL_DISPLAY(22, 78, CHAPTER_MENU_DISPLAY, SMG_M_BORDER);
      end if;
      if LIMITED_BORDERS then
        CREATE_VIRTUAL_DISPLAY(NUM_ROWS => 19, NUM_COLUMNS => 80, NEW_DISPLAY_ID
          => ANNEX_MENU_DISPLAY);
      else

--        CREATE_VIRTUAL_DISPLAY_ATTRIBUTES(19, 78, ANNEX_MENU_DISPLAY,
        --          SMG_M_BORDER, SMG_M_BOLD);
        CREATE_VIRTUAL_DISPLAY(19, 78, ANNEX_MENU_DISPLAY, SMG_M_BORDER);
      end if;
      DISPLAY_MENU(MENU_ANNEX_FILE_NAME, ANNEX_MENU_DISPLAY);
      DISPLAY_CHAPTER_MENU(MENU_CHAPTER_FILE_NAME);

      if LIMITED_BORDERS then
        CREATE_VIRTUAL_DISPLAY(NUM_ROWS => 19, NUM_COLUMNS => 80, NEW_DISPLAY_ID
          => MAIN_MENU_DISPLAY);
      else

        --        CREATE_VIRTUAL_DISPLAY_ATTRIBUTES(19, 78, MAIN_MENU_DISPLAY,
        --          SMG_M_BORDER, SMG_M_BOLD);
        CREATE_VIRTUAL_DISPLAY(19, 78, MAIN_MENU_DISPLAY, SMG_M_BORDER);
      end if;
      if LIMITED_BORDERS then
        CREATE_VIRTUAL_DISPLAY(NUM_ROWS => 19, NUM_COLUMNS => 80, NEW_DISPLAY_ID
          => TEXT_SCREEN_DISPLAY);
      else

--        CREATE_VIRTUAL_DISPLAY_ATTRIBUTES(19, 78, TEXT_SCREEN_DISPLAY,
        --          SMG_M_BORDER, SMG_M_BOLD);
        CREATE_VIRTUAL_DISPLAY(19, 78, TEXT_SCREEN_DISPLAY, SMG_M_BOLD);
      end if;


      CREATE_VIRTUAL_DISPLAY(1, 78, VD_2_ID, SMG_M_BORDER, SMG_M_BOLD);

    end if;

  end INITIALIZE;




------------------------------------------------------------------------------


  procedure TERMINATE_LRM is
  --TERM_ID : in LONGWORD_UNSIGNED;
  --                          VD_2_ID : in LONGWORD_UNSIGNED



  --  LOGIC:
  --  delete all virtual displays (pop the stack)
  --  delete the pasteboard


  begin
    POP_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID);
    POP_VIRTUAL_DISPLAY(MAIN_MENU_DISPLAY, TERM_ID);
    if IS_OPEN(SAVE_FILE) then
      CLOSE(SAVE_FILE);
    end if;
    CLS;
    NEW_LINE(2);
    PUT_LINE("Thank you for using the Ada Language Reference Manual Reader.");
  end TERMINATE_LRM;




------------------------------------------------------------------------------

  procedure DISPLAY_MAIN_MENU(IN_FILE_NAME : in STRING) is


  -- read menu text from file, and put entire file on screen.

    EMPTY_STRING_80 : STRING(1 .. 80);
    LAST_CHAR       : NATURAL := 0;
    READ_IN_FILE    : FILE_TYPE;
    READ_IN_LINE    : STRING(1 .. 80);


  begin
    EMPTY_STRING_80 := (others => ' ');
    PASTE_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID, 22, 2);
    PASTE_VIRTUAL_DISPLAY(MAIN_MENU_DISPLAY, TERM_ID, 2, 2);

    OPEN(READ_IN_FILE, IN_FILE, IN_FILE_NAME);
    while not END_OF_FILE(READ_IN_FILE) loop
      READ_IN_LINE := EMPTY_STRING_80;
      GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
      PUT_LINE(DISPLAY_ID => MAIN_MENU_DISPLAY, TEXT => READ_IN_LINE);
    end loop;

  end DISPLAY_MAIN_MENU;






  ---------------------------------------------------------------------------

------------------------------------------------------------------------------

  procedure SCROLL_TEXT(IN_FILE_NAME : in STRING;
                        SAVE_TITLE   : in STRING;
                        SAVE_FILE    : in out FILE_TYPE) is



  -- scroll text file on the screen, 19 lines at a time

    type COMMAND is (CONTINUE, DISPLAY_AGAIN, EXIT_COMMAND, SAVE, NOTHING);

    BLANK_COUNT      : NATURAL := 0;
    CURRENT_LINE     : NATURAL := 0;
    EXIT_NOW         : BOOLEAN := FALSE;
    GOOD_ANSWER      : BOOLEAN;
    LAST_CHAR        : NATURAL := 0;
    LAST_COMMAND     : COMMAND := NOTHING;
    READ_IN_FILE     : FILE_TYPE;
    READ_IN_LINE     : STRING(1 .. 156);
    EMPTY_STRING_156 : STRING(1 .. 156);
    RECD_STR_LEN     : WORD_UNSIGNED;
    SAVING           : BOOLEAN := FALSE;
    TERM_CODE        : WORD_UNSIGNED;
    WAIT_STR         : STRING(1 .. 10);
    LINE_COUNT       : NATURAL := 0;

  begin
    EMPTY_STRING_156 := (others => ' ');

    OPEN(READ_IN_FILE, IN_FILE, IN_FILE_NAME);
    ERASE_DISPLAY(TEXT_SCREEN_DISPLAY);
    PASTE_VIRTUAL_DISPLAY(TEXT_SCREEN_DISPLAY, TERM_ID, 2, 2);

    --    PASTE_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID, 22, 2);
    while not EXIT_NOW loop
      LINE_COUNT := 0;
      if LAST_COMMAND /= SAVE then

        while ((not END_OF_FILE(READ_IN_FILE)) and (LINE_COUNT < SCREEN_HEIGHT))
          loop
          READ_IN_LINE := EMPTY_STRING_156;
          GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);

          --          don't need a SKIP_LINE statement.
          --          SKIP_LINE (READ_IN_FILE);
          if LAST_CHAR = 0 then
            BLANK_COUNT := BLANK_COUNT + 1;
          else
            BLANK_COUNT := 0;
          end if;
          if BLANK_COUNT < 3 then
            if LAST_CHAR > SCREEN_WIDTH then
              PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE(1
                .. SCREEN_WIDTH));
              PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE(
                SCREEN_WIDTH + 1 .. LAST_CHAR));
              LINE_COUNT := LINE_COUNT + 2;
            else
              PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE(1
                .. LAST_CHAR));
              LINE_COUNT := LINE_COUNT + 1;
            end if;
          end if;
          if SAVING then
            PUT_LINE(SAVE_FILE, READ_IN_LINE(1 .. LAST_CHAR));
          end if;
          CURRENT_LINE := CURRENT_LINE + 1;
        end loop;

      end if;

      GOOD_ANSWER := FALSE;
      while not GOOD_ANSWER loop
        GOOD_ANSWER := TRUE;
        if END_OF_FILE(READ_IN_FILE) then
          if SAVING then
            NEW_LINE(SAVE_FILE, 3);
          end if;
          READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => WAIT_STR, TIMEOUT
            => 500, PROMPT_STRING => "     E[xit]   S[ave]   D[isplay again] "
            , MAX_LENGTH => 1, RECEIVED_STRING_LENGTH => RECD_STR_LEN,
            TERMINATOR_CODE => TERM_CODE, DISPLAY_ID => VD_2_ID);
        else
          READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => WAIT_STR, TIMEOUT
            => 500, PROMPT_STRING =>
            "     E[xit]   C[ontinue]   S[ave]   D[isplay again] ", MAX_LENGTH
            => 1, RECEIVED_STRING_LENGTH => RECD_STR_LEN, TERMINATOR_CODE =>
            TERM_CODE, DISPLAY_ID => VD_2_ID);
        end if;
        PUT_LINE(DISPLAY_ID => VD_2_ID, TEXT => "               ");
        case WAIT_STR(1) is
          when 'E' | ASCII.LC_E =>
            LAST_COMMAND := EXIT_COMMAND;
            EXIT_NOW := TRUE;
            exit;
          when 'S' | ASCII.LC_S =>
            LAST_COMMAND := SAVE;
            if not SAVING then
              if not IS_OPEN(SAVE_FILE) then
                CREATE(SAVE_FILE, OUT_FILE, LRM_READER_SAVE_FILE_NAME);
              end if;
              PUT_LINE(SAVE_FILE,
                "Reference from Ada Language Reference Manual:");
              PUT_LINE(SAVE_FILE, SAVE_TITLE);

              -- write title of what is being saved to save_file.
              NEW_LINE(SAVE_FILE, 2);
              SAVING := TRUE;
              if CURRENT_LINE > 1 then
                RESET(READ_IN_FILE, IN_FILE);
                for I in 1 .. CURRENT_LINE loop
                  GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
                  PUT_LINE(SAVE_FILE, READ_IN_LINE(1 .. LAST_CHAR));
                end loop;
              end if;
            end if;
          when 'D' | ASCII.LC_D =>
            LAST_COMMAND := DISPLAY_AGAIN;
            RESET(READ_IN_FILE, IN_FILE);
            CURRENT_LINE := 0;
            PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => "      ");
          when 'C' | ASCII.LC_C =>
            LAST_COMMAND := CONTINUE;

          -- continue the display
          when others =>
            GOOD_ANSWER := FALSE;
        end case;

      -- while not good_answer loop
      end loop;

    --  while not exit_now loop
    end loop;


    if SAVING then
      NEW_LINE(SAVE_FILE, 3);
    end if;
    CLOSE(READ_IN_FILE);
    UNPASTE_VIRTUAL_DISPLAY(TEXT_SCREEN_DISPLAY, TERM_ID);

  --    UNPASTE_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID);
  end SCROLL_TEXT;




------------------------------------------------------------------------------

  procedure WELCOME(IN_FILE_NAME : in STRING) is



  --  display welcome message for 3 seconds

    KEY_TO_CONTINUE         : CHARACTER;
    LAST_CHAR               : NATURAL := 0;
    LINE_COUNT              : NATURAL;
    RECD_STR_LEN, TERM_CODE : WORD_UNSIGNED;
    WAIT_STR                : STRING(1 .. 10);
    WELCOME_FILE            : FILE_TYPE;
    -- menu.welcome_msg is 19 lines x 80 cols
    WELCOME_ID              : LONGWORD_UNSIGNED;
    WELCOME_LINE            : STRING(1 .. 80);



    -- the widest size virt disp that can have visible borders on a
    -- terminal is 78 columns. this must be displayed at column 2.



  begin
    OPEN(WELCOME_FILE, IN_FILE, IN_FILE_NAME);

    --"menu.welcome_msg");
    GET_LINE(WELCOME_FILE, WELCOME_LINE, LAST_CHAR);
    if LIMITED_BORDERS then
      CREATE_VIRTUAL_DISPLAY(NUM_ROWS => 22, NUM_COLUMNS => 78, NEW_DISPLAY_ID
        => WELCOME_ID, VIDEO_ATTRIBUTES => SMG_M_BOLD);
    else
      CREATE_VIRTUAL_DISPLAY(22, 78, WELCOME_ID, SMG_M_BORDER);

    -- was 19, 78   15, 74
    end if;
    PASTE_VIRTUAL_DISPLAY(WELCOME_ID, TERM_ID, 2, 2);

    --was2,2  4,4
    if not LIMITED_BORDERS then
      LABEL_BORDER(WELCOME_ID, "WELCOME", 0);
    end if;

    while not END_OF_FILE(WELCOME_FILE) loop
      GET_LINE(WELCOME_FILE, WELCOME_LINE, LAST_CHAR);
      SKIP_LINE(WELCOME_FILE);
      PUT_LINE(DISPLAY_ID => WELCOME_ID, TEXT => WELCOME_LINE);
    end loop;

    READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => WAIT_STR, MAX_LENGTH => 1
      , TIMEOUT => 10, RECEIVED_STRING_LENGTH => RECD_STR_LEN, TERMINATOR_CODE
      => TERM_CODE, DISPLAY_ID => WELCOME_ID);
    POP_VIRTUAL_DISPLAY(WELCOME_ID, TERM_ID);

    CLOSE(WELCOME_FILE);
  end WELCOME;




  ---------------------------------------------------------------------------

  procedure CREDITS(SAVE_FILE : in out FILE_TYPE) is



  -- scroll credit on the screen


  begin
    SCROLL_TEXT(CREDITS_FILE_NAME, "Credits          ", SAVE_FILE);

  end CREDITS;

------------------------------------------------------------------------------

  procedure DISPLAY_EXPLAIN(IN_FILE_NAME : in STRING) is



  -- scroll text file on the screen, 19 lines at a time

    GOOD_ANSWER     : BOOLEAN;
    LAST_CHAR       : NATURAL := 0;
    READ_IN_FILE    : FILE_TYPE;
    READ_IN_LINE    : STRING(1 .. 80);
    EMPTY_STRING_80 : STRING(1 .. 80);
    RECD_STR_LEN    : WORD_UNSIGNED;
    TERM_CODE       : WORD_UNSIGNED;
    WAIT_STR        : STRING(1 .. 10);
    LINE_COUNT      : NATURAL := 0;

  begin
    EMPTY_STRING_80 := (others => ' ');
    OPEN(READ_IN_FILE, IN_FILE, IN_FILE_NAME);
    PASTE_VIRTUAL_DISPLAY(TEXT_SCREEN_DISPLAY, TERM_ID, 2, 2);
    PASTE_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID, 22, 2);

    while not (END_OF_FILE(READ_IN_FILE)) loop

      LINE_COUNT := 0;

      while (LINE_COUNT < (SCREEN_HEIGHT - 2)) loop
        READ_IN_LINE := EMPTY_STRING_80;
        if not END_OF_FILE(READ_IN_FILE) then
          GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);

          --          don't need a SKIP_LINE statement.
          --          SKIP_LINE (READ_IN_FILE);
          if LAST_CHAR > SCREEN_WIDTH then
            PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE(1
              .. SCREEN_WIDTH));
            PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE(
              SCREEN_WIDTH + 1 .. LAST_CHAR));
            LINE_COUNT := LINE_COUNT + 2;
          else
            PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE);
            LINE_COUNT := LINE_COUNT + 1;
          end if;
        else
          exit;
        end if;
      end loop;
      READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => WAIT_STR, TIMEOUT => 5
        , PROMPT_STRING => "     C[ontinue] ", MAX_LENGTH => 1,
        RECEIVED_STRING_LENGTH => RECD_STR_LEN, TERMINATOR_CODE => TERM_CODE,
        DISPLAY_ID => VD_2_ID);
      PUT_LINE(DISPLAY_ID => VD_2_ID, TEXT => "               ");

    --  while not eof(read_in_file) loop
    end loop;

    CLOSE(READ_IN_FILE);
    UNPASTE_VIRTUAL_DISPLAY(TEXT_SCREEN_DISPLAY, TERM_ID);
    UNPASTE_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID);


  end DISPLAY_EXPLAIN;





------------------------------------------------------------------------------

  procedure SELECT_FROM_MAIN_MENU(MAIN_MENU_CHOICE : out STRING) is

    MAIN_MENU_CHOICE_LEN : WORD_UNSIGNED;
    TERM_CODE            : WORD_UNSIGNED;

  begin
    PUT_LINE(DISPLAY_ID => VD_2_ID, TEXT => "                        ");
    READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => MAIN_MENU_CHOICE,
      MAX_LENGTH => 1, RECEIVED_STRING_LENGTH => MAIN_MENU_CHOICE_LEN,
      PROMPT_STRING => "Choose from 1 - 7, please: ", TERMINATOR_CODE =>
      TERM_CODE, DISPLAY_ID => VD_2_ID);
    PUT_LINE(DISPLAY_ID => VD_2_ID, TEXT => "                        ");
  end SELECT_FROM_MAIN_MENU;

------------------------------------------------------------------------------

  procedure DO_ANNEX_MENU(SAVE_FILE : in out FILE_TYPE) is

    ANNEX_MENU_CHOICE     : STRING(1 .. 2);
    ANNEX_MENU_CHOICE_LEN : WORD_UNSIGNED;
    TERM_CODE             : WORD_UNSIGNED;


  begin
    PASTE_VIRTUAL_DISPLAY(ANNEX_MENU_DISPLAY, TERM_ID, 2, 2);
    loop
      READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => ANNEX_MENU_CHOICE,
        MAX_LENGTH => 1, RECEIVED_STRING_LENGTH => ANNEX_MENU_CHOICE_LEN,
        PROMPT_STRING => "Choose from A - F or Q, please: ", TERMINATOR_CODE =>
        TERM_CODE, DISPLAY_ID => VD_2_ID);
      PUT_LINE(DISPLAY_ID => VD_2_ID, TEXT => "              ");
      case ANNEX_MENU_CHOICE(1) is
        when 'A' | 'a' =>
          SCROLL_TEXT(LRM_FILE_NAME_PREFIX(1 .. LRM_FILE_NAME_PREFIX_LENGTH) &
            "chapa.doc", "Annex A          ", SAVE_FILE);
        when 'B' | 'b' =>
          SCROLL_TEXT(LRM_FILE_NAME_PREFIX(1 .. LRM_FILE_NAME_PREFIX_LENGTH) &
            "chapb.doc", "Annex B          ", SAVE_FILE);
        when 'C' | 'c' =>
          SCROLL_TEXT(LRM_FILE_NAME_PREFIX(1 .. LRM_FILE_NAME_PREFIX_LENGTH) &
            "chapc.doc", "Annex C          ", SAVE_FILE);
        when 'D' | 'd' =>
          SCROLL_TEXT(LRM_FILE_NAME_PREFIX(1 .. LRM_FILE_NAME_PREFIX_LENGTH) &
            "chapd.doc", "Annex D          ", SAVE_FILE);
        when 'E' | 'e' =>
          SCROLL_TEXT(LRM_FILE_NAME_PREFIX(1 .. LRM_FILE_NAME_PREFIX_LENGTH) &
            "chape.doc", "Annex E          ", SAVE_FILE);
        when 'F' | 'f' =>
          SCROLL_TEXT(LRM_FILE_NAME_PREFIX(1 .. LRM_FILE_NAME_PREFIX_LENGTH) &
            "chapf.doc", "Annex F          ", SAVE_FILE);
        when 'Q' | 'q' =>
          UNPASTE_VIRTUAL_DISPLAY(ANNEX_MENU_DISPLAY, TERM_ID);
          exit;
        when others =>
          null;
      end case;
    end loop;


  end DO_ANNEX_MENU;



  ---------------------------------------------------------------------------

------------------------------------------------------------------------------


  procedure SCROLL_CHAP(IN_FILE_NAME       : in STRING;
                        FIRST_LINE         : in NATURAL;
                        LAST_LINE          : in NATURAL;
                        SAVE_FILE          : in out FILE_TYPE;
                        UNTIL_EOF          : in BOOLEAN;
                        CITATION_REQUESTED : in STRING) is




  -- scroll text file on the screen, 19 lines at a time

    type COMMAND is (CONTINUE, DISPLAY_AGAIN, EXIT_COMMAND, SAVE, NOTHING);

    AT_LAST_LINE     : BOOLEAN := FALSE;
    BLANK_30         : STRING(1 .. 30) := (others => ' ');
    BLANK_COUNT      : NATURAL := 0;
    EXIT_NOW         : BOOLEAN := FALSE;
    GOOD_ANSWER      : BOOLEAN;
    LAST_CHAR        : NATURAL := 0;
    LAST_COMMAND     : COMMAND := NOTHING;
    READ_IN_FILE     : FILE_TYPE;
    READ_IN_LINE     : STRING(1 .. 156);
    EMPTY_STRING_156 : STRING(1 .. 156);
    RECD_STR_LEN     : WORD_UNSIGNED;
    SAVING           : BOOLEAN := FALSE;
    TERM_CODE        : WORD_UNSIGNED;
    WAIT_STR         : STRING(1 .. 10);
    LINE_COUNT       : NATURAL := 0;
    CURRENT_LINE     : NATURAL := 0;


    procedure GOTO_FIRST_LINE(FIRST_LINE : in NATURAL) is
      READ_IN_LINE : STRING(1 .. 156);
      LAST_CHAR    : NATURAL;

    begin
      RESET(READ_IN_FILE, IN_FILE);
      for I in 1 .. (FIRST_LINE - 1) loop
        GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
      end loop;
    end GOTO_FIRST_LINE;


  begin

    ERASE_DISPLAY(TEXT_SCREEN_DISPLAY);
    EMPTY_STRING_156 := (others => ' ');
    OPEN(READ_IN_FILE, IN_FILE, IN_FILE_NAME);
    PASTE_VIRTUAL_DISPLAY(TEXT_SCREEN_DISPLAY, TERM_ID, 2, 2);

    REPASTE_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID, 23, 2);

    -- was 22, 2
    GOTO_FIRST_LINE(FIRST_LINE);
    CURRENT_LINE := FIRST_LINE - 1;
    while not EXIT_NOW loop
      LINE_COUNT := 0;

      if LAST_COMMAND /= SAVE then

        if UNTIL_EOF then

          while ((not END_OF_FILE(READ_IN_FILE)) and (LINE_COUNT <= 18)) loop
            READ_IN_LINE := EMPTY_STRING_156;
            GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
            if LAST_CHAR = 0 then
              BLANK_COUNT := BLANK_COUNT + 1;
            else
              BLANK_COUNT := 0;
            end if;
            if SAVING then
              PUT_LINE(SAVE_FILE, READ_IN_LINE(1 .. LAST_CHAR));
            end if;
            CURRENT_LINE := CURRENT_LINE + 1;

            --          don't need a SKIP_LINE statement.
            --          SKIP_LINE (READ_IN_FILE);
            if BLANK_COUNT < 3 then
              if LAST_CHAR > SCREEN_WIDTH then
                LINE_COUNT := LINE_COUNT + 2;
                PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE
                  (1 .. SCREEN_WIDTH));
                PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE
                  (SCREEN_WIDTH + 1 .. LAST_CHAR));
              else
                PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => READ_IN_LINE
                  (1 .. LAST_CHAR));
                LINE_COUNT := LINE_COUNT + 1;
              end if;
            end if;
          end loop;

        else

          while ((CURRENT_LINE < (LAST_LINE - 1)) and (LINE_COUNT <= 18)) loop
            READ_IN_LINE := EMPTY_STRING_156;
            GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
            if LAST_CHAR = 0 then
              BLANK_COUNT := BLANK_COUNT + 1;
            else
              BLANK_COUNT := 0;
            end if;
            if SAVING then
              PUT_LINE(SAVE_FILE, READ_IN_LINE(1 .. LAST_CHAR));
            end if;
            CURRENT_LINE := CURRENT_LINE + 1;

            --          don't need a SKIP_LINE statement.
            if BLANK_COUNT < 3 then
              if (not (LAST_CHAR < 42 and LAST_CHAR > 0 and READ_IN_LINE(1 .. 30
                ) = BLANK_30)) then

                if LAST_CHAR > SCREEN_WIDTH then
                  LINE_COUNT := LINE_COUNT + 2;
                  PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT =>
                    READ_IN_LINE(1 .. SCREEN_WIDTH));
                  PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT =>
                    READ_IN_LINE(SCREEN_WIDTH + 1 .. LAST_CHAR));
                else
                  PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT =>
                    READ_IN_LINE(1 .. LAST_CHAR));
                  LINE_COUNT := LINE_COUNT + 1;
                end if;
              end if;
            end if;
          end loop;
          if CURRENT_LINE >= (LAST_LINE - 1) then
            AT_LAST_LINE := TRUE;
          end if;
        end if;


      end if;

      GOOD_ANSWER := FALSE;
      while not GOOD_ANSWER loop
        GOOD_ANSWER := TRUE;
        if END_OF_FILE(READ_IN_FILE) or (AT_LAST_LINE) then
          READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => WAIT_STR, TIMEOUT
            => 500, PROMPT_STRING => "     E[xit]   S[ave]   D[isplay again] "
            , MAX_LENGTH => 1, RECEIVED_STRING_LENGTH => RECD_STR_LEN,
            TERMINATOR_CODE => TERM_CODE, DISPLAY_ID => VD_2_ID);
        else
          READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => WAIT_STR, TIMEOUT
            => 500, PROMPT_STRING =>
            "     E[xit]   C[ontinue]   S[ave]   D[isplay again] ", MAX_LENGTH
            => 1, RECEIVED_STRING_LENGTH => RECD_STR_LEN, TERMINATOR_CODE =>
            TERM_CODE, DISPLAY_ID => VD_2_ID);
        end if;
        PUT_LINE(DISPLAY_ID => VD_2_ID, TEXT => "               ");
        case WAIT_STR(1) is
          when 'E' | ASCII.LC_E =>
            LAST_COMMAND := EXIT_COMMAND;
            EXIT_NOW := TRUE;
            exit;
          when 'S' | ASCII.LC_S =>
            LAST_COMMAND := SAVE;
            if not SAVING then
              if not IS_OPEN(SAVE_FILE) then
                CREATE(SAVE_FILE, OUT_FILE, LRM_READER_SAVE_FILE_NAME);
              end if;

              -- write citation title to file save_file.
              PUT_LINE(SAVE_FILE,
                "Chapter reference from Ada Language Reference Manual:");
              for I in 1 .. 11 loop
                case CITATION_REQUESTED(I) is
                  when 'c' | 'C' =>
                    PUT(SAVE_FILE, "Chapter ");
                  when 's' | 'S' =>
                    PUT(SAVE_FILE, " Section ");
                  when 'v' | 'V' =>
                    PUT(SAVE_FILE, '.');
                  when 'p' | 'P' =>
                    PUT(SAVE_FILE, " Paragraph ");
                  when ' ' =>
                    null;
                  when others =>
                    PUT(SAVE_FILE, CITATION_REQUESTED(I));
                end case;
              end loop;
              NEW_LINE(SAVE_FILE, 3);

              -- write citation title to file save_file.
              SAVING := TRUE;
              if CURRENT_LINE > FIRST_LINE then
                GOTO_FIRST_LINE(FIRST_LINE);
                for I in FIRST_LINE .. (CURRENT_LINE) loop
                  READ_IN_LINE := EMPTY_STRING_156;
                  GET_LINE(READ_IN_FILE, READ_IN_LINE, LAST_CHAR);
                  PUT_LINE(SAVE_FILE, READ_IN_LINE(1 .. LAST_CHAR));
                end loop;
              end if;
            end if;
          when 'D' | ASCII.LC_D =>
            LAST_COMMAND := DISPLAY_AGAIN;
            GOTO_FIRST_LINE(FIRST_LINE);
            CURRENT_LINE := FIRST_LINE - 1;
            PUT_LINE(DISPLAY_ID => TEXT_SCREEN_DISPLAY, TEXT => "      ");
          when 'C' | ASCII.LC_C =>
            LAST_COMMAND := CONTINUE;
            null;

          -- continue the display
          when others =>
            GOOD_ANSWER := FALSE;
        end case;

      -- while not good_answer loop
      end loop;

    --  while not eof(read_in_file) loop
    end loop;


    if SAVING then
      NEW_LINE(SAVE_FILE, 3);
    end if;
    CLOSE(READ_IN_FILE);
    UNPASTE_VIRTUAL_DISPLAY(TEXT_SCREEN_DISPLAY, TERM_ID);
    REPASTE_VIRTUAL_DISPLAY(VD_2_ID, TERM_ID, 22, 2, CHAPTER_MENU_DISPLAY);


  end SCROLL_CHAP;








------------------------------------------------------------------------------


------------------------------------------------------------------------------


  function EXTRACT_SECTION(CITATION : in STRING) return INTEGER is

  --perhaps global
  --  Extract integer part of section number from citation.

    FOUND         : BOOLEAN := FALSE;
    I             : INTEGER;
    FIRST_SECTION : INTEGER := 0;
    LAST_SECTION  : INTEGER := 0;

  begin
    I := 3;
    loop
      case CITATION(I) is
        when 's' | 'S' =>
          FIRST_SECTION := I + 1;
        when 'v' | 'V' | 'p' | 'P' =>
          LAST_SECTION := I - 1;
          FOUND := TRUE;
        when others =>
          null;
      end case;
      if I = 11 then
        exit;
      else
        I := I + 1;
      end if;
      exit when FOUND;
    end loop;
    if not FOUND then
      for I in reverse 1 .. 11 loop
        if CITATION(I) /= ' ' then
          LAST_SECTION := I;
          FOUND := TRUE;
          exit when FOUND;
        end if;
      end loop;
    end if;

    return INTEGER'VALUE(CITATION(FIRST_SECTION .. LAST_SECTION));
  end EXTRACT_SECTION;




------------------------------------------------------------------------------

  function EXTRACT_CHAPTER(CITATION : in STRING) return INTEGER is

  --perhaps global
  --  Extract chapter from citation.

    FOUND     : BOOLEAN := FALSE;
    I         : INTEGER;
    LAST_CHAP : INTEGER := 0;

  begin
    I := 2;
    loop
      case CITATION(I) is
        when 'p' | 'P' | 's' | 'S' =>
          LAST_CHAP := I - 1;
          FOUND := TRUE;
        when others =>
          null;
      end case;
      if I = 11 then
        exit;
      else
        I := I + 1;
      end if;
      exit when FOUND;
    end loop;
    if not FOUND then
      for I in reverse 1 .. 11 loop
        if CITATION(I) /= ' ' then
          LAST_CHAP := I;
          FOUND := TRUE;
          exit when FOUND;
        end if;
      end loop;
    end if;

    return INTEGER'VALUE(CITATION(2 .. LAST_CHAP));
  end EXTRACT_CHAPTER;


------------------------------------------------------------------------------

  procedure GET_NEXT_SECTION_NUMBER(NEXT_SECTION         : in out STRING;
                                    CHAPTER_MENU_DISPLAY : in LONGWORD_UNSIGNED
                                      ;
                                    LAST_LINE            : in out NATURAL;
                                    UNTIL_EOF            : in out BOOLEAN;
                                    SUBSECTION           : in BOOLEAN) is

  --perhaps global

    ORIGINAL_CHAPTER : INTEGER;  -- chapter part of requested chapter reference
    ORIGINAL_SECTION : INTEGER; -- integer part of section of requested chapter reference
    CURRENT_CHAPTER  : INTEGER;
    CURRENT_SECTION  : INTEGER;
    -- integer part of section of requested chapter reference
    NOT_PARAGRAPH    : BOOLEAN;
    NS               : LEGAL_CITATIONS;
    CITATION_STRING  : STRING(1 .. 11);


  begin
    LAST_LINE := 0;
    UNTIL_EOF := FALSE;
    NS := LEGAL_CITATIONS'VALUE(NEXT_SECTION);
    ORIGINAL_CHAPTER := EXTRACT_CHAPTER(NEXT_SECTION);
    ORIGINAL_SECTION := EXTRACT_SECTION(NEXT_SECTION);
    if SUBSECTION then
      loop
        NOT_PARAGRAPH := TRUE;
        if NS /= C14S7P3 then
          NS := LEGAL_CITATIONS'SUCC(NS);
        else
          UNTIL_EOF := TRUE;
          goto DISPLAY_REMAINDER_OF_FILE;
        end if;

        --        >>>>>> detect next chapter
        --
        --
        LEGAL_CITATIONS_IO.PUT(NEXT_SECTION, NS);
        CURRENT_CHAPTER := EXTRACT_CHAPTER(NEXT_SECTION);
        if CURRENT_CHAPTER > ORIGINAL_CHAPTER then
          UNTIL_EOF := TRUE;
          goto DISPLAY_REMAINDER_OF_FILE;
        end if;
        for I in reverse 1 .. 11 loop
          if ((NEXT_SECTION(I) = 'p') or (NEXT_SECTION(I) = 'P')) then
            NOT_PARAGRAPH := FALSE;
          end if;
        end loop;
        if NOT_PARAGRAPH then
          exit;
        end if;
      end loop;
    else
      loop
        if NS /= C14S7P3 then
          NS := LEGAL_CITATIONS'SUCC(NS);
        else
          UNTIL_EOF := TRUE;
          goto DISPLAY_REMAINDER_OF_FILE;
        end if;
        LEGAL_CITATIONS_IO.PUT(NEXT_SECTION, NS);
        CURRENT_CHAPTER := EXTRACT_CHAPTER(NEXT_SECTION);
        if CURRENT_CHAPTER > ORIGINAL_CHAPTER then
          UNTIL_EOF := TRUE;
          goto DISPLAY_REMAINDER_OF_FILE;
        else
          CURRENT_SECTION := EXTRACT_SECTION(NEXT_SECTION);
          if CURRENT_SECTION > ORIGINAL_SECTION then
            UNTIL_EOF := FALSE;
            LAST_LINE := CHAP_POINTERS(NS);
            exit;
          end if;
        end if;
      end loop;

    -- if subsection
    end if;

    <<DISPLAY_REMAINDER_OF_FILE>> null;

    if not UNTIL_EOF then
      LAST_LINE := CHAP_POINTERS(NS);
    end if;
  end GET_NEXT_SECTION_NUMBER;

------------------------------------------------------------------------------


  procedure DO_CHAPTER_MENU(SAVE_FILE : in out FILE_TYPE) is


    ALL_CHAPTER                   : BOOLEAN := FALSE;
    ALL_SECTION                   : BOOLEAN := FALSE;
    CHAP_FILENAME                 : STRING(1 .. 18);
    CHAPTER_CHOICE                : STRING(1 .. 3);
    CHAPTER_CHOICE_INT            : INTEGER;
    CHAPTER_CHOICE_LEN            : WORD_UNSIGNED;
    CHAPTER_CHOICE_LEN_INT        : INTEGER;
    CITATION_REQUESTED            : STRING(1 .. 11) := "c1p1       ";
    CITATION_REQUESTED_LENGTH     : NATURAL;
    CITATION_TO_GET               : LEGAL_CITATIONS := C1P1;
    CITATION_MARKER               : LEGAL_CITATIONS := C1P1;
    EXIT_CHAPTER_LOOP             : BOOLEAN;
    EXIT_CHOICE                   : STRING(1 .. 1);
    EXIT_CHOICE_LEN               : WORD_UNSIGNED;
    FIRST_LINE                    : NATURAL := 0;
    FIRST_TIME_THROUGH_OUTER_LOOP : BOOLEAN := TRUE;
    GOOD_ANSWER                   : BOOLEAN;
    I                             : INTEGER :=  -1;
    LAST_LINE                     : NATURAL := 0;
    NEXT_CITATION                 : STRING(1 .. 11);
    NEXT_CITATION_LENGTH          : NATURAL;
    NONEXISTENT_CITATION_MESSAGE  : STRING(1 .. 78);
    NONEXISTENT_CITATION_REPLY    : STRING(1 .. 2);
    NONEXISTENT_CITATION_LEN      : WORD_UNSIGNED;
    PARAGRAPH_CHOICE              : STRING(1 .. 2);
    PARAGRAPH_CHOICE_LEN          : WORD_UNSIGNED;
    PARAGRAPH_CHOICE_LEN_INT      : INTEGER;
    PLACE                         : NATURAL := 0;
    REQUEST_LENGTH                : NATURAL := 2;
    SECTION_BEGIN, SECTION_END    : NATURAL := 0;
    SECTION_CHOICE                : STRING(1 .. 5);
    SECTION_CHOICE_LEN            : WORD_UNSIGNED;
    SECTION_CHOICE_LEN_INT        : INTEGER;
    SUBSECTION                    : BOOLEAN;
    TERM_CODE                     : WORD_UNSIGNED;
    UNTIL_EOF                     : BOOLEAN := FALSE;
    C1                            : STRING(1 .. 3);
    C2                            : INTEGER;
    ROW, COL                      : INTEGER;
    DUMP_FILE                     : FILE_TYPE;

    ---------------------------------------

    function CHAPTER_NUMBER(CHAP     : in STRING;
                            CHAP_LEN : in WORD_UNSIGNED) return INTEGER is
      I          : INTEGER;
      CHAP_LEN_I : INTEGER;
      TEMP       : INTEGER := 0;
    begin
      CHAP_LEN_I := INTEGER(CHAP_LEN);
      if CHAP_LEN_I > 0 then
        TEMP := INTEGER'VALUE(CHAP(1 .. CHAP_LEN_I));
      else
        TEMP := 0;
      end if;
      return TEMP;
    end CHAPTER_NUMBER;

    ---------------------------------------


    function VALID_CHAPTER(CHAP : in INTEGER) return BOOLEAN is
    --perhaps global
      TEMP_RESULT : BOOLEAN;
    begin
      case CHAP is
        when 1 .. 14 =>
          TEMP_RESULT := TRUE;
        when others =>
          TEMP_RESULT := FALSE;
      end case;
      return TEMP_RESULT;
    end VALID_CHAPTER;

    ---------------------------------------

    procedure GET_CITATION_FROM_USER is
    -- local -- term_code
    -- parameter -- chapter_choice_int
    begin
      CHAPTER_CHOICE := "   ";
      SECTION_CHOICE := "     ";
      PARAGRAPH_CHOICE := "  ";

      ERASE_CHARS(CHAPTER_MENU_DISPLAY, 30, 16, 1);
      ERASE_CHARS(CHAPTER_MENU_DISPLAY, 30, 17, 1);
      ERASE_CHARS(CHAPTER_MENU_DISPLAY, 45, 18, 1);
      SET_CURSOR_ABS(CHAPTER_MENU_DISPLAY, 16, 1);
      READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => CHAPTER_CHOICE,
        MAX_LENGTH => 3, RECEIVED_STRING_LENGTH => CHAPTER_CHOICE_LEN,
        PROMPT_STRING => " Enter chapter, please: ", TIMEOUT => 90,
        TERMINATOR_CODE => TERM_CODE, DISPLAY_ID => CHAPTER_MENU_DISPLAY);
      READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => SECTION_CHOICE,
        MAX_LENGTH => 5, RECEIVED_STRING_LENGTH => SECTION_CHOICE_LEN,
        PROMPT_STRING => "               section: ", TERMINATOR_CODE =>
        TERM_CODE, DISPLAY_ID => CHAPTER_MENU_DISPLAY);
      READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => PARAGRAPH_CHOICE,
        MAX_LENGTH => 3, RECEIVED_STRING_LENGTH => PARAGRAPH_CHOICE_LEN,
        PROMPT_STRING => "             paragraph: ", TERMINATOR_CODE =>
        TERM_CODE, DISPLAY_ID => CHAPTER_MENU_DISPLAY);
      CHAPTER_CHOICE_INT := CHAPTER_NUMBER(CHAPTER_CHOICE, CHAPTER_CHOICE_LEN);
      if VALID_CHAPTER(CHAPTER_CHOICE_INT) then
        GOOD_ANSWER := TRUE;
      end if;
      SET_CURSOR_ABS(CHAPTER_MENU_DISPLAY, 20, 1);
    end GET_CITATION_FROM_USER;

    ---------------------------------------

    procedure COMBINE_STRINGS_INTO_IMAGE_FORM is
    --perhaps global
    -- local -- place, request_length, section_begin, section_end
    begin
      CITATION_REQUESTED := "           ";
      CITATION_REQUESTED_LENGTH := 0;
      CHAPTER_CHOICE_LEN_INT := INTEGER(CHAPTER_CHOICE_LEN);
      SECTION_CHOICE_LEN_INT := INTEGER(SECTION_CHOICE_LEN);
      PARAGRAPH_CHOICE_LEN_INT := INTEGER(PARAGRAPH_CHOICE_LEN);
      CITATION_REQUESTED(1) := 'C';
      CITATION_REQUESTED(2 .. 2) := CHAPTER_CHOICE(1 .. 1);
      CITATION_REQUESTED(2 .. (CHAPTER_CHOICE_LEN_INT + 1)) := CHAPTER_CHOICE(1
        .. CHAPTER_CHOICE_LEN_INT);
      PLACE := CHAPTER_CHOICE_LEN_INT + 2;
      REQUEST_LENGTH := PLACE - 1;
      if (SECTION_CHOICE_LEN_INT > 0) then
        CITATION_REQUESTED(PLACE) := 'S';
        SECTION_BEGIN := PLACE + 1;
        for I in 1 .. SECTION_CHOICE_LEN_INT loop
          if SECTION_CHOICE(I) = '.' then
            CITATION_REQUESTED(PLACE + I) := 'v';
            SUBSECTION := TRUE;
          else
            CITATION_REQUESTED(PLACE + I) := SECTION_CHOICE(I);
          end if;
        end loop;
        SECTION_END := SECTION_BEGIN + SECTION_CHOICE_LEN_INT - 1;
        PLACE := PLACE + SECTION_CHOICE_LEN_INT + 1;
        REQUEST_LENGTH := PLACE - 1;
        if PARAGRAPH_CHOICE_LEN_INT <= 0 then
          ALL_SECTION := TRUE;
        end if;
      else
        if PARAGRAPH_CHOICE_LEN_INT <= 0 then
          ALL_CHAPTER := TRUE;
        end if;
      end if;

      -- if section_choice_len_int > 0
      if (PARAGRAPH_CHOICE_LEN_INT > 0) then
        CITATION_REQUESTED(PLACE) := 'P';
        CITATION_REQUESTED((PLACE + 1) .. (PLACE + PARAGRAPH_CHOICE_LEN_INT))
          := PARAGRAPH_CHOICE(1 .. PARAGRAPH_CHOICE_LEN_INT);
        REQUEST_LENGTH := PLACE + PARAGRAPH_CHOICE_LEN_INT;
      end if;

    -- if paragraph_choice_len_int > 0
    end COMBINE_STRINGS_INTO_IMAGE_FORM;

    ---------------------------------------

    procedure FILL_IN_CHAPTER_FILENAME(CHAP_FILENAME      : out STRING;
                                       CHAPTER_CHOICE_INT : in INTEGER) is

      TEMP_CHAP_FILENAME : STRING(1 .. 10) := "chap  .doc";
      TEMP_LENGTH        : NATURAL;

      --perhaps global
    begin
      if CHAPTER_CHOICE_INT in 1 .. 14 then
        case CHAPTER_CHOICE_INT is
          when 1 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "01";
          when 2 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "02";
          when 3 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "03";
          when 4 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "04";
          when 5 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "05";
          when 6 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "06";
          when 7 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "07";
          when 8 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "08";
          when 9 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "09";
          when 10 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "10";
          when 11 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "11";
          when 12 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "12";
          when 13 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "13";
          when 14 =>
            TEMP_CHAP_FILENAME(5 .. 6) := "14";
          when others =>
            null;
        end case;

        -- Length of CHAP_FILENAME := LRM_FILE_NAME_PREFIX_LENGTH
        -- + Length(TEMP_CHAP_FILENAME)
        TEMP_LENGTH := LRM_FILE_NAME_PREFIX_LENGTH + 10;
        CHAP_FILENAME(1 .. TEMP_LENGTH) := LRM_FILE_NAME_PREFIX(1 ..
          LRM_FILE_NAME_PREFIX_LENGTH) & TEMP_CHAP_FILENAME;
      end if;
    end FILL_IN_CHAPTER_FILENAME;

    ---------------------------------------

    procedure VALIDATE_CITATION(CITATION_REQUESTED : in STRING;
                                REQUEST_LENGTH     : in NATURAL;
                                CITATION_TO_GET    : out LEGAL_CITATIONS) is
    --perhaps global
    begin

      CITATION_TO_GET := LEGAL_CITATIONS'VALUE(CITATION_REQUESTED(1 ..
        REQUEST_LENGTH));

    end VALIDATE_CITATION;



    ------------------------------------------------------------
    --              do_chapter_menu_smg  body
    ------------------------------------------------------------


    --do_chapter_menu_smg
  begin


    PASTE_VIRTUAL_DISPLAY(CHAPTER_MENU_DISPLAY, TERM_ID, LEFT_MOST, TOP_MOST);
    EXIT_CHAPTER_LOOP := FALSE;

    loop

      -- block for exception CONSTRAINT_ERROR
      begin
        if not FIRST_TIME_THROUGH_OUTER_LOOP then
          SET_CURSOR_ABS(CHAPTER_MENU_DISPLAY, 1, 1);
          READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT => EXIT_CHOICE,
            MAX_LENGTH => 1, PROMPT_STRING =>
            "Do you want to leave the Chapter Menu now? ", TERMINATOR_CODE =>
            TERM_CODE, DISPLAY_ID => CHAPTER_MENU_DISPLAY,
            RECEIVED_STRING_LENGTH => EXIT_CHOICE_LEN);
          ERASE_CHARS(CHAPTER_MENU_DISPLAY, 45, 1, 1);
          case EXIT_CHOICE(1) is
            when 'y' | 'Y' =>
              EXIT_CHAPTER_LOOP := TRUE;
            when others =>
              null;
          end case;
        end if;

        FIRST_TIME_THROUGH_OUTER_LOOP := FALSE;
        exit when EXIT_CHAPTER_LOOP;


        ERASE_CHARS(CHAPTER_MENU_DISPLAY, 30, 17, 1);

        GOOD_ANSWER := FALSE;
        while not GOOD_ANSWER loop
          GET_CITATION_FROM_USER;
        end loop;

        -- Combine the contents of strings chapter_choice, section_choice
        --   and paragraph_choice into one string in the same format as
        --   the enumerated type legal_citations.
        SUBSECTION := FALSE;
        COMBINE_STRINGS_INTO_IMAGE_FORM;

        -- Here we have at least a valid chapter.
        -- See if its a legal citation.
        -- If its NOT a legal citation, will raise exception constraint_error,
        --   perform exception block (when constraint_error), and
        --   exit procedure do_chapter_menu_smg.

        VALIDATE_CITATION(CITATION_REQUESTED, REQUEST_LENGTH, CITATION_TO_GET);

        FILL_IN_CHAPTER_FILENAME(CHAP_FILENAME, CHAPTER_CHOICE_INT);
        FIRST_LINE := CHAP_POINTERS(CITATION_TO_GET);


        if PARAGRAPH_CHOICE_LEN_INT > 0 then
          LAST_LINE := CHAP_POINTERS(LEGAL_CITATIONS'SUCC(CITATION_TO_GET));
          SCROLL_CHAP(CHAP_FILENAME, FIRST_LINE, LAST_LINE, SAVE_FILE, FALSE,
            CITATION_REQUESTED);
        else
          if SECTION_CHOICE_LEN_INT <= 0 then
          -----entire chapter
            SCROLL_CHAP(CHAP_FILENAME, FIRST_LINE, 0, SAVE_FILE, TRUE,
              CITATION_REQUESTED);
          else
            NEXT_CITATION := CITATION_REQUESTED;
            GET_NEXT_SECTION_NUMBER(NEXT_CITATION, CHAPTER_MENU_DISPLAY,
              LAST_LINE, UNTIL_EOF, SUBSECTION);
            SCROLL_CHAP(CHAP_FILENAME, FIRST_LINE, LAST_LINE, SAVE_FILE,
              UNTIL_EOF, CITATION_REQUESTED);
          end if;
        end if;

        -- erase error message from nonexistent citation
        ERASE_CHARS(CHAPTER_MENU_DISPLAY, 60, 21, 1);
        ERASE_CHARS(CHAPTER_MENU_DISPLAY, 60, 22, 1);

      exception
        when CONSTRAINT_ERROR =>
          SET_CURSOR_ABS(CHAPTER_MENU_DISPLAY, 20, 1);
          NONEXISTENT_CITATION_MESSAGE := (others => ' ');
          NONEXISTENT_CITATION_MESSAGE(1 .. 7) := "Chapter";
          NONEXISTENT_CITATION_MESSAGE(9 .. (8 + CHAPTER_CHOICE_LEN_INT)) :=
            CHAPTER_CHOICE(1 .. CHAPTER_CHOICE_LEN_INT);
          PLACE := 10 + CHAPTER_CHOICE_LEN_INT;
          if SECTION_CHOICE_LEN_INT > 0 then
            NONEXISTENT_CITATION_MESSAGE(PLACE .. PLACE + 6) := "Section";
            PLACE := PLACE + 8;
            NONEXISTENT_CITATION_MESSAGE(PLACE .. (PLACE +
              SECTION_CHOICE_LEN_INT - 1)) := SECTION_CHOICE(1 ..
              SECTION_CHOICE_LEN_INT);
            PLACE := PLACE + SECTION_CHOICE_LEN_INT + 1;
          end if;
          if PARAGRAPH_CHOICE_LEN_INT > 0 then
            NONEXISTENT_CITATION_MESSAGE(PLACE .. PLACE + 8) := "Paragraph";
            PLACE := PLACE + 10;
            NONEXISTENT_CITATION_MESSAGE(PLACE .. (PLACE +
              PARAGRAPH_CHOICE_LEN_INT - 1)) := PARAGRAPH_CHOICE(1 ..
              PARAGRAPH_CHOICE_LEN_INT);
            PLACE := PLACE + PARAGRAPH_CHOICE_LEN_INT + 1;
          end if;
          NONEXISTENT_CITATION_MESSAGE(PLACE .. PLACE + 24) :=
            "is not a valid reference.";
          PUT_LINE(DISPLAY_ID => CHAPTER_MENU_DISPLAY, TEXT =>
            NONEXISTENT_CITATION_MESSAGE);
          -- Display "Please try again " message for 15 seconds.
          READ_STRING(KEYBOARD_ID => KB_ID, RECEIVED_TEXT =>
            NONEXISTENT_CITATION_REPLY, MAX_LENGTH => 1, PROMPT_STRING =>
            "  Please try again. ", TERMINATOR_CODE => TERM_CODE, DISPLAY_ID =>
            CHAPTER_MENU_DISPLAY, RECEIVED_STRING_LENGTH =>
            NONEXISTENT_CITATION_LEN, TIMEOUT => 15);

          -- end of block for exception CONSTRAINT_ERROR
      end;

    end loop;

    UNPASTE_VIRTUAL_DISPLAY(CHAPTER_MENU_DISPLAY, TERM_ID);

  end DO_CHAPTER_MENU;

------------------------------------------------------------------------------
end LRM_SMG;

------------------------------------------------------------------------------