Imported from Google Code.
I used this script to generate blueprints when I worked as a technical documentation specialist at Geocell.
##Summary This is a Python library and script to convert UseCaseMaker 2.0 file to different formats via AsciiDoc.
Use Case Maker is an OpenSource program written on C#, that helps system developers to easily write Use Cases. The Use Cases may then be exported as reports, although their format is fixed and can't be customized. There is no chance to include the Use Cases generated in such way to other documents.
Goal of this project is to convert UseCaseMaker 2.0 file (which actually is an XML file) to AsciiDoc source. The latter then could be either directly compiled to many different presentation formats (docbook, html, htmlhelp, pdf, plaintext, dvi, PostScript, TeX, etc.) or become a part of more general documentation, written in AsciiDoc or DocBook.
##Script tool
The library contains a tool called ucm2asciidoc. It is a command-line
tool that performs file conversion:
ucm2asciidoc
Converts UseCaseMaker file to Use Cases
in different human-readable formats,
using AsciiDoc.
Usage:
ucm2asciidoc [options] usecasemaker_filename
Options:
-c, --title-char=TITLECHAR
Characters for titles. When only one character
specified, it is used to underline titles of Use Cases.
If more than one, the first is used to underline
title of document, the second - to underline titles
of the Use Cases.
Default: "=-"
-f, --format
Output format. Format can be:
* asciidoc -- AsciiDoc source
* docbook -- DocBook XML, generated by asciidoc tool
* html -- HTML, generated by asciidoc tool
* chunked -- chunked HTML (a2x)
* htmlhelp -- HtmlHelp files (a2x)
* manpage -- MAN page (a2x)
* pdf -- PDF file (a2x, dblatex)
* text -- plain text file (a2x)
* xhtml -- XHTML file (a2x)
* dvi -- DVI file (a2x, dblatex)
* ps -- PostScript file (a2x, dblatex)
* tex -- TeX file (a2x, dblatex).
-o, --output=FILENAME
Output file. By default - usecasemaker_filename with
appropriate extension
-v, --verbose
Verbosely print processing information
-t, --title
Title of AsciiDoc document. Used only in case when
--title-char consists of two characters.
Default: usecasemaker_filename without extension
Notes:
* To build a separate document default --title-char
must be used. This option is useful when
including Use Cases in another AsciiDoc file
as a section.
* When using --format other than asciidoc,
the AsciiDoc must be installed (asciidoc and a2x
executables must be available).
License:
Copyright (c) 2009, David Avsajanishvili
The tool is released under modified BSD license
See Also:
* UseCaseMaker: http://use-case-maker.sourceforge.net
* AsciiDoc: http://www.methods.co.nz/asciidoc/index.html
###Example
Let's see an example. Say, we have an example file called "SampleUseCase.ucm", consisting of two Use Cases (the sample could be downloaded here):
If we call ucm2asciidoc with filename parameter only,
an !AsciiDoc source will be generated:
ucm2asciidoc SampleUseCase.ucm
The output is written to SampleUseCase.asciidoc file:
// ''''''''''''''''''''''''''''''''''''''''''''''''''
// THIS FILE IS GENERATED AUTOMATICALLY - DON'T EDIT!
// ''''''''''''''''''''''''''''''''''''''''''''''''''
// Use Cases retrieved from UseCaseMaker
// XML file with help of ucm2asciidoc script.
// ''''''''''''''''''''''''''''''''''''''''''''''''''
SampleUseCase
=============
Perform login (UC1)
--------------------
// Description:
This action precedes any other activity between the "User" and the "System",
because the User must be authenticated and logged in to perform anything.
// Labeled list:
--
Pre-Conditions::
"User" is not yet logged in.
Post-Conditions::
- "User" is logged into the "System"
- Login event is written to the system log.
Trigger (External)::
"User" starts a work session with the "System"
--
// Notes:
[NOTE]
============================
* System administrator is responsible to give 'username' and 'password' for authentication;
* A secure connection with a server where the "System" is deployed must be established.
============================
// Step Flows:
[cols="3m,12",options="header"]
|==========================================================
|UC1 | Main success scenario
|1 |"User" opens GUI of the "System"
|2 |"System" checks whether "User" is already logged in, and finds that he isn't.
|3 |"System" displays ``Login'' page in the GUI.
|4 |"User" enters his 'username' and 'password' to appropriate fields.
|5 |"User" clicks ``Login'' button.
...
###Generating HTML
An HTML output could be generated by running the tool with
--format parameter and (optionally) specifying title of the
document:
ucm2asciidoc --format=html --title="Sample UseCase" SampleUseCase.ucm
To make this example working [http://www.methods.co.nz/asciidoc/ AsciiDoc] should be installed in the System. The result is:
###Generating PDF
To produce PDF and DVI outputs, LaTeX or MiKTeX (for Windows) have to be installed. Also, AsciiDoc requires dblatex to create TeX from DocBook. By running the command:
ucm2asciidoc --format=pdf --title="Sample UseCase" SampleUseCase.ucm
we get a PDF file, named "SampleUseCase.pdf":
##Installation
To install ucm2asciidoc tool:
- Download and install Python;
- Download ucm2asciidoc and install it;
- To produce HTML and DocBook output, AsciiDoc must be installed;
- To produce PDF, DVI and other formats under Linux, install LaTeX and dblatex;
- To produce PDF, DVI and others under Windows, you need to install MiKTeX, download dblatex and make it working.