Graphics objects documentation

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

Graphics objects documentation

Pantxo
Hi,

The current documentation for graphics objects is sparse and inhomogeneous. M. Godfrey has already started tidying things up but, as he suggests,  it would certainly be preferable to automate the doc generation for a few reasons:
* Having properties match between doc and octave interpreter
* Homogenize the way we document default values, valid values ...
* Have (as much as possible) common descriptions for properties that are shared by all objects (e.g. type, tag, ...)

In order to make a first step I wrote an octave function that pretty much does the above mentioned tasks, plus add an @anchor for each item so that we can do cross referencing.

Now the questions are:
* Do people think that this automation process is really worth,
* Is it acceptable to do this with octave?  If so, are there examples of .txi files generated  by octave scripts somewhere in the doc (I am interested in Makefile.in rules examples)?

Pantxo
Reply | Threaded
Open this post in threaded view
|

Re: Graphics objects documentation

Michael Godfrey

On 09/25/2014 12:51 PM, Pantxo Diribarne wrote:

> Hi,
>
> The current documentation for graphics objects is sparse and
> inhomogeneous. M. Godfrey has already started tidying things up but,
> as he suggests,  it would certainly be preferable to automate the doc
> generation for a few reasons:
> * Having properties match between doc and octave interpreter
> * Homogenize the way we document default values, valid values ...
> * Have (as much as possible) common descriptions for properties that
> are shared by all objects (e.g. type, tag, ...)
>
> In order to make a first step I wrote an octave function that pretty
> much does the above mentioned tasks, plus add an @anchor for each item
> so that we can do cross referencing.
>
> Now the questions are:
> * Do people think that this automation process is really worth,
> * Is it acceptable to do this with octave?  If so, are there examples
> of .txi files generated  by octave scripts somewhere in the doc (I am
> interested in Makefile.in rules examples)?
>
> Pantxo
Obviously I think this is a very good idea!  And, since octave is
already used to
generate the plots that are shown in the Manual, it can (really must) be
used
to generate the property documentation.

Thanks for taking this on!

Michael


Reply | Threaded
Open this post in threaded view
|

Re: Graphics objects documentation

bpabbott
Administrator
In reply to this post by Pantxo
On Sep 25, 2014, at 7:51 AM, Pantxo Diribarne <[hidden email]> wrote:

> Hi,
>
> The current documentation for graphics objects is sparse and inhomogeneous. M. Godfrey has already started tidying things up but, as he suggests,  it would certainly be preferable to automate the doc generation for a few reasons:
> * Having properties match between doc and octave interpreter
> * Homogenize the way we document default values, valid values ...
> * Have (as much as possible) common descriptions for properties that are shared by all objects (e.g. type, tag, ...)
>
> In order to make a first step I wrote an octave function that pretty much does the above mentioned tasks, plus add an @anchor for each item so that we can do cross referencing.
>
> Now the questions are:
> * Do people think that this automation process is really worth,
> * Is it acceptable to do this with octave?  If so, are there examples of .txi files generated  by octave scripts somewhere in the doc (I am interested in Makefile.in rules examples)?
>
> Pantxo

I like the idea.

Many figures are already produces vias scripts.  The doc-strings from the m-files are also grabbed and placed into the documentation.

For this task, I'd write a script to produced an entire section for the manual and then use "input" or "include" to place it where it should go.

Ben
Reply | Threaded
Open this post in threaded view
|

Re: Graphics objects documentation

Mike Miller
In reply to this post by Pantxo
On Thu, Sep 25, 2014 at 13:51:46 +0200, Pantxo Diribarne wrote:
> * Do people think that this automation process is really worth,

Yes.

> * Is it acceptable to do this with octave?  If so, are there examples of
> .txi files generated  by octave scripts somewhere in the doc (I am
> interested in Makefile.in rules examples)?

Absolutely.

One example is the contributors list, look for mkcontrib.awk in
doc/interpreter. If you can write a script to generate a texinfo
snippet, it can simply be @included where it should be placed in the
manual, this is exactly what is done for the contributors list.

The generated file should be named .texi, the .txi extension seems to
only be used for files that are preprocessed into .texi files.

--
mike

Reply | Threaded
Open this post in threaded view
|

Re: Graphics objects documentation

Pantxo
Le 25/09/2014 14:47, Mike Miller a écrit :

> On Thu, Sep 25, 2014 at 13:51:46 +0200, Pantxo Diribarne wrote:
>> * Do people think that this automation process is really worth,
> Yes.
>
>> * Is it acceptable to do this with octave?  If so, are there examples of
>> .txi files generated  by octave scripts somewhere in the doc (I am
>> interested in Makefile.in rules examples)?
> Absolutely.
>
> One example is the contributors list, look for mkcontrib.awk in
> doc/interpreter. If you can write a script to generate a texinfo
> snippet, it can simply be @included where it should be placed in the
> manual, this is exactly what is done for the contributors list.
Thanks you, "contributers.texi" example is definitely what I was looking
for.

Pantxo

Reply | Threaded
Open this post in threaded view
|

Re: Graphics objects documentation

Pantxo
I have proposed an implementation here
https://savannah.gnu.org/bugs/?42536 .
Comments are very welcome, especially about the way I included the texi
files generation in doc/interpreter/Makefile.am.

Pantxo


Reply | Threaded
Open this post in threaded view
|

Re: Graphics objects documentation

Pantxo
Le 13/10/2014 02:58, Ben Abbott a écrit :

> On Oct 12, 2014, at 6:07 PM, Pantxo Diribarne <[hidden email]> wrote:
>
>> I have proposed an implementation here https://savannah.gnu.org/bugs/?42536 .
>> Comments are very welcome, especially about the way I included the texi files generation in doc/interpreter/Makefile.am.
>>
>> Pantxo
> I had no problem applying the patch and building. Looks like a good start!
>
> Should it be applied to default, gui-release, or stable?
>
> Ben
>
I think default is better: I noticed a few inconsistencies in the
properties list (e.g. patches and other non text related objects having
an 'interpreter' property) that will have to be fixed before the
documentation is right. Furthermore, most of the docstrings still remain
to be written.


Pantxo

Reply | Threaded
Open this post in threaded view
|

Re: Graphics objects documentation

Pantxo
Le 13/10/2014 09:09, Pantxo Diribarne a écrit :

> Le 13/10/2014 02:58, Ben Abbott a écrit :
>
>> On Oct 12, 2014, at 6:07 PM, Pantxo Diribarne
>> <[hidden email]> wrote:
>>
>>
>>
>>> I have proposed an implementation here
>>> https://savannah.gnu.org/bugs/?42536 .
>>>
>>> Comments are very welcome, especially about the way I included the
>>> texi files generation in doc/interpreter/Makefile.am.
>>>
>>>
>>>
>>> Pantxo
>>>
>> I had no problem applying the patch and building. Looks like a good
>> start!
>>
>>
>>
>> Should it be applied to default, gui-release, or stable?
>>
>>
>>
>> Ben
>>
>>
>>
> I think default is better: I noticed a few inconsistencies in the
> properties list (e.g. patches and other non text related objects having
> an 'interpreter' property) that will have to be fixed before the
> documentation is right. Furthermore, most of the docstrings still remain
> to be written.
>
>
>
>
>
> Pantxo
>
>
>
Hi,

Following M. Godfrey suggestions and in absence of negative feedback, I
have pushed a modified changeset at
http://hg.savannah.gnu.org/hgweb/octave/rev/1f2a16d41ba2

You are now kindly invited to fill in the (many) blanks :-)

Thanks,

Pantxo