readme.txt

Introduction

This readme.txt file includes various instructions, descriptions, and information about all aspects of a TMSS Digital Support Suite (DSS). The contents of this readme file will apply to all users. below is a breakdown and description of the contents of this readme file.

1.0 Contents of this zip file

2.0 OmniMark

3.0 ISO Entities

1.0 Contents of this Zip File

This zip file contains the following pieces of the DSS:

1) Resolved DTD (with entity calls removed)

2) Tag Description Table

3) OmniMark zip file(s)

4) ISO Entities zip file

5) Release Notes

6) This README file

2.0 OmniMark

OmniMark is a text processing language that is used by the TMSS group to allow authors to auto-generate redundant material that may be difficult to tag manually. Every DSS released by the Air Force TMSS will have an OmniMark zip file that contains, at a minimum, the scripts needed to complete tagging for 38784STD-B requirements.

The OmniMark zip file contains all programs, the script to run these program and a readme.txt file specific to that individual program.

2.1 Use of OmniMark scripts

The OmniMark scripts must be customized to meet the requirements of your system.

All OmniMark scripts operate from the Unix command line and utilize a library file, a concrete syntax, and OmniMark programs.

There are four basic elements of a script identified by a special delimiter on the script command line.

-s identifies the source program, concrete syntax and the input file for this particular program, as well as their locations on your system. When a $1 is used within a -s parameter, it means the name will be input from the command line.

-of identifies the output file of the program

-library identifies the library file and its location on your system

-define identifies any special files needed by OmniMark as input into the program. In most cases, the -define parameter is used to gather files created by OmniMark during processing. At the end of most scripts, all files created during the processing of an instance are deleted from your directory.

Below is an example of a very basic script:

OmniMark -s /mydirectory/OmniMark/myprogram.xom /mydirectory/OmniMark/28001con.syn input.file -of output.fil -library library.file

OmniMark uses the ";" character to indicate a comment so if this character precedes any line in a file, OmniMark will not recognize it. This character may be helpful if our example file uses ISO entities not currently available on your system. Also, if you need to comment our programs for any reason, use of this ";" character will allow you insert comments without harming the functionality of the program.

You will need to perform these steps.

1. Define the directory structure

2. Create a library file.

3. Modify your scripts to point to the directory location of the programs, the concrete syntax, and a library file.

2.1.1 Directory Structure

OmniMark does not really concern itself with a particular directory structure.

You only need to develop a structure that you can understand and maintain. You may want to keep your scripts and programs in a central location, but it is not necessary. You can use a root directory and several sub-directories with a unique subdirectory for programs, scripts, etc. Or, if you prefer, you can put the scripts, programs, library files, and concrete syntax in one directory.

2.1.1.1 Create a Library File

The library file is merely a map for OmniMark to navigate your system. You need to identify the ISO Entities and any DTD that OmniMark will reference. At runtime, an OmniMark script will go out and search the system based on your library file and locate the ISO Entities and the particular DTD needed to parse your input file. Your particular library file can have any name you desire.

This file contains a sample library file that you can reference or modify to suit your system.

In addition, any DTD that will be referenced by an OmniMark script or program must be declared in the library file. It is not necessary to include a DTD declaration for every DTD loaded onto your system, since you may not run OmniMark on every DTD. BUT, it is a wise practice to add any new DTD since at some point, it may become necessary to execute an OmniMark script on an instance that calls that DTD. In addition, every DSS will, in all likelihood, utilize the OmniMark programs developed for 38784STD-B.

2.1.1.2 Modify Scripts

The scripts provided in this zip file can be made compliant with your directory structure. For example, the script:

LM_LICENSE_FILE=$OMNIMARK_DIR/license.dat export LM_LICENSE_FILE omnimark -s /omnimark/87929B-IV3D1P0_remove_dash1.xom $1 -of $1.dash -library /omnimark/wndlibrary.txt omnimark -s /omnimark/87929B-IV3D1P0_remove_contents1.xom /omnimark/28001con.syn $1.dash -of $1.out -library /omnimark/wndlibrary.txt -define inputfile $1

2.2 Running an OmniMark program

There are many different types of scripts released with the TMSS DSSs. They range in spectrum from executing one program to several complete compositions coupled with numerous OmniMark programs throughout. Not only will some of these scripts execute an OmniMark program, they possibly invoke some command line executions like parsing your DTD.

To execute a script, from your working directory type in:

scriptname.sh filename where scriptname.sh is the script you wish to run and filename is the name of the file you wish to use as input

You may decide that you have no need for any of the OmniMark scripts that we provide as part of a release. In most cases, these scripts just facilitate tagging that can be performed manually. But, the scripts will save authoring time.

All DSSs that rely on MIL-STD-38784 will be able to utilize 38784STD- BV8a scripts to generate acronym lists, alphabetical indices, or assist in the composition of the verification status page. MIL-STD-38784 will also include scripts and programs to generate a numerical index or reference designator index when developing a combined manual.

Every DSS released by the TMSS office will contain these standard 38784 scripts and associated programs within a zip file. In addition, your particular DSS may have its own set of unique OmniMark scripts and programs. Contained within each zip file will be the scripts, programs, and a readme file that will outline the purpose of the OmniMark for your DSS and provide a list of the scripts and programs provided for your DSS.

3.0 ISO Entities

The ISO entities are needed to properly parse and compose instances using the AF TMSS DTD and FOSI. These files are included as a zip within the zip file for your DSS.

3.1 Contents of the zip file

3.2 Installation

The first step to properly installing the ISO components of this zip file is to copy all of the entity and graphic files onto your system. We would suggest that you create a directory on your system to house all the entity and graphic files.

Once you have loaded the files onto your system and/or identified their directory, you must modify all declarations.

Simply stated, for example, the - SMALL EPS SYMBOLS - V1 is a file that contains nothing but entity declarations for each of the small eps symbols contained in the tar files (small eps symbols 1 tar and small eps symbols 2 tar). This file must be called by your DTD. The DTD calls the SMALL EPS SYMBOLS using its public identifier and that file in turn, will call all the small eps symbols by their individual public identifiers.

The declarations for all of these files must be modified to point to the location of these files on your system. For example, the DTD declaration for SMALL EPS Symbols on the JCALS system is:

<!ENTITY % local-small-symbols "INCLUDE" > <!ENTITY % eps-sml PUBLIC "-//your system//ENTITIES small EPS symbols v1//EN"> %eps-sml;

These three lines contain a marked section set to INLCUDE (line 1), the declaration (line2) and the entity call (line3).

You will have to modify your DTD to point to the correct location of these files on your system. For instance, if your files are located on your system in a directory called isoentities, the above declaration would be modified to read:

<!ENTITY % local-small-symbols "INCLUDE" > <!ENTITY % eps-sml PUBLIC "-//your system//ENTITIES small EPS symbols v1//EN" "/isoentities/ENTITIES_small_EPS_symbols_v1"> %eps-sml;

In addition, each line of the SMALL EPS SYMBOLS V1 file must be modified in a text editor to reflect the location of the graphic files on your system. Below is an example of the file with this modification.

<!ENTITY adown SYSTEM "/isoentities/adown.eps" NDATA EPS> <!ENTITY ai SYSTEM "/isoentities/ai.eps" NDATA EPS>