#+PROPERTY documentation

#+PROPERTY documentation

[Daimrod]

[-- Attachment #1: Type: text/plain, Size: 499 bytes --]

Hi,

It would be nice if the documentation mentioned the need to reparse the
org buffer with `C-c C-c' when a property is set with #+PROPERTY.
(info "(org) Property syntax")

And, IMO, it should also be mentioned here:
(info "(org) Buffer-wide header arguments").

A simple footnote like the one present here:
(info "(org) Tag inheritance") should be sufficient.

> (1) As with all these in-buffer settings, pressing `C-c C-c'
> activates any changes in the line.

-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: #+PROPERTY documentation

[John Hendy]

On Mon, Jan 21, 2013 at 12:41 PM, Daimrod <daimrod@gmail.com> wrote:
> Hi,
>
> It would be nice if the documentation mentioned the need to reparse the
> org buffer with `C-c C-c' when a property is set with #+PROPERTY.
> (info "(org) Property syntax")

As in adding to the header arguments? Yeah, probably wouldn't hurt,
though it is, as stated below, documented that *any* change to the
header arguments requires C-c C-c.

On a side note, is there the possibility for "normal" users to submit
git based changes to the manual? I know how to do this for Worg, but
I'd be happy to update stuff in the manual, too, when I catch them.
These sorts of things could be tweaked by the finder and it would save
the maintenance team a bit -- just scan the commit and notes for
rationale and accept.


John

>
> And, IMO, it should also be mentioned here:
> (info "(org) Buffer-wide header arguments").
>
> A simple footnote like the one present here:
> (info "(org) Tag inheritance") should be sufficient.
>
>> (1) As with all these in-buffer settings, pressing `C-c C-c'
>> activates any changes in the line.
>
> --
> Daimrod/Greg

Re: #+PROPERTY documentation

[Daimrod]

[-- Attachment #1: Type: text/plain, Size: 1355 bytes --]

John Hendy <jw.hendy@gmail.com> writes:

> On Mon, Jan 21, 2013 at 12:41 PM, Daimrod <daimrod@gmail.com> wrote:
>> Hi,
>>
>> It would be nice if the documentation mentioned the need to reparse the
>> org buffer with `C-c C-c' when a property is set with #+PROPERTY.
>> (info "(org) Property syntax")
>
> As in adding to the header arguments? Yeah, probably wouldn't hurt,
> though it is, as stated below, documented that *any* change to the
> header arguments requires C-c C-c.
>
> On a side note, is there the possibility for "normal" users to submit
> git based changes to the manual? I know how to do this for Worg, but
> I'd be happy to update stuff in the manual, too, when I catch them.
> These sorts of things could be tweaked by the finder and it would save
> the maintenance team a bit -- just scan the commit and notes for
> rationale and accept.

Sure, one can modify the file doc/org.texi. And you're right, I should
have submit a patch.

> John
>
>>
>> And, IMO, it should also be mentioned here:
>> (info "(org) Buffer-wide header arguments").
>>
>> A simple footnote like the one present here:
>> (info "(org) Tag inheritance") should be sufficient.
>>
>>> (1) As with all these in-buffer settings, pressing `C-c C-c'
>>> activates any changes in the line.
>>
>> --
>> Daimrod/Greg

-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: #+PROPERTY documentation

[John Hendy]

On Mon, Jan 21, 2013 at 4:35 PM, Daimrod <daimrod@gmail.com> wrote:
> John Hendy <jw.hendy@gmail.com> writes:
>
>> On Mon, Jan 21, 2013 at 12:41 PM, Daimrod <daimrod@gmail.com> wrote:
>>> Hi,
>>>
>>> It would be nice if the documentation mentioned the need to reparse the
>>> org buffer with `C-c C-c' when a property is set with #+PROPERTY.
>>> (info "(org) Property syntax")
>>
>> As in adding to the header arguments? Yeah, probably wouldn't hurt,
>> though it is, as stated below, documented that *any* change to the
>> header arguments requires C-c C-c.
>>
>> On a side note, is there the possibility for "normal" users to submit
>> git based changes to the manual? I know how to do this for Worg, but
>> I'd be happy to update stuff in the manual, too, when I catch them.
>> These sorts of things could be tweaked by the finder and it would save
>> the maintenance team a bit -- just scan the commit and notes for
>> rationale and accept.
>
> Sure, one can modify the file doc/org.texi. And you're right, I should
> have submit a patch.

Wasn't criticizing, for the record :) I actually didn't know one could do that!

Glad I learned something, and hopefully I can give back to Org more, now!


John

>
>> John
>>
>>>
>>> And, IMO, it should also be mentioned here:
>>> (info "(org) Buffer-wide header arguments").
>>>
>>> A simple footnote like the one present here:
>>> (info "(org) Tag inheritance") should be sufficient.
>>>
>>>> (1) As with all these in-buffer settings, pressing `C-c C-c'
>>>> activates any changes in the line.
>>>
>>> --
>>> Daimrod/Greg
>
> --
> Daimrod/Greg

Re: #+PROPERTY documentation

[Daimrod]

[-- Attachment #1.1: Type: text/plain, Size: 1381 bytes --]

Daimrod <daimrod@gmail.com> writes:

> John Hendy <jw.hendy@gmail.com> writes:
>
>> On Mon, Jan 21, 2013 at 12:41 PM, Daimrod <daimrod@gmail.com> wrote:
>>> Hi,
>>>
>>> It would be nice if the documentation mentioned the need to reparse the
>>> org buffer with `C-c C-c' when a property is set with #+PROPERTY.
>>> (info "(org) Property syntax")
>>
>> As in adding to the header arguments? Yeah, probably wouldn't hurt,
>> though it is, as stated below, documented that *any* change to the
>> header arguments requires C-c C-c.
>>
>> On a side note, is there the possibility for "normal" users to submit
>> git based changes to the manual? I know how to do this for Worg, but
>> I'd be happy to update stuff in the manual, too, when I catch them.
>> These sorts of things could be tweaked by the finder and it would save
>> the maintenance team a bit -- just scan the commit and notes for
>> rationale and accept.
>
> Sure, one can modify the file doc/org.texi. And you're right, I should
> have submit a patch.
>
>> John
>>
>>>
>>> And, IMO, it should also be mentioned here:
>>> (info "(org) Buffer-wide header arguments").
>>>
>>> A simple footnote like the one present here:
>>> (info "(org) Tag inheritance") should be sufficient.
>>>
>>>> (1) As with all these in-buffer settings, pressing `C-c C-c'
>>>> activates any changes in the line.
>>>

So, here is a patch for this:

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-add-footnote-to-recall-the-user-to-refresh-the-org-b.patch --]
[-- Type: text/x-diff, Size: 1413 bytes --]

From 09e569a651e77e8f2c1c2d1f0a285c69688fbd05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Jadi?= <gregoire.jadi@gmail.com>
Date: Mon, 21 Jan 2013 23:45:47 +0100
Subject: [PATCH] add footnote to recall the user to refresh the org buffer
 when settings are changed.

---
 doc/org.texi |    8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 61f1ee5..c2bdd58 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -4954,7 +4954,9 @@ publishers and the number of disks in a box like this:
 @end example
 
 If you want to set properties that can be inherited by any entry in a
-file, use a line like
+file, use a line like@footnote{As
+with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
+changes in the line.}
 @cindex property, _ALL
 @cindex #+PROPERTY
 @example
@@ -13252,7 +13254,9 @@ of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
 For example the following would set @code{session} to @code{*R*}, and
 @code{results} to @code{silent} for every code block in the buffer, ensuring
 that all execution took place in the same session, and no results would be
-inserted into the buffer.
+inserted into the buffer.@footnote{As
+with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
+changes in the line.}
 
 @example
 #+PROPERTY: session *R*
-- 
1.7.10.4


[-- Attachment #1.3: Type: text/plain, Size: 21 bytes --]


-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: #+PROPERTY documentation

[Thomas S. Dye]

Aloha Daimrod (Greg),

Daimrod <daimrod@gmail.com> writes:

>
> So, here is a patch for this:

If you add [PATCH] to the email Subject, your patch will be brought to
the attention of the developers.

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: #+PROPERTY documentation

[Daimrod]

[-- Attachment #1: Type: text/plain, Size: 335 bytes --]

tsd@tsdye.com (Thomas S. Dye) writes:

> Aloha Daimrod (Greg),
>
> Daimrod <daimrod@gmail.com> writes:
>
>>
>> So, here is a patch for this:
>
> If you add [PATCH] to the email Subject, your patch will be brought to
> the attention of the developers.

I didn't know, thanks.

> All the best,
> Tom

-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

[PATCH] Re: #+PROPERTY documentation

[Daimrod]

[-- Attachment #1.1: Type: text/plain, Size: 550 bytes --]

Daimrod <daimrod@gmail.com> writes:

> Hi,
>
> It would be nice if the documentation mentioned the need to reparse the
> org buffer with `C-c C-c' when a property is set with #+PROPERTY.
> (info "(org) Property syntax")
>
> And, IMO, it should also be mentioned here:
> (info "(org) Buffer-wide header arguments").
>
> A simple footnote like the one present here:
> (info "(org) Tag inheritance") should be sufficient.
>
>> (1) As with all these in-buffer settings, pressing `C-c C-c'
>> activates any changes in the line.

Here is a patch for this:

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-add-footnote-to-recall-the-user-to-refresh-the-org-b.patch --]
[-- Type: text/x-diff, Size: 1413 bytes --]

From 09e569a651e77e8f2c1c2d1f0a285c69688fbd05 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Jadi?= <gregoire.jadi@gmail.com>
Date: Mon, 21 Jan 2013 23:45:47 +0100
Subject: [PATCH] add footnote to recall the user to refresh the org buffer
 when settings are changed.

---
 doc/org.texi |    8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 61f1ee5..c2bdd58 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -4954,7 +4954,9 @@ publishers and the number of disks in a box like this:
 @end example
 
 If you want to set properties that can be inherited by any entry in a
-file, use a line like
+file, use a line like@footnote{As
+with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
+changes in the line.}
 @cindex property, _ALL
 @cindex #+PROPERTY
 @example
@@ -13252,7 +13254,9 @@ of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
 For example the following would set @code{session} to @code{*R*}, and
 @code{results} to @code{silent} for every code block in the buffer, ensuring
 that all execution took place in the same session, and no results would be
-inserted into the buffer.
+inserted into the buffer.@footnote{As
+with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
+changes in the line.}
 
 @example
 #+PROPERTY: session *R*
-- 
1.7.10.4


[-- Attachment #1.3: Type: text/plain, Size: 21 bytes --]


-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: #+PROPERTY documentation

[Nick Dokos]

Daimrod <daimrod@gmail.com> wrote:

> John Hendy <jw.hendy@gmail.com> writes:
> 
> > On Mon, Jan 21, 2013 at 12:41 PM, Daimrod <daimrod@gmail.com> wrote:
> >> Hi,
> >>
> >> It would be nice if the documentation mentioned the need to reparse the
> >> org buffer with `C-c C-c' when a property is set with #+PROPERTY.
> >> (info "(org) Property syntax")
> >
> > As in adding to the header arguments? Yeah, probably wouldn't hurt,
> > though it is, as stated below, documented that *any* change to the
> > header arguments requires C-c C-c.
> >
> > On a side note, is there the possibility for "normal" users to submit
> > git based changes to the manual? I know how to do this for Worg, but
> > I'd be happy to update stuff in the manual, too, when I catch them.
> > These sorts of things could be tweaked by the finder and it would save
> > the maintenance team a bit -- just scan the commit and notes for
> > rationale and accept.
> 
> Sure, one can modify the file doc/org.texi. And you're right, I should
> have submit a patch.
> 

I believe that just as with code changes, doc changes also need FSF
copyright assignment. 

Nick

Re: #+PROPERTY documentation

[Achim Gratz]

Nick Dokos writes:
> I believe that just as with code changes, doc changes also need FSF
> copyright assignment. 

The FSF owns the copyright to all of Org, including the documentation.
So yes, anything over 20 lines non-trivial chnages needs to be assigned
to FSF.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: #+PROPERTY documentation

[Daimrod]

[-- Attachment #1: Type: text/plain, Size: 1378 bytes --]

Nick Dokos <nicholas.dokos@hp.com> writes:

> Daimrod <daimrod@gmail.com> wrote:
>
>> John Hendy <jw.hendy@gmail.com> writes:
>> 
>> > On Mon, Jan 21, 2013 at 12:41 PM, Daimrod <daimrod@gmail.com> wrote:
>> >> Hi,
>> >>
>> >> It would be nice if the documentation mentioned the need to reparse the
>> >> org buffer with `C-c C-c' when a property is set with #+PROPERTY.
>> >> (info "(org) Property syntax")
>> >
>> > As in adding to the header arguments? Yeah, probably wouldn't hurt,
>> > though it is, as stated below, documented that *any* change to the
>> > header arguments requires C-c C-c.
>> >
>> > On a side note, is there the possibility for "normal" users to submit
>> > git based changes to the manual? I know how to do this for Worg, but
>> > I'd be happy to update stuff in the manual, too, when I catch them.
>> > These sorts of things could be tweaked by the finder and it would save
>> > the maintenance team a bit -- just scan the commit and notes for
>> > rationale and accept.
>> 
>> Sure, one can modify the file doc/org.texi. And you're right, I should
>> have submit a patch.
>> 
>
> I believe that just as with code changes, doc changes also need FSF
> copyright assignment. 

Ok, I've already sent an assignment request for another patch and it
should be confirmed by the end of the week.

> Nick

-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: #+PROPERTY documentation

[Bastien]

Achim Gratz <Stromeko@nexgo.de> writes:

> Nick Dokos writes:
>> I believe that just as with code changes, doc changes also need FSF
>> copyright assignment. 
>
> The FSF owns the copyright to all of Org, including the
> documentation.

More precisely, the FSF owns the copyright of GNU Emacs, and
assignments are signed but the contributors for contributions
to GNU Emacs.

Since Org is part of GNU Emacs, the FSF owns the copyright
for the Org manual that is part of GNU Emacs.

It does not own the copyright for changes that are ahead of
GNU Emacs and not yet merged. 

But we ask contributors to proceed with the assignment ahead
of the merge, that's easier.

> So yes, anything over 20 lines non-trivial chnages needs to be assigned
> to FSF.

Indeed.

-- 
 Bastien

Re: #+PROPERTY documentation

[Bastien]

Hi Daimrod,

Daimrod <daimrod@gmail.com> writes:

> Ok, I've already sent an assignment request for another patch and it
> should be confirmed by the end of the week.

Don't be too optimistic, it takes usually longer, at least three
weeks.  You can still send patches, we will apply them when the FSF 
confirmed your assignment is processed.   This leaves a window for
discussing the change, if needed.

Thanks for your contributions!

-- 
 Bastien

Re: [PATCH] Re: #+PROPERTY documentation

[Bastien]

Daimrod <daimrod@gmail.com> writes:

> Here is a patch for this:

Thanks.  Please add a proper ChangeLog to it.

See http://orgmode.org/worg/org-contribute.html#sec-5

You also need to add TINYCHANGE at the bottom of the
git commit message.

Thanks for your efforts!

-- 
 Bastien

Re: [PATCH] Re: #+PROPERTY documentation

[Daimrod]

[-- Attachment #1.1: Type: text/plain, Size: 381 bytes --]

Bastien <bzg@altern.org> writes:

> Daimrod <daimrod@gmail.com> writes:
>
>> Here is a patch for this:
>
> Thanks.  Please add a proper ChangeLog to it.
>
> See http://orgmode.org/worg/org-contribute.html#sec-5

Thanks.

> You also need to add TINYCHANGE at the bottom of the
> git commit message.
>
> Thanks for your efforts!

Is it better?

I'll also reformat my other patches.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-Documentation-Add-footnotes-to-recall-the-user-to-re.patch --]
[-- Type: text/x-diff, Size: 1582 bytes --]

From 4c71f10ecfdd8e44642cb18d27fe42a9b17fe1b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Jadi?= <gregoire.jadi@gmail.com>
Date: Mon, 21 Jan 2013 23:45:47 +0100
Subject: [PATCH] Documentation: Add footnotes to recall the user to refresh
 the org buffer when settings are changed

* doc/org.texi: Add a footnote to the following sections:
- (info "(org) Property syntax")
- (info "(org) Buffer-wide header arguments")

TINYCHANGE
---
 doc/org.texi |    8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index 61f1ee5..c2bdd58 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -4954,7 +4954,9 @@ publishers and the number of disks in a box like this:
 @end example
 
 If you want to set properties that can be inherited by any entry in a
-file, use a line like
+file, use a line like@footnote{As
+with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
+changes in the line.}
 @cindex property, _ALL
 @cindex #+PROPERTY
 @example
@@ -13252,7 +13254,9 @@ of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see
 For example the following would set @code{session} to @code{*R*}, and
 @code{results} to @code{silent} for every code block in the buffer, ensuring
 that all execution took place in the same session, and no results would be
-inserted into the buffer.
+inserted into the buffer.@footnote{As
+with all these in-buffer settings, pressing @kbd{C-c C-c} activates any
+changes in the line.}
 
 @example
 #+PROPERTY: session *R*
-- 
1.7.10.4


[-- Attachment #1.3: Type: text/plain, Size: 21 bytes --]


-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: [PATCH] Re: #+PROPERTY documentation

[Bastien]

Hi Daimrod,

Daimrod <daimrod@gmail.com> writes:

>> Thanks for your efforts!
>
> Is it better?

Yes, close to perfect.  As noted in the link I gave, you need to use
`C-x 4 a' in the section of the manual you changed in order to create
a proper ChangeLog.

In your case, the ChangeLog should start like this:

  * org.texi (Property syntax, Buffer-wide header arguments):

Also, please add only one such footnote.  Having twice the same
footnote is confusing for the readers -- if they remember "there
is a footnote for this..." they will not be able to remember if 
it was the first or the second one.  Choose the one that is the
most important -- given that the information is already available 
in another section.

> I'll also reformat my other patches.

Thanks!

-- 
 Bastien

Re: [PATCH] Re: #+PROPERTY documentation

[Daimrod]

[-- Attachment #1.1: Type: text/plain, Size: 1102 bytes --]

Bastien <bzg@altern.org> writes:

> Yes, close to perfect.  As noted in the link I gave, you need to use
> `C-x 4 a' in the section of the manual you changed in order to create
> a proper ChangeLog.

It's weird, `C-x 4 a' wasn't able to determine correctly the sections
changed. :/

> In your case, the ChangeLog should start like this:
>
>   * org.texi (Property syntax, Buffer-wide header arguments):
>
> Also, please add only one such footnote.  Having twice the same
> footnote is confusing for the readers -- if they remember "there
> is a footnote for this..." they will not be able to remember if 
> it was the first or the second one.  Choose the one that is the
> most important -- given that the information is already available 
> in another section.

You're right. I've replaced the footnote by a paragraph in (info "(org)
Property syntax") because this footnote was already present elsewhere,
and removed the footnote in (info "(org) Buffer-wide header arguments")
because there is a link to (info "(org) Property syntax").

Here is (I hope) the final patch :)


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-Update-documentation-of-buffer-wide-properties.patch --]
[-- Type: text/x-diff, Size: 996 bytes --]

From be60dcba66d24d84986ea2650c2ef6ad96d29c8e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Jadi?= <gregoire.jadi@gmail.com>
Date: Thu, 24 Jan 2013 13:04:11 +0100
Subject: [PATCH] Update documentation of buffer-wide properties

* doc/org.texi (Property syntax): Recall the user to refresh the org
  buffer when properties are set on a per-file basis.

TINYCHANGE
---
 doc/org.texi |    3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/org.texi b/doc/org.texi
index 61f1ee5..6447f9c 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -4961,6 +4961,9 @@ file, use a line like
 #+PROPERTY: NDisks_ALL 1 2 3 4
 @end example
 
+Contrary to properties set from a special drawer, you have to refresh the
+buffer with @kbd{C-c C-c} to activate this changes.
+
 If you want to add to the value of an existing property, append a @code{+} to
 the property name.  The following results in the property @code{var} having
 the value ``foo=1 bar=2''.
-- 
1.7.10.4


[-- Attachment #1.3: Type: text/plain, Size: 21 bytes --]


-- 
Daimrod/Greg

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]