# ehf(8)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## NAME

ehf - MicroEmacs help file

## SYNOPSIS

!<helpTag>
<Text Description>
...
|<helpId>
<Text Description Line>
...
$?
...
<Text Description>
!<helpTag>
!<helpTag>
<Text Description>
...

## DESCRIPTION

The on-line help information is retained in the file me.ehf, this is an ASCII text file which holds all of the on-line help information. The help file comprises of formatted text <Text Description> which is literally displayed to the user when help information is requested. Each text description is delimited into pages with a !<helpTag> which identifies the block of text with a help label.

The !<helpTag> is placed before the text description and is identified by a exclamation mark (`!') placed at the beginning of the line. The <helpTag> is the identifying name used by the help system and takes the following form:

`LSSNNNN...`

Where:

L

Is the length of the "`NNNN...`" name which must be matched, a value of '`` ' indicates that the whole name must be matched, otherwise the value must be in the range '`1`' - '`9`' indicating the number of characters to be match.

SS

Is the section number of the page, the first character should be a numeric (i.e. '`3`' for a macro) and the second is an optional section letter. A value of '`` ' indicates no section number and/or letter.

NNNN...

The page name, the length is unlimited but must be on one line.

Multiple <helpTag>'s may be associated with a common text description by proceeding a block of text with multiple tags, each on a separate line, with no intervening non-tag lines (i.e. lines that do not commence with !).

The <Text Description> that follows is the text associated with the tag. When the help system is invoked with the tag then the text is displayed. There are 2 types of internal command lines, lines starting with a '`|`' indicate that the following line should only be displayed if the requested help page is <helpId>, where <helpId> is the the name used in the <helpTag>. This is a useful mechanism for pages with multiple <helpTag>s.

Lines which contain just "`$?`" are MicroEmacs command lines where `?` can be:

`a`

For a command help page display any global key bindings, for variables display its current value.

MicroEmacs uses a special hilighting scheme to control color schemes and hyper-text links, the special embedded tags all start with and escape character (0x1b or '`^[`') and are defined as follows:

`^[c?`

Tag used to change color where `?` can be:

`A` white, used for main text.
`B` red, used for underlining.
`C` green, used for italic font.
`D` cyan, used for bold font.
`E` light yellow, used for a header.
`F` light red, used for and image link.

`^[s?`

Tag used to change hilighting scheme where `?` can be:

`A` Normal ehf hilight.
`B` MicroEmacs macro (or emf) hilighting.

Note that other tags can only be used in the normal ehf hilighting scheme.

`^[ls<link>^[lm<name>^[le`

Used to create hyper-links, `<link>` is the help link name which can be omitted if it is the same as `<name>`. `<name>` should not contain any other tags, it is automatically displayed in the magenta color scheme.

## NOTES

When the help system is invoked for the first time, me.ehf is loaded into internal memory and fragmented into labeled pages using the <helpTag> information. Hence, any edits made to me.emf are not visible in the help system until the next session.

Macros and alike may add additional help information to the internal help database at run-time using the define-help(2) command.

The help hilighting is applied to the help buffer from the hilighting macro's defined in hkhelp.emf. The hilighting is NOT part of the help file.

Special hilighting keys may be included in me.ehf provided that they are interpreted by the help hilighting defined in hkehf.emf.

<Text Description> lines cannot commence with !, | or $ in the first column.

## EXAMPLE

The following help entry defines the help for global-mode(2), add-global-mode(3) and delete-global-mode(3). It uses most features mentioned, namely multiple link names, color and scheme changes and several hyper-text links:

    ! 2 global-mode
    ! 3 add-global-mode
    ! 3 delete-global-mode
    ^[cE^[cENAME ^[cE^[cA

    |global-mode
        global-mode - Change a global buffer mode
    |add-global-mode
        add-global-mode - Set a global buffer mode
    |delete-global-mode
        delete-global-mode - Remove a global buffer mode
    $a

    ^[cE^[cESYNOPSIS ^[cE^[cA

        ^[cCn^[cA ^[cDglobal-mode^[cA "^[cCmode^[cA" (^[cDesc m^[cA)
        ^[cDadd-global-mode^[cA "^[cCmode^[cA"
        ^[cDdelete-global-mode^[cA "^[cCmode^[cA"

    ^[cE^[cEDESCRIPTION ^[cE^[cA

        ^[cDglobal-mode^[cA changes the state of one of the hereditary
        global modes. A buffer's modes are initialized to the global
        modes when first created. This command is very useful in changing
        some of the default behavior such as case sensitive searching (see
        the example below). See ^[ls^[lmOperating Modes^[le for a full list
        and description of modes. Also see ^[ls^[lmbuffer-mode(2)^[le for a
        full description of the use of the argument ^[cCn^[cA.

        The ^[ls^[lminfo(2)^[le command gives a list of the current global
        and buffer modes.

        ^[cDadd-global-mode^[cA and ^[cDdelete-global-mode^[cA are macros
        defined in me3_8.emf which use global-mode to add or remove a global
        mode. They are defined for backward compatibility and for ease of
        use; they are simple macros, add-global-mode is defined as follows:
    ^[sB
            define-macro add-global-mode
                ; Has the require mode been given as an argument, if so add it
                !force 1 global-mode @1
                !if &not $status
                    ; No - use 1 global-mode to add a mode
                    !nma 1 global-mode
                !endif
            !emacro

    ^[sA

    ^[cE^[cEEXAMPLE ^[cE^[cA

        The following example globally disables ^[ls^[lmexact(2m)^[le and
        ^[ls^[lmmagic(2m)^[le modes, if these lines are copied to the user
        setup file then are searches will be simple and case insensitive by
        default:
    ^[sB
            -1 global-mode "exact"
            -1 global-mode "magic"

    ^[sA

    ^[cE^[cENOTES ^[cE^[cA

        Globally adding ^[ls^[lmbinary(2m)^[le and ^[ls^[lmcrypt(2m)^[le
        modes is strongly discouraged as any file loaded would be assigned
        these modes. Instead the use of commands ^[ls^[lmfind-bfile(3)^[le
        and ^[ls^[lmfind-cfile(3)^[le are recommended.

        ^[ls^[lmauto(2m)^[le, ^[ls^[lmautosv(2m)^[le, ^[ls^[lmbackup(2m)^[le,
        ^[ls^[lmexact(2m)^[le, ^[ls^[lmmagic(2m)^[le, ^[ls^[lmquiet(2m)^[le,
        ^[ls^[lmtab(2m)^[le and ^[ls^[lmundo(2m)^[le modes are present on all
        platforms by default. On Windows and DOS platforms ^[ls^[lmcr(2m)^[le
        is also present and on DOS ^[ls^[lmctrlz(2m)^[le is also present.

    ^[cE^[cESEE ALSO ^[cE^[cA

        ^[ls^[lmOperating Modes^[le, ^[ls^[lmbuffer-mode(2)^[le,
        ^[ls^[lmfind-bfile(3)^[le, ^[ls^[lmfind-cfile(3)^[le,
        ^[ls^[lminfo(2)^[le.

## FILES

The help file me.ehf is located in the MicroEmacs 2009 macros directory and should exist on the $search-path(5).

## SEE ALSO

define-help(2), $search-path(5).

(c) Copyright JASSPA 2009
Last Modified: 2009/10/03
Generated On: 2009/10/12

</HMTL>