options parameter
+ can be used to specify arbitrary extra parameters.
+
+ @param options A list of extra options to pass to convert
+ @param output_format The output format to use
+ @param input_file The full path to the input file
+ @param output_file The full path to the output file
+} {
+ set args [list]
+ foreach option $options {
+ lappend args $option
+ }
+ if ![empty_string_p $output_format] {
+ set output_file "${output_format}:${output_file}"
+ }
+ if ![empty_string_p $geometry] {
+ lappend args {-geometry} $geometry
+ }
+ lappend args $input_file
+ lappend args $output_file
+ eval "exec [convert_path] [join $args]"
+}
+
+ad_proc -public ::ImageMagick::tmp_dir {
+} {
+ Returns the ImageMagick temporary directory (with trailing slash).
+} {
+ set tmp_dir [parameter::get_from_package_key \
+ -package_key image-magick -parameter TmpDir]
+ if { ![regexp {/$} $tmp_dir] } { append tmp_dir / }
+ return $tmp_dir
+}
+
+ad_proc -public ::ImageMagick::tmp_file {
+} {
+ Creates a new temporary file name.
+ @return The full path to the temporary file location.
+} {
+ return "[tmp_dir][ns_mktemp imXXXXXX]"
+}
+
+ad_proc -public ::ImageMagick::delete_tmp_file {
+ filename
+} {
+ Tests the path is valid and deletes the file.
+} {
+ set filename [expand_tmp_file $filename]
+ if {![validate_tmp_file $filename]} {
+ error "$filename is not an ImageMagick tmp file"
+ }
+ file delete $filename
+}
+
+ad_proc -private ::ImageMagick::shorten_tmp_file {
+ filename
+} {
+} {
+ set exp "^[tmp_dir](im\[0-9A-Za-z\]{6})$"
+ regexp $exp $filename match filename
+ return $filename
+}
+
+ad_proc -private ::ImageMagick::expand_tmp_file {
+ filename
+} {
+ Returns the full path to the temporary file. If the filename passed is
+ is just the filename (without full path), the temporary directory is
+ prepended. If its already the full path, its just returned. No validation
+ is performed.
+} {
+ if { ![regexp {^/} $filename] } {
+ set filename "[tmp_dir]${filename}"
+ }
+ return $filename
+}
+
+ad_proc -private ::ImageMagick::validate_tmp_file {
+ filename
+} {
+ Checks the given filename is a geniune temporary file.
+} {
+ set filename [expand_tmp_file $filename]
+ set exp "^[tmp_dir]im\[0-9A-Za-z\]{6}$"
+ return [regexp $exp $filename]
+}
+
+ad_proc -public ::ImageMagick::serve_tmp_file {
+ filename
+} {
+ Serves the given file, having first validated that it is a genuine tmp
+ file (and not, say, /etc/passwd). The filename passed in can be either
+ the full path to the file, or just the filename in the ImageMagick
+ temporary directory.
+} {
+ set filename [expand_tmp_file $filename]
+ if { ![validate_tmp_file $filename] } {
+ ad_return_complaint 1 {Identifies attributes of the file specified. This currently supports + the following attributes:
+By You
+ + + +NOTE: Some of the sections of this template +may not apply to your package, e.g. there may be no user-visible UI +elements for a component of the OpenACS Core. Furthermore, it may be +easier in some circumstances to join certain sections together, +e.g. it may make sense to discuss the data model and transactions API +together instead of putting them in separate sections. And on +occasion, you may find it easier to structure the design discussion by +the structure used in the requirements document. As this template is +just a starting point, use your own judgment, consult with peers when +possible, and adapt intelligently.
+ +Also, bear in mind the audience for detailed +design: fellow programmers who want to maintain/extend the software, +AND parties interested in evaluating software quality.
+When applicable, each of the following items +should receive its own link:
+ +User directory
OpenACS administrator directory
Subsite administrator directory
Tcl script directory (link to the API browser page for the package)
PL/SQL file (link to the API browser page for the package)
Data model
Requirements document
ER diagram
Transaction flow diagram
This section should provide an overview of +the package and address at least the following issues:
+ +What this package is intended to allow the user (or different + classes of users) to accomplish.
Within reasonable bounds, what this package is not intended + to allow users to accomplish.
The application domains where this package is most likely to + be of use.
A high-level overview of how the package meets its + requirements (which should have been documented elsewhere). This is + to include relevant material from the "features" section + of the cover sheet (the cover sheet is a wrapper doc with links to + all other package docs).
Also worthy of treatment in this section:
+ +When applicable, a careful demarcation between the + functionality of this package and others which - at least + superficially - appear to address the same requirements.
Note: it's entirely possible that a discussion of what a package is +not intended to do differs from a discussion of future improvements +for the package.
+For a given set of requirements, typically +many possible implementations and solutions exist. Although +eventually only one solution is implemented, a discussion of the +alternative solutions canvassed - noting why they were rejected - +proves helpful to both current and future developers. All readers +would be reminded as to why and how the particular solution developed +over time, avoiding re-analysis of problems already solved.
+Although currently only a few package +documentation pages contain a discussion of competing software, +(e.g. chat, portals), this section should be present whenever such +competition exists.
+ +If your package exhibits features missing from competing + software, this fact should be underscored.
If your package lacks features which are present in + competing software, the reasons for this should be discussed here; + our sales team needs to be ready for inquiries regarding features + our software lacks.
Note that such a discussion may differ from a discussion of a +package's potential future improvements.
+No single design solution can optimize every +desirable software attribute. For example, an increase in the security +of a system will likely entail a decrease in its ease-of-use, and an +increase in the flexibility/generality of a system typically entails a +decrease in the simplicity and efficiency of that system. Thus a +developer must decide to put a higher value on some attributes over +others: this section should include a discussion of the tradeoffs +involved with the design chosen, and the reasons for your +choices. Some areas of importance to keep in mind are:
+ +Areas of interest to users:
+ +Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability
Areas of interest to developers:
+Maintainability
Portability
Reusability
Testability
Here's where you discuss the abstractions +used by your package, such as the procedures encapsulating the legal +transactions on the data model. Explain the organization of +procedures and their particulars (detail above and beyond what is +documented in the code), including:
+ +Problem-domain components: key algorithms, e.g. a + specialized statistics package would implement specific mathematical + procedures.
User-interface components: e.g. HTML widgets that the + package may need.
Data management components: procedures that provide a stable + interface to database objects and legal transactions - the latter + often correspond to tasks.
Remember that the correctness, completeness, and stability of the +API and interface are what experienced members of our audience are +looking for. This is a cultural shift for us at aD (as of mid-year +2000), in that we've previously always looked at the data models as +key, and seldom spent much effort on the API (e.g. putting raw SQL in +pages to handle transactions, instead of encapsulating them via +procedures). Experience has taught us that we need to focus on the +API for maintainability of our systems in the face of constant +change.
+ +Also noteworthy is that although the OpenACS currently utilizes the +AOLserver Tcl API, the current drive towards Java is likely to effect +a change in the content of these sections in the future.
The data model discussion should do more than +merely display the SQL code, since this information is already be +available via a link in the "essentials" section above. +Instead, there should be a high-level discussion of how your data +model meets your solution requirements: why the database entities were +defined as they are, and what transactions you expect to occur. (There +may be some overlap with the API section.) Here are some starting +points:
+ +The data model discussion should address the intended usage + of each entity (table, trigger, view, procedure, etc.) when this + information is not obvious from an inspection of the data model + itself.
If a core service or other subsystem is being used (e.g., + the new parties and groups, permissions, etc.) this should also be + mentioned.
Any default permissions should be identified + herein.
Discuss any data model extensions which tie into other + packages.
Transactions
+Discuss modifications which the database may undergo from your + package. Consider grouping legal transactions according to the + invoking user class, i.e. transactions by an OpenACS-admin, by + subsite-admin, by a user, by a developer, etc.
In this section, discuss user interface +issues and pages to be built; can organize by the expected classes of +users. These may include:
+ +Developers
OpenACS administrators (previously known as site-wide administrators)
Subsite administrators
End users
You may want to include page mockups, site-maps, or other visual +aids. Ideally this section is informed by some prototyping you've +done, to establish the package's usability with the client and other +interested parties.
+ +Note: In order that developer documentation be uniform across +different system documents, these users should herein be designated as +"the developer," "the OpenACS-admin," "the +sub-admin," and "the user," respectively.
+ +Finally, note that as our templating system becomes more entrenched +within the OpenACS, this section's details are likely to shift from UI +specifics to template interface specifics.
Under OpenACS 4, parameters are set at two +levels: at the global level by the OpenACS-admin, and at the subsite +level by a sub-admin. In this section, list and discuss both levels +of parameters.
If the system presently lacks +useful/desirable features, note details here. You could also comment +on non-functional improvements to the package, such as usability.
+ +Note that a careful treatment of the earlier "competitive +analysis" section can greatly facilitate the documenting of this +section.
Although a system's data model file often +contains this information, this isn't always the case. Furthermore, +data model files often undergo substantial revision, making it +difficult to track down the system creator. An additional +complication: package documentation may be authored by people not +directly involved in coding. Thus to avoid unnecessary confusion, +include email links to the following roles as they may apply:
+ +System creator
System owner
Documentation author
| Document Revision # | +Action Taken, Notes | +When? | +By Whom? | +
|---|
($Id: design.html,v 1.1 2005/08/31 17:05:18 leed Exp $)
+ + + Index: openacs-4/packages/image-magick/www/doc/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/image-magick/www/doc/index.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/image-magick/www/doc/index.html 31 Aug 2005 17:05:18 -0000 1.1 @@ -0,0 +1,26 @@ + + + + + +By You
+ + +Briefly explain to the reader what this +document is for, whether it records the requirements for a new system, +a client application, a toolkit subsystem, etc. Remember your +audience: fellow programmers, AND interested non-technical parties +such as potential clients, who may all want to see how rigorous our +engineering process is. Here and everywhere, write clearly and +precisely; for requirements documentation, write at a level that any +intelligent layperson can understand.
+Very broadly, describe how the system meets a +need of a business, group, the OpenACS as a whole, etc. Make sure +that technical and non-technical readers alike would understand what +the system would do and why it's useful. Whenever applicable, you +should explicitly state what the business value of the system is.
+Discuss the high-level breakdown of the +components that make up the system. You can go by functional areas, +by the main transactions the system allows, etc.
+ +You should also state the context and dependencies of the system +here, e.g. if it's an application-level package for OpenACS 4, briefly +describe how it uses kernel services, like permissions or +subsites.
Determine the types or classes of users who +would use the system, and what their experience would be like at a +high-level. Sketch what their experience would be like and what +actions they would take, and how the system would support them.
+Describe other systems or services that are +comparable to what you're building. If applicable, say why your +implementation will be superior, where it will match the competition, +and where/why it will lack existing best-of-breed capabilities. This +section is also in the Design doc, so write about it where you deem +most appropriate.
+Include all pertinent links to supporting and related material, + such as:
+System/Package "coversheet" - where all documentation for this software is linked off of
Design document
Developer's guide
User's guide
Other-cool-system-related-to-this-one document
Test plan
Competitive system(s)
The main course of the document, +requirements. Break up the requirements sections (A, B, C, etc.) as +needed. Within each section, create a list denominated with unique +identifiers that reflect any functional hierarchy present, +e.g. 20.5.13. - for the first number, leave generous gaps on the first +writing of requirements (e.g. 1, 10, 20, 30, 40, etc.) because you'll +want to leave room for any missing key requirements that may +arise.
+ +10.0 A Common Solution
+Programmers and designers should only have to learn a single + system that serves as a UI substrate for all the functionally + specific modules in the toolkit.
+ +++10.0.1
+The system should not make any assumptions about how pages + should look or function.
+ +10.0.5
+Publishers should be able to change the default + presentation of any module using a single methodology with + minimal exposure to code.
+
For guidelines writing requirements, take a look at the quality standards, along with a good +example, such as OpenACS 4 Package +Manager Requirements.
+ +Besides writing requirements in natural language, consider using +the following techniques as needed:
+ +Pseudocode - a quasi programming language, combining the + informality of natural language with the strict syntax and control + structures of a programming language.
Finite State Machines - a hypothetical machine that can be in + only one of a given number of states at any specific time. Useful + to model situations that are rigidly deterministic, that is, any set + of inputs mathematically determines the system outputs.
Decision Trees and Decision Tables - similar to FSMs, but + better suited to handle combinations of inputs.
Flowcharts - easy to draw and understand, suited for event + and decision driven systems. UML is the industry standard + here.
Entity-Relationship diagrams - a necessary part of Design + documents, sometimes a high-level ER diagram is useful for + requirements as well.
Although in theory coding comes after design, +which comes after requirements, we do not, and perhaps should not, +always follow such a rigid process (a.k.a. the waterfall lifecyle). +Often, there is a pre-existing system or prototype first, and thus you +may want to write some thoughts on implementation, for aiding and +guiding yourself or other programmers.
+| Document Revision # | +Action Taken, Notes | +When? | +By Whom? | +
|---|
($Id: requirements.html,v 1.1 2005/08/31 17:05:18 leed Exp $)
+ + +