Re: [O] Some orgtbl doc issues

[Carsten Dominik]

Hi Rustom, 

thanks for this.

On 16.8.2013, at 16:30, Rustom Mody <address@hidden> wrote:

> Ive recently been poking around in orgtbl mode and encountered some
> issues.  Not sure how much is my own lack of understanding and how
> much there are some little doc issues.
> 
> 1 Option names dont match
> =========================
> 
>  - Its orgtbl-radio-table-templates in emacs
>  - Its orgtbl-radio-tables in doc Appendix A.6.2

Fixed, thanks.

> 
> 
> 2 Receiving string
> ==================
> 
>  - Seems to be "RECEIVE ORGTBL"

It is BEGIN RECEIVE ORGTBL followed by a table name.  As the example in the 
manual shows.  Does this have to be more explicit?

>  - String seems to be hardwired. Which may be ok if its by design.

Yes, hardwired by design.

>  - Not clear what is the relation of this string and
>    orgtbl-radio-templates

The templates insert a BEGIN RECEIVE/END RECEIVE table template with
*proper commenting* around it in different programming modes.
I improved this in the docs.

>  - I find 1 space is fixed between RECEIVE and ORGTBL. Multiple
> allowed between ORGTBL and table-name

OK, I have removed this restriction.

>  - Its not clear from the doc whether its "RECEIVE ORGTBL" or
>  "/* RECEIVE ORGTBL"

That depends on the programming mode.  The documentation says that the lines 
must be comments in the current mode, I would think that this is clear enough.

>  - Subtle interaction between # in org and host mode comment char -- #
>    in python, shell etc -- could do with some elaboration

Can you propose something for the documentation?

> 
> 
> 3 hook system
> =============
> 
>  - What are the hooks for orgtbl?
>  - How do the org hooks relate to the orgtbl hooks?
>  - Note: orgtbl is for those who are not otherwise using orgmode

What to you mean?  Mode hooks, or hooks for specific functionality of the 
table?  If table commands run hooks, the corresponding trgtbl commands will do 
so as well, because they simply call the table functions in an environment 
where the proper keys bindings are not accessible.

orgtbl-mode is a standard minor mode and has `orgtbl-mode-hook', similar to all 
other minor modes.  See the documentation of define-minor-mode.  Do you feel 
the manual should say so?  It does not document many other hooks in org either, 
because there are too many.


> 
> 4 Long header line
> ==================
> 
>  I could not figure out how to split a long
>  :#+ORGTBL: SEND...  line

It cannot be split.

Regards

- Carsten

> 
> Regards
> Rusi
>