Topics for Theory of Operation



ClearSVN – Theory of Operation

Introduction and Purpose 2

Purpose of ClearSVN 2

References 2

User Guide 2

Runtime Environment/How to Install 2

What Export Does 3

What Import Does 4

Running the Script 4

command option behavior 4

Types of Paths 6

Log Writing 7

Use Case CookBook 7

Caveats with Moving and Renaming files in SVN 7

error handling 7

Theory of Operation 8

Command Execution 8

path manipulation 9

command line argument handling 9

the logging mechanism 9

error handling 9

exception handling 10

tree comparison 10

file comparison 10

Topic Mappings 10

The import algorithm: overview and details 10

Differences in Directory Representations 10

Import 11

The Change, Change List classes and parsing of the SVN log 13

ClearCase representation of directory changes 13

Subversion representation of directory changes 13

SVN log parsing difficulties 13

The export algorithm: overview and details 13

Porting to Non-Windows Platforms 14

Appendix A: Documenting the code 14

Emacs macros to help document the code 14

Introduction and Purpose

Purpose of ClearSVN

The ClearSVN script functions as a bridge between ClearCase and Subversion. It allows you to update, on an ongoing basis, work done in one repository to the other repository. The script is able to update in either direction, synchronizing either from ClearCase to Subversion, or from Subversion to ClearCase.

A lot of care has gone into writing this script so that it preserves lines of history of each file and directory that it updates. This means that if files and directories are renamed or moved by developers working on one side, that when those changes are updated to the other side most if not all of the lines of history will remain intact. In most cases, moves and renames will not break the history of a file or directory. There are some edge cases that it is impossible to code for, but on the whole, the script accomplishes this goal across the two systems.

The script was developed with Python Version 2.0 on a Windows XP platform. ClearSVN has been tested under Subversion 1.0.4, Clearcase 2002, and Clearcase 2003.

References

Subversion is open source software, to obtain a copy go here:



For more information on Subversion, you can access the SVN book online:



This script is a product developed by CollabNet:



ClearCase is an IBM/Rational product. Useful reference material available from IBM includes:

 Rational ClearCase / Rational ClearCase LT Administrator's Guide, Version 2003.06.0 for Windows/Unix, Published by IBM/Rational

Scope

This document strives to primarily cover the theory of operation behind the internal workings of the bridge script. The idea is to support a maintainer in being able to work on the code. Additionally, as this bridge script becomes productized, those doing planning and design of the next revision should find the theory of operation helpful.

We also suppose that having a user guide being able to run the bridge script is necessary. That, however, is not the primary focus of the current revision of this document.

User Guide

In this revision of this document, the User Guide portion is presented in incomplete form. The focus of this revision is on describing the internal workings of the bridge script. What you read in the following sections of the user guide may seem incomplete.

Setting up the environment for running the bridge script

In describing how to setup and use the bridge, we are going to assume that you have a Windows machine with ClearCase and Subversion installed and operational. We’re not going to explain how to install either of those applications. Please see some of the material described in the References section for more information on those topics.

What we are going to tell you is how to install the bridge script and use it to update changes between ClearCase and Subversion.

To use the script you should be on a Windows XP machine. While we expect the script will work with other flavors of the Windows operating system, we note that the script has not been tested on any of those other flavors, such as Windows 2000, Windows 2003, etc.

In order to run the script you have to have it on your machine in a place where it can be found in the PATH. You will, of course, need to have Python 2.0 or later installed in order to execute the script. ActiveState has a good flavor of Python (), and you may be able to search internet to find any of a number of other good Python implementations that you can use successfully.

To summarize what has just been mentioned, you need to the following basics setup and operating correctly:

• Windows machine

• ClearCase

• Subversion

• Python

• ClearSVN – the bridge script.

The two update modes: import and export

The script has two modes: import and export. The meaning of these modes is ClearCase-centric, so, import means synchronizing from Subversion into ClearCase while the export mode is for synchronizing changes from ClearCase into Subversion.

A point of terminology: in the following discussion, we need to be able to refer generically, without regard to ClearCase or Subversion, to the act of sending out changes, or bringing them in. It will be confusing if we say ‘import’ and ‘export,’ since those terms already refer to the update modes of the bridge script. Therefore, we will say ‘sending out’ and ‘receiving’ to mean the generic acts of sending changes out from either type of repository or receiving changes into either type of repository.

You can increase your chances of successfully importing or exporting by following the practice of using special branches for sending and, particularly, receiving. It is not required you work this way, but you will most likely avoid extra work by best leveraging the merge capabilities inherent to Subversion as well as ClearCase.

To show what sending and receiving branches are all about, consider the following diagram:

[pic]

Typically, organizations have several types of branches in their SCM system. Or, they may only use one, but at the very least, every organization has some type of ‘main’ branch – even if that branch is not explicitly named ‘main.’ This branch is where the critical builds are performed. It is the branch to which production code changes are delivered.

For sending out, you always want to send a known revision, or baseline, over to the other system.

• For ClearCase, that means exporting out of a view configured to point to either:

o Base ClearCase: a label.

o ClearCase UCM: a UCM baseline.

• For Subversion, importing into ClearCase from a working copy configured to a known revision.

In either case, it behooves you not to have any locally modified files, or any files that did not come from the repository present in either work space (working copy or view) that participates in update with the bridge script. In ClearCase terminology, this specifically means no checkouts and no view private files of any kind.

For receiving changes into a given system, consider the following diagram:

[pic]

For receiving you will have less work to do if the only changes ever made on the receiving branch are the changes brought in due to an update using the bridge script. Here’s why: if you don’t do this, then you (of course) are opening the door to the possibility that some type of merge be done as part of the update process. This merge will be required to integrate changes you’ve allowed on the receiving branch to properly be combined with imported changes. Why not do this the ‘normal’ way by means of a merge down to the ‘main’ branch?

It is important to realize that outside-of-system merge we just mentioned would not leverage the merge capabilities of either ClearCase or SVN. Such a merge would have to be satisfactorily completed prior to checking in or committing the changes brought in by an update. We recommend avoiding this situation by maintaining a clean receiving branch, as shown in the above diagram.

exporting from ClearCase to Subversion

You need to have an SVN working copy that is configured for the latest on whatever branch in SVN that you will export into. You also need to have two ClearCase views configured along the export branch you want to export from. One is ‘current’ and the other ‘before’ – which would actually represent the view configuration of the last time you exported.

To setup for import:

You need to have a ClearCase view configured to point at the latest on whatever branch you will use to import into. You also need to have an SVN working copy from which you will export changes.

What is the recommended branching strategy for updating between the systems?

What picture could we draw to help explain the branching best practice for doing updates?

Can’t we show the ‘hello’ invocation?

Shouldn’t we explain how to import and how to export?

Shouldn’t we show sample sessions so that an expert reader would be able to quickly assess this material and their situation and get going?

Can’t we explain the idea that you should only import to a branch that only receives import changes? That if you do not follow that policy that you are then dealing with overwriting changes on update, or somehow having to merge outside the purview of the versioning system, so that you are not using the ideal tools?

Isn’t the idea to have an import or export branch run parallel to a main branch that contains the main project work that an organization deals with? Then you use the tool to move changes over, to and from the side branch? Isn’t this ideal for ClearCase? Hadn’t it better be done slightly differently with SVN? If so, how? We don’t know yet, do we?

importing from Subversion to ClearCase

Before running the export function, you must do the following:

1. Set up a “before” view in ClearCase (CC)

2. Set up a current view in CC

3. Set up a Subversion working copy (which should match the before view of CC)

The Script will figure out the delta from #1 (the before view in CC) to #2 (the latest code in CC) and apply the changes to #3 (Subversion). The Script will do basic checking to ensure that 1, 2, and 3 exist. It will then compare #1 and #3 to ensure that they are equal (there is a force mode to force to proceed if they do not match – otherwise the script will stop).

The Script then compares #1 and #2; it determines directory changes, then file changes and modifications, and builds a list of changes. The script will then make the changes in the subversion working copy.

Subversion has atomic commit – SVN info will tell you which files have modified, all have to go in on commit w/o merge conflicts, or none go in.

What Import Does

To get an idea of how import from Subversion into ClearCase works, the following diagram illustrates the fact that the Subversion log plays a key role in how the script determines the changes to migrate over:

command option behavior

Next we have provided a section that covers the command line options and how you use these options to control the various features of the bridge.

You can run this program in one of two modes. In import mode, it

pulls changes into ClearCase from Subversion. Use export mode to push

changes from ClearCase to Subversion. For more information about how

to invoke an import or export, use one of the following:

clearsvn.py import -h

clearsvn.py export -h

[Editor: need an intro to this table saying what it’s for and on what field it is ordered. May want to factor out options that are common between import and export, and then just cover the differences? What is clearer?]

|letter |long form |description |default (if any) |

|-h |--help |Print usage information to STDOUT. | |

|-a |--accept |Automatically resolve suggested Add-to-Move resolutions, without prompting. See |Off |

| | |section xxx | |

[Editor: go ahead migrate the rest of the following command line option descriptions into the table above.]

-c, --ccview-root=DIR Use DIR as the path within a ClearCase view

and VOB to which Subversion changes are

imported.

-f, --force Proceed even when the uppermost revision in the

synchronization range does not match the

Subversion working copy revision.

-h, --help Display this usage information.

-l, --log-file=FILE Use FILE as an alternate logfile.

[default: \"log.txt\" in the current directory]

-n No-op mode. Provides for running the script,

finding directory changes and comparing

files, but without making any changes in

any repository. File comparisons may be wrong

due to directory changes (such as adds) not

having been made.

-p, --post-import-scan=WHEN Declare under what conditions to compare the

Subversion working copy include path and the

ClearCase view directory after import

completes. Valid options are \"always\" and

\"onwarn\" (meaning only if a relevant

warning occurs during the import).

-q, --quiet Avoid querying the user. Any unresolved Adds

will be treated as Adds (not Moves).

[default: off]

-r N:M Range of Subversion revisions to sync.

-s, --svn-root=DIR Use DIR as the Subversion client root directory.

-t, --tree-path=DIR Inform the script that DIR is the directory

(relative to the root of the repository) which

is reflected in the Subversion working copy.

-u, --username=USERNAME Use USERNAME for any authentication needs

Subversion may have.

-v, --verbosity=MODE Set the verbosity level. Valid options are

\"low\", \"med\", and \"high\". [default: low]

-w, --password=PASSWORD Use PASSWORD for any authentication needs

Subversion may have.

Example:

clearsvn.py import -s D:\\svnstuff\\client3\\our_project \\

-t \\trunk -c M:\\Bob_view\\the_vob\\our_project \\

-v med -r 217:213 -p onwarn -u bob -w p4ssw3rd

[Editor: do the table thing again, for these options, for export mode.]

Options:

-b, --ccref-view-root=DIR Use DIR as the path of the \"before\" ClearCase

configuration view.

-c, --ccview-root=DIR Use DIR as the path of the \"current\" ClearCase

configuration view.

-f, --force Proceed even when the \"before\" view and the

Subversion working copy do not match. (Not

recommended.)

-h, --help Display this usage information.

-l, --log-file=FILE Use FILE as an alternate logfile.

[default: \"log.txt\" in the current directory]

-n No-op mode. Provides for running the script,

finding directory changes and comparing

files, but without making any changes in

any repository. File comparisons may be wrong

due to directory changes (such as adds) not

having been made.

-r, --re-export Resume an aborted export. This option

cannot be combined with any other command

line option except -n (no-op).

-s, --svn-root=DIR Use DIR as the Subversion client root directory.

-u, --username=USERNAME Use USERNAME for any authentication needs

Subversion may have.

-v, --verbosity=MODE Set the verbosity level. Valid options are

\"low\", \"med\", and \"high\". [default: low]

-w, --password=PASSWORD Use PASSWORD for any authentication needs

Subversion may have.

Types of Paths

A variety of concepts relating to path representations come up. There are the paths on the physical disk locations that designate the root of the Clearcase view or SVN workspace. Within both ClearCase and Subversion there is the concept of a path within the corresponding repository. This section tells you about each type of path and what you use it for.

[Editor: can probably just have a table, or several subsections that describe the types of paths … probably follows from the material on the command line options and/or log contents. These are about the only two places the user will encounter paths.]

Log Writing

In this subsection, we cover the feature of the log that the SVN bridge writes out. There are some command line options that influence the logging behavior. We describe some of the ways that you can control how the bridge does logging. We give a few examples of output you might find in the log and tell how you might want to use that output.

Use Case CookBook

In another section, one of the things we cover are some of the use cases, sort of like a cookbook, so that you can see how to get started quickly and find answers to some of the common problems that may come up.

[Editor: have a section on setup, to prime the system, as well as just doing export, just doing import. Comment on the round-trip scenario.]

Caveats with Moving and Renaming files in SVN

Just to make it clear and delineate the territory: Sander's bug is when you do a move of an element under a folder and then rename that folder, all in the same commit.

• Just doing moves or renames is not bad (unless you do it on a branch, and then merge it to the trunk)

• Doing one rename, committing, and then doing the other is also ok.

• And if you tried to move the folder, then move the file under it, Subversion wouldn't let you do that.

To wit, if refactoring only touches files, and never moves directories, then Sander's Bug will never arise.

(The suggested protocol – will be documented at a later date in the Usage documentation)

error handling

This script has been designed to be very conservative and helpful. Conservative means that the script has been written in such a way that it rarely if ever makes the assumption that an operation will succeed quietly. Rather, a lot of effort is taken to always capture the status result code as well as output of any shell commands executed by the Bridge. The Helpful aspect of this code is that diagnostic messages, like errors and warnings, are always intended to provide as much information as possible to aid a human being in solving a problem.

This section talks about some of the error messages and their meanings. See the internal view section to understand how error handling was implemented.

 

Performance Issues

In terms of performance, I only have the roughest of guesses: a few seconds per file synchronized (even if the file only has to be scanned and not updated). Bear in mind, the script does not use an algorithm that 100% processes one file, then 100% processes another, but rather works in some stages so that each file is hit several times for different purposes (though the contents should be scanned only a single time / the name is checked on another occasion). I have no idea what network bandwidth requirements are created.

Theory of Operation

This section explains the theory of operation of the ClearSVN program. With this description of the internal workings of the bridge, details about the program logic are exposed to enable programmers to make modifications and add new features and extensions to the program.

We begin an overview of the internals by describing each of the major features of the bridge giving an implementation overview. The bridge really centers around the import and export algorithms and all the details that flow from there. Dealing with the differences in how directory changes are treated by ClearCase and SVN consumes a lot of the “brainshare” of the design and the code, so we delve into this subject appropriately deeply. Up front, we define what a directory change means in each system, referring back to this definition often.

Command Execution

The script has to execute a variety of ClearCase, Subversion, and general shell commands. Some of the general shell commands include operations to copy files and directories.

The key to having a robust script is that whenever the script issues a command to the shell it should capture the return code that the shell returns. It is valuable since a non-zero status indicates some type of problem. The script acting to check a status is in the user’s interest so that the script does not blindly proceed in the case of an error.

It is also useful to capture STDOUT and STDERR from commands.

There are a couple of provisions for passing commands to the shell:

• the run_cmd subroutine allows a caller to pass in a string to be executed in the shell and get back a return code.

• the cmd_object class is a class for running commands, getting status codes, and capturing the STDOUT and STDERR stream output from the command. The run_cmd routine is essentially a wrapper around cmd_object.

You should just read the code for run_cmd; it is pretty straightforward.

The cmd_object class deserves a few words. It might seem peculiar at first glance. Its init method does the real work of executing a command. An object of this class has data that is essentially the STDOUT and STDERR output captured from executing the command. If a non-zero status code comes back from the command then an exception is raised.

You should refer to the code for more details, but there is one more point to mention. The implementation of this class uses temporary files to capture the two output streams. This might seem like a performance hit, but in practice, it does not seem to be a problem at all.

The shell context that executes the commands is whatever Python invokes. This is an area of potential porting issue for a Unix or Linux implementation.

path manipulation

Path manipulation occurs frequently throughout this code. In this section of the internal view section, we talk about means for manipulating and dealing with these paths. It turns out, for example, that determine subsumption – whether one path is included below another – is a useful operation that is necessary to making several algorithms found in the bridge successful.

command line argument handling

In this section we describe how command line arguments are handled. The behavior of the script given various command line options is covered in the external view section (Part I). In this section we cover the data that represents the command line options, describe how the options are parsed and validated, and finally, how the options are interpreted. In some cases, we end up referring you to the subsection of the Internal View description where the feature controlled or influenced by the command line option is described in more detail.

the logging mechanism

In this subsection we describe how the logging feature has been implemented. In the Internal View, section xxx describes how the bridge script handles logging. In this subsection we cover the logging class, how the various verbosity levels are handled, the creation of the logging file, as well as some of the idioms in the code used to generate log output. Finally, some of the issues with dealing with the log as currently implemented are briefly discussed.

error handling

This section talks about the design and implementation of error handling code in the Bridge script. Many of the error messages are simply handled by means of the logging and error reporting mechanism, which are closely related in this script’s design. In some cases, errors are handled by means of the Python exception-handling feature. This aspect is covered in the next section in more detail.

exception handling

This section explains how exceptions are handled in the code. Several of the idioms are shown.

tree comparison

In this section we discuss the tree compare routine. It is used both in the import and export algorithms.

file comparison

This subsection tells you how the script has provided for doing file comparisons.

Topic Mappings

This section has a few diagrams and explains the relationship of the various topics in this theory of operation. This section therefore is your guide to reading the rest of this document: turn here to most quickly find whatever information you are looking for. No, we haven’t provided a traditional index like a professionally written technical book would have!

The import algorithm: overview and details

In this section we first give an overview of the import algorithm. We next go through it again, the second time in some detail. The import algorithm attempts to preserve history as well as possible by preserving lines of change when files and directories are renamed or moved.

Differences in Directory Representations

What does “preserve history as well as possible” really mean? First, this script does not endeavor to replicate version for version changes from one system to the other. The goal is that whatever changes are present at the head of one side, at the time of synchronization (import or export) will be reflected in the other side after the script runs.

But, more important are the directory. Both ClearCase and Subversion have a capability of representing operations like – adds, renames, moves, and deletes - as changes (we call these “directory changes.” A great deal of effort went into this script so that these directory changes can be transferred across systems to effectively preserve history. Specifically, if a file is moved or renamed, and then changed, the changes follow a single thread of history associated with that file. We have designed the script not to break this thread of history to the greatest degree possible.

It has been challenging to preserve these directory changes because ClearCase and subversion use differing models of these types of changes. There is more about this topic within this document.

Here is an example of the differences. Suppose you do the following:

1. In Subversion, on the trunk branch, create a new file called foo1.c

2. Branch the trunk to “mybranch”. Note that foo1.c now appears on the branch.

3. On the trunk, rename foo1.c to foo2.c.

4. On “mybranch” checkout foo1.c, make and commit a change to foo1.c.

5. Merge changes on “mybranch” into the trunk.

You will observe that you get an error from Subversion to the effect that there is no “foo1.c” file. This is because Subversion uses a path-based approach to tracking changes. ClearCase uses an object-id approach to tracking changes. ClearCase would have supported the merge in this case.

Our point in making this illustration is not to say one system is better or worse than another is – our purpose is to bridge the system. It is therefore of paramount importance to be aware of the models that both sides use in representing directory changes.

Import

Some of the parameters passed to the script are as follows:

1. subversion working copy specified

2. target view in CC

3. –r revA revB -- to revisions numbers of SVN repository

#2 & 3 revA should match the target view in CC – revA should correspond to the last one synched to CC **

**NOTE/Exception: at Phillips they do round trip changes, make changes in CC, synch to SVN then synch back to CC. So LEAVE out the revisions for revA and revB where you synched to ClearCase.

Steps Executed during Import

I. ClearSVN does an SVN rev (or log?) –r A…B .

a. Parses the log (NOTE: could be a whole subsection on peculiarities of sVN log. i.e. if you do X it reports Y)

b. It does it chronologically, oldest to most recent

c. In the log, there are A=adds, D=deletes, M=modify. We ignore the modifies in the log – will figure these out by tree scans later. Just looking at adds and deletes – want to get directory/path changes. The list will have A target from:source path (indicates move, called “add with a source”)

D target

Script will try to match up adds with sources with deletes to identify moves. Scan chronologically to find those adds easier

d. Directory changes are made on CC side.

e. Then does a treescan comparing CC view with SVN working copy. Determines what’s in one side and not in other, and files w/diff contents.

f. The tree should be identical, but some files at this point should have different contents.

g. File modifications at this point would be handled by checkout on CC side and copy the file in to the target view.

h. No check-ins are done pending review by user.

NOTE: The log reporting does not let you tie moves back to the original directory on the SVN side.

Internal list for collecting info from SVN

A target1 from: source path

D target2

M target3

where A= Add, D = Delete, and M = Modify.

In parsing the log the script builds a changelist, ordered and sorted by path, each is a record. The sorting is done according to paths, so that all code in the same sub tree is contiguous, this simplifies the algorithms and helps with performance. The sorting cannot be on a string basis, it must be on a path basis.

Record information =

Operator - each changes operation is either an add or delete (A or D)

Original path

Current path

Flag indicating if item is currently “parented”

Parented == if there is an add, script will set operation to add, orig. and current will be set target path from the log, and the parented flag will be set to indicate that it does exist (Plain Jane Add)

Suppose that the file was added, and later deleted. You get a delete with a target that will be the same as the add. Will build a change record with a D and has the target path, and parent would be false (off) – as a result of the delete the item is no longer there (for simple delete). Suppose we now had the incorrect add with a later delete: will build the record first, then goes through the list to see if there are any previous records for this file. If there is one that matches up with the add, we will update the add record, and turn parented off. If this was part of a move, there will be a delete and an add with the source. Within a rev, we process deletes first then adds.

When there is an add with source, if we see this we expect to find a delete and find that the source matches the filename of the delete record, instead of putting the add in as a separate change, we edit the delete record, to leave original path and set current path to target of the original add in the log. Then set the parented flag to true.

So we will have an add that is not parented and a delete that is parented and has two different paths – which indicates that the file was moved.

To make the changes on CC side, we interpret these records. If we see an add that’s not parented we ignore it (where someone had added it then deleted it).

If we see a delete that is parented, we know that was a move.

If you did a series of moves, it will just do the overall move (first to last) not all in the middle… If there are sequences of changes – add, move, move, delete, the script will ignore it – will handle the sequence of changes. Give antoher example

The Change, Change List classes and parsing of the SVN log

The Change class is used to represent directory changes (adds, deletes, and replacements). This section talks about how Change class is used in conjunction with the Change List class in order to implement a the SVN log parser.

ClearCase representation of directory changes

This subsection introduces how ClearCase represents directory changes

Subversion representation of directory changes

This subsection introduces how SVN represents directory changes

SVN log parsing difficulties

This subsection gives some of the gory details about the type of output one sees in the SVN log for when certain sequences of changes have taken place in the repository. What you will see from reading this section is that it is virtually impossible to parse an SVN log and successfully determine a set of changes that could be made that reflect an object-id based model of changes.

The export algorithm: overview and details

In this section we first give an overview of the export algorithm. We next go through that algorithm again, the second time in some detail.

During the comparison, the algorithm creates a list for each tree, then compares the lists. If it finds a file, it compares the two versions; if it is a directory it pushes that onto the list for further study. The script sets aside directory and file moves… if it is a directory move, the script will not scan w/in those subdirectories, it will handle the moved directories in the next pass through the list. The script does a sequence of passes, if something is on one side and not the other, it tries to reconcile the object ID to see if it is a move, otherwise it is considered a new or removed directory or file.

Once the pass concludes, the script has created a list of:

• files and directories changed,

• files and directories added,

• files and directories deleted,

• files and directories moved.

Potentially we have holes in the tree where directories were renamed or added – b/c the commit would not have yet been done in SVN. B/c the directories may have been moved or added, the files under them have not yet been “handled” so they will not be in the list.

If an add, the script just copies the added directory to SVN and does a commit – SVN is recursive in its commit. We start a second pass - we know something was added. The script will compare the before view to the after view, comparing just directories previously skipped. So, you commit the first pass, then you commit the second pass – which will then match the SVN tree structure.

The script will make the changes but not auto commit the final commit, so if there is one commit needed, nothing will be committed, (if there are N commits needed, the script will do N-1 commits), this is done so that the changes can be reviewed. Script will auto commit all but the last command so that you can commit the directory changes to get the next pass and process the files under that directory change. NOTE: this is an anomaly, b/c you can technically commit file changes in the first pass that have not been reviewed which could potentially mess up the system.

Porting to Non-Windows Platforms

As of this writing, the script has only been used and tested in a Windows environment. This section tells you what issues you should anticipate in the event you want to port to Unix or Linux. This is not an exhaustive list; there may be other issues that you may be aware of not mentioned here.

• Shell execution. Differences between the DOS shell vs. Unix shell will have to be addressed for each of the commands that the script executes.

Paths. Care has been taken to try to use the Python os.path module for manipulating paths. That said, this is a potential area for problems.

Appendix A: Documenting the code

Emacs macros to help document the code

The python code has been documented using Emacs – these macros help format the python code for code comments. You may want to insert these into your .emacs file, for instance.

(defun insert-python-class-header ()

(interactive)

(insert

(string ?" ?" ?") "

Purpose:

What design provision are we addressing here?

Data Model:

What data does this thing appear to model from an external view?

Highlights of methods:

Without getting too detailed (methods are covered separately), what is the rhyme and reason behind the methods that are provided? \n" (string ?" ?" ?" ?\n)))

(defun insert-python-header ()

(interactive)

(insert

(string ?" ?" ?") "

Parameters:

Return value:

Exceptions:

What it does:

How it works:\n" (string ?" ?" ?" ?\n)))

(defun format-bill8 (top bottom)

(interactive "r")

(save-excursion

(let ((end-marker (progn

(goto-char bottom)

(point-marker))))

(goto-char top)

;; then indent format the paragraph

(setq default-justification 'full)

(setq fill-column 72)

(fill-individual-paragraphs top end-marker t)

)))

(global-set-key [f5] 'format-bill8)

-----------------------

[pic]

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download