# Demonstrating updates and additions  
      
This document was derived from the processing of the file dr_egeria_intro_part1.md; All the Dr.Egeria statements have been 
preserved (including the generated attributes such as the unique GUIDs), and the explanatory text has been replaced.

In this document we will add glossary categories, update existing terms to categorize them, and add some new terms that
further explain dr.egeria.  This document is being written off-line (actually on a plane) - demonstrating one of the 
intriguing features of dr.egeria - because its just text, it can be edited anywhere and anytime that there is a text 
editor. Dr.Egeria files can be emailed, sent via text message, slack, or maintained in a `git` repository. 
It's just text with markdown annotations.

Ok, let's get started. First, we have the `Update Glossary` command below. There is nothing new we need to add at this
point so we can just leave it as-is. When this document is processed it will apply updates but if there are none, 
It doesn't matter.

However, now is a good time to start to more formally specify the attributes available to `Create` or `Update` glossary
commands:


| Attribute Name | Input Required? | Read Only | Generated/Default? | Unique? | Notes                                                                                                    |
|:---------------|:----------------|-----------|:-------------------|:--------|:---------------------------------------------------------------------------------------------------------|
| Glossary Name  | Yes             | No        | No                 | No      | A display name (informal name).                                                                          |
| Language       | No              | No        | No                 | No      | The primary language for the glossary.                                                                   |
| Description    | No              | No        | No                 | No      | A textual description of this glossary.                                                                  |
| Usage          | No              | No        | No                 | No      | How the glossary is meant to be used, and by whom.                                                       |
| Qualified Name | Maybe           | No        | Yes                | Yes     | The qualified name can either be provided by the user or generated. If generated, a pattern is followed. |
| GUID           | No              | Yes       | Yes                | Yes     | GUIDs are always generated by Egeria. They are meant for automation, not people.                         |

The table above shows us what attributes must be provided and which are optional. Once an object is created, and a qualified name is generated, it is good practice to use it as there can 
be many objects with the same name, and this is a common way to disambiguate them. If you specify an object name (e.g. Glossary Name) and that name already exists, Dr.Egeria will report an error
and suggest that you provide a **Qualified Name** as well. You will also note that the GUID is generated by Egeria and is read-only. It is possible that some commands
may require a GUID to be specified, but in general we will use the **Qualified Name** to identify objects. 

> Comment: In the Egeria and pyegeria APIs, Glossary Name is actually referenced as a **Display Name**. It is perfectly fine for multiple objects to have the same display name.
> However, it is required that even though the may share the same display name, they must have different qualified names and GUIDs. So if you provide a Glossary Name that already exists,
> you will get an error message that suggests that you provide a Qualified Name in addition to the Glossary Name.

___ 

# Glossary Categories

Sometimes it can be useful to provide more structure to the glossary. The way to do this is through categories. 
In Egeria, a category can have a single parent category and multiple child categories. A term can be assigned to 
multiple categories. When we have a large number of terms, a category structure can be particularly helpful in finding the
terms that are most relevant to a particular topic. Using categories is optional.

Ok, now let's create a couple of glossary categories. They will be:

* **Writing Dr.Egeria Markdown** - where we describe elements of the Dr.Egeria language as terms within the category.
* **Processing Dr.Egeria Markdown** - where we describe the commands for processing Dr.Egeria.
 

Glossary categories have the following attributes:


| Attribute Name  | Input Required? | Read Only | Generated/Default? | Unique? | Notes                                                                                                    |
|:----------------|:----------------|-----------|:-------------------|:--------|:---------------------------------------------------------------------------------------------------------|
| Category Name   | Yes             | No        | No                 | No      | A display name (informal name).                                                                          |
| Owning Glossary | Yes             | No        | No                 | Yes     | This is the qualified name of the glossary that owns this category.                                      |
| Description     | No              | No        | No                 | No      | A textual description of this category                                                                   |
| Qualified Name  | Maybe           | No        | Yes                | Yes     | The qualified name can either be provided by the user or generated. If generated, a pattern is followed. |
| GUID            | No              | Yes       | Yes                | Yes     | GUIDs are always generated by Egeria. They are meant for automation, not people.                         |

> Note: Qualified Names can either be user specified or generated. If generated the following the form:
`{local-qualifier}::{type}::{display name}::{version}`. Local-Qualifier is an optional string that can be useful to both disambiguate similar names and to add some local context. Local qualifiers could be set to organization names, functions, business context, etc. The settings for a local qualifier is set either by setting the environment variable `EGERIA_LOCAL_QUALIFIER` or by passing in a parameter when executing one of the Dr.Egeria enabled commands. This could also be set for a team by an Egeria administrator.

Ok, here we go:

___

# Create Category  
  
## Category Name  
  
Writing Dr.Egeria Markdown  
  
## Owning Glossary  
  
Glossary::Egeria-Markdown  
  
## Description  
  
These terms describe the elements of the Dr.Egeria Markdown language and how to use them.   


___

# Create Category  
  
## Category Name  
  
Processing Dr.Egeria Markdown  
  
## In Glossary  
  
Glossary::Egeria-Markdown  
  
## Description  
  
These terms describe commands to process Dr.Egeria Markdown.  
   

___  

> Note: If you look at the examples above, you will notice that sometimes we specify **In Glossary** and sometimes we specify **Owning Glossary**. 
> There is no difference. We will have preferred names that we will use when we generate a Dr.Egeria markdown file, but we try
> to be flexible and allow for common name variations. You will see how we document this as we proceed.
  
Now, let's add categories to the terms.  Let's review the attributes of a term:


| Attribute Name  | Input Required? | Read Only | Generated/Default? | Unique? | Notes                                                                                                                |
|:----------------|:----------------|:----------|:-------------------|:--------|:---------------------------------------------------------------------------------------------------------------------|
| Term Name       | Yes             | No        | No                 | No      | A display name (informal name).                                                                                      |
| Owning Glossary | Yes             | No        | No                 | Yes     | This is the qualified name of the glossary that owns this term.                                                      |
| Categories      | No              | No        | No                 | Yes     | This is the name of the category. Multiple categories can be assigned, separated by a `,` or line.                   | 
| Description     | No              | No        | No                 | No      | A textual description of this term                                                                                   |
| Qualified Name  | No              | Yes       | No                 | Yes     | The qualified name can either be provided by the user or generated. If generated, a pattern is followed.             |
| GUID            | No              | Yes       | Yes                | Yes     | GUIDs are always generated by Egeria. They are meant for automation, not people.                                     |

> When we provide a category name in the `Categories` attribute, We can use either the display name form (Category Name) or the qualified name form. If we find that the display name is not unique, 
> you will need to provide the qualified name. Its safer to use the qualified name, but a little less readable.

___  

# Update Term

## Term Name 

Command

## Summary
Commands are how a user of the Dr.Egeria markdown language requests an action.

## In Glossary
Glossary::Egeria-Markdown

## Categories

Category::Writing Dr.Egeria Markdown, Category::Processing Dr.Egeria Markdown

## Status
ACTIVE

## Description
Commands are how a user can request Egeria to take an action such as Create or Update an Egeria element. Freddie
provides
a limited (but growing) set of commands. Dr.Egeria commands align with the pyegeria 'hey-egeria' command line interface.

## Examples
Create Glossary or
Update Glossary or
Create Term or
Update Term

## Usage
Commands are used in the Dr.Egeria markdown language.

## Published Version

0.2

## Qualified Name



___

# Update Term

## Term Name 

Source

## Summary
Source of the markdown content.

## In Glossary
Glossary::Egeria-Markdown

## Categories

Processing Dr.Egeria Markdown 

## Status
ACTIVE

## Description
Source of the markdown content - could be jupyter or plain markdown file.

## Examples

## Usage


## Published Version

0.2

## Qualified Name
Term::Source::0.1


___

# Update Term
  
## In Glossary  
  
Glossary::Egeria-Markdown  
  
## Term Name  
  
Directive  
  
## Categories  
  
Processing Dr.Egeria Markdown  
  
## Summary  
  
A directive defines how the command is to be processed.  
  
## Description  
  
Directives are one of:  
  
* display - just display what we've found  
* validate - check the validity of the requested action  
* process - process the requested action  
 
  
  
## Version  
  
0.2 
  
## Status  
  
DRAFT  
  
## Qualified Name  
Term::Directive::0.1  

  
# Inspecting the Glossary

Now that we have created a glossary, categories, and terms we can use some new commands to show us what we have done.
We will start with the `List Glossaries` command. This command will list all the glossaries that are available to us.

___

# List Glossaries

___

This will return a markdown table of all known glossaries based on the defaults set for the optional attributes. Here 
is a more detailed specification of the attributes:

| Attribute Name | Input Required? | Read Only? | Generated/Default?               | Unique? | Notes                                     |
|----------------|-----------------|------------|----------------------------------|---------|-------------------------------------------|
| Search String  | No              | No         | default is All glossaries        | No      |                                           |
| Output Format  | No              | No         | default is Markdown List (table) | No      | options are: LIST, DICT, MD, FORM, REPORT |

Lets describe the output formats a bit further:

* LIST - This is the default format. It returns a markdown table of the glossaries.
* DICT - This returns a python dictionary (or JSON representation) of the glossaries. 
* MD - This returns a markdown document of the glossaries.
* FORM - This returns a Dr.Egeria markdown form designed to be used as a starting point for updating the glossary definitions.
* REPORT - This returns a markdown document of the glossaries that is designed to be more readable and perhaps suitable to be used in a report.

Going further, we can issue similar commands to list categories and terms:

The attributes for the `List Categories` command are the same as the `List Glossaries` command:
Attributes for the `List Terms` command are:


| Attribute Name | Input Required? | Read Only? | Generated/Default?               | Unique? | Notes                                     |
|----------------|-----------------|------------|----------------------------------|---------|-------------------------------------------|
| Glossary Name  | No              | No         | Default is All glossaries        | No      |                                           |
| Search String  | No              | No         | default is All terms             | No      |                                           |
| Output Format  | No              | No         | default is Markdown List (table) | No      | options are: LIST, DICT, MD, FORM, REPORT |



___

# List Categories
## Output Format
REPORT

___
# List Terms
## Output Format
DICT

  
