Offline documentation (Org Manual info file) of org hooks is misleading

Offline documentation (Org Manual info file) of org hooks is misleading

[libreville]

Howdy friends,

Chapter A.1 Hooks of the Org Manual reads, in its entirety:

"Org has a large number of hook variables for adding functionality. 
This appendix illustrates using a few.  A complete list of hooks with
documentation is maintained by the Worg project at
<https://orgmode.org/worg/doc.html#hooks>."

(I have the manual for Org 9.3, the online version of the chapter is
newer, but identical at this point.)

Contrary to what it says, I couldn't find any illustrations of hook
usage in the appendix. The Variables index only refers to four, and
they're in other places.

Perhaps the line about illustrating could be deleted, to avoid sending
people on a search for something that isn't there?

Best regards,
libreville

Re: Offline documentation (Org Manual info file) of org hooks is misleading

[Ihor Radchenko]

libreville <libreville@riseup.net> writes:

> Chapter A.1 Hooks of the Org Manual reads, in its entirety:
> ...
> Contrary to what it says, I couldn't find any illustrations of hook
> usage in the appendix. The Variables index only refers to four, and
> they're in other places.
>
> Perhaps the line about illustrating could be deleted, to avoid sending
> people on a search for something that isn't there?

Agree.
Would you be interested to submit a patch?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Offline documentation (Org Manual info file) of org hooks is misleading

[libreville]

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

Here's my attempt.

It's my first time doing this, so kindly let me know if there's
something I can do better!

For example, should I have replaced the subject line of this email with
the subject in the formatted .patch?


On 2023-06-21 10:26, Ihor Radchenko wrote:
> libreville <libreville@riseup.net> writes:
> 
>> Chapter A.1 Hooks of the Org Manual reads, in its entirety:
>> ...
>> Contrary to what it says, I couldn't find any illustrations of hook
>> usage in the appendix. The Variables index only refers to four, and
>> they're in other places.
>>
>> Perhaps the line about illustrating could be deleted, to avoid sending
>> people on a search for something that isn't there?
> 
> Agree.
> Would you be interested to submit a patch?

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Delete-reference-to-non-existent-examples-of-hook-us.patch --]
[-- Type: text/x-diff; name=0001-Delete-reference-to-non-existent-examples-of-hook-us.patch, Size: 981 bytes --]

From c1fda8d0162583db709c90f01df2b8678ddc7957 Mon Sep 17 00:00:00 2001
From: libreville <libreville@riseup.net>
Date: Wed, 21 Jun 2023 13:04:19 +0200
Subject: [PATCH] Delete reference to non-existent examples of hook usage.

---
 doc/org-manual.org | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 4feb15e71..21582fe8e 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -21128,10 +21128,9 @@ of Org.
 :END:
 #+cindex: hooks
 
-Org has a large number of hook variables for adding functionality.
-This appendix illustrates using a few.  A complete list of hooks with
-documentation is maintained by the Worg project at
-https://orgmode.org/worg/doc.html#hooks.
+Org has a large number of hook variables for adding functionality.  A
+complete list of hooks with documentation is maintained by the Worg
+project at https://orgmode.org/worg/doc.html#hooks.
 
 ** Add-on Packages
 :PROPERTIES:
-- 
2.30.2

Re: Offline documentation (Org Manual info file) of org hooks is misleading

[Ihor Radchenko]

libreville <libreville@riseup.net> writes:

> Here's my attempt.

Thanks!

> It's my first time doing this, so kindly let me know if there's
> something I can do better!

Generally, we have instructions in https://orgmode.org/worg/org-contribute.html#first-patch

> For example, should I have replaced the subject line of this email with
> the subject in the formatted .patch?

Not necessarily. Although, adding [PATCH] to the subject would be
helpful as an indication.

> From c1fda8d0162583db709c90f01df2b8678ddc7957 Mon Sep 17 00:00:00 2001
> From: libreville <libreville@riseup.net>
> Date: Wed, 21 Jun 2023 13:04:19 +0200
> Subject: [PATCH] Delete reference to non-existent examples of hook usage.

1. I'd add "org-manual: ..." to indicate which part of Org is modified.
2. There is no need to end the subject (first) line with "."
3. You need to add TINYCHANGE cookie, unless you have FSF copyright
   assignment.
4. Changelog entry would be good, although this is a simple patch and we
   can skip it here.

Hope it is going to be a good practice :)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

[PATCH] Re: Offline documentation (Org Manual info file) of org hooks is misleading

[libreville]

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

Thanks a lot for the pointers.
Is this better?

On 2023-06-21 11:35, Ihor Radchenko wrote:
> libreville <libreville@riseup.net> writes:
> 
>> Here's my attempt.
> 
> Thanks!
> 
>> It's my first time doing this, so kindly let me know if there's
>> something I can do better!
> 
> Generally, we have instructions in https://orgmode.org/worg/org-contribute.html#first-patch
> 
>> For example, should I have replaced the subject line of this email with
>> the subject in the formatted .patch?
> 
> Not necessarily. Although, adding [PATCH] to the subject would be
> helpful as an indication.
> 
>> From c1fda8d0162583db709c90f01df2b8678ddc7957 Mon Sep 17 00:00:00 2001
>> From: libreville <libreville@riseup.net>
>> Date: Wed, 21 Jun 2023 13:04:19 +0200
>> Subject: [PATCH] Delete reference to non-existent examples of hook usage.
> 
> 1. I'd add "org-manual: ..." to indicate which part of Org is modified.
> 2. There is no need to end the subject (first) line with "."
> 3. You need to add TINYCHANGE cookie, unless you have FSF copyright
>    assignment.
> 4. Changelog entry would be good, although this is a simple patch and we
>    can skip it here.
> 
> Hope it is going to be a good practice :)

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-manual.org-Delete-ref-to-non-existent-examples-o.patch --]
[-- Type: text/x-diff; name=0001-org-manual.org-Delete-ref-to-non-existent-examples-o.patch, Size: 1187 bytes --]

From 6d0ade6af4ec4ab2fd8be578dd8851fae9e91253 Mon Sep 17 00:00:00 2001
From: libreville <libreville@riseup.net>
Date: Wed, 21 Jun 2023 13:04:19 +0200
Subject: [PATCH] org-manual.org: Delete ref to non-existent examples of hook
 usage

 Date:      Wed Jun 21 13:04:19 2023 +0200
 Changes to be committed:
	modified:   doc/org-manual.org

* org-manual.org:  Delete ref to non-existent examples of hook usage in
A.1 Hooks

TINYCHANGE
---
 doc/org-manual.org | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 4feb15e71..21582fe8e 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -21128,10 +21128,9 @@ of Org.
 :END:
 #+cindex: hooks
 
-Org has a large number of hook variables for adding functionality.
-This appendix illustrates using a few.  A complete list of hooks with
-documentation is maintained by the Worg project at
-https://orgmode.org/worg/doc.html#hooks.
+Org has a large number of hook variables for adding functionality.  A
+complete list of hooks with documentation is maintained by the Worg
+project at https://orgmode.org/worg/doc.html#hooks.
 
 ** Add-on Packages
 :PROPERTIES:
-- 
2.30.2

Re: [PATCH] Re: Offline documentation (Org Manual info file) of org hooks is misleading

[Ihor Radchenko]

libreville <libreville@riseup.net> writes:

> Thanks a lot for the pointers.
> Is this better?

Yup. Thanks!

Applied, onto main, with amendment.

I have removed

>  Date:      Wed Jun 21 13:04:19 2023 +0200
>  Changes to be committed:
> 	modified:   doc/org-manual.org

I have also fixed the changelog entry and added "." at the end of the
sentence there.

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=eab92e8f7

You are now listed in the contributor list.
https://git.sr.ht/~bzg/worg/commit/3f85dd4c

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [PATCH] Re: Offline documentation (Org Manual info file) of org hooks is misleading

[libreville]

Great! Thanks for the help and nice working with you. :)

On 2023-06-21 11:58, Ihor Radchenko wrote:
> libreville <libreville@riseup.net> writes:
> 
>> Thanks a lot for the pointers.
>> Is this better?
> 
> Yup. Thanks!
> 
> Applied, onto main, with amendment.
> 
> I have removed
> 
>>  Date:      Wed Jun 21 13:04:19 2023 +0200
>>  Changes to be committed:
>> 	modified:   doc/org-manual.org
> 
> I have also fixed the changelog entry and added "." at the end of the
> sentence there.
> 
> https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=eab92e8f7
> 
> You are now listed in the contributor list.
> https://git.sr.ht/~bzg/worg/commit/3f85dd4c