Re: [jamboost] V2 UML diagrams

From: David Abrahams (dave_at_[hidden])
Date: 2003-01-13 08:09:57

Vladimir Prus <ghost_at_[hidden]> writes:

> David Abrahams wrote:
>> Vladimir Prus <ghost_at_[hidden]> writes:
>> 
>> 
>>>I've just uploaded a couple of UML diagrams to
>>>
>>> http://boost.sourceforge.net/boost-build2/diagrams/
>>>
>>>The first shows main classes, 
>> 
>> 
>> I understand that, and as you can see I've transcribed it into the
>> relevant .jam files.
>
> Thanks! I'm yet not on speaking terms with emacs picture-mode,
> so hardly could do that. BTW, they look very nice!

I've forgotten more than I once knew, so it was harder than it
should've been ;-)

Basically, you just do M-x "picture mode" C-h C-b and see what you've
got to work with. I have a few additional rules I wrote for rectangle
manipulation in my .emacs:

;; Emacs has a bunch of built-in commands for working with rectangular regions
;; of the screen (try "M-x apropos RET rectangle" for a list). These can be
;; *really cool* for making diagrams in text. There a couple of really useful
;; things missing from the built-in rectangle support, though, especially if
;; you're making pictures. First, the built-in yank-rectangle moves text which
;; is to the right of point over to avoid the new text. Sometimes you just want
;; that, but other times you just want to drop in a yanked rectangle on top of
;; what's there without disturbing the rest of the picture. That's what
;; my-yank-replace-rectangle does. Also, there's no built-in way of copying a
;; region to the rectangle kill-buffer. For that, we have my-save-rectangle.
(defun my-yank-replace-rectangle ()
"Replace a rectangular region with the last killed rectangle, placing its upper left corner at point."
(interactive)
(my-replace-rectangle killed-rectangle))

(defun my-replace-rectangle (rectangle)
"Replace rectangular region with RECTANGLE, placing its upper left corner at point.
RECTANGLE's first line is inserted at point, its second
line is inserted at a point vertically under point, etc.
RECTANGLE should be a list of strings.
After this command, the mark is at the upper left corner
and point is at the lower right corner."
(let (
(lines rectangle)
(insertcolumn (current-column))
(save-overwrite-mode overwrite-mode)
(width (length (car rectangle)))
(endcolumn (+ (current-column) (length (car rectangle))))
(first t))
(push-mark)
(setq overwrite-mode nil)
(while lines
(or first
(progn
(forward-line 1)
(or (bolp) (insert ?\n))))
(move-to-column-force endcolumn)
(delete-backward-char width)
(setq first nil)
(insert (car lines))
(setq lines (cdr lines)))
(overwrite-mode save-overwrite-mode)
))

(defun my-save-rectangle (start end)
"Save rectangle with corners at point and mark as last killed one.
Calling from program, supply two args START and END, buffer positions."
(interactive "r")
(setq killed-rectangle (extract-rectangle start end)))

(defun my-kill-rectangle (start end)
"Save rectangle with corners at point and mark as last killed one,
and erase it. Calling from program, supply two args START and END,
buffer positions."
(interactive "r")
(my-save-rectangle start end)
(clear-rectangle start end))

(global-set-key "\C-xr\C-k" 'my-kill-rectangle)
(global-set-key "\C-xr\C-y" 'my-yank-replace-rectangle)
(global-set-key "\C-xr\C-w" 'my-save-rectangle)

>>>and the second is a sequence chart showing how a project with
>>>simple main target, created by the "make" rule, might be generated.
>> 
>> 
>> I don't understand that one. What are v1 and v2?
>
> First, let's assume that jamfile contains:
>
> make foo : bar : make-foo-from-bar ;
>
> v1 and v2 are two instances of file-target class, v1 corresponds to
> the "foo" file, and v2 --- to the "bar" file.

More-descriptive names, e.g. "source" and "target", would've helped
here.

> The anonymous instance of make-target creates both v1 and v2, as
> well as action "a". (The "create" message means that the recipient
> of the message is created). Later, the action for generation of v1
> is set, and v1 is returned as result of call to generate.

What's the blob on the left which is the source of the first generate
message?

> After that, v1 is actualized, as shown by the following messages.

What is the self-referential loop on V1?

>>>Please take a look at those and let me know:
>>>1. If diagrams have any change of improving your understanding.
>> 
>> 
>> Yes, the first one helps. The second one still leaves me with
>> questions.
>
> Are there remaining questions?

I don't think so.

>>>2. Is the quality OK? (There're scanned from hand-drawings).
>> 
>> 
>> IMO the scan quality is OK, but the hand-drawings need to be cleaner
>> if they're going to communicate well, which is why I converted them to
>> ASCII.
>
> What should be improved, precisely. Looking at them now, I see that
> text is probably less readable than it should. The arrows looks
> good, however :-)

It's usable, just messy. Messiness is distracting and interferes with
understanding. Laying things out without overlapping elements
(e.g. lines), where possible, also helps.

-- 
David Abrahams
dave_at_[hidden] * http://www.boost-consulting.com
Boost support, enhancements, training, and commercial distribution