Re: afterstep.man page

Andrew Sullivan (asullivan@sprint.ca)
Fri, 4 Dec 1998 17:10:04 -0500 (EST) 

Hi,

Sorry this has taken rather a while.  And also, for my sorry state when I
was on #afterstep the other day.  Rule: do not go on IRC after having a
few.

Anyway, here we go.  Fewer abbrev. this time.  (Sorry about that, I
couldn't resist.)  As always, feel free to ignore anything I say!

Line 10, in the synopsys: is it the switch "-version", or "-v"?  I think
it should be "-v" _or_ "--version".  If you append "-version", you get the
version number, and a "usage" error when AS tries to parse the second
option ("e").

Lines 13-14, in the Description: "an X11 window manager with a NEXTSTEP
look and feel, and attempts to go beyond . . ."  The syntax is awkward
here.  Maybe "which attempts to go beyond..." or even "but which..."

Line 51, in Initialization: The default configuration files location.
These could be moved at install time, couldn't they?  Maybe you can add
"or possibly another directory selected by the system administrator"?

Line 52, In Initialization: "if copied (and edited to suite a user's
needs) to": should be "suit".

Line 53, in Initialization: "\fI~/GNUstep/Library/AfterStep\fP, these will
override."  Maybe rephrase as "the latter will override the former", for
clarity?

Line 58, Initialization: "incompatible" instead of "non-compatible"?

Line 61, Invocation: " typically invoked from the users \fI~/.xinitrc\fP
".  Should be either "user's" or "users'".  (I prefer the latter).  In the
latter case, you can remove the "the," so the passage reads "typically
invoked from users' \fI~/.xinitrc\fP..."

Line 69, Anatomy of Desktop: "screen.  This is to serve as being somewhat
similar to the Windows(R)  StartBar, where windows appear when opened and
can be Maximized from..."  This is sort of awkward.  Maybe try, "This
functions in a manner similar to the Windows ..."?

Lines 74-5, Anatomy: "will expand to.  This module controls which desktop
and or view is visable as well as handling the graphics picked"  The
referent of "This" is unclear, because the actual antecedent is actually
WinList, when you must mean Pager.  Maybe just replace "This" with
"Pager".  Also, "visible".  Finally, for consistency, the second verb
should be in the same voice as the first; so, "and also handles" instead
of "as well as handling".  (Jeez, picky, eh?)

Lines 76-78, Anatomy: "the module .BR Wharf(1) , this acts as a button
bar"  The comma should be a semicolon.  "to which applications can be
started from or in." You have at least one too many prepositions here.
How about "in or from which applications can be started"?

Line 79, Anatomy: "A default \fIstartmenu\fP is also provided which was
created ..."  Inconsistent tenses.  Should be either "which is created" or
"which will have been created".  The second is actually the correct one,
as the "is" here is not really the present tense, but is describing 
hypothetcal case (where a user starts AS with defaults).  It doesn't much
matter, though, because of the plastic nature of English tenses.  (Tell
you, I'm glad I studied Latin in high school.  It comes in sooo handy.
:/)

Line 83, Anatomy: "top decoration is called the TitleBar which contains
various window action".  The "which" here would be better replaced by a
semicolon and "it": "called the TitleBar; it contains ..."  Or, if you
want, "The top decoration, called the TitleBar, contains..."  Also, I
thought this is spelled Titlebar?  The fvwm 1.2 man pages just call it
title bar.  No, wait, you're right.  Arrgh!  Now I'll have to change the
FAQ again.

Line 85, Anatomy: "called the Handles or low bar, which contains the..."
Same problem with the "which" here.

Line 90, Modules: "but transmits commands to \fBafterstep\fP to execute."
"Transmits commands _for_ afterstep to execute"?  Or "transmits commands
to afterstep for the latter to execute"?

Line 102, Config files: "The \fIbackgrounds/\fP directory is the location
\fBafterstep\fP looks for" .  Looks needs an object, but location won't
work without a preposition.  How about "directory where afterstep
looks..."?

Line 109, Config files: "Valid images are currently XPM, JPEG, and PNG".
You need a "formats" in here somewhere.  

Line 118, Config: "options for a window, i.e. \fIshaded\fP,".  Should be
"e.g."  "I.e." must exhaust all possibilities, and this list does not.

Line 135 ff, Config: Do you want to say that any "look" or "feel" file
should be placed in these directories, or do you want to say "should be
placed in these directories, or the user's ~/G/L/A/look|feel directory"?

Line 148, Config: "configuration files, these are the".  Comma splice.
Either make these two sentences, or use a semicolon.  You could also use a
colon, and just make a list: "configuration files: Pager's image files,
the current ..."

Line 152, Config: "files is a futile attempt unless "  Attempt at what?
 Maybe just "editing these files is futile unless..."

Line 173, Config options: Maybe mention that there must be exactly one
base file for every colordepth?

Line 183-4, Config options: " Valid pixmaps are currently XPM, JPEG, and
PNG."  Add "formats"?

Line 199-200, Config options: As above.

Line 229, Config options: "The \fI"WM_NAME"\fP can the window's name" Can
"be"?  Also, I thought this _had_ to be the WM_CLASS.  That's certainly
what the database file itself says.  Also, you can use the Ident module to
get this.

Line 236 ff, Config options: It would be good if you could put the default
option in the same place for each description.  So, for instance, you
have "NoFocus" but don't list "Focus"; you have Icon | NoIcon, where
"NoIcon" is _not_ the default; and you have NoTitles | Titles and
NoHandles | Handles where the latter item _is_ the default.  This way,
looking down the list, the reader faces a consistent pattern.

Line 304, Config options: "used in the \feel.name\fP file, " Missing an
"fI" here.

Line 314, Config options: "of a desks particular boundaries; where it will
then place it upon another desk or view."  "desk's".  Also, it iosn't
clear what the second clause means, partially, I suspect, because it's a
fragment.  Is the "where" a location, or "whereupon"?  And does the "it
will then place it" mean "this function will then cause the window to open
at that x-location"?

Line 322, Config options: same thing here as for ViewportX, above.

Lines 326-7 are commented out, I guess.  Are these functions broken, or
are you just not done with their desriptions?  What I have about these in
the FAQ I took from Ethan's e-mail:

>Color {forecolor} {backcolor}
>     ForeColor {color}
>     BackColor {color}
>       Change both the foreground (text) color, and the background color
>for
>       this window.  ForeColor changes only the foreground color.
>BackColor
>       changes only the background color.

Line 334-5, Config options: "following conditions are met \- there is" 
 The dash should be a colon.  "the \fIloo.name\fP file;" missing a "k".

Line 369, Config options: "Adds support for Motif window manager function
hints to be overriden." Should "adds" be "forces" here?  That is, doesn't
this function actually override the MWM function hints?  (I could be
wrong, I just thought that's what it did.)

Line 384, Config options: "Specifing this will disable the illusion that
the title bars are being ..." Specifying.

Line 389 ff, Config options: The sections on ClickToFocus and ClickToRaise
are, I think, missing something.  If you use both together, clicking
_anywhere_ on the window will raise and focus it.  (Is that right?  I know
I do that, anyway.)  These two sections together imply that you must click
on the TitleBar to get focussed&raised.  By the way, for consistency, you
should spell it TitleBar here, too, or else change earlier instances back
to title bar.

Lines 420-21, Config options: "\fIStubbornIconPlacement\fP has no effect
unless \fISmartPlacement\fP is also specified."  Why is this remark about
StubbornIconPlacement under "StubbornPlacement"?  Is it because
"SmartPlacement" is the opposite of "StubbornPlacement"?  If so, you need
to specify that.

Line 643, Config options (look): The move/resize window is the little thng
that pops up and tells you the current geometry, right?  If so, then the
description you give as the options here is backwards to some behaviour
that works for me.  I have ResizeMoveGeometry -+, but the window appears
in the upper right.

Line 954, Built in functions: Does Focus always raise the window, too?  I
thought that raising and focusing were two different operations.

Line 961 ff: Are the question marks because you're not sure if the
description is right, or because you're not sure if the function still
exists?  I don;t actually know anything about this function, so I'm afraid
I won't be much help here.  Sorry.  (Same is true about GotoPage.)  Also,
throughout this section (where there seem to be the lines of "?"s), there
are several little typos, including lots of missing periods.  I don't
mention them here, as I imagine that you're not done with the section yet
anyway.

Ok, this is as far as I got so far, and I presume that the line numbers
are beginning to change at this point any way, since you mentioned that
this section is not finished.

If you want me to keep going from this point on, just let me know (and
send me any updates since the version I now have, so I'm not giving you
remarks on anything you've already changed!).

Yours,
A.

Andrew Sullivan | asullivan@sprint.ca (better)| ajsulliv@mcmaster.ca (worse)
                                   *  *  *
                Go to http://lowrent.org/asfaq/, or issue
'finger -l ajsulliv@mcmail.cis.mcmaster.ca' to find the AfterStep FAQ file.