Re: Linguistic work on rgbPaint.
Mats Erik Andersson wrote:
> The attachments are threefold:
>
> rgbpaint.xml is the Docbook source, intended for peer reviewing,
>
> manpage.xsl, are stylesheets and evaluation helpers.
> xhtml.xsl
>
> A crash course in Docbook compilation now follows! Only two dependencies:
>
> # apt-get install xsltproc docbook-xsl
Funnily enough I see I've already got those (probably from some
build-dependency for a package I needed to build for a bugreport).
> Once these are in place, and putting the above three files in a common
> directory, the command
>
> $ xsltproc manpage.xsl rgbpaint.xml
>
> will produce a subdirectory "$(PWD)/man/" where the manual page rgbpaint.1
> is deposited. Correspondingly
>
> $ xsltproc xhtml.xsl rgbpaint.xml
> $ lynx html/index.html
>
> will create "$(PWD)/html/" and deposit three XHTML files there for viewing.
Yes, that all works.
> Personally, I find Vim very useful in giving me syntax highlighting
> of rgbpaint.xml. Beyond that help I believe there is only one issue
> in reading the XML source. The tags <xref> will expand in the target
> format to either a title content, augmented by a noun phrase, or the
> verbatim content of a tag <xreflabel> of the identifier referenced to.
> For this reason I recommend using the xsltproc calls above. It is only
> a matter of following the attribute "id" to locate the correct section.
I won't need my vi-handling bargepole: even nano can do adequate
syntax highlighting on XML. The indent level's a pain, though.
> The two target formats display slightly different emphasises, but are
> mostly identical. With a bit of luck, anyone trying these steps in
> Docbook compilation for the first time, might enjoy it enough to expand
> the private tool box with also this knowledge for future work! The trick
> with the stylesheets is to make some costumisation and to hide two very
> long file paths.
Okay; rgbpaint.txt, attached, is a w3m dump of the XHTML, to make it
easier for anyone else to butt in. But my second attachment is a
patch for rgbpaint.xml.
Inline commentary on my revisions:
| rgbpaint
| Prev Manual for rgbpaint.
|
| ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
| Name
|
| rgbpaint — A simple pixel-based painting program.
|
| Synopsis
|
| rgbpaint [ options ] [ image-file ] [ -stamps file ... ]
|
| Description
|
| rgbPaint is a very basic painting program created by forking mtPaint
| at version 3.09, and then simplifying the user interface. Colour
| handling is pixel-based with a small, but replaceable palette. Saving
| and editing image files is done using ICO, JPEG and PNG formats.
| Additional image formats can be loaded, but not saved in the original
| format.
Saying that colour handling is pixel-based really isn't seeing it
from the reader's point of view. For the user, colour handling is
palette-based! Likewise saying that editing files is done using
image formats. Rejigging the whole thing:
rgbPaint is a very basic painting program created by forking mtPaint
at version 3.09, and then simplifying the user interface. It relies
on a small but modifiable palette for pixel-based image editing.
Images can be saved in ICO, JPEG and PNG formats; files in other
image formats can be loaded, but not saved in the original format.
| Options
|
| The program accepts the following options:
|
| --help
|
| Print usage information.
|
| -d dir
|
| Use dir as the default directory for loading and saving image
| files.
(This dump has lost some formatting.)
| -s
|
| Grab a screen shot.
Insert "during launch"? This seems to be the only place this
functionality is mentioned.
| -stamps
|
| Any file names remaining on the command line will be loaded as
| stamp thumbnails.
Isn't it more accurate to say they'll be loaded as stamps (and
displayed as thumbnails)?
| -svg dir
|
| Load program icons in SVG format from the directory dir.
|
| -thumb size
|
| Set largest width (equal to height) of any stamp thumbnail.
| Permitted values for size are in the range 32 to 256 pixels.
| Default is 40.
Set size in pixels that stamp thumbnails should be reduced to
(if larger). The default is 40 pixels on a side; permitted
values are in the range 32–256 pixels.
(If the file is 50x200, does it rescale to 10x40 or just to 40x40?)
|
| -u limit
|
| Set the undo buffer to encompass limit MB storage, in the range
| from 1 MB to 500 MB. Default is 32 MB.
"Encompass" is rarely the word:
Set the maximum size of the undo buffer to limit MB. The
default is 32 MB; permitted values are in the range 1–500.
| --version
|
| Print version information.
|
| First impression
|
| When launched, rgbPaint will present itself with a view on a large
| Canvas, using most of the available window area. At the top there
| will be a Task panel, and a Brush and colour panel will be at the
| left edge. Possibly a rather narrow Stamp panel can be inset at the
| bottom edge, then containing iconized images.
When launched, rgbPaint will use most of its available window area
to present a view of a large Canvas. At the top there will be a
Tasks panel, and a Brushes/Colours panel will be at the left edge.
It's possible for a rather narrow Stamps panel containing iconised
images to be inset at the bottom edge.
| The task panel
The Tasks panel
(I gather I have to change it here if I want it to change elsewhere)
| In this panel an action is selected. The available actions are best
| named in subgroups, according to character:
Here and later you don't need to talk about the process of
describing them when you could be getting on with describing them!
This panel is used for selecting actions. The available actions
can be classified into the following groups:
| ● New image, Load image file, Save image file, Save image file as
| ● Paint, Flood fill, Make selection
| ● Cut, Copy, Paste, Paste text
| ● Undo, Redo, Transform colour, Pan window, Scaling
|
| The first group clearly alludes to the creation of a blank image, and
| to storing or retrieving images, existing or new. Each action
| conducts its own security check in order not to destroy any material
| not yet saved.
"Existing or new" doesn't quite make sense - I can't load a file
unless it exists. Can't it just say:
The first group deals with creating new blank images and reading
from or writing to image files. Each action conducts its own safety
check in order not to lose unsaved data.
(A security check would ask for my passport.)
| The second group determines a main mode upon which the program acts.
| When in Paint mode, a pencil will act as pointer symbol, while Fill
| mode displays as a bucket being emptied. Selection mode uses more
| than one icon and is compound, so it will be better explained in the
| section called “Making and using selections”.
The second group picks the main mode rgbPaint should enter. When it
is in Paint mode, the cursor will become a pencil symbol, while Fill
mode displays as a bucket being emptied. Selection mode is more
complicated, using more than one icon - see the section “Making
and using selections”.
| The third group encompasses actions that operate on a selected
| portion of the canvas: Cutting out from the canvas, making a Copy in
| memory of the content within the marked area, Pasting the copy back
| from memory onto the canvas, or opening a dialog window Text, that
| will deploy a new selection area, exactly large enough to hold the
| text snippet that is to be written using the dialog window.
I'm not 100% sure I follow that last bit, but:
The third group covers actions that operate on a selected portion of
the canvas: Cutting out a shape from the canvas, making a Copy in
memory of the content within the marked area, Pasting the copy back
from memory onto the canvas, or opening a dialog window for Text,
which will deploy a new selection area just large enough to hold
the snippet of text specified using the dialog window.
| The final group lists the odd actions: Undo an editing step, Redo an
| undone step, Transform the overall colour settings, Pan the window
| across the canvas (a miniature window is shown with a pane whose
| movements are controlled by the arrow keys), and finally, to set the
| Scaling of the canvas.
Not so much oddities as leftovers:
The final group lists miscellaneous actions: [...], or finally,
set the Scaling of the canvas.
| Making and using selections
|
| The Selection main mode is intended to grab and to manipulate
| portions of the full canvas. It can itself be thought of as being
| divided into three further states:
Say "for grabbing and manipulating".
| Resting
|
| is indicated by a cross-wires icon and happens when no corner
| marker has been set.
That's "cross-hairs".
| Marking
|
| shows one out of four corner icons. They all indicate how the
| next corner will be used to lay down a rectangle together with
| the previously set corner. To get a feeling for this, it is best
| to experiment a little by moving the pointer around.
I don't follow the "how the next corner will be used" bit. I
suppose "how the next point selected will be used"? I'm guessing
that the mechanic is you click to select the first point, then if
(say) your cursor is below and to the left of that point it displays
an "L" icon.
| A corner is set by left clicking, and two set corners show up as
| a rectangle outlined by dashed lines. A right click will cancel
| all corners, and will return to the resting state.
|
| Moving
|
| means that the pointer is hovering above a selected area, and
| that this area may be moved around. The icon consists of two
| crossed double-ended arrows, but can look similar to a diamond
| shape with four small, internal squares.
For once I have no trouble following that.
| The selected area can be moved around using the keyboard
| shortcuts (see the section called “Keyboard shortcuts”), or by
| holding the left mouse button down and moving the pointer around.
|
| The brush and colour panel
The Brushes/Colours panel
| Here the user chooses brush and colour for painting, or colour only
| for flood filling. There are ten different brushes, six solid and
| four thin ones. A solid brush can give a square or a round outline,
| each in one out of three differing thicknesses. The buttons for
| brushes are collected at the upper part of the panel.
There may be better words for the "solid/thin" opposition, but I'm
not thinking of them. Broad versus thin? Solid versus linear?
| Out of the four available thin brushes, the smallest is so thin as to
| paint one pixel at a time, making possible very accurate brush work.
| The other three are of larger sizes, but they all colour pixels in a
| random fashion within their outline, so they act somewhat like
| staining a surface.
Re-ordering slightly:
Here the user chooses a brush and colour for painting, or colour only
for flood filling. The upper part of the panel holds the ten
different brushes, six solid and four thin ones. The solid brushes
can give a square or a round outline in any of three thicknesses.
Out of the four available thin brushes, the smallest is so thin as to
paint one pixel at a time, making possible very accurate brush work.
The other three are of larger sizes, but they all colour pixels in a
random fashion within their outline, so they act somewhat like
staining a surface.
| At the lower part of this panel there are twenty buttons displaying a
| palette of available colours. By clicking on either of these, the
| corresponding colour is chosen for painting, until it is replaced. An
| elongated button, between the upper and the lower areas, will always
| display the active colour.
|
| The colour displaying button, near mid panel, has a further useful
| function. Clicking on the left mouse button will summon a colour
| editor. This allows the user to blend a new colour, which will, once
| accepted, replace the colour that was active before touching the
| button.
Again reordering:
In the lower part of the panel there are twenty buttons displaying a
palette of available colours. Clicking on any of these chooses the
corresponding colour for painting, until it is replaced.
An elongated button, between the upper and the lower areas, will
always display the active colour, and has a further useful function.
Clicking the left mouse button on it will summon a colour editor.
This allows the user to blend a new colour, which will, once
accepted, replace the colour that was previously active.
| The stamp panel
The Stamps panel
| This extra panel, at the bottom of the program window, comes to life
| only if rgbpaint was summoned using the command line switch -stamps,
| and with existing image files to follow. The displayed size of any
| thumbnail image is determined by the switch -thumb, or is set to 40
| pixels, in width as well as in height.
This extra panel, at the bottom of the program window, comes to life
only if rgbPaint was launched using the command line switch -stamps,
followed by the names of existing image files. The displayed size
of any thumbnail image is determined by the switch -thumb, or
defaults to 40 pixels in both width and height.
(This seems to say that by default a 4x20 image will be scaled *up*
in an aspect-ratio-distorting fashion.)
Oh, why is it <command>&prog;</command> here rather than &software;?
| If the user left clicks on a thumbnail image, a copy of the image
| will appear in the middle of the canvas, with the size of the
| original image, not that of the thumbnail. The copy is is fact only a
| marked area (see the section called “Making and using selections”),
| and can be moved around at will with the left mouse button, until a
| final right click will deposit a copy on the canvas. The marked area
| is still sitting on top, so it may again be moved around to make
| additional imprints.
I think the verb is "left-clicks", though the noun may be "right
click".
| Keyboard shortcuts
|
| There are some keyboard keys that come handy at times. The digits
| change the image scaling in pre-determined steps. The keys + and -
| give a fine grained scaling up or down.
That's "come in handy". Or maybe the whole thing is better as "Some
handy keyboard shortcuts are available".
"Digits" has the improbable but distracting alternative
interpretation of "users' fingers", so say "the number keys" or
"the keys 1–9" (depending which it is).
| Any <arrow> key move the mouse pointer in small steps across the
| canvas, steps which can be made larger by pressing Shift-Arrow. When
| instead using Ctrl-Arrow, the whole canvas will shift in the implied
| direction.
I'm interpreting "any <keycap><arrow></keycap> key" as being
short for something specific and super-fiddly like
"Any of <keycap><left-arrow></keycap>,
<keycap><right-arrow></keycap>,
<keycap><up-arrow></keycap>, or
<keycap><down-arrow></keycap>" rather than just being an
overdecorated version of the phrase "any arrow key"... just to
clarify I'm going to capitalise "Arrow" too, to match keycap names
like Ctrl and Home.
s/move/moves/; and rephrase the last sentence to avoid dangling
modifier:
Using Ctrl-Arrow will instead shift the whole canvas in the
corresponding direction.
| Control sequences
|
| +, -
|
| Scale up, scale down.
|
| 1 .. 9
|
| Change scaling to fixed levels.
Hang on, not 0?
"Dotdot" ellipses are the punctuation equivalent of jargon; for a
range the normal en_GB is "1–9" (with a dash rather than hyphen or
minus).
|
| End
|
| Summon the Pan Window dialog.
|
| f
|
| Select Flood fill mode.
|
| Ins
|
| Summon the Transform colour dialog.
|
| p
|
| Select the Paint mode.
|
| q
|
| Quit the program.
|
| s
|
| Activate Make Selection mode.
|
| t
|
| Open the dialog window Paste Text.
Surely "Summon the Text paste dialog"?
Oops, nearly missed it: en_GB "dialogue". It doesn't feel right,
but only for the same reason that my fingers don't like typing
"colour" near syntax-highlighting.
| Movement
|
| <arrow>
|
| Move pointer slightly.
Make these <keycap>Arrow</keycap>.
|
| Shift-<arrow>
|
| Move pointer in larger steps.
|
| Ctrl-<arrow>
|
| Move canvas with pointer staying behind.
Move canvas rather than pointer.
|
| Home
|
| Go to the top of the canvas.
I can imagine the asymmetry of Home and End catching people out...
| Ctrl-Home
|
| Go to the far left of the canvas.
|
| PgUp, PgDn
|
| Move the canvas up or down, one page at a time.
|
| Ctrl-PgUp, Ctrl-PgDn
|
| Move the canvas left or right, one page at a time.
|
| Tailored task icons
|
| There is a built-in possibility to tailor the optics of the task
| icons, as they appear in the Task panel. This is mostly an issue for
| the administrator of a kiosk system or similar, not a task for the
| casual user. It does make sense to use this in the command string
| registered with the Debian menu system for rgbpaint. At least for
| systems where users are expected to access the program only that way.
This has suddenly got a bit hard to follow. Um...
Customised task icons
(Or can I safely change that when it seems to be tied to a filename?)
There is a built-in facility for customising the appearance of the
task icons as they appear in the Tasks panel. This is mostly an issue
for the administrators of kiosk systems or similar, not for the casual
user. It can also make sense to use this in the rgbPaint command
string registered with the Debian menu system, at least for systems
where this is the only way users are expected to access the program.
| The command line switch -svg allows the specification of a directory,
| where particular vector image files are searched for. Their names are
| all of the form "stock-XXX.svg", and as the name imply, they must be
| of SVG format. The string XXX takes exactly one of the following
| values: new, open, save, saveas, cut, copy, paste, undo, redo, text,
| paint, fill, select, sun, or zoom. All these are needed for the
| expected functionality. It is straightforward to deduce the meaning
| of each name, simply by looking at the standard layout.
What's "sun"? Should it be "pan"?
The command line switch -svg allows a directory to be specified
where rgbPaint should look for particular vector image files in
SVG format. Their names must all be of the form "stock-XXX.svg",
where the XXX is one of the following words: new, open, save,
saveas, cut, copy, paste, undo, redo, text, paint, fill, select,
pan, or zoom. Each will provide an icon for the obvious
corresponding function, and all must be present.
(Does it mean that if one is missing rgbPaint will crash, or ignore
the directory, or what?)
(I notice " doesn't get smartquotes. A matter for the XSL
files?)
| Homepage
|
| http://mtpaint.sourceforge.net/rgbpaint.html
|
| Program Authors
|
| Mark Tyler, Dmitry Groshev
|
| Manual Authors
|
| The original manual page stub was taken as starting point for a
| complete rewrite as Docbook source, and was substantially extended by
| Mats Erik Andersson and Justin B Rye.
You've done all the heavy lifting, I'm just buffing the paintwork.
Okay, now to see if I can copy all these tweaks into the XML without
getting too baffled...
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
rgbpaint
Prev Manual for rgbpaint.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Name
rgbpaint — A simple pixel-based painting program.
Synopsis
rgbpaint [ options ] [ image-file ] [ -stamps file ... ]
Description
rgbPaint is a very basic painting program created by forking mtPaint
at version 3.09, and then simplifying the user interface. Colour
handling is pixel-based with a small, but replaceable palette. Saving
and editing image files is done using ICO, JPEG and PNG formats.
Additional image formats can be loaded, but not saved in the original
format.
Options
The program accepts the following options:
--help
Print usage information.
-d dir
Use dir as the default directory for loading and saving image
files.
-s
Grab a screen shot.
-stamps
Any file names remaining on the command line will be loaded as
stamp thumbnails.
-svg dir
Load program icons in SVG format from the directory dir.
-thumb size
Set largest width (equal to height) of any stamp thumbnail.
Permitted values for size are in the range 32 to 256 pixels.
Default is 40.
-u limit
Set the undo buffer to encompass limit MB storage, in the range
from 1 MB to 500 MB. Default is 32 MB.
--version
Print version information.
First impression
When launched, rgbPaint will present itself with a view on a large
Canvas, using most of the available window area. At the top there
will be a Task panel, and a Brush and colour panel will be at the
left edge. Possibly a rather narrow Stamp panel can be inset at the
bottom edge, then containing iconized images.
The task panel
In this panel an action is selected. The available actions are best
named in subgroups, according to character:
● New image, Load image file, Save image file, Save image file as
● Paint, Flood fill, Make selection
● Cut, Copy, Paste, Paste text
● Undo, Redo, Transform colour, Pan window, Scaling
The first group clearly alludes to the creation of a blank image, and
to storing or retrieving images, existing or new. Each action
conducts its own security check in order not to destroy any material
not yet saved.
The second group determines a main mode upon which the program acts.
When in Paint mode, a pencil will act as pointer symbol, while Fill
mode displays as a bucket being emptied. Selection mode uses more
than one icon and is compound, so it will be better explained in the
section called “Making and using selections”.
The third group encompasses actions that operate on a selected
portion of the canvas: Cutting out from the canvas, making a Copy in
memory of the content within the marked area, Pasting the copy back
from memory onto the canvas, or opening a dialog window Text, that
will deploy a new selection area, exactly large enough to hold the
text snippet that is to be written using the dialog window.
The final group lists the odd actions: Undo an editing step, Redo an
undone step, Transform the overall colour settings, Pan the window
across the canvas (a miniature window is shown with a pane whose
movements are controlled by the arrow keys), and finally, to set the
Scaling of the canvas.
Making and using selections
The Selection main mode is intended to grab and to manipulate
portions of the full canvas. It can itself be thought of as being
divided into three further states:
Resting
is indicated by a cross-wires icon and happens when no corner
marker has been set.
Marking
shows one out of four corner icons. They all indicate how the
next corner will be used to lay down a rectangle together with
the previously set corner. To get a feeling for this, it is best
to experiment a little by moving the pointer around.
A corner is set by left clicking, and two set corners show up as
a rectangle outlined by dashed lines. A right click will cancel
all corners, and will return to the resting state.
Moving
means that the pointer is hovering above a selected area, and
that this area may be moved around. The icon consists of two
crossed double-ended arrows, but can look similar to a diamond
shape with four small, internal squares.
The selected area can be moved around using the keyboard
shortcuts (see the section called “Keyboard shortcuts”), or by
holding the left mouse button down and moving the pointer around.
The brush and colour panel
Here the user chooses brush and colour for painting, or colour only
for flood filling. There are ten different brushes, six solid and
four thin ones. A solid brush can give a square or a round outline,
each in one out of three differing thicknesses. The buttons for
brushes are collected at the upper part of the panel.
Out of the four available thin brushes, the smallest is so thin as to
paint one pixel at a time, making possible very accurate brush work.
The other three are of larger sizes, but they all colour pixels in a
random fashion within their outline, so they act somewhat like
staining a surface.
At the lower part of this panel there are twenty buttons displaying a
palette of available colours. By clicking on either of these, the
corresponding colour is chosen for painting, until it is replaced. An
elongated button, between the upper and the lower areas, will always
display the active colour.
The colour displaying button, near mid panel, has a further useful
function. Clicking on the left mouse button will summon a colour
editor. This allows the user to blend a new colour, which will, once
accepted, replace the colour that was active before touching the
button.
The stamp panel
This extra panel, at the bottom of the program window, comes to life
only if rgbpaint was summoned using the command line switch -stamps,
and with existing image files to follow. The displayed size of any
thumbnail image is determined by the switch -thumb, or is set to 40
pixels, in width as well as in height.
If the user left clicks on a thumbnail image, a copy of the image
will appear in the middle of the canvas, with the size of the
original image, not that of the thumbnail. The copy is is fact only a
marked area (see the section called “Making and using selections”),
and can be moved around at will with the left mouse button, until a
final right click will deposit a copy on the canvas. The marked area
is still sitting on top, so it may again be moved around to make
additional imprints.
Keyboard shortcuts
There are some keyboard keys that come handy at times. The digits
change the image scaling in pre-determined steps. The keys + and -
give a fine grained scaling up or down.
Any <arrow> key move the mouse pointer in small steps across the
canvas, steps which can be made larger by pressing Shift-Arrow. When
instead using Ctrl-Arrow, the whole canvas will shift in the implied
direction.
Control sequences
+, -
Scale up, scale down.
1 .. 9
Change scaling to fixed levels.
End
Summon the Pan Window dialog.
f
Select Flood fill mode.
Ins
Summon the Transform colour dialog.
p
Select the Paint mode.
q
Quit the program.
s
Activate Make Selection mode.
t
Open the dialog window Paste Text.
Movement
<arrow>
Move pointer slightly.
Shift-<arrow>
Move pointer in larger steps.
Ctrl-<arrow>
Move canvas with pointer staying behind.
Home
Go to the top of the canvas.
Ctrl-Home
Go to the far left of the canvas.
PgUp, PgDn
Move the canvas up or down, one page at a time.
Ctrl-PgUp, Ctrl-PgDn
Move the canvas left or right, one page at a time.
Tailored task icons
There is a built-in possibility to tailor the optics of the task
icons, as they appear in the Task panel. This is mostly an issue for
the administrator of a kiosk system or similar, not a task for the
casual user. It does make sense to use this in the command string
registered with the Debian menu system for rgbpaint. At least for
systems where users are expected to access the program only that way.
The command line switch -svg allows the specification of a directory,
where particular vector image files are searched for. Their names are
all of the form "stock-XXX.svg", and as the name imply, they must be
of SVG format. The string XXX takes exactly one of the following
values: new, open, save, saveas, cut, copy, paste, undo, redo, text,
paint, fill, select, sun, or zoom. All these are needed for the
expected functionality. It is straightforward to deduce the meaning
of each name, simply by looking at the standard layout.
Homepage
http://mtpaint.sourceforge.net/rgbpaint.html
Program Authors
Mark Tyler, Dmitry Groshev
Manual Authors
The original manual page stub was taken as starting point for a
complete rewrite as Docbook source, and was substantially extended by
Mats Erik Andersson and Justin B Rye. The new format was chosen in
order to simplify translations, and was originally intended for the
Debian GNU/Linux system, but the text may be used by others.
Permission is granted to copy, distribute and/or modify this document
under the same terms as rgbPaint itself.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Prev Up
Manual for rgbpaint. Home
--- rgbpaint.xml.orig 2010-12-03 21:13:18.000000000 +0000
+++ rgbpaint.xml.jbr 2010-12-03 21:12:25.000000000 +0000
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding='UTF-8'?>
+<?xml version='1.0' encoding='UTF-8'?> <!-- -*- html -*- !-->
<!--
vim: set sw=2 ts=2:
-->
@@ -98,10 +98,10 @@
&software;
is a very basic painting program created by forking mtPaint
at version 3.09, and then simplifying the user interface.
- Colour handling is pixel-based with a small, but replaceable
- palette. Saving and editing image files is done using ICO,
- JPEG and PNG formats. Additional image formats can be loaded,
- but not saved in the original format.
+ It relies on a small but modifiable palette for pixel-based
+ image editing. Images can be saved in ICO, JPEG and PNG
+ formats; files in other image formats can be loaded, but not
+ saved in the original format.
</para>
</refsect1>
@@ -136,7 +136,7 @@
</term>
<listitem>
<para>
- Grab a screen shot.
+ Grab a screen shot during launch.
</para>
</listitem>
</varlistentry>
@@ -147,7 +147,7 @@
<listitem>
<para>
Any file names remaining on the command line will be loaded
- as stamp thumbnails.
+ as stamps.
</para>
</listitem>
</varlistentry>
@@ -168,9 +168,10 @@
</term>
<listitem>
<para>
- Set largest width (equal to height) of any stamp thumbnail.
- Permitted values for <replaceable>size</replaceable> are in
- the range 32 to 256 pixels. Default is 40.
+ Set size in pixels that stamp thumbnails should be
+ reduced to (if larger). The default is 40 pixels
+ on a side; permitted values are in the range
+ 32–256.
</para>
</listitem>
</varlistentry>
@@ -180,9 +181,10 @@
</term>
<listitem>
<para>
- Set the undo buffer to encompass
- <replaceable>limit</replaceable> MB storage, in the
- range from 1 MB to 500 MB. Default is 32 MB.
+ Set the maximum size of the undo buffer to
+ <replaceable>limit</replaceable> MB. The
+ default is 32 MB; permitted values are in the range
+ 1–500.
</para>
</listitem>
</varlistentry>
@@ -202,22 +204,22 @@
<refsect1>
<title>First impression</title>
<para>
- When launched, &software; will present itself with a view
- on a large <emphasis>Canvas</emphasis>, using most of the
- available window area. At the top there will be a
- <xref linkend="task.panel.en"/>,
- and a <xref linkend="brush-colour.panel.en"/> will be at
- the left edge. Possibly a rather
- narrow <xref linkend="stamp.panel.en"/> can be inset
- at the bottom edge, then containing iconized images.
+ When launched, &software; will use most of its available
+ window area to present a view of a large
+ <emphasis>Canvas</emphasis>. At the top
+ there will be a <xref linkend="task.panel.en"/>, and a
+ <xref linkend="brush-colour.panel.en"/> will be at the left
+ edge. It's also possible for a rather narrow
+ <xref linkend="stamp.panel.en"/> containing iconised images
+ to be inset at the bottom edge.
</para>
</refsect1>
- <refsect1 id="task.panel.en" xreflabel="Task panel">
- <title>The task panel</title>
+ <refsect1 id="task.panel.en" xreflabel="Tasks panel">
+ <title>The Tasks panel</title>
<para>
- In this panel an action is selected. The available actions are
- best named in subgroups, according to character:
+ This panel is used for selecting actions. The available actions
+ can be classified into the following groups:
</para>
<itemizedlist spacing="compact">
<listitem>
@@ -254,35 +256,35 @@
</listitem>
</itemizedlist>
<para>
- The first group clearly alludes to the creation of a blank image,
- and to storing or retrieving images, existing or new. Each action
- conducts its own security check in order not to destroy any material
- not yet saved.
+ The first group deals with creating new blank images and reading
+ from or writing to image files. Each action conducts its own safety
+ check in order not to lose unsaved data.
</para>
<para>
- The second group determines a main mode upon which the program acts.
- When in <emphasis>Paint</emphasis> mode, a pencil will act as pointer
- symbol, while <emphasis>Fill</emphasis> mode displays as a bucket
- being emptied. <emphasis>Selection</emphasis> mode uses more than
- one icon and is compound, so it will be better explained in
+ The second group picks the main mode &software; should enter. When
+ it is in <emphasis>Paint</emphasis> mode, the cursor will become a
+ pencil symbol, while <emphasis>Fill</emphasis> mode displays as a
+ bucket being emptied. <emphasis>Selection</emphasis> mode is more
+ complicated, using more than one icon - see the section
<xref linkend="select.mode.en"/>.
</para>
<para>
- The third group encompasses actions that operate on a selected portion
- of the canvas: <emphasis>Cutting</emphasis> out from the canvas, making a
- <emphasis>Copy</emphasis> in memory of the content within the marked area,
- <emphasis>Pasting</emphasis> the copy back from memory onto the canvas,
- or opening a dialog window <emphasis>Text</emphasis>, that will deploy
- a new selection area, exactly large enough to hold the text snippet
- that is to be written using the dialog window.
+ The third group covers actions that operate on a selected portion of
+ the canvas: <emphasis>Cutting</emphasis> out a shape from the canvas,
+ making a <emphasis>Copy</emphasis> in memory of the content within the
+ marked area, <emphasis>Pasting</emphasis> the copy back from memory
+ onto the canvas, or opening a dialogue window for
+ <emphasis>Text</emphasis>, which will deploy a new selection area just
+ large enough to hold the snippet of text specified using the dialogue
+ window.
</para>
<para>
- The final group lists the odd actions: <emphasis>Undo</emphasis>
+ The final group lists miscellaneous actions: <emphasis>Undo</emphasis>
an editing step, <emphasis>Redo</emphasis> an undone step,
<emphasis>Transform</emphasis> the overall colour settings,
<emphasis>Pan</emphasis> the window across the canvas
(a miniature window is shown with a pane whose movements are controlled
- by the arrow keys), and finally, to set the <emphasis>Scaling</emphasis>
+ by the arrow keys), or finally, set the <emphasis>Scaling</emphasis>
of the canvas.
</para>
</refsect1>
@@ -290,15 +292,15 @@
<refsect1 id="select.mode.en">
<title>Making and using selections</title>
<para>
- The <emphasis>Selection</emphasis> main mode is intended to grab and to
- manipulate portions of the full canvas. It can itself be thought of as
- being divided into three further states:
+ The <emphasis>Selection</emphasis> main mode is intended for grabbing
+ and manipulating portions of the full canvas. It can itself be thought
+ of as being divided into three further states:
<variablelist>
<varlistentry>
<term>Resting</term>
<listitem>
<para>
- is indicated by a cross-wires icon and happens when no corner
+ is indicated by a cross-hairs icon and happens when no corner
marker has been set.
</para>
</listitem>
@@ -308,7 +310,7 @@
<listitem>
<para>
shows one out of four corner icons. They all indicate how the
- next corner will be used to lay down a rectangle together with
+ next point selected will be used to lay down a rectangle together with
the previously set corner. To get a feeling for this, it is
best to experiment a little by moving the pointer around.
</para>
@@ -340,50 +342,44 @@
</para>
</refsect1>
- <refsect1 id="brush-colour.panel.en" xreflabel="Brush and colour panel">
- <title>The brush and colour panel</title>
+ <refsect1 id="brush-colour.panel.en" xreflabel="Brushes/Colours panel">
+ <title>The Brushes/Colours panel</title>
<para>
- Here the user chooses brush and colour for painting, or colour only
- for flood filling. There are ten different brushes, six solid and four
- thin ones. A solid brush can give a square or a round outline, each in
- one out of three differing thicknesses. The buttons for brushes are
- collected at the upper part of the panel.
- </para>
- <para>
- Out of the four available thin brushes, the smallest is so thin as
- to paint one pixel at a time, making possible very accurate brush work.
- The other three are of larger sizes, but they all colour pixels
- in a random fashion within their outline, so they act somewhat like
- staining a surface.
- </para>
- <para>
- At the lower part of this panel there are twenty buttons displaying
- a palette of available colours. By clicking on either of these, the
- corresponding colour is chosen for painting, until it is replaced.
- An elongated button, between the upper and the lower areas, will
- always display the active colour.
+ Here the user chooses a brush and colour for painting, or colour only
+ for flood filling. The upper part of the panel holds the ten different
+ brushes, six solid and four thin ones. The solid brushes can give a
+ square or a round outline in any of three thicknesses. Out of the four
+ available thin brushes, the smallest is so thin as to paint one pixel
+ at a time, making possible very accurate brush work. The other three
+ are of larger sizes, but they all colour pixels in a random fashion
+ within their outline, so they act somewhat like staining a surface.
+ </para>
+ <para>
+ In the lower part of the panel there are twenty buttons displaying a
+ palette of available colours. Clicking on any of these chooses the
+ corresponding colour for painting, until it is replaced.
</para>
<para>
- The colour displaying button, near mid panel, has a further useful
- function. Clicking on the left mouse button will summon a colour
- editor. This allows the user to blend a new colour, which will,
- once accepted, replace the colour that was active before touching
- the button.
+ An elongated button, between the upper and the lower areas, will
+ always display the active colour, and has a further useful function.
+ Clicking the left mouse button on it will summon a colour editor.
+ This allows the user to blend a new colour, which will, once accepted,
+ replace the colour that was previously active.
</para>
</refsect1>
- <refsect1 id="stamp.panel.en" xreflabel="Stamp panel">
- <title>The stamp panel</title>
+ <refsect1 id="stamp.panel.en" xreflabel="Stamps panel">
+ <title>The Stamps panel</title>
<para>
This extra panel, at the bottom of the program window, comes to
- life only if <command>&prog;</command> was summoned using the
- command line switch <option>-stamps</option>, and with existing
- image files to follow. The displayed size of any thumbnail image
- is determined by the switch <option>-thumb</option>, or is
- set to 40 pixels, in width as well as in height.
+ life only if <command>&prog;</command> was launched using the
+ command line switch <option>-stamps</option>, followed by the
+ names of existing image files. The displayed size of any thumbnail
+ image is determined by the switch <option>-thumb</option>, or
+ set to 40 pixels in both width and height.
</para>
<para>
- If the user left clicks on a thumbnail image, a copy of the
+ If the user left-clicks on a thumbnail image, a copy of the
image will appear in the middle of the canvas, with the size
of the original image, not that of the thumbnail. The copy is
is fact only a marked area (see <xref linkend="select.mode.en"/>),
@@ -397,14 +393,14 @@
<refsect1 id="keyboard.shortcuts.en">
<title>Keyboard shortcuts</title>
<para>
- There are some keyboard keys that come handy at times.
- The digits change the image scaling in pre-determined steps.
- The keys <keycap>+</keycap> and <keycap>-</keycap> give a fine
- grained scaling up or down.
+ Some handy keyboard shortcuts are available. The keys
+ <keycap>1</keycap>–<keycap>9</keycap> change image scaling
+ in pre-determined steps. The keys <keycap>+</keycap> and
+ <keycap>-</keycap> give a fine-grained scaling up or down.
</para>
<para>
- Any <keycap><arrow></keycap> key move the mouse pointer in small
- steps across the canvas, steps which can be made larger by pressing
+ Any <keycap><Arrow></keycap> key moves the mouse pointer in small
+ steps across the canvas - steps which can be made larger by pressing
<keycombo action="press">
<keycap>Shift</keycap><keycap>Arrow</keycap>
</keycombo>.
@@ -425,7 +421,7 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><keycap>1</keycap> .. <keycap>9</keycap></term>
+ <term><keycap>1</keycap>–<keycap>9</keycap></term>
<listitem>
<para>
Change scaling to fixed levels.
@@ -436,7 +432,7 @@
<term><keycap>End</keycap></term>
<listitem>
<para>
- Summon the <emphasis>Pan Window</emphasis> dialog.
+ Summon the <emphasis>Pan Window</emphasis> dialogue.
</para>
</listitem>
</varlistentry>
@@ -452,7 +448,7 @@
<term><keycap>Ins</keycap></term>
<listitem>
<para>
- Summon the <emphasis>Transform colour</emphasis> dialog.
+ Summon the <emphasis>Transform colour</emphasis> dialogue.
</para>
</listitem>
</varlistentry>
@@ -484,7 +480,7 @@
<term><keycap>t</keycap></term>
<listitem>
<para>
- Open the dialog window <emphasis>Paste Text</emphasis>.
+ Summon the <emphasis>Text paste</emphasis> dialogue.
</para>
</listitem>
</varlistentry>
@@ -492,7 +488,7 @@
<variablelist>
<title>Movement</title>
<varlistentry>
- <term><keycap><arrow></keycap></term>
+ <term><keycap>Arrow</keycap></term>
<listitem>
<para>
Move pointer slightly.
@@ -503,7 +499,7 @@
<term>
<keycombo action="press">
<keycap>Shift</keycap>
- <keycap><arrow></keycap>
+ <keycap>Arrow</keycap>
</keycombo>
</term>
<listitem>
@@ -516,12 +512,12 @@
<term>
<keycombo action="press">
<keycap>Ctrl</keycap>
- <keycap><arrow></keycap>
+ <keycap>Arrow</keycap>
</keycombo>
</term>
<listitem>
<para>
- Move canvas with pointer staying behind.
+ Move canvas rather than pointer.
</para>
</listitem>
</varlistentry>
@@ -574,26 +570,25 @@
</variablelist>
</refsect1>
- <refsect1 id="tailored.icons.en">
- <title>Tailored task icons</title>
+ <refsect1 id="customised.icons.en">
+ <title>Customised task icons</title>
<para>
- There is a built-in possibility to tailor the optics of the task icons,
- as they appear in the <xref linkend="task.panel.en"/>.
- This is mostly an issue for the administrator of a kiosk system or similar,
- not a task for the casual user. It does make sense to use this in the
- command string registered with the Debian menu system for
- <command>&prog;</command>. At least for systems where users are
- expected to access the program only that way.
- </para>
- <para>
- The command line switch <option>-svg</option> allows the specification
- of a directory, where particular vector image files are searched for.
- Their names are all of the form "stock-XXX.svg", and as the
- name imply, they must be of SVG format. The string XXX takes exactly
- one of the following values: new, open, save, saveas, cut, copy, paste,
- undo, redo, text, paint, fill, select, sun, or zoom. All these are
- needed for the expected functionality. It is straightforward to deduce
- the meaning of each name, simply by looking at the standard layout.
+ There is a built-in facility for customising the appearance of the task
+ icons as they appear in the <xref linkend="task.panel.en"/>.
+ This is mostly an issue for the administrators of kiosk systems or similar,
+ not for the casual user. It can also make sense to use this in the
+ <command>&prog;</command> command string registered with the Debian menu
+ system for systems where this is the only way users are expected to access
+ the program.
+ </para>
+ <para>
+ The command line switch <option>-svg</option> allows a directory to be
+ specified where &software; should look for particular vector image files
+ in SVG format. Their names must all be of the form "stock-XXX.svg",
+ where the <replaceable>XXX</replaceable> is one of the following words:
+ new, open, save, saveas, cut, copy, paste, undo, redo, text, paint, fill,
+ select, pan, or zoom. Each will provide an icon for the obvious
+ corresponding function, and all must be present.
</para>
</refsect1>
Reply to: