Toolkit:
Basic Authoring of Process Web Pages
The authoring environment for the Rational Unified Process
(RUP) is
based on Microsoft FrontPage®, and CorelDraw™. This Toolkit page does not intend
to replace the manuals for these tools, but to point out their specific use
in the development of Web sites based on the Rational
Project Web Template, and in modifying the RUP.
See Toolkit: Rational
Unified Process Styleguide. It contains a lot of useful information — please
read it!
See also Toolkit: Modifying the
Treebrowser and Toolkit: Preparing for Publication.
Overview
To author Web pages:
-
Getting Started
- Modifying the Web Site
- Reviewing Contents
and Language
- Publishing the Online
Process
- Working in Microsoft Word
- Known Problems
Using Microsoft Office® 97
Microsoft FrontPage Web-server
With the installation of Microsoft FrontPage, you get a Web-server. You'll be
asked to give a location for this server. Web sites located to the server area
can be reached via the server.
Example
In a Web browser, you will type something like:
http://mywebserver/mywebsite
Other computers in the network can also browse Webs on your server.
Working with a Private Copy of the Site (no version management)
- Place your copy in the root folder of your Microsoft FrontPage Web-server
or in a working directory of your choice.
Example
C:\Webs\FrontPage Webs\Content\mycopy
C:\Work\4.2\mywebcopy
Sharing a Site
It is, of course, possible to place the site on a file server in a network
and allow several people access it, but without the safety of a version control
system. The procedure is the same as above.
Two things regarding zip-files:
- When you zip up a site, make sure that all folders "_vti_xxx"
are included. Sometimes this requires that you unmark the folders as
invisible (making them visible) via Properties in you favorite
file-browser.
- When you unzip a site, select "All files" or you may not get
empty folders, which are relevant to the structure of the site.
To zip a folder structure with its files, follow these steps:
- Open the winzip file.
- Go to the folder that contains what you want to zip.
- Select Actions>Add.
- Make sure that file name is "*.*". Also click the checkbox Include
System and Hidden Files.
- Click on Add with Wildcards.
Now you have a zip file with a folder structure. When people unzip this,
they'll get a folder structure in which the files reside.
Managing the Version
Operations that change the shared borders or the theme will cause a lot, if
not all, of the files to be updated. This means that all such operations must be
done by one person, with all files checked in by the rest of the group.
Changing an Existing File
To change an existing file, simply open it from the Microsoft FrontPage
Explorer by double-clicking the file. Microsoft FrontPage Editor will display
the file. The editor is fairly straightforward to use. For details on the
editor, please refer to Microsoft FrontPage's manual and online help.
Modifying Pictures
To change an existing picture, we recommend you use CorelDraw because most
pictures in the RUP are developed using CorelDraw. The
pictures can be downloaded, in CorelDraw format, from the RUP Resource Center.
There are a number of templates defined for the RUP:
- Activity
- Artifact
- Concept
- Guideline
- Report
- Tool Mentor
- Discipline Introduction
- Workflow Detail
- Role
Templates are not currently available for the Rational Project Web Example.
We recommend tool mentor authors use Microsoft FrontPage.
To create a new file using a template:
- In Page mode, select File->New->Page.
- Select the template you want and click OK.
- If prompted where to store pictures, specify the images folder at the top
level of the Web site.
 The RUP Templates are not
Listed!?
If the RUP templates don't show up in the list, then you
haven't installed them yet. To install the templates, following the instruction
in Installing FrontPage Templates.
Creating a New Template
Microsoft FrontPage allows you to create new templates in the File->Save
As dialogue.
- Create a page to be the new template.
- Remove the theme from the template by selecting Format->Theme... (A
new page created from the template will apply the current Web site theme.)
- Select File->Save As... and click As FrontPage template
(*.tem). Give a title, filename, and description for the template. Then
select Save Template in Current Web.
- Click OK. The template will be automatically saved to the pages
folder in the Microsoft FrontPage installation folder.
Tips: Create an empty Web for template creation. The templates are not
site-specific and you'll get "cleaner" templates if the currently
opened site does not have a theme or any specific shared borders. In the
HTML-code, you should have the following lines for theme and border
respectively:
<meta name="Microsoft Theme" content="none,
default">
<meta name="Microsoft Border" content="bl, default">
The "bl" for border stands for "bottom" and
"left". If that has changed since this was written, you can adjust
accordingly, using letters "t" for "top" and "r"
for "right".
This should ensure that the new pages take on the site's default settings for
theme and borders. If this doesn't happen automatically, simply set theme from
the Format menu and shared borders from the Tools menu.
Modifying an Existing Template
When you select File->New... you get the list of existing templates
and you can select one to base your new page on. Edit an existing template by
creating a new page using the template, modify it, and then save it again as a
template:
- Choose File->New... and open the template you want to edit.
- Modify the page.
- Choose File->Save As...
- Click As Template...
- In the following dialog, click Browse. Choose your template from
the list. Click OK.
- If you want to change any of the template information, do so, and click OK.
You'll be asked to confirm overwriting the existing template.
Reviewing Language
- If your language reviewer has HTML authoring installed with Microsoft
Word, you can send HTML files to them and they can convert them to Word. If
not, create Word versions of the documentation by opening the HTML files in
Word, and then saving them as Word files. Optionally, combine files into
longer documents. (Microsoft Word97 supports importing HTML. Microsoft Word
7 can use Internet Assistant from www.microsoft.com.)
- In the Revisions dialog of the Tools menu, set Mark while
editing and lock the document to make sure edits are recorded.
- Send documentation to language reviewer.
- When the edited documentation returns, it's easy to find changes using the
merge revisions or by printing the document with the change marks visible.
- Correct the HTML source manually.
Do not use Microsoft Word97 for converting to HTML because the generated HTML
code is of poor quality and very different from the HTML you get when you author
documents in Microsoft FrontPage. (Word puts in lots of formatting tags and
loses the structure of the document.)
Reviewing Contents
Publish the whole site where it can be accessed by the reviewers, or send
zip-archives or CDs with the site. There are a few different ways that comments
on contents can be submitted.
- They can be marked on hard copies printed from the Web.
- You can use bookmarks in Netscape Navigator and send in the bookmark file.
Navigator allows you to comment your bookmarks, and these comments will show
up if you display the bookmark file in the browser along with a link to the
page they concern.
- There is a comment facility in Microsoft FrontPage that shows the comments
in the Normal view of the editor, but they do not show up in the Preview
view or in a Web browser.
- They can convert to Microsoft Word files using Word's HTML authoring
capabilities and the Revision tool.
Publishing the entire Microsoft FrontPage Web can be done in several ways:
- If you want to publish it with all the Microsoft FrontPage files, copy the
whole Microsoft FrontPage Web (the top-level folder and subfolders) to a new
location. If you zip the files, see Section: Zip files
for more details.
- If you want to publish it using as little memory as possible, then remove
all files that are not necessary. We recommend that you remove all folders
named "_vti_cnf" and their contents.
- You can also use the Microsoft FrontPage publish command, as follows:
- Start Microsoft FrontPage and open the working directory containing the
FrontPage Web.
- From the File menu, select Publish Web....
- Set the path to wherever you want to publish the online process.
Publishing on UNIX
When you have published the site on a UNIX server:
- Check file permissions.
In the top folder, the following command will give read permission to
everybody for the whole site.
> chmod -R ugo+r
Then make sure the site read-only by removing the write permission:
> chmod -R ugo-w
- Check the capitalization of filenames and rename those files that are
incorrect. Most filenames are lowercase letters and that is a good
file-naming strategy.
When it is more convenient to author text in Microsoft Word, here are some
guidelines.
- Use Word for white papers and first drafts. Once you have moved your
document to Microsoft FrontPage, you do not want to go round-tripping via
Word.
- For review purposes, you can convert to Word, but be aware of the extra
work if you want to take the file back to FrontPage. It's probably easier to
update the original file in FrontPage than it is to convert the Word file
once it's back from being reviewed. See the section titled Review
Contents and Language.
Do NOT use Word's HTML Editing Capabilities
You can open any HTML document in Microsoft Word, including the files you've
created in Microsoft FrontPage. You'll get different menus with specific HTML
features. When you save your document, it will automatically be saved as HTML.
The same happens if you choose a Web document template using File->New
to create a new document. The HTML document can subsequently be opened in
FrontPage.
Important things you want to know!!!
- Word will write over the original HTML, and it's more than likely that
you'll lose some important information. For example:
- Paragraphs "classified" in FrontPage, such as
Normal.picturetext.
- The link to the style sheet, however, is preserved.
- The styles in the style list in HTML mode are okay to use because they'll
produce real HTML code, but FrontPage may not necessarily support all
of them; that is, you may have to edit HTML code in FrontPage if you want to
use, for example, "blockquote".
- You cannot use the Revision tool in HTML mode.
- When sending HTML files to colleagues, remember to zip the pictures along
with the files.
Here are some of the problems found when using Microsoft Office 97.
Topics:
There have been reports of Microsoft Word crashing when opening HTML files.
Find out if you have any problems with Word by trying to open the following
types of files.
- a very simple HTML file
- with no shared borders, and no themes
- with no theme, but with shared borders
- with shared borders and themes
If you can open all four of them using Word, you do not have to upgrade. If
you can open all except "theme_and_borders.htm", then you probably
won't gain anything by upgrading.
Make sure you have the latest version of Word. To find out about the version,
you must locate the WinWord.exe file. In most cases, it's located at the
following path on you machine:
"D:\Program Files\Microsoft Office\Office\WINWORD.EXE" (or perhaps on
C: drive).
- Select it, and right-click Properties.
- Select the tab Version.
- Now you can see the version number close to the top of the window. In the
frame further down there is also a entry called "Version".
If you have problems with the above, there are two things to do: 1) make sure
you have Web Authoring Tools installed. If so and it still crashes, 2) upgrade
Microsoft Office with Service Release 1. See the following two sections for
details on Web Authoring Tools and Service Release 1.
Here is how you could check to see if you have the Web Authoring Tools
installed:
First, insert the Microsoft Office CD into the appropriate drive on your
computer.
- Click the Windows Start button. Select Start -> Settings
-> Control Panel.
- Double-click Add/Remove Programs.
- Select Microsoft Office Professional Edition from the Install/Uninstall
tab.
- Click Add/Remove.
- Wait for awhile.
- Click Add/Remove.
- Check that "Web Authoring Tools" are installed.
- If they aren't, install them.
Microsoft has something called "Service Release 1", which is an
upgrade to its Office program. You must download and install this. When you've
done so, you should be able to open HTML files.
To find the "Service Release 1", go to the homepage for Microsoft
Office.
When you send out your Web information for review, be sure that everyone else
can read your HTML files. We recommend you complete these steps:
- Make a copy of the material you are sending out for review.
- Remove the theme before you send it out. (In Microsoft FrontPage Explorer,
select Format>Theme.)
- To increase readability, you can also remove the "shared
borders". (In FrontPage Explorer, select Add/Remove and deselect
all borders.)
Both steps 2 and 3 are reversible (at least according to our experiments).
IMPORTANT: You must also inform your reviewers about the Service Release 1
and where to get it.
If you create a new page in Microsoft FrontPage Editor and insert an image in
it (insert clipart or copy from another FrontPage page), and then save the page,
FrontPage will prompt you about where to save the image. FrontPage suggests a
path, but often you'll want to change to another folder; for example, a
dedicated image folder. To save the image to the folder that FrontPage suggests
cause no problems, however, if you change it, FrontPage protests and says that
the Web, to which the page belongs, is not opened. Here are some ways to work
around the problem:
- Save the image to the suggested folder, and then move it using FrontPage
Explorer.
- Import the image to the folder in which you want it, and then insert the
image using the Insert->Image... menu command.
- Place the new page into the navigation view. (Please note: the RUP does not use the navigation view.)
Copyright
© 1987 - 2001 Rational Software Corporation
| 
Process Engineer Toolkit >
Basic Authoring of Process Web Pages
