Dear Justin,
somewhat overdone motivations on my new changes to your improvements.
Appended patch and master copy.
söndag den 5 december 2010 klockan 10:58 skrev Justin B Rye detta:
> Justin B Rye wrote:
> > Inline commentary on my revisions:
>
> A couple of afterthoughts.
>
> [...]
> >| First impression
>
> That's a rather misleading section name, but I left it because I was
> hoping to be struck by inspiration later for some better
> alternative. All I can think of is "Appearance".
Thus returning to my original naming! Fair enough.
>
> [...]
> > 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???.
>
> I missed the fact that the XSL automatically inserts the phrase "the
> section called" - which gets a bit repetitive; is that "called"
> really necessary?
I will dig deeper into the stylesheet to see if the behaviour can
be tampered with. So for I have only been disturbed by the feature,
I have never dug into it.
>
> [...]
> >| Control sequences
>
> That's not a great name for the category, since it seems to imply
> that <f> is a sequence of control keys. For a contrast with
> "Movement" keys, I'd suggest "Actions".
Good.
>
> The ordering <End>, <f>, <Ins>, <p>, <q> is unintuitive; I'd shift
> <Ins> up to be with (probably before) before <End>. I suppose I'd
> also put <+>, <-> after rather than before the number keys.
My original list was alphabetically sorted, which might be counter
intuitive. The new ordering is impeccable.
>
> Attached are a revised patch of the XML and a copy of my version of
> the XHTML output.
>
> Some thoughts I haven't acted on in the patch:
>
> There's no FILES section - it would be a natural place to put the
> explanation about the SVG-icons directory, but might also say what
> the defaults are for -d <dir>.
I have now attempted this.
>
> You could also use a SEE ALSO for the references to mtPaint.
Also done.
>
> I was assuming that the phrase "originally intended for the Debian
> GNU/Linux system" in the colophon was something automated, but I see
> you define &debian; within rgbpaint.xml, so I should mention that
> Squeeze comes in more flavours than just Linux. On the other hand
> if you didn't have this fact in mind when you wrote the manual, that
> means it's accurate anyway...
This is tricky. I am already contributing to the GNU/kFreeBSD port
on other matters, but the phrasing
Debian GNU/Linux and GNU/kFreeBSD
is not to my taste. Besides I have not yet tested this software with
Debian GNU/kFreeBSD. The alternative "Debian system" might come close
to a policy violation. I need advice on the proper naming here.
Here is an inlined motivation on my new changes (collapsed tabbing):
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.
+ scaled to (up or down depending on original size).
+ The default is 40 pixels on a side; permitted values
+ are in the range 32–256.
Down-scaling as well as up-scaling.
- When launched, &software; will use most of its available
- window area to present a view of a large
+ When launched, <command>&prog;</command> 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
+ edge. It is also possible for a rather narrow
<xref linkend="stamp.panel.en"/> containing iconised images
to be inset at the bottom edge.
It is the executable program that displays this behaviour.
I have resolved the compound "It's" based on the difficulty
for us foreigner to use similar constructs impeccably. A day
of reading any Debian mail list will display this fact in
sufficiently clarity.
- 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 second group picks the main mode, which <command>&prog;</command>
+ 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
<xref linkend="select.mode.en"/>.
I found " ... main mode, which ... " to meet my expectancy better. Correct?
Again, it is the executable that displays this behaviour. Line breaking
follows suite.
- image is determined by the switch <option>-thumb</option>, or
+ image is determined by the switch <option>-thumb</option>, or
Trailing white space.
of the original image, not that of the thumbnail. The copy is
- is fact only a marked area (see <xref linkend="select.mode.en"/>),
+ in fact only a marked area (see <xref linkend="select.mode.en"/>),
A case of "is is" accross line break. Intended: "is in".
- Any <keycap><Arrow></keycap> key moves 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
Ought not "Arrow" have precedence over "<Arrow>" in running prose?
I would personally be more forgiving with "<arrow>".
system for systems where this is the only way users are expected to access
- the program.
+ the program. See next section for the details.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Files</title>
+ <para>
+ At launch time, <command>&prog;</command> will record the current
+ working directory as the default location where to fetch and store
+ image files. This is the directory suggested every time a file
+ dialogue is brought into action. Using the command line option
+ <option>-d</option>, it is possible to set another location.
+ A reasonable choice is
+ "<option>-d</option> <filename class="directory">~</filename>"
+ for accessing the home directory of the user.
</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.
+ specified where <command>&prog;</command> 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 key words: new, open, save, saveas, cut, copy,
+ paste, undo, redo, text, paint, fill, select, sun, or zoom.
+ Each will provide an icon for the obvious corresponding function.
+ A missing icon will be replaced by a default choice, but there is
+ no guarantee that the fall-back icon will be unique, nor be relevant
+ for the intended purpose.
Lifting the old paragraph explaining '-svg' into a new section, prepending
a new paragraph on the "fetch directory". Again the command name is inserted,
and "sun" is placed back where it belongs. The final three lines try to
describe the result in case of an incomplete file collection. The wording
is so weak as to pass in all cases, whether I patch the software against
this bug or not!
Best regards,
Mats
Attachment:
rgbpaint.xml
Description: XML document
diff --git a/rgbpaint.xml b/rgbpaint.xml index 60aff28..9f81a9b 100644 --- a/rgbpaint.xml +++ b/rgbpaint.xml @@ -169,9 +169,9 @@ <listitem> <para> 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. + scaled to (up or down depending on original size). + The default is 40 pixels on a side; permitted values + are in the range 32–256. </para> </listitem> </varlistentry> @@ -204,12 +204,12 @@ <refsect1> <title>Appearance</title> <para> - When launched, &software; will use most of its available - window area to present a view of a large + When launched, <command>&prog;</command> 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 + edge. It is also possible for a rather narrow <xref linkend="stamp.panel.en"/> containing iconised images to be inset at the bottom edge. </para> @@ -261,11 +261,11 @@ check in order not to lose unsaved data. </para> <para> - 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 second group picks the main mode, which <command>&prog;</command> + 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 <xref linkend="select.mode.en"/>. </para> <para> @@ -375,14 +375,14 @@ 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 + 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 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"/>), + in fact only a marked area (see <xref linkend="select.mode.en"/>), 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 @@ -399,8 +399,8 @@ <keycap>-</keycap> give a fine-grained scaling up or down. </para> <para> - Any <keycap><Arrow></keycap> key moves 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>. @@ -579,16 +579,33 @@ 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. + the program. See next section for the details. + </para> + </refsect1> + + <refsect1> + <title>Files</title> + <para> + At launch time, <command>&prog;</command> will record the current + working directory as the default location where to fetch and store + image files. This is the directory suggested every time a file + dialogue is brought into action. Using the command line option + <option>-d</option>, it is possible to set another location. + A reasonable choice is + "<option>-d</option> <filename class="directory">~</filename>" + for accessing the home directory of the user. </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. + specified where <command>&prog;</command> 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 key words: new, open, save, saveas, cut, copy, + paste, undo, redo, text, paint, fill, select, sun, or zoom. + Each will provide an icon for the obvious corresponding function. + A missing icon will be replaced by a default choice, but there is + no guarantee that the fall-back icon will be unique, nor be relevant + for the intended purpose. </para> </refsect1> @@ -602,6 +619,18 @@ </refsect1> <refsect1> + <title> + See also + </title> + <para> + <citerefentry> + <refentrytitle>mtpaint</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>, the more extensive kin of &software;. + </para> + </refsect1> + + <refsect1> <title>Program Authors</title> <para> Mark Tyler, Dmitry Groshev