*vim-grm.txt*  Package for the GRM language.

This plugin is only available if 'compatible' is not set.

==============================================================================
CONTENT                                                 *vim-grm*

1. Introduction                                                |vim-grm-intro|
2. Settings                                                 |vim-grm-settings|
3. Commands                                                 |vim-grm-commands|
4. Variables                                               |vim-grm-variables|
5. Example                                                   |vim-grm-example|
6. License                                                   |vim-grm-license|

==============================================================================
INTRODUCTION                                                   *vim-grm-intro*

This package provides syntax and functionalities for GRM files. All files that
have for extensions "grm" or "grmd" are considered as GRM files.

==============================================================================
SETTINGS                                                    *vim-grm-settings*

To disable file type detection, set |b:did_ftdetect| to "1" when you open a
buffer for a file that has for extension "grm" or "grmd".

To disable plugin options like changes on 'formatoptions' or 'commentstring',
set |b:did_ftplugin| when you open a buffer for a file that has for extension
"grm" or "grmd".

                                                         *g:grm_enable_indent*
'g:grm_enable_indent'  boolean (default on)
                       global

Enable automatic indentation. To disable indentation, set
|g:grm_enable_indent| to "0".

                                          *g:grm_autoload_definition_document*
'g:grm_autoload_definition_document' boolean (default off)
                                     global

Enable automatic loading of GRM Definition Document. To enable it, set
|g:grm_autoload_definition_document| to "1".

It searches in the current directory and recursively in the parent directories
for a GRM Document File as defined in |g:grm_defintion_document_filenames|.

See |g:grm_definition_to_json_prg| to know how the file is parsed.

                                          *g:grm_defintion_document_filenames*
'g:grm_defintion_document_filenames'
                    list (default [ "definition.grmd", "definitions.grmd" ])
                    global

The list of file names to search when automatically loading GRM Definition
Documents.

                                                *g:grm_definition_to_json_prg*
'g:grm_definition_to_json_prg'  string (default "")
                                global

Set the program on your system to use to parse a GRM Definition Document and
to outpout the result as a JSON. This package cannot parse a GRM document (for
the moment) so it requires another program to do this job.

The program must take as an argument the file path of the GRM Definition
Document to parse. If there is an error, "null" must be returned in stdout and
the errors in stderr. If there is no errors, a JSON must be returned with this
format. >

    {
      "comment": "Definition document whole comment.",
      "nodes": {
        "my-named-node": {
          "attributes": {
            "my-named-attribute": {
              "optional": true,
              "empty": false,
              "comment": "Attribute definition comment.",
              "position": {
                "line": 81,
                "column": 2
              }
            }
          }
          "comment": "Node definition comment.",
          "position": {
            "line": 156,
            "column": 1
          }
        }
      },
      "marks": [
        {
          "name": "my-named-node",
          "start": "<",
          "end": ">",
          "verbatim": true,
          "comment": "Mark definition comment",
          "position": {
            "line": 175,
            "column": 1
          }
        }
      ]
    }

<
Fields starting by "my-" are field must contain the real node name or
attribute name. The objects "position" can be "null". The values must contain
the real values.

The rules for producing the JSON are explained in details in the official GRM
documentation.

                                                     *g:grm_activate_omnifunc*
'g:grm_activate_omnifunc'  boolean (default on)

When true, the 'omnifunc' option is set so the completion returned when doing
a |i_CTRL-X_CTRL-O| are according to the type of GRM document edited and the
loaded GRM Definition Document. To disable omnifunc completion, set
|g:grm_activate_omnifunc| to "0".

                                                 *g:grm_syntax_sync_fromstart*
'g:grm_syntax_sync_fromstart'  boolean (default on)

When true, set "syntax sync fromstart" (see |:syn-sync-first|). It may make
things slow when using huge file. To disable this option, set
|g:grm_syntax_sync_fromstart| to "0". We highly recommend you to let this
option on because syntax highlighting is easily wrong otherwise!

==============================================================================
COMMANDS                                                    *vim-grm-commands*

                                                  *:GRMLoadDefinitionDocument*
:GRMLoadDefinitionDocument {file}

Loads a GRM Definition Document that will be referenced by the package for
various features. Example. >
    :GRMLoadDefinitionDocument /path/to/definition.grmd

Only one Definition Document can be loaded by Vim instance. If you must write
one different files using different Definition Documents then you must use
multiple Vim instances.

                                                *:GRMReloadDefinitionDocument*
:GRMReloadDefinitionDocument

Reload the already loaded GRM Definition Document. This is necessary if the
file was changed because the package does not autodetect file changes.
Example. >
    :GRMReloadDefinitionDocument
<
==============================================================================
VARIABLES                                                  *vim-grm-variables*

This is the list of read-only variables created by vim-grm. You should not
modify them directly.

                                                     *g:grm_loaded_definition*
g:grm_loaded_definition  dict

The GRM Definition Document loaded with the |:GRMReloadDefinitionDocument| or
updated with the |:GRMLoadDefinitionDocument|.

                                                *g:grm_loaded_definition_path*
g:grm_loaded_definition_path  string

The full path for the loaded GRM Definition Document.

                                    *g:grm_has_autoloaded_definition_document*
g:grm_has_autoloaded_definition_document  boolean

It is used to prevent from trying to autoload a GRM Definitino Document every
time. It is set to "v:true" if the mechanism for autoloading GRM Definition
Document was activated. It does not mean that there is a valid definition
loaded: it is "v:true" even if no file were found or if the file were invalid.
It is the user responsability to fix the file and to reload it manually.

==============================================================================
EXAMPLE                                                      *vim-grm-example*

We describe here a configuration example and the associated workflow. In this
scenario, we suppose that you have installed a program
"grm-definition-to-json" to parse the GRM Definition Document.

Let say you are a student writing a lot of lessons and you also have a
website. For both usage, you use GRM. Your lessons go to one directory in your
system and your webpages in another. For the lessons you defined a
"lesson.grmd" GRM Definition Document and for the website "website.grmd" file.
Each file is in the root of their respective directory.

In your |$MYVIMRC|, you define those GRM Definition Document files and that
you want vim-grm to automatically load them. >

    let g:grm_defintion_document_filenames = [
        \ "definition.grmd", "definitions.grmd",
        \ "lessons.grmd", "website.grmd"
        \ ]
    let g:grm_definition_to_json_prg = 'grm-definition-to-json'
    let g:grm_autoload_definition_document = 1

You are now in your lessons directory and you start to write a new lesson in
a file named "compsci.grm" somewhere. Before the file is opened, vim-grm
automatically loads the GRM Definition Document "lesson.grmd" and you can have
all the features associated with it (highlighting...).

You realize that you need to add a not yet defined verbatim mark. You can edit
directly your "lesson.grmd" file by using the |g:grm_loaded_definition_path|.
>
    :execute "new " . g:grm_loaded_definition_path

Once you have done your edit, you can save "lesson.grmd" and reload it. >
    :w
    :GRMReloadDefinitionDocument

If there are no error messages, you can close "lesson.grmd" and go back to
"compsci.grm". While writing your lesson, you can see that the new verbatim
marks are not recognized. This is normal, this is because you need to manually
tell Vim to script associated with this buffer. It is as simple as to call the
|:edit| command. >
    :e

From now, you can continue to write your lesson and enjoy your updates.

==============================================================================
LICENSE                                                      *vim-grm-license*

Public domain or BSD-0 if creating something in the public domain is not
available in your jurisdiction.

 vim:tw=78:et:isk=!-~,^*,^\|,^\":ft=help:norl:
