Tool Mentor: Authoring Web Pages

The authoring environment for the Rational Unified Process is based on Microsoft® FrontPage®, and CorelDraw™. This "Authoring Web Pages" does not intend to replace the manuals for these tools, but to point out their specific use in the development of the Rational Unified Process online.

See also, Guideline: Rational Unified Process Style Guide. It contains a lot of useful information -- Read it!

See also, Tool Mentor: Modifying the Treebrowser, and Tool Mentor: Using the Rational Unified Process Tools.

Topics

• Getting Started
• Modifying the Process
• Review Contents and Language
• Publishing the Online Process
• Producing Manuals
• Converting from HTML to Microsoft Word
• Working in Microsoft Word
• Know Problems Using Microsoft FrontPage

Getting Started

Microsoft FrontPage Web-server

With the installation of Microsoft® FrontPage® you get a web-server. You will 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 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

• In Microsoft FrontPage, choose File->Open FrontPage web.
• In the dialog, click More Webs.
• In the following dialog, in the field "Select a Web server of disk location", either select your Microsoft FrontPage web-server or type the path to the working directory with your copy of the site.

  Example

  abbe:8080
  C:\Work\4.2\mywebcopy

• Click List Webs.
• If you have specified a folder outside the web-server, and Microsoft FrontPage doesn't recognize it as a Microsoft FrontPage web-site, you will be prompted with a question asking if you want to convert it to a web-site. Click Yes.
• Select the web site from the list, and click OK.
• Next time you open the site in Microsoft FrontPage, it will be listed in the first dialog box.

  My web copy didn't show up in the list!?

If your web-site didn't show up in the list of webs to choose from, then Microsoft® FrontPage® doesn't recognize it as a Microsoft FrontPage web-site. Then you import the web-site. The following procedure will place the site on your Microsoft FrontPage web-server.

• Place the folder of the site outside of your Microsoft FrontPage Webs folder.
• In Microsoft FrontPage Explorer, choose File->New->FrontPage Web.
• Select the radio button for Import an Existing Web. Give the site a title (and change the folder name if you want to). Click OK.
• Microsoft FrontPage creates a new site and invokes an import wizard to help you with the import.
• Select the radio button for importing From a source directory of files.
• Specify the folder where the site from which you are importing.
• Check the Include subfolders box.
• Click Next.
• Select files to exclude it you want to. The click Next.
• Click Finish.

Shared 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.

Zipping a Microsoft FrontPage Web

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 the Properties in you favorite file-browser.
• When you un-zip a site, select "All files", or else you may not get empty folders, which are relevant to the structure of the site.

How to zip a folder structure, with its files:

1. Open the winzip file.
2. Go to the folder that contains what you want to zip.
3. Select Actions>Add.
4. Make sure that file name is "*.*". Also click the checkbox "Include System and Hidden Files."
5. Click on "Add with Wildcards."

Now you have a zip file with a folder structure. When people unzip this they will get a folder structure, in which the files reside.

Modifying the Process

Version Management

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.

Change 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 straight-forward to use. For details on the editor, please refer to Microsoft® FrontPage's manual and help.

Create a New File

There are a number of templates defined for the Rational Unified Process:

• RUP About this Manual
• RUP Activity
• RUP Artifact
• RUP Manual chapter
• RUP Concept
• RUP Document Artifact
• RUP Guideline
• RUP Iteration Workflow
• RUP Report
• RUP Tool Mentor
• RUP Workflow Introduction
• RUP Workflow Detail
• RUP Worker

We recommend Tool Mentor authors to use Microsoft® Word and their material will subsequently be converted to HTML. (A Tool Mentor Microsoft Word template can be constructed based on rup_simple.dot.)

To create a new file using a template:

1. In FrontPage editor, select File->New...
2. Select the template you want and click OK.
3. If prompted where to store pictures, specify the images folder at the top level of the web-site.

The Rational Unified Process Templates are not Listed!?

If the Rational Unified Process templates don't show up in the list, then you haven't installed them yet. To install the templates:

1. Copy the folders inside the folder "templates/fp_tmpl/".
2. Paste these folders into the "pages" folder in your Microsoft FrontPage installation folder, for example
   C:/Program Files/Microsoft FrontPage/pages.
   The Rational Unified Process template folders should end with .tem and be at the same level as the other template folders.
3. In the Microsoft FrontPage editor, choose File->New.
4. From the list of templates, select the one you want. The Rational Unified Process templates are named "RUP xxx".

Create a New Template

Microsoft® FrontPage® allows you to create new templates in the File->Save As dialogue.

1. Create a page to be the new template.
2. Remove the theme from the template by selecting Format->Theme... in the Microsoft FrontPage Editor (not Microsoft FrontPage Explorer!). (A new page created from the template will apply the current web-site theme.)
3. Select File->Save As... and click As template. Give a title, filename, and description for the template.
4. 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 will get "cleaner" templates if the site that is currently opened 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.

Modify an Existing Template

When you do File->New... you get the list of existing templates and you can select one to base your new page on. You edit an existing template by creating a new page using the template, edit it, and then save it again as a template:

1. Choose File->New... and open the template you want to edit.
2. Edit the page.
3. Choose File->Save As...
4. Click As Template...
5. In the following dialog, click Browse. Choose your template from the list. Click OK.
6. If you want to change any of the template information, do so, and click OK. You will be asked to confirm overwriting the existing template.

Review Contents and Language

Language Review

• 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 of HTML. Microsoft® Word 7 can use Internet Assistant from www.microsoft.com.)
  See also the process described under Producing Manual.
• In the Revisions dialog (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.)

Contents Review

Publish the whole site where it can be accessed by the reviewers, or send zip-archives or CD's 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, together with a link to the page they concern.
• There is a comment facility in Microsoft® FrontPage® which 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 use the Revision tool.

Publishing the Online Process

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 sub-folders) 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 you want to remove all file that are not necessary. We recommend that you remove all folders named "_vti_cnf", and there contents.
• You can also use the Microsoft FrontPage publish command:

1. Start Microsoft FrontPage and open the working directory containing the FrontPage web.
2. In the menu File, select Publish FrontPage web....
3. 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 .

  To make the site read-only:

  > chmod -R ugo-w .

• Check capitalization of filenames and rename the files if they are incorrect. (Most filenames are lower-case letters, and that is a good file-naming strategy.)

Producing Manuals

Converting the HTML files

The following assumes Microsoft® Word 97.

• Download the rup.dot Microsoft® Word template file and place it in your Microsoft® Word template folder, if it's not already there. A suggestions is to create a separate folder for Rational Unified Process Word templates, for example named "RUP" in the Word's template folder (typically C:\Program Files\Microsoft Office\Templates) and place a copy of this template file, and others, there.
• Create a new document using the rup.dot Word template. This will be the master document for the manual.
• Edit the title of the manual on the first page.
• Remove the theme from the site.
• For each HTML file that goes into the manual, open it in Word and attach the rup.dot template (Tools menu, Templates and add-ins). Save it as a Word document.
• Go through the document and adjust formatting as needed. See HTML To Microsoft Word for detailed information. The Style Guide also describes how Paper Manual Styles were applied in 4.1, of which most still apply.
• In the master document, add the newly converted document. If you get problems with too many subdocuments, either combine subdocuments or merge subdocuments with the master document.
• When all subdocuments have been incorporated into the master document, go to the first page of the master document. From the Page setup dialog (File menu), set the correct margins, page size, and layout parameters. Make sure to select Whole document, but see specifically the settings for Layout below.

  Margins: Top 1", Bottom 1", Inside 1", Outside 0.75", Header 0.5", Footer 0.5", Mirror margins
  Paper Size: Custom size  Width: 7" Height 9", Portrait
  Paper Source: Default tray

  For the Layout tab, there is a caution: Generally, each section should begin on an Odd page, Odd and Even pages should be different, and the first page should be Different. However, for the last few sections (those of the Index) do not follow the general rule. You can do this in two ways:

  1. Set
     Layout: Section start Odd page, Headers and Footers: Different odd and even, Different first page, Vertical alignment: Top
     for the whole document, and edit the last sections to be:
     • after the Index heading: Continuous
     • after the index: New page
  2. Or, set individually for each chapter section as indicated above, leaving the index sections as they are in the template.
• Update the table of contents field in the master document.
• Save the master document.

See also Working with Microsoft Word.

Handling Pictures

• Go through the manual, and for each picture, locate the corresponding picture in CorelDraw™ and paste that one into the manual instead.
• See also about Pictures in the Style Guide.

Converting HTML to Microsoft Word

Things to do when reformatting an HTML document to a Microsoft® Word document Rational Unified Process style, assuming it has been formatted according to the Style Guide.

1. In FrontPage: Open the file, remove theme and shared borders. Save as a new HTML-file.
2. Open the new HTML file in Word
3. Save it as a Word-document.
4. Tools->Templates and Add-Ins, attach rup.dot, check the box to automatically update styles, and uncheck the HTML.VLL. (A suggestions is to create a separate folder for Rational Unified Process Word templates, for example named "RUP" in Word's template folder (typically C:\Program Files\Microsoft Office\Templates) and place a copy of this template file, and others, there.)
5. For the following structure and style elements do:

Working in Microsoft Word

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 reviewing purposes you can convert to Word, but be aware of the extra work if you want to take the file back to FrontPage. (It is probably easier to update the original file in FrontPage than to convert the Word-file once it is back from reviewing. See also in section Review Contents and Language.)

Regular Microsoft Word Documents

With a regular Microsoft® Word document, you will be able to use the Revision tool in Word.

• Use the Word template rup_simple.dot. A suggestions is to create a separate folder for Rational Unified Process Microsoft® Word templates, for example named "RUP" in Word's template folder (typically C:\Program Files\Microsoft Office\Templates) and place a copy of this template file, and others, there.
• For headings, use the styles H1 - H6. When converting your Word document to HTML, you will get correct HTML code. (Using styles Heading 1, etc. will be converted to layout information such as font face and size, rather than the structure information saying that it is a heading.)
• Other "safe" styles to use:
  • regular bulleted lists
  • regular numbered lists
  • tables
  • centered and right adjusted text (and left of course)
  • bold, italic, and underlined (although an orthodox HTML person would disagree)

Moving to Microsoft FrontPage

When you are ready to start working in Microsoft® FrontPage® please follow the following recommendations:.

• Save your Microsoft® Word-document as HTML in Word.
• Import your newly converted HTML-file into the FrontPage web-site where it is to reside.
• Open the file in the FrontPage Editor.
• Mark all and select (default font) for the entire page.
• While still all selected, open Format->Font and set the size to Normal.
• Check all pictures to make sure they look OK. Sometimes Word scales them and this corrupts the bitmap images. If that's the case, find the original GIF-file, or create a fresh GIF-file from the original picture.
• For picture texts, select them and choose Normal.picturetext from the style list. (This will tag the paragraph with the "class=picturetext" in the HTML code.) Do the same with table headings, definitions and alpha-lists. (See the Style Guide.)

These steps will be undone if you open the file in Word, and you have to redo them if you want to use FrontPage again.

Do NOT use Word's HTML Editing Capabilities

You can open any HTML document in Microsoft® Word, including the files you have created in Microsoft® FrontPage®. You will get different menus with specific HTML features. When you save your document, it will automatically be saved as in 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 is more than likely that you will lose some important information. For example:
  • Paragraphs "classified" in FrontPage, e.g., Normal.picturetext.
  • However, the link to the stylesheet is preserved.
• The styles in the style list in HTML mode are OK to use, because it will produce real HTML code, but it's not necessarily so that FrontPage will support you with all of them, i.e., 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. If you want to this function, see below on Regular Microsoft Word Documents.
• When sending HTML files to colleagues, remember to zip along the pictures.

Known Problems Using Microsoft FrontPage

Here are some of the problems found when using Microsoft® FrontPage®.

Topics:

• Plus and Minus Bullets
• Using Microsoft Word as an HTML Editor
  • Web Authoring Tools
  • Service Release 1
  • Sending out for Review
• Inserting Images

Plus and Minus Bullets

May 98

There are bullet lists for advantages and disadvantages with certain tailorings. In the stylesheet (rop.css) there are styles defined for these, "Bulleted List.minus" and "Bulleted List.plus". For some reason, Microsoft® FrontPage® Editor does not save this correctly; maybe because of interference with the theme. The styles are left in the stylesheet, should you want to use them with another editor, or for future upgrades of FrontPage, which might fix the problem.

Using Microsoft Word as an HTML Editor

Reported May 98

There have been reports on Microsoft® Word crashing when opening HTML files. First you should find out if You have any problems with Word. Do that by trying to open the following types of files. If you can open all four, using Word, you do not have to upgrade. If you can open all, except "theme_and_borders.htm" then you probably do not gain anything by upgrading.

a) a very simple HTML file.

b) with no shared borders, and no themes.

c) with no theme, but with shared borders.

d) with shared borders and themes.

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 is located at the following path on you machine:
"D:\Program Files\Microsoft Office\Office\WINWORD.EXE" (or "C:" of course).

1. Select it, and right-click "Properties".
2. Select the tab "Version"
3. 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, and if so and it still crashed, 2) upgrade Office with Service Release 1. See below for details on Web Authoring Tools and Service Release 1.

Web Authoring Tools

Here is how you could check to see if you have the Web Authoring Tools installed:

First, you need the Office CD, and put it into the PC.

1. Click on the Windows "Start" button. Select Start -> Settings -> Control Panel.
2. Double-click on Add/Remove Programs.
3. Select Microsoft Office Professional Edition. (that's on the Install/Uninstall tab).
4. Click on the button Add/Remove.
5. (wait for a while)
6. Click on Add/Remove.
7. Check that "Web Authoring Tools" are installed.
8. If they are not, install them.

Service Release 1

Microsoft has something called "Service Release 1" which is an upgrade of Office. You must download and install this. When you have done this you should be able to open HTML files.

To find the "Service Release 1", go to the homepage for Microsoft Office.

Sending out for Review

When you send out the stuff for review; to be sure that everyone else can read your HTML files, we recommend that you:

a) Make a copy of your material to send out for review.

b) Remove the theme, before you send it out. (In Microsoft® FrontPage® Explorer select View>Themes.)

c) To increase readability, you can also remove the "shared borders". (In FrontPage Explorer select Tools>Shared Borders, and deselect all borders.)

Both these operations, (b) and (c), are reversible (at least according to our experiments tells us so).

IMPORTANT: Then you must also inform your reviewers about the Service Release 1, and where to get it.

Inserting Images

Reported April 98

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 for where to save the image. FrontPage suggests a path, but often you want to change to another folder, for example a dedicated image folder. To save the image to the folder FrontPage suggests cause no problems, but 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 via the FrontPage Explorer.

First import the image to the folder in which you want it. Then insert the image using the Insert->Image... menu command.

First place the new page into the navigation view. (Rational Unified Process 5.1 does not use the navigation view.)