From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rustom Mody Subject: Re: Some orgtbl doc issues Date: Sat, 31 Aug 2013 22:02:59 +0530 Message-ID: References: <1AA0B1B9-9A50-4289-84BD-F0F1E9E7FAFB@gmail.com> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=089e0122aa24a02c1904e540e528 Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:46717) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VFo71-000300-2g for emacs-orgmode@gnu.org; Sat, 31 Aug 2013 12:33:24 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VFo6y-0000BQ-TR for emacs-orgmode@gnu.org; Sat, 31 Aug 2013 12:33:23 -0400 Received: from mail-ob0-x230.google.com ([2607:f8b0:4003:c01::230]:41711) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VFo6y-0000BM-MT for emacs-orgmode@gnu.org; Sat, 31 Aug 2013 12:33:20 -0400 Received: by mail-ob0-f176.google.com with SMTP id uz19so3058839obc.35 for ; Sat, 31 Aug 2013 09:33:20 -0700 (PDT) In-Reply-To: <1AA0B1B9-9A50-4289-84BD-F0F1E9E7FAFB@gmail.com> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Carsten Dominik Cc: emacs-orgmode --089e0122aa24a02c1904e540e528 Content-Type: text/plain; charset=ISO-8859-1 Well clearly the radio tables section reads better now. Further comments inline. Before that some general comments. The Python list thread starting here http://mail.python.org/pipermail/python-list/2013-July/653164.html As you will see some python programmers (including emacsers!) seem to have a need for something like this and dont seem to know about org. And by extension one may assume other languages than python also. In short this seems to be a general need. So what is written below should be taken less from my own pov -- I am hardly an org power-user but still a user -- than from the pov of a general emacser -- a programmer who uses emacs and knows next to nothing about org On Fri, Aug 30, 2013 at 10:16 PM, Carsten Dominik wrote: > Hi Rustom, > > thanks for this. > > On 16.8.2013, at 16:30, Rustom Mody 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 a problem in itself. It becomes a problem in connection with the dfault value of org-radio-table-templates which contains many instances of BEGIN RECEIVE ORGTBL %n and thereby suggests that that is changeable > > - 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. > Some languages (eg Python) have no multiline comment but have a multiline string which is also ok to use > > > - 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 orgtbl commands will > do so as well, because they simply call the table functions in an > environment where the proper keys bindings are not accessible. > As I said at start of this mail, we are looking at orgtbl for otherwise non-org users. For that audience I was exploring whether vanilla org would work OTB ie without any of my org-settings also not the latest but one bundled with emacs Since at that point I really could not understand orgtbl-radio-table-templates and thought it had to be set I asked. As it appears now, it works without any customization so the point is moot. Nevertheless the general question is: If a non-org user of orgtbl needs to set up minor-mode specific customization where is it to be done? > 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. > There are programming related organizations for which something like 80-char lines is really not negotiable! So I hope this can be considered as a feature request of course a very minor one Regards > > - Carsten > Speaking generally, maybe someone should respond to that python list thread. It can be me however someone more org-knowledgeable may be more appropriate :-) Thanks and regards Rusi -- http://blog.languager.org --089e0122aa24a02c1904e540e528 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
Well clearly the radio tables section reads better now. Fu= rther comments inline.
Before that some general comments.

The Pyt= hon list thread starting here
http://mail.python.o= rg/pipermail/python-list/2013-July/653164.html

As you= will see some python programmers (including emacsers!) seem to have a need= for something like this and dont seem to know about org. And by extension = one may assume other languages than python also. In short this seems to be = a general need.

So what is written below should be tak= en less from my own pov -- I am hardly an org power-user but still a user -= - than from the pov of a general emacser -- a programmer who uses emacs and= knows next to nothing about org


On Fri,= Aug 30, 2013 at 10:16 PM, Carsten Dominik <carsten.dominik@gmail.= com> wrote:
Hi Rustom,

thanks for this.

On 16.8.2013, at 16:30, Rustom Mody <rustompmody@gmail.com> wrote:

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

Fixed, thanks.

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

It is BEGIN RECEIVE ORGTBL followed by a table name. =A0As the exampl= e in the manual shows. =A0Does this have to be more explicit?

> =A0- String seems to be hardwired. Which may be ok if its by design.
Yes, hardwired by design.

Not a p= roblem in itself.

It becomes a problem in connection with= the dfault value of org-radio-table-templates which contains many instance= s of

BEGIN RECEIVE ORGTBL %n

and thereby suggests that that is changeable
<= br>

> =A0- Not clear what is the relation of this string and
> =A0 =A0orgtbl-radio-templates

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

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

OK, I have removed this restriction.

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

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

Some languages (eg Python= ) have no multiline comment but have a multiline string which is also ok to= use
=A0

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

Can you propose something for the documentation?

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

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

As I said at start of this mail, we are lo= oking at orgtbl for otherwise non-org users.
For that audienc= e I was exploring whether vanilla org would work OTB
ie witho= ut any of my org-settings
also not the latest but one bundled with emacs

Since at t= hat point I really could not understand orgtbl-radio-table-templates and th= ought it had to be set I asked. As it appears now, it works without any cus= tomization so the point is moot.=A0 Nevertheless the general question is: I= f a non-org user of orgtbl needs to=A0 set up minor-mode specific customiza= tion where is it to be done?


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


>
> 4 Long header line
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>
> =A0I could not figure out how to split a long
> =A0:#+ORGTBL: SEND... =A0line

It cannot be split.

There ar= e programming related organizations for which something like 80-char lines = is really not negotiable!
So I hope this can be considered as a feature request of course a very mino= r one

Regards

- Carsten


Sp= eaking generally, maybe someone should respond to that python list thread.<= br>
It can be me however someone more org-k= nowledgeable may be more appropriate :-)

Thanks and regards
Rusi

--

http://blog.languager= .org
--089e0122aa24a02c1904e540e528--