Patches to the manual

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Patches to the manual

pathematica
Recently, I posted a question about syntax required for a particular problem (see specifying RGB triplets).

I received the information I required within minutes (literally) in the next post.

The discussion that followed suggested that the functionality I required was not well documented.

A later post suggested submitting a patch for the manual.

I have a hard copy of the manual and I have checked the online version (which is presumably the most up to date one).

I have self taught coding skills for high level languages, with a tiny amount of experience of writing machine code. I have taken a maths degree relatively late in life but I have never had any formal education in computing (used in the general sense to include coding).

I have a sense of guilt that I use this great software without contributing to the generation of code.

I am slightly intimidated by the idea of contributing patches for the code itself. The same sense of a lack of technical insight also discourages contributing prose for the manual.

It did occur to me that I might submit some simple text for the manual on the solution the problem for which I had sought help. Both the hardcopy manual and the online have sections at the beginning that describe how individuals might submit code for patches to the program. Unfortunately, neither appear to offer information about how individuals might contribute relatively non-technical prose for the manual.

Have I missed the relevant part of the book (or the relevant link)?

Would the addition of a link and a means for contributing prose for the manual be a sensible idea?

Is there an official wiki somewhere, that might form the basis of revisions to the manual?

If not, would it help if there were one? (I'm afraid I would not know how to set one up).

Thanks for the program itself and for the rapid help available in the forum.
However good you think Octave is, it's much, much better.
Reply | Threaded
Open this post in threaded view
|

Re: Patches to the manual

Jordi Gutiérrez Hermoso-2
On 22 April 2011 11:31, pathematica <[hidden email]> wrote:

> It did occur to me that I might submit some simple text for the manual on
> the solution the problem for which I had sought help.

Thanks a lot for proposing this help. There's no need to feel guilty,
but I'm very glad you have considered contributing to Octave.

> Is there an official wiki somewhere, that might form the basis of
> revisions to the manual?

We do have a wiki. If you can write draft additions to the manual
there but are uncomfortable with preparing patches to the manual, I
can take whatever you write there and prepare the patches, crediting
you. It has a password because it's our makeshift captcha. I'll send
you the password privately in a minute.

Thanks,
- Jordi G. H.
_______________________________________________
Help-octave mailing list
[hidden email]
https://mailman.cae.wisc.edu/listinfo/help-octave
Reply | Threaded
Open this post in threaded view
|

Re: Patches to the manual

pathematica
I have added an entry to the wiki.

The question remains whether it would be useful to have instructions in the manual how to contribute to the manual itself (rather than to the code).

On the other hand, as the manual exists, I presume that the present arrangement is sufficient!

Best wishes
However good you think Octave is, it's much, much better.
Reply | Threaded
Open this post in threaded view
|

Re: Patches to the manual

Jordi Gutiérrez Hermoso-2
On 22 April 2011 17:17, pathematica <[hidden email]> wrote:
> I have added an entry to the wiki.

Namely, this one:

     http://wiki.octave.org/wiki.pl?Producing_Graphical_Output

I'll see about adding this discussion and examples to the manual.
Where did you have in mind that it should go?

- Jordi G. H.
_______________________________________________
Help-octave mailing list
[hidden email]
https://mailman.cae.wisc.edu/listinfo/help-octave
Reply | Threaded
Open this post in threaded view
|

Re: Patches to the manual

pathematica
This post was updated on .
HI Jordi

The page numbers cited in this post 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, it was the section headed "Specifying color" (appended to the end; the numbers 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 for the plot function (reprising page 193 of the manual). Obviously, this would be redundant when translating for 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 of the manual.

Additions
These are probably best included on page 195 of the manual.

Suggested words for the index:
'color' (this is already present in the index but it points only to page 231, which discusses surface plots);
'RGB notation in plots'
or just
'RGB'

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 status (as the second part of a property-value pair);
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, ... "
or perhaps for succintness, just
" , 'color', ... "

Perhaps there should be some comment in the section on plot3. In particular, in the subsection headed by the hanging indent "plot3 (args)", it might be helpful to include the comment:
"It is possible to specify the color of the plot using RGB triplets, as described for the plot function [on page 195]."
A suitable place might be on page 210, just before the entry that begins "An example of the use of ...".

The problem I face when offering suggestions to include in the manual is to find a way that harmonizes with the existing text and, also, 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) the text of the manual itself.

Best wishes.
However good you think Octave is, it's much, much better.
Reply | Threaded
Open this post in threaded view
|

Re: Patches to the manual

pathematica
By the way, I have also added instructions for achieving a "cubic" aspect ratio in three-dimensional plots. You guys explained how to do this for me in a previous thread. This does not appear to be well-documented in the manual.

The entry in the wiki might be considered for translation to a form suitable for inclusion on page 210 in the manual, perhaps in a subsection headed (by hanging indent), "axis" before the one headed "view". In this particular case, the text in the wiki appears more or less suitable without modification for translation into the manual (except for the part where I illustrated how to open a new figure, which I squeezed in on a whim!).

Please would someone check the technical details (I copied the commands from a script I kept and I cannot remember whether there was some technical reason for the choice of parameters passed to gca(), or whether I found them by experimentation).

Best wishes
However good you think Octave is, it's much, much better.