ATCSDoc How To

This Help File describes how to perform some basic build and maintenance and upgrade operations on the atcsdoc module.

Currently a number of operations have to be performed by hand. In the future they will be integrated in the src/Makefile and will be hopefully standardized when the final Development Process and tools will be defined.

How to:

Check Web Consistency
Generate diagrams from Rose model
Generate filtered files for DD and SRS documentation
Print standard Postscript (PS II) files under Windows
Survive MS-Word
Update printable documents
View MS-Word Postscript files with Ghostview
Web Publishing with Rose 2000
Prepare for CMM Archive
Restore from CMM Archive
Add a new Use Case
Add a new Package
Add Change Bars and produce Electronic Archive Document
Add drive independent links in Rose

Check Web Consistency

The Web consistency checking is performed using the MomSpider tool.

To run it:

Log in as atcsmgr on te13 (or any VLT UNIX machine)
atcs@te13:~ [41]-> momspider

The results are put in the ~atcsmgr/ATS/atcsdoc directory.

The tool has been installed in the atcsmgr local directory and proper configuration files are in ~atcsmgr/:

.momspider-avoid

.momspider-instruct

.momspider-sites

It has been necessary to hack the tool to allow it to work locally, without a web server running.

Look in particular for the "Broken links" section.

__oOo__

Generate diagrams in EMF and GIF from Rose model

All the diagrams included in the Requirements and Design documents are extracted from Use Cases and Logical views of the Rose model using the ATA docExpress tool (a license is installed on PC10064, G.Chiozzi). Freeware limited versions are installed on PC10065 (R.Karban) and PC10067 (P.Duhoux).

This tool generates two files per diagrams in format GIF and EMF. All diagrams are imported in an HTML document that serves as entry from a WWW navigator.

Note: All paths are given relative to the home directory of the module atcsdoc.

Using the licenced product Reporter PRO, perform the following steps:

Open the model (atcsdoc\Model\Rose\atcs.mdl) in Rational Rose under Windows
Select the menu: Report -> Document with DocExpress…
In the report panel, select:

Report Format is HTML

Report Type Name is Diagrams by view and type

In the reports [HTML] panel, select:

View is Use Case View
Set the output file name to X:\ATS\atcsdoc\Model\Rose\doc\<modelName>_uc;.html
Finish

Three (3) more reports have to be generated with 3 different file names

View is Logical View, file name is <modelName>_lv;.html
Note: The logical view is very big, and we got very often Rose crasching. To avoid this:

Use the very latest version of Rose.
Generate the lv from a freshly rebooted PC
Do no keep the web browser open when generating and do not open it when requested by doc express at the end of the generation

View is Deployment View, file name is <modelName>_dv;.html
View is Component View, file name is <modelName>_cv;.html

Generate the final image files for the online and for the printable documentation:

atcs@te13:~ [41]-> cd ~atcsmgr/ATS/atcsdoc/src
(or where the module is)

atcs@te13:~ [42]-> make diagrams
(this assumes that the binary tools have been already built with make all)

Using the freeware product Reporter LITE 1.4.1, only steps 3 and 4 differ:

In the welcome panel, click on "Continue…" and in the report panel, select:

Report Format is HTML

Report Type is Pre-Defined Reports

In the pre-defined reports [HTML] panel, select:

Report Type Name is Use Case View

Set the output file name to X:\ATS\atcsdoc\Model\Rose\doc\<modelName>_uc.html
Finish
Report Type Name is Logical View

Set the output file name to X:\ATS\atcsdoc\Model\Rose\doc\<modelName>_lv.html
Finish
Report Type Name is Component View

Set the output file name to X:\ATS\atcsdoc\Model\Rose\doc\<modelName>_cv.html
Finish
Report Type Name is Deployment View

Set the output file name to X:\ATS\atcsdoc\Model\Rose\doc\<modelName>_dv.html
Finish

Proceed with step 5 as described above

Pay attention to the "\", that must be used on the PC for pathnames, while "/" must be used in UNIX.

Outputs

docExpress generates the following files:

<modelName>.html: Full html view.

<modelName>_FV.html: Full html view using frames for TOC, LOF and LOT.

<modelName>_TOC.html: Table of content

<modelName>_LOF.html: List of Figures

<modelName>_LOT.html: List of Tables

tmp_<mmddhhmnssn>.EMF: Diagram in EMF format and
tmp_<mmddhhmnssn>.gif: Diagram in GIF format
where <mmddhhmnssn> indicates the generation date (month, day, hour, minute, second) followed by a current index.

Extraction for online documentation

The Makefile calls the tool atcsdocXP2IMG (located under bin).

It is an automatic procedure that parses the file Model/Rose/doc/<modelName>.html and renames the image files tmp_*.EMF and tmp_*.gif to their assigned named into the Images directories of Model/UseCases and Model/Packages respectively. (The file extension of the .EMF files is set to .emf).

The Deployment View diagram is copied to Model/Packages/Images/deployment.<format>).

The Class Hierarchy is copied to Model/Packages/Images/classHierarchy.<format>).

The lookup tables are maintained inside the script source and are the consistency links between the model and the documentation.

The Use Case diagrams for both UseCase and Logical views are named as the package/sub-system prefix; the Class diagrams names are built using the <prefix>_class.<format> naming convention.

__oOo__

Generate filtered files for DD and SRS documentation

Printable documents can include only information relevant at requirements level or also all available information, added at design time or after design.

Specific DD and SRS files are generated from the online documentation and put in the ./object/DD and ./object/SRS directories.

This is done by the UNIX Makefile using the atcsdocHTML2DD and atcsdocHTML2SRS tools.

atcs@te13:~ [41]-> cd ~atcsmgr/ATS/atcsdoc/src
(or where the module is)

atcs@te13:~ [42]-> make filter
(this assumes that the binary tools have been already built with make all)

__oOo__

Print standard Postscript (PS II) files under Windows

Install the standard Windows:

Apple Laser Writer II NT driver and print to file.

To name a file "xxxx.ps" it is necessary to put the filename in quotes ("), otherwise Windows will add a ".prt" extension automatically.

__oOo__

Survive MS-Word

Microsoft Word has many bugs and nuances, but with some tricks it is possible to survive (we are using MS-Word 97 SR2):

To avoid crashes and corrupted documents when updating documents with many external links:

In the Tools->Option->Save panel, toggle OFF "Allow Fast Save" and "Allow Background Save" options
To update all links, always take the Edit->Links panel, select the links you want (also all) and update. DO NOT update many links directly from the editable area.

If document have links to HTML files, open and edit only one at the time. Word has just one search path for included files and gets confused if you have more documents open. It is better to open document from the File->Open menu. If you cannot find some imported files, close every document and reopen only the one you want from the File->Open menu.
Always update the TOC of a document just before printing. Go to the TOC and press F9. Otherwise it is very common to get "ERROR: Bookmark not found"

__oOo__

Update printable documents

To update the printable document, once all files have been generated one should in principle just:

Open the document (strictly from the Open menu of Worg and not with drag and drop)
Select all
Press F9 to update the links

Unfortunately the SRS and DD documents are big and contains too many links for what Word97 (SR2b) can handle.

Actually in most of the cases word corrupts the document when trying this procedure. There are two different effect:

Sometimes the message "not enough memory to update the display" appears and the document is corrupted
Sometimes everything seems OK, but when one reopens the document after saving it, Word reports that the document is corrupted.

The procedure to get through is lengthy but works and consists in updating few links at the time:

Open the document
Select the menu Edit-Links
Select some 20-30 links, marking the first one, going to the last one and marking it pressing shift at the same time
Click "Update Now"
Close the Links dialog box
Save and Close the file
Open it again
If the file opens properly, make a backup copy, for example selecting the file with explorer and making Ctrl-C Ctrl-V, then go back to step 2 to process another 20 links
If the file does not open properly, take a backup copy and repeat selecting fewer links.

__oOo__

View MS-Word Postscript files with Ghostview

Sometimes when opening with Ghostview Poscript files generate in Windows, in particular with MS-Word, there are problems (errores are reported, only only a limited number of pages is accessible).

In order to view Postscript files generated by MS-Word, it is typically necessary to check in Ghostview the menu:

Options -> Ignore DSC

Web Publishing with Rose 2000

For proper use of the Rose Web Publisher follow these steps:

delete X:\ATS\atcsdoc\Model\Rose\Html\*
Open the model with Rose and load ALL sub-units
Select Tools-Web Publisher
Select as Level of Detail: Intermediate.
Select as Root File Name: X:\ATS\atcsdoc\Model\Rose\Html\atcsrose.htm
Press Publish and Wait...
Open a Unix shell as atcsmgr
cd to atcsdoc/src and execute:

make web (NEVER run more than once after published by Rose)

All loose ends in the model are linked to a a file containing some information about the loose end. Since there might be several thousands of them, we remove them and replace them by one single file. The web publish tool produces links that have the Windows path in it. We don't require those in our case. Several paths produced by the tool are consolidated.

transfer to web-server
update Search indices of Web Server

Login to Sambar Server as Administrator
Goto Search administration
Select atcsdoc index
Hit "Site Index" button

Prepare for CMM Archive

Before archiving the module atcsdoc under CMM, it is mandatory to prepare this repository as follows:

atcs@te13:~ [41]-> cd ~atcsmgr/ATS/atcsdoc/src
(or where the module is)

atcs@te13:~ [42]-> make archive

The module is now ready for being archived under CMM.

Note: The internal directory structure has been modified:

none of the paths to the following directories is accessible:

atcsdoc/ArchiveDocuments

atcsdoc/MilestoneReleases

atcsdoc/Model/Rose

atcsdoc/Model/Notes

atcsdoc/Plan

The Rose Web Publisher repository atcsdoc/Model/Rose/Html has been removed.

Restore from CMM Archive

After having checkout the module atcsdoc from the CMM Archive, it is mandatory to restore this repository as follows:

atcs@te13:~ [41]-> cd ~atcsmgr/ATS/atcsdoc/src
(or where the module is)

atcs@te13:~ [42]-> make expand

The module is now ready for being updated.

Note: The Rose Web Publisher repository atcsdoc/Model/Rose/Html has not been restored.
See Web Publishing with Rose 2000 for the procedure.

Add new Use Case

add Use Case HTML files
add Use Case HTML file to Index files (*TOC_*.htm, *IndexIp_*.htm)
add Use Case to Rose Model
link Use Case HTML to Rose Use Case bubble
add Use Case Diagram of Use Case view to Rose/diagramList_uc.tcl table
Generate diagrams from Rose model
Generate filtered files for DD and SRS documentation
include Use Case "object/DD, object/SRS" HTML file in MS word document

Add new Package

add Package HTML file
add Package HTML file to Architecture.html
add new Package in Logical View to Rose Model
add Use Case Diagram in Logical View Package to Rose Model
link Use Case/Package HTML to Rose Use Case/Package bubbles
add Package HTML file to Index files (*TOC_DD.htm, *IndexIp_DD.htm)
add Use Case Diagram of Logical view to Rose/diagramList_lv.tcl table
Generate diagrams from Rose model
Generate filtered files for DD and SRS documentation
include Package "object/DD" HTML file in MS word document

Add Change Bars and produce Electronic Archive Document

Open atcsdoc\ArchiveDocuments\VLT-XXX\Document.doc
Edit-Links
Select all links
break links
select all remaining links (only graphics)
tick "Save picture in document"
"Update Now"
Close dialog
File-Save As "DocumentNL.doc"
Tools-Track Changes-Compare Documents
Select "atcsdoc\Docs\VLT-XXX\"previous version".doc
Ignore Warnings "...longer than 750..."
Tools-Track Changes-Higlight Changes
tick "Hilight..."
goto Options...
Inserted text "Mark none", Deleted text "Mark Hidden", Changed formatting "Marked none", Changed lines "Mark outside border"
File-Save As-atcsdoc\ArchiveDocuments\VLT-XXX\DocumentDiff1-2.doc
remove manually in tables added(empty) rows (added by diff)
remove in header added(empty) rows (added by diff)
update TOC

Add drive independent links in Rose

Open Rational Rose w/o model
Select File-Edit Path Map
Enter in "Symbol" field _ROOT (e.g. ATCS_ROOT)
Enter in "Actual Path" the path of the documentation module (e.g. X:\ATS\atcsdoc)
Click "Add"
Whenever you link from the Rose Model to an external file that matches the defined path of the variable, the actual path is replaced with the variable.
If the model is loaded on a different machine where the variable is defined, the variable is replaced with the actual path.

__oOo__


Send comments to `<Gianluca Chiozzi gchiozzi@eso.org>` Last modified: Fri Jul 13 09:58:19 METDST 2001 This is version: "@(#) $Id: HowTo.html,v 1.19+ 2000/07/11 15:35:49 vltsccm Exp $"