National Instruments 370769C-01 User Manual

NI MATRIXx

DocumentItTM User Guide

DocumentIt User Guide

April 2007 370769C-01

Support

Worldwide Technical Support and Product Information

ni.com

National Instruments Corporate Headquarters

11500 North Mopac Expressway Austin, Texas 78759-3504 USA Tel: 512 683 0100

Worldwide Offices

Australia 1800 300 800, Austria 43 662 457990-0, Belgium 32 (0) 2 757 0020, Brazil 55 11 3262 3599, Canada8004333488, China862150509800, CzechRepublic420224235774, Denmark4545762600, Finland 385 (0) 9 725 72511, France 33 (0) 1 48 14 24 24, Germany 49 89 7413130, India 91 80 41190000, Israel 972 3 6393737, Italy 39 02 413091, Japan 81 3 5472 2970, Korea 82 02 3451 3400, Lebanon 961 (0) 1 33 28 28, Malaysia 1800 887710, Mexico 01 800 010 0793, Netherlands 31 (0) 348 433 466, New Zealand 0800 553 322, Norway 47 (0) 66 90 76 60, Poland 48 22 3390150, Portugal 351 210 311 210, Russia 7 495 783 6851, Singapore 1800 226 5886, Slovenia 386 3 425 42 00, South Africa 27 0 11 805 8197, Spain 34 91 640 0085, Sweden 46 (0) 8 587 895 00, Switzerland 41 56 2005151, Taiwan 886 02 2377 2222, Thailand 662 278 6777, Turkey 90 212 279 3031, United Kingdom 44 (0) 1635 523545

For further support information, refer to the Technical Support and Professional Services appendix. To comment on National Instruments documentation, refer to the National Instruments Web site at ni.com/info and enter the info code feedback.

Important Information

Warranty

The media on which you receive National Instruments software are warranted not to fail to execute programming instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not execute programming instructions if National Instruments receives notice of such defects during the warranty period. National Instruments does not warrant that the operation of the software shall be uninterrupted or error free.

A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before any equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are covered by warranty.

National Instruments believes that the information in this document is accurate. The document has been carefully reviewed for technical accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected. In no event shall National Instruments be liable for any damages arising out of or related to this document or the information contained in it.

XCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF

MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. CUSTOMER’S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL

NSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR DAMAGES RESULTING

FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of

the liability of National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence. Any action against National Instruments must be brought within one year after the cause of action accrues. National Instruments shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein does not cover damages, defects, malfunctions, or service failures caused by owner’s failure to follow the National Instruments installation, operation, or maintenance instructions; owner’s modification of the product; owner’s abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties, or other events outside reasonable control.

Copyright

Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical, including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without the prior written consent of National Instruments Corporation.

National Instruments respects the intellectual property of others, and we ask our users to do the same. NI software is protected by copyright and other intellectual property laws. Where NI software may be used to reproduce software or other materials belonging to others, you may use NI software only to reproduce materials that you may reproduce in accordance with the terms of any applicable license or other legal restriction.

Trademarks

Autocode™, DocumentIt™, MATRIXx™, National Instruments™, NI™, ni.com™, SystemBuild™, and Xmath™ are trademarks of National Instruments Corporation.

Other product and company names mentioned herein are trademarks or trade names of their respective companies.

Members of the National Instruments Alliance Partner Program are business entities independent from National Instruments and have no agency, partnership, or joint-venture relationship with National Instruments.

Patents

For patents covering National Instruments products, refer to the appropriate location: Help»Patents in your software, the patents.txt file on your CD, or

ni.com/paten ts.

WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS

(1) NATIONAL INSTRUMENTS PRODUCTS ARE NOT DESIGNED WITH COMPONENTS AND TESTING FOR A LEVEL OF RELIABILITY SUITABLE FOR USE IN OR IN CONNECTION WITH SURGICAL IMPLANTS OR AS CRITICAL COMPONENTS IN ANY LIFE SUPPORT SYSTEMS WHOSE FAILURE TO PERFORM CAN REASONABLY BE EXPECTED TO CAUSE SIGNIFICANT INJURY TO A HUMAN.

(2) IN ANY APPLICATION, INCLUDING THE ABOVE, RELIABILITY OF OPERATION OF THE SOFTWARE PRODUCTS CAN BE IMPAIRED BY ADVERSE FACTORS, INCLUDING BUT NOT LIMITED TO FLUCTUATIONS IN ELECTRICAL POWER SUPPLY, COMPUTER HARDWARE MALFUNCTIONS, COMPUTER OPERATING SYSTEM SOFTWARE FITNESS, FITNESS OF COMPILERS AND DEVELOPMENT SOFTWARE USED TO DEVELOP AN APPLICATION, INSTALLATION ERRORS, SOFTWARE AND HARDWARE COMPATIBILITY PROBLEMS, MALFUNCTIONS OR FAILURES OF ELECTRONIC MONITORING OR CONTROL DEVICES, TRANSIENT FAILURES OF ELECTRONIC SYSTEMS (HARDWARE AND/OR SOFTWARE), UNANTICIPATED USES OR MISUSES, OR ERRORS ON THE PART OF THE USER OR APPLICATIONS DESIGNER (ADVERSE FACTORS SUCH AS THESE ARE HEREAFTER COLLECTIVELY TERMED “SYSTEM FAILURES”). ANY APPLICATION WHERE A SYSTEM FAILURE WOULD CREATE A RISK OF HARM TO PROPERTY OR PERSONS (INCLUDING THE RISK OF BODILY INJURY AND DEATH) SHOULD NOT BE RELIANT SOLELY UPON ONE FORM OF ELECTRONIC SYSTEM DUE TO THE RISK OF SYSTEM FAILURE. TO AVOID DAMAGE, INJURY, OR DEATH, THE USER OR APPLICATION DESIGNER MUST TAKE REASONABLY PRUDENT STEPS TO PROTECT AGAINST SYSTEM FAILURES, INCLUDING BUT NOT LIMITED TO BACK-UP OR SHUT DOWN MECHANISMS. BECAUSE EACH END-USER SYSTEM IS CUSTOMIZED AND DIFFERS FROM NATIONAL INSTRUMENTS' TESTING PLATFORMS AND BECAUSE A USER OR APPLICATION DESIGNER MAY USE NATIONAL INSTRUMENTS PRODUCTS IN COMBINATION WITH OTHER PRODUCTS IN A MANNER NOT EVALUATED OR CONTEMPLATED BY NATIONAL INSTRUMENTS, THE USER OR APPLICATION DESIGNER IS ULTIMATELY RESPONSIBLE FOR VERIFYING AND VALIDATING THE SUITABILITY OF NATIONAL INSTRUMENTS PRODUCTS WHENEVER NATIONAL INSTRUMENTS PRODUCTS ARE INCORPORATED IN A SYSTEM OR APPLICATION, INCLUDING, WITHOUT LIMITATION, THE APPROPRIATE DESIGN, PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION.

Conventions

The following conventions are used in this manual:

» The » symbol leads you through nested menu items and dialog box options

to a final action. The sequence File»Page Setup»Options directs you to pull down the File menu, select the Page Setup item, and select Options from the last dialog box.

This icon denotes a note, which alerts you to important information.

bold Bold text denotes items that you must select or click in the software, such

as menu items and dialog box options. Bold text also denotes parameter names.

italic Italic text denotes variables, emphasis, a cross-reference, or an introduction

to a key concept. Italic text also denotes text that is a placeholder for a word or value that you must supply.

monospace Text in this font denotes text or characters that you should enter from the

keyboard, sections of code, programming examples, and syntax examples. This font is also used for the proper names of disk drives, paths, directories, programs, subprograms, subroutines, device names, functions, operations, variables, filenames and extensions, and code excerpts.

monospace bold Bold text in this font denotes the messages and responses that the computer

automatically prints to the screen. This font also emphasizes lines of code that are different from the other examples.

monospace italic

Platform Text in this font denotes a specific platform and indicates that the text

Italic text in this font denotes text that is a placeholder for a word or value that you must supply.

following it applies only to that platform.

Chapter 1 Introduction

Manual Organization .....................................................................................................1-1

DocumentIt and the Rapid Prototyping Concept...........................................................1-2

Automatic Document Generation Process.....................................................................1-4

Cruise Control Example.................................................................................................1-6

How to Access National Instruments-Supplied Files ....................................................1-10

Related Publications ......................................................................................................1-11

Chapter 2 Invoking DocumentIt

How to Generate Design Documentation ......................................................................2-1

Generating Documentation From Within SystemBuild ..................................2-1

Platform Specific Differences...........................................................2-3

Template Information .......................................................................2-5

Generating Documentation from Xmath.........................................................2-5

Generating Documentation from the OS.........................................................2-7

Generate a Textual Version of a Model ..........................................................2-7

Chapter 3 Customizing the Generated Documentation

Appendix A DocumentIt Options

Appendix B Generating Documents Using FrameMaker

Appendix C Generating 2167A Documents Using FrameMaker

Appendix D Generating 2167A Documents Using Interleaf

Contents

Appendix E Generating Documents Using Microsoft Word

Appendix F Generating ASCII Documents

Appendix G Technical Support and Professional Services

Index

DocumentIt User Guide vi ni.com

Introduction

With SystemBuild and DocumentIt menu options, you can generate

high-quality design documentation automatically from SystemBuild block

diagrams. This guide provides the information you need to start using

DocumentIt, as well as the more advanced details necessary to customize

the generated design documentation.

Manual Organization

• Chapter 1 provides an overview of the National Instruments design documentation generation concept, a description of the basic steps required to produce documentation, and a brief example of documentation generation from a SystemBuild model. This chapter, along with Chapter 2, Invoking DocumentIt, will give you everything you need to know in order to generate documentation using any of the templates described in Appendix B, Generating Documents Using

FrameMaker, through Appendix E, Generating Documents Using Microsoft Word.

If you want to create custom documentation, refer to the Related

Publications section of Chapter 3, Customizing the Generated Documentation.

• Chapter 2, Invoking DocumentIt, tells how to generate documents from SystemBuild, the Xmath Commands window, and from the operating system command line.

• Chapter 3, Customizing the Generated Documentation , points you to a detailed explanation of template files ( document. NI supplies DocumentIt templates ( the examples given in Appendix B, Generating Documents Using

FrameMaker, through Appendix E, Generating Documents Using Microsoft Word. You can copy the

examples and modify them using the information in this chapter.

• Appendix A, DocumentIt Options, provides a description of the DocumentIt options, and explains how to use an

*.tpl) for formatting a

*.tpl files) for each of

*.tpl files from any of these

autostar.opt file.

Chapter 1 Introduction

• Appendix B, Generating Documents Using FrameMaker, provides a description of how to generate a sample design document using DocumentIt and FrameMaker templates.

• Appendix C, Generating 2167A Documents Using FrameMaker, provides a description of how to generate a sample design document conforming closely with DOD-STD-2167A using DocumentIt and FrameMaker templates.

• Appendix D, Generating 2167A Documents Using Interleaf, provides a description of how to generate a sample design document conforming closely with DOD-STD-2167A using DocumentIt and Interleaf templates.

• Appendix E, Generating Documents Using Microsoft Word, provides a description of how to use a template to create a general purpose document in Microsoft Word.

• Appendix F, Generating ASCII Documents, provides a description of how to generate a sample design document using a DocumentIt template.

DocumentIt and the Rapid Prototyping Concept

Conventional real-time system development usually takes place in stages with separate tools for control design, software engineering, data acquisition, testing, and design documentation. The MATRIXx product family integrates tools for each stage of system development into a single environment. This allows a design to move easily from one stage to the next, making it possible to create a well-documented working prototype early in the design process. Figure 1-1 shows DocumentIt in the MATRIXx product line.

Within the MATRIXx design automation product family, a system model can be built, simulated, analyzed, tested, and debugged using SystemBuild and Xmath. Real-time code in a high-level language for the model—C or Ada—using AutoCode and design documentation can be generated automatically with DocumentIt. The generated application code can be evaluated on the host with SystemBuild simulation or run on NI real time hardware. Finally, the generated application code can be cross-compiled and linked for implementation on an embedded processor. Documentation can be updated and automatically generated along each step of the process.

DocumentIt User Guide 1-2 ni.com

MATRIXx Product Family

Tools

Xmath

(Analysis/Design)

SystemBuild

(Modeling/Simulation)

Chapter 1 Introduction

AutoCode

(Code Generation)

Real Time Hardware

Cross-Compilers/

Real-Time

Operating System

(pSOS or VxWorks)

(Implementation on an

embedded processor)

DocumentIt

(Document Generation)

ASCII Output

Document

FRFrameMaker

MMS Word

Figure 1-1. DocumentIt in the MATRIXx Product Line

InInterleaf

Chapter 1 Introduction

Automatic Document Generation Process

As an integral part of MATRIXx Rapid Prototyping concept, DocumentIt lets you generate design documentation from a SystemBuild block diagram model quickly, automatically, and without programming skills. DocumentIt details the software design in a uniform standardized documentation format and fully supports the SystemBuild hierarchical approach to system design.

Because DocumentIt uses templates to format documents and select specific contents, you can configure DocumentIt to suit your particular documentation needs. The templates can be readily modified to conform to any documentation standard. For example, DocumentIt can be used to generate the following:

• Detailed description of the design in ASCII format

• Most industry-standard formats

• Tables containing SuperBlock and Block inputs and outputs, State Transition Diagrams, and Global data

• Documents formatted for FrameMaker (including DOD-STD-2167A) and Microsoft Word (or any application that reads RTF)

A typical sequence for using DocumentIt is as follows. This sequence corresponds to the sequence of steps shown in Figure 1-2:

1. Build and Document the Model.

Develop the continuous-time plant model and corresponding discrete-time controller SuperBlocks using SystemBuild block diagrams. The SystemBuild model is built up from a large palette of blocks which combine to describe the way the model works and how it should be controlled. DocumentIt automatically extracts information from the Inputs, Outputs, Document, and Comment fields for SuperBlocks and primitive blocks.

DocumentIt User Guide 1-4 ni.com

SystemBuild/Xmath

Model Simulation

Step 1

Chapter 1 Introduction

SystemBuild

Model File

(.rtf)

Step 2

Command

Options

Step 3

Document with

FrameMaker

Markup Cmds.

Step 4

FrameMaker Interleaf

Standard

Document

Step 5

DocumentIt

Design Documentation

Generator

ASCII

Document with

Interleaf

Markup Cmds.

(.dac)

Step 4

Step 2

Interleaf

Markup

Te m p la t e *

Standard

Template File

FrameMaker

Markup

Te m p la t e *

Document with Microsoft Word

Commands

Microsoft

Word

Step 4

*Use markup templates for general purpose or

DOD-STD-2167A documents

Figure 1-2. DocumentIt Automatic Documentation Generation Process

2. Customize documentation generation.

Tailor your generated design document using the template programming language (TPL) provided in DocumentIt. This programming language lets you implement virtually any template file

Chapter 1 Introduction

Note RTF can be read by most word processing and desktop publishing programs, but it

is the native format in Word.

for a specialized purpose. DocumentIt output in this case is an ASCII text file, which you can use with almost any text editor. You can edit the file or print it as a simple unformatted ASCII file.

Typically, the template file contains DocumentIt parameters and publishing commands such as rich text format (RTF) or FrameMaker markup language (MML), which DocumentIt writes directly to the output file.

3. Generate the design document.

Invoke DocumentIt from inside SystemBuild, from the Xmath Commands window, or from the operating system prompt. DocumentIt loads discrete-time and continuous-time SuperBlocks, reading the associated data to generate the design documentation in accordance with the template instructions.

4. Process documents with markup commands.

Import DocumentIt document files with FrameMaker, Interleaf, or RTF markup commands into FrameMaker, Interleaf, or Microsoft Word, respectively. These applications automatically recognize the document formats.

5. Print the formatted document.

Save the model design document in RTF, FrameMaker (MML), or ASCII format, and send it to a printer in any printer output form such as PostScript or portable document format (PDF).

Cruise Control Example

This section illustrates the use of DocumentIt. Figure 1-3 shows a modified version of the cruise control model. This model is found in:

(UNIX) $CASE/DIT/templates/fmaker/general/

Controller_Logic_gen.dat

(Windows) %CASE%\case\DIT\templates\fmaker\general\

Controller_Logic_gen.dat

DocumentIt User Guide 1-6 ni.com

Chapter 1 Introduction

Figure 1-3. Cruise Control SystemBuild Diagram

The cruise control model consists of the highest-level SuperBlock, two embedded SuperBlocks, and associated units. Figure 1-4 shows the associated SuperBlock Properties dialog. Click Help for information on each field in the dialog.

Chapter 1 Introduction

Figure 1-4. SuperBlock Properties for Cruise Control Diagram

The information from the SuperBlock Properties dialog can be included in the DocumentIt ASCII output file by using the appropriate keywords in the template file. The excerpt from a template file shown in Example 1-1 produces entries in the DocumentIt ASCII output file shown in Example 1-2.

Example 1-1 Template File Excerpt

@SEGMENT MAIN() STRING S1 @ Software Design Document

@SCOPE SUPERBLOCK 0@

Overview : @S1=user_param("OVERVIEW_s", "SUPERBLOCK")@@S1@ Architecture: @user_param("ARCHITECTURE_s", "SUPERBLOCK")@@S1@ System States and Models: @S1=user_param("SYSTEM_STATES_AND_MODES_s", "SUPERBLOCK")@@S1@

DocumentIt User Guide 1-8 ni.com

Chapter 1 Introduction

Num Ext. In = @num_sb_in_i@ Num Ext. Out = @num_sb_out_i@ Num SuperBlocks = @num_blks_in_sb_i@ Attribute = @sb_attr_s@ Frequency = @sb_freq_r@

Has Input Data = @sb_has_in_data_b@ @ENDSEGMENT@

Example 1-2 DocumentIt ASCII Output File

================================== Software Design Document

Overview : This cruise controller regulates vehicle speed around a set point. This cruise controller has three external inputs as follows:

the desired "speed" or velocity of the vehicle,

the current "speed,"

the current "acceleration" of the vehicle.

This cruise controller has one external output, which is the throttle actuator command.

Architecture: There are three SuperBlocks in this model.

The SuperBlocks are as follows:

the "Differentials" SuperBlock computes the difference between desired and measured velocity and acceleration, adds computed target acceleration to measured acceleration, and outputs a servo-limited throttle command based upon these differences

the "Cruise Control Logic" SuperBlock determines whether or not throttle position should be altered, based upon the difference between actual and desired vehicle velocity, and

the "Mux3" SuperBlock determines the target acceleration based upon inputs from the control logic.

Chapter 1 Introduction

System States and Models: This model is enabled and disabled externally.

Num Ext. In = 3 Num Ext. Out = 1 Num SuperBlocks = 3 Attribute = Discrete Frequency = 50.0000

Has Input Data = 1

Similarly, information from all SuperBlock/block dialogs and input/output description dialogs can be included within an ASCII output file by the appropriate use of the keywords in the template file.

How to Access National Instruments-Supplied Files

At several places in this manual, you are asked to execute, study, or copy and modify certain files we provide for your use. The paths to the files are specified by environment variables, which are established by the startup software for your convenience. For UNIX, the environment variables are:

Va ri ab le Status (as delivered)

xmath

$MTXHOME Available from operating system or Xmath

Commands window

$SYSBLD Available from Xmath Commands window and

SystemBuild Load/Save dialog

$XMATH Available from Xmath Commands window

$CASE Available from Xmath Commands window

To mak e

$SYSBLD, $XMATH, or $CASE available from the operating

system, in the Xmath Commands window, type:

oscmd ("echo $

where

variable

is SYSBLD, XMATH, or CASE, as you require. The Xmath software will display the required path. From the operating system, place this path in a

setenv statement and execute it.

For information on Windows environment variables, refer to the Xmath User Guide.

DocumentIt User Guide 1-10 ni.com

Related Publications

National Instruments provides a complete library of publications to support its products. In addition to this guide, publications (from NI and other sources) that you may find particularly useful when using DocumentIt include the following:

• SystemBuild User Guide

• Xmath User Guide

• AutoCode User Guide

• AutoCode Reference

• Template Programming Language User Guide

• Military Standard: Defense System Software Development, DOD-STD-2167A, February 1988

• MML Reference from Adobe Systems Incorporated

This manual will help you create custom documentation formats using FrameMaker MML markup language.

For additional documentation, refer to the MATRIXx Help or the NI Web site at

ni.com.

Chapter 1 Introduction

Invoking DocumentIt

This chapter tells how to generate documents from SystemBuild, Xmath, and from the operating system prompt.

How to Generate Design Documentation

Using DocumentIt, you can generate design documentation from:

• SystemBuild—generates a real-time file ( block and SuperBlock documentation from a model using the Generate Documentation dialog (the recommended method).

• Xmath—generates an SuperBlock documentation from a model using an Xmath command. Refer to Appendix A, DocumentIt Options, for the Xmath command options.

• Operating system prompt—lets you extract block and SuperBlock documentation from a to Appendix A, DocumentIt Options, for the operating system command options.

.rtf file and then extracts block and

.rtf file, using the autostar command. Refer

.rtf) and then extracts

Generating Documentation From Within SystemBuild

To use DocumentIt while inside SystemBuild, complete the following steps:

1. Select a Top-Level SuperBlock. By default, the name of the SuperBlock you select is used for both the real-time file (RTF) file and the documentation output file.

2. Select Tools»DocumentIt from the Catalog Browser (or press <Ctrl-D>) to open the Generate Documentation dialog. Refer to the

Windows section or the UNIX section for platform-specific

information.

Chapter 2 Invoking DocumentIt

3. Select your options. The available options include:

Block Parameters Select the source of the %Var information:

%Vars from Xmath—uses the latest values

of the Xmath variables.

Block Defaults—uses the block’s default values.

Typecheck If selected, the Analyzer checks for matching

data types for input and output signals. AutoCode generates the appropriate data types in the target language that correspond to the SystemBuild data types. If not selected, input and output signals and parameter data are assumed to be FLOAT. In this case, DocumentIt only generates the RT_FLOAT data type for signals and data. Default = 0.

Template File Specify (or browse for) the DocumentIt

template

.tpl or .dac file to be used to

format the documentation. The standard ASCII template is used by default.

Config File An options configuration file that lists the

AUTOSTAR settings for both AutoCode and

DocumentIt. The default options file is

autostart.opt. By default, DocumentIt

first looks for a file of that name in the current working directory; explicitly specified DocumentIt keywords are evaluated later, and override any options file settings.

MS Word Enable special processing for Microsoft Word

RTF file generation. This option is required if you are using the Microsoft Word template as described in Appendix E, Generating

Documents Using Microsoft Word.

4. Click OK and monitor the status of your document generation in the

Xmath Commands window log area.

DocumentIt displays the following message:

Documentation generation complete.

Document generated and saved in file:

block_name

.doc.

5. Open your generated document in the appropriate editor.

DocumentIt User Guide 2-2 ni.com

Chapter 2 Invoking DocumentIt

Platform Specific Differences

The DocumentIt Generate Documentation dialog has some platform-specific features.

Windows

SystemBuild uses the standard Windows selection dialog to display an output file name in the File name field. The Look in field displays the working directory which will be the output directory for your generated file. You can select any drive or directory for the generated file.

If you want more information on standard portions of the dialog, click the question mark (?) icon on the dialog title bar, and then position the question mark cursor over a field or icon and click. The Windows help for that field will be displayed.

Depending on the template file used, the document can be either an ASCII text file or an ASCII file with embedded word processor markup language formatting commands. These commands are word processor specific. Example templates are provided to support FrameMaker, Interleaf, and rich text format (RTF), used by Microsoft Word and read by other programs.

Note A generated Microsoft Word file has the extension .doc. DocumentIt uses the

extension described in the Generating Documentation from the OS section.

.rtf for real-time files which can be used with the autostar command as

Chapter 2 Invoking DocumentIt

UNIX

The Generate Documentation dialog uses a standard Motif File Selection dialog to specify the name of the output documentation file in the Selection field.

Filter Displays the file selection directory path. Uses standard

shell wildcard character(s) to select the files shown in the Files listing. Default value is the current directory with the

*.cat filter. Pressing <Return> after changing the filter

path updates the listings in Directories and Files.

Directories Lists the directories within the current directory.

Double-click the directory name to change the current directory.

Files Lists the files in the selected directory that meet the filter

criteria. If the rest of the dialog is filled out to your satisfaction, double-click a file to save to that file name.

DocumentIt User Guide 2-4 ni.com

Chapter 2 Invoking DocumentIt

Selection Displays the complete path to the file selected in the Files

listing. Because this name is used for both the RTF file and the documentation file, any extensions will be stripped before creating the

.rtf and source file names.

Template Information

Appendix B, Generating Documents Using FrameMaker, through Appendix E, Generating Documents Using Microsoft Word, provide examples of automatic documentation generation using DocumentIt templates, as follows:

• Appendix B, Generating Documents Using FrameMaker, describes how to generate a general purpose design document using DocumentIt and FrameMaker templates.

• Appendix C, Generating 2167A Documents Using FrameMaker, describes how to generate a sample design document conforming closely with DOD-STD-2167A using DocumentIt and FrameMaker templates.

• Appendix D, Generating 2167A Documents Using Interleaf, describes how to generate a sample design document conforming closely with DOD-STD-2167A using DocumentIt and Interleaf templates.

• Appendix E, Generating Documents Using Microsoft Word, describes how to generate a sample design document using DocumentIt and Microsoft Word templates.

• Appendix F, Generating ASCII Documents, describes how to generate a sample design document in ASCII text file format using a DocumentIt template.

Generating Documentation from Xmath

The documentit command lets you process a model to generate design documentation.

Two syntaxes are supported:

documentit, {model =

template=

documentit model, {options}

name3

}

name1

, file =

name2

Chapter 2 Invoking DocumentIt

where

name1

identifies the model to be processed for documentation

generation. The model can be either:

• A string in quotes (“”), which must be the name of a SuperBlock that exists in the current SystemBuild Catalog. This SuperBlock is analyzed and processed to generate documentation.

• A variable, not in quotes. Variables should be assigned to a string, the string must be the name of a SuperBlock in the current catalog. It is analyzed and processed to generate documentation.

Whenever a file name or other string is included in a command string, it must be enclosed in quotes, but a variable name must not be in quotes.

name2

is the name for the generated output document file. This value must

be a string or string variable, as well. If the

file =

provided, documentation will be generated in the file

name3

is the name of the template file used to tailor the document. This

name2

option is not

mode1.doc.

value must be a string or string variable. If this option is not provided, the template

ascii

_documentit.tpl (in the directory $CASE/DIT/templates/

) is used (%CASE% for Windows).

Refer to Appendix A, DocumentIt Options, for a complete list of DocumentIt options used in the second command syntax.

Examples:

documentit "

The system generates a real-time file named

topSB

.rtf. It loads this file

and processes it to produce the document file. The output file name is

topSB

.doc.

documentit "

documentit, {model = "

Either syntax processes the SuperBlock produce documentation, using the template file file name is

DocumentIt User Guide 2-6 ni.com

topSB

", {template="mytemplate"}

topSB

", template = "mytemplate"}

topSB

in the current catalog to

mytemplate. The output

.doc.

Generating Documentation from the OS

If a model file already exists, it is also possible to execute DocumentIt from the operating system prompt. The input file for processing must be a real-time file ( command:

% autostar {options}

Many of the options are the same as the fields in the documentation generation dialog. Refer to Appendix A, DocumentIt Options, for a complete list of DocumentIt options.

DocumentIt runs, creating a document file. When the operating system prompt returns, the process is complete.

Examples:

% autostar -h

shows a help display.

% autostar -doc -t FM.tpl

.rtf). At the operating system prompt, execute the

model_file

SysBld_file

Chapter 2 Invoking DocumentIt

.rtf

processes the model file

FM.tpl to produce a document file named

the template file

Note The DocumentIt real-time file (.rtf) input file is not the same as the rich text

format file (

.rtf) word processing output file. Only the file extension is the same.

FM.tpl exists in your working directory.

SysBld_file

Generate a Textual Version of a Model

One use of DocumentIt is to generate a textual version of a model. For example, the TPL sample file ( generates output similar to the text shown in Example 2-2, which documents the Arbitrate Throttle Control SuperBlock from the Supercruise demo model.

Example 2-1 Sample TPL File for Documenting a Block

@SEGMENT MAIN() INT i, j@@

@LOOPP i eq 0, i lt nsupblks_i, i=i plus 1@@

@SCOPE SUPERBLOCK i@@

superblock name: @sb_name_s@

superblock inputs: @num_sb_in_i@

superblock outputs: @num_sb_out_i@

.rtf using a template file named

SysBld_file

block_info.tpl) shown in Example 2-1

.doc. It assumes

+ 55 hidden pages

National Instruments 370769C-01 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

DocumentIt User Guide

Support

Worldwide Technical Support and Product Information

National Instruments Corporate Headquarters

Worldwide Offices

Important Information

Warranty

Copyright

Trademarks

Patents

WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS

Conventions

Contents

Manual Organization

DocumentIt and the Rapid Prototyping Concept

Figure 1-1. DocumentIt in the MATRIXx Product Line

Automatic Document Generation Process

Figure 1-2. DocumentIt Automatic Documentation Generation Process

Cruise Control Example

Figure 1-3. Cruise Control SystemBuild Diagram

Figure 1-4. SuperBlock Properties for Cruise Control Diagram

How to Access National Instruments-Supplied Files

Related Publications

How to Generate Design Documentation

Generating Documentation From Within SystemBuild

Platform Specific Differences

Template Information

Generating Documentation from Xmath

Generating Documentation from the OS

Generate a Textual Version of a Model