LotusScript.doc - User Manual

User Manual

This page describes how to use the LotusScript.doc application, how to configure your Domino installation and the various requirements of which there are very few.

To get started right away jump to the QuickStart-section. This section assumes you know how to load and configure tasks on a Domino server as well as how to sign and deploy databases.

Table of contents

QuickStart
This section describes how to get started quickly using the LotusScript.doc application.

This consists of the following steps:

Download LotusScript.doc, extract the lsdoc.nsf database from the ZIP-file and copy the database to a Domino server or local Notes client (there is no requirements as to where to place the database).
Sign the database or simply trust me... :-)
(optional) Adjust the ACL (see the ACL-section for more information on this).
Create a "Simple Configuration Document" for an existing database.
Build LotusScript.doc documentation based on the created configuration document.
Open the LotusScript.doc database in a web-browser to browse the documentation.

You might want to refer to the below sections for more information on various topics.

Requirements
LotusScript.doc has the following requirements:

Lotus Notes 6.0.x/6.5.x client if you need to generate documentation locally.
Lotus Notes 5.0.x client if all you need is to configure LotusScript.doc for generating documentation on the server.
Lotus Notes Designer 5.0.x/6.0.x/6.5.x client if you would like to browse documentation locally using the Web Previewer Process.
Lotus Domino 6.0.x/6.5.x server if you would like to generate the documentation on the server.
Lotus Domino 5.0.x/6.0.x/6.5.x server with the HTTP task loaded to share the documentation with colleagues.

Create a LotusScript.doc configuration document
Each database you would like to generate documentation for should have its own configuration document in the database. To create a new configuration document go to the "Create"-menu and select the "1. LotusScript.doc Configuration".

Fill in the description, the database server and the database path fields - leave the server field blank for a local database. Once you have completed these three fields press the F9 key to update the form.

Updating the form will display a number of additional fields allowing you to control which design elements are actually documented. You can control whether to document all design elements, some design elements or none of the design elements of a particular type. Repeat the decision process for forms, views, agents, script libraries and the database script. The default is to document all design elements of all types.

Scrolling further down will allow you to set some parameters further controlling what is actually documented.

Generate documentation manually
There are two options for generating the documentation for a configuration document manually - one is in the foreground and the other is using a background thread.

To perform the generation in the foreground use the "Build LotusScript.doc"-action in the main view. This agent will run on the selected configuration document and block the client until done.

The second option is to use the "LotusScript.doc\Build LotusScript.doc in background thread"-action from the Actions-menu. This will build the documentation for the selected configuration document in a background thread and will hence not lock the client. This is useful when generating documentation for large databases and you would like to continue working in your Notes client.

Please note: You may select more than one configuration document to process at a time.

Generate documentation on a schedule
Documentation can be (re)built on a scheduled basis using a scheduled agent. The agent is called "SCHEDULED - Build LotusScript.doc" and can be enabled and scheduled using the Domino Designer client as you normally would any agent.

Please note that only the configuration documents enabled for the background agent will be included when the agent runs.

Styling the documentation
The documentation is styled using CSS (Cascading Style Sheet). To learn more about CSS please visit the W3C.

The stylesheet can be found in a document called "stylesheet.css" in the "Excluded HTML"-view. The stylesheet, which is originally from the Hibernate project, can be edited using the Notes client. Feel free to change the stylesheet any way you like.

Browsing documentation

Please note: To browse the generated documentation locally you need to use the Web Preview process and hence have the Domino Designer client installed. You will also need to start the Web Preview process before using the "Preview in Web Browser"-action.

To browse a documentation set on the server simply select the configuration document in the Notes database and click the "Preview in Web Browser" action button.

This assumes that you have configured the database if the server is not on a Notes client.

Configuring the database
The database has a profile document with some configuration information such as the hostname of the server to use for previewing documentation etc.

To access the profile document use the "Database Setup"-action in the main view.

Please note: To edit the profile document you will need to have the [DBAdmin]-role in the ACL.

Configuring Domino
Bascially LotusScript.doc doesn't require any special configuration on the Domino server apart from having the HTTP task loaded. You might want to create a virtual host on your Domino server such as http://lsdoc.example.com to make it easier to access documentation.

ACL

Roles
The database has a single role called [DBAdmin]. This role should be assigned to users that need to configure the database profile.

Access levels
Users creating and maintaining configuration documents should have Editor access.

Users that simply need to browse documentation could suffice with Reader access.

Tips and Hints

Inserting comment template using SmartIcon
Tip submitted by Harald Osmann.

(replay animation)

To ease the process of creating a new comment you can use a SmartIcon that when pressed will insert a blank comment at the current cursor position. The SmartIcon will insert the following comment (the username will of cause be that of the active Notes user):

'/**
' * 
' * @param 
' * @return 
' * @author Mikkel Heisterberg
' */

Use the following code for the SmartIcon (but feel free to tweek it any way you like) - the code contains two lines:
Apo := @Char(39);
@Command([Execute]; "cmd"; " /c @echo set W = WScript.CreateObject(\"WScript.Shell\") > t.vbs & @echo W.AppActivate \"Designer\" >> t.vbs & @echo W.SendKeys \""+ Apo +"/**{ENTER}" + Apo +" * {ENTER}" + Apo +" * @param{ENTER}" + Apo +" * @return{ENTER}" + Apo +" * @author {ENTER}" + Apo + " */\" >> t.vbs & cscript t.vbs")

The icon for the SmartIcon can of cause be anything but I have created two images you can use. The easist is to right-click the image you want and save it to the disk and add the image as an Image Resource in your bookmark.nsf file. This will make it selectable when creating the SmartIcon.

The below SmartIcon code will insert the code for the lsdoc_description() method:
@Command([Execute]; "cmd"; " /c @echo set W = WScript.CreateObject(\"WScript.Shell\") > t.vbs & @echo W.AppActivate \"Designer\" >> t.vbs & @echo W.SendKeys \"Private Sub lsdoc_description{(}{)}{ENTER}{%}REM{ENTER}\" >> t.vbs & cscript t.vbs")

Private Sub lsdoc_description()
%REM

%END REM
End Sub