Re: Patches to the manual

[pathematica]

HI Jordi

The page numbers cited refer to Version 3 of the manual (ISBN
9-780954-612061)

My contribution to the wiki was not the whole section on plotting (someone
had already started a section on the plot function and it seemed appropriate
to include it there), rather the bit headed "Specifying color" (appended to
the end; the number in the specimen Octave code start again from 1). 

As the wiki does not have all of the text that is present in the manual,
first I had to back fill some information about the general properties of
the plot function. 

There was a brief introduction to the syntax (reprising page 193 of the
manual).

There was a description of some aspects of the 'fmt' and 'property-value'
arguments (reprising some of the content on page 194, but expanding some of
the points). 

Some of the entry was abbreviated. For example: 
I did not describe the variations in the syntax for the initial arguments
specifying dependent variable, with its various opportunities for implying
independent variable, or defining the independent variable explicitly.
I did not expand on variations in the syntax for the 'fmt' argument, which
is discussed on the manual on page 195 of the manual. In particular, I did
not explain how to combine more than one argument into a single 'fmt' value
as described on page 195.

Additions 
Probably best included on page 195

Suggested words for the index: 
'color' (at present this only refers to page 231, which discusses surface
plots)
'RGB notation in plots'

I introduced the syntax for the use of 'color' as a 'property-value' pair. I
reprised some of the discussion of property-value pairs given on page 194
but mine was more verbose (and less technical, as it was aimed at a less
sophisticated audience). Perhaps some of this might be included on page 194

I tried to describe the specific details about how the RGB values should be
passed, including:
details of its format (a row vector);
details of its elements (a value in the closed range [0, 1]);
advice how to specify RGB triplets as conventional two byte integers (using
decimals);
advice how to specify RGB triplets as conventional two byte integers (using
hexadecimals).

I think this would best be included either in or below the section that is
headed 
"plot (h, ...)                                             Function File

possibly just below the subsection heading 'c' (at the beginning of a
hanging indent) on page 195, just before the subsection heading ";title;"

A suitable subsection heading might be
" ..., 'color', RGBvalue, ... "

The problem I face in offering suggestions is to mesh with the original text
and to get the balance right between terseness (presumably to keep down the
size of the manual and the printing costs) and verbosity (to assist the
relatively unsophisticated or neophytes to Octave). 

To illustrate the difficulty, this post itself has become somewhat long!

This discussion also highlights the problem of editing a wiki, which uses a
different approach to the manual, rather than having a facility to edit (in
ways that would not necessarily lead to change before approval) of the text
of the manual itself. 

Best wishes.

--
View this message in context: 
http://octave.1599824.n4.nabble.com/Patches-to-the-manual-tp3468264p3469675.html
Sent from the Octave - General mailing list archive at Nabble.com.