C Library Functions - help_command (3)
NAME
help_command(3f) - [M_framework__help] uses a specially formatted text array to provide a HELP interface (LICENSE:PD)
CONTENTS
Synopsis
Description
Options
Example
SYNOPSIS
Syntax:
function help_command(text_array,topic,position)
DESCRIPTION
This routine, when given a CHARACTER array displays the text interactively. The special topics "manual","topics", and "search" are reserved. "manual" causes the entire array to be displayed. "topics" displays all lines not beginning with a space or three or more equal signs, and "search" must be followed by a string to search for in the manual.A line beginning with a non-blank character in column one is a topic
A topic with the preceding line beginning with "===" is a special topic that will be displayed up to the next line beginning with "==="
The special topic "manual" displays the entire help text
The help text is paged based on the values in the position() array. The first value is the current line count on the current page, and the second value is how many lines should be displayed as a page before a paging prompt is produced. POSITION(2) is typically set to 23. POSITION(1) can be set to zero, especially if the calling page is not tracking paging itself.
Entering a "q" at the prompt exits the help text. To see other options enter an "h" at the prompt.
h #----------------------------------------------------# PAGING | f|SPACE b forward or backward one page | | u d redraw up or down one-half page | | r refresh page | | e y | j k refresh page moving up or down one line | #----------------------------------------------------# JUMPING | g go to top of manual | | NNN go to line number NNN. Use a sign (+-) | | for a relative move. | | . toggle line numbering | #----------------------------------------------------# SEARCHING | /STRING advance to next line containing string | | ?STRING search for string above current line | | n N find next occurrence up or down in file | | \STRING show all lines with specified string. | | t displays topic lines. | #----------------------------------------------------# | w FILENAME write entire user guide to local file | | h display this help | | q quit | #----------------------------------------------------# Anything else is ignored. Line count is 25 out of 54 . Page size is 23 (see "lines") continue ..A normal topic is displayed until another topic line (line beginning with a non-blank) is encountered
The help text must begin with a line starting with "==="
If a line is preceded by an "===" line it is considered a section instead of a topic, and all lines between that line and the next line beginning with "===" are displayed.
OPTIONS
help_text The block of text to treat as the input document topic What topic or section to search for (case sensitive). A blank is equivalent to "SUMMARY". There are several reserved names. "manual" means the entire help text, and "topics" shows only lines not beginning with a blank, and "search" does a case-insensitive search for a string. position A small array with two values. The second value is the size of the page to be used between pauses. The first one indicates how many lines on the current page have been displayed.
EXAMPLE
Sample program:
program demo_help_command use M_framework__help, only : help_command character(len=:),allocatable :: help_text(:) integer :: position(2) position=[0,23] help_text=[character(len=80) :: & ’==============================================’,& ’ A sample help text file. ’,& ’ Note the first line MUST start with "===" ’,& ’==============================================’,& ’SUMMARY ’,& ’ This is usually a crib sheet ’,& ’==============================================’,& ’SECTION1 ’,& ’topic1 ’,& ’ A description of topic 1 ’,& ’ ’,& ’ and any general text you want ’,& ’ ’,& ’topic2 A description of topic 2 ’,& ’topic3 ’,& ’ A description of topic 3 ’,& ’ more description of topic 3 ’,& ’ and more description of topic 3 a ’,& ’ and more description of topic 3 b ’,& ’ and more description of topic 3 c ’,& ’ and more description of topic 3 d ’,& ’ and more description of topic 3 e ’,& ’ and more description of topic 3 f ’,& ’ and more description of topic 3 g ’,& ’ and more description of topic 3 h ’,& ’ and more description of topic 3 i ’,& ’ and more description of topic 3 j ’,& ’ and more description of topic 3 k ’,& ’ and more description of topic 3 l ’,& ’ and more description of topic 3 m ’,& ’ and more description of topic 3 n ’,& ’ and more description of topic 3 o ’,& ’ and more description of topic 3 p ’,& ’ and more description of topic 3 q ’,& ’ and more description of topic 3 r ’,& ’ and more description of topic 3 s ’,& ’ and more description of topic 3 t ’,& ’ and more description of topic 3 u ’,& ’ and more description of topic 3 v ’,& ’ and more description of topic 3 w ’,& ’ and more description of topic 3 x ’,& ’ and more description of topic 3 y ’,& ’ and more description of topic 3 z ’,& ’==============================================’,& ’SECTION2 ’,& ’topic4 A description of topic 4 ’,& ’ this is the last part of SECTION1 ’,& ’topic5 ’,& ’ This is all about the fifth topic and is ’,& ’ just displayed as-is. The text cannot start ’,& ’ in column one or it will be seen as the ’,& ’ beginning of a topic. ’,& ’==============================================’,& ’ ’ ]write(*,*)’>>>>>’ call help_command(help_text,’’,position) write(*,*)’>>>>>topic1’ call help_command(help_text,’topic1’,position) write(*,*)’>>>>>topics’ call help_command(help_text,’topics’,position) write(*,*)’>>>>>manual’ call help_command(help_text,’manual’,position) end program demo_help_command
| Nemo Release 3.1 | help_command (3) | July 22, 2023 |
