emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Offline documentation (Org Manual info file) of org hooks is misleading
       [not found] <mailman.0.1687332940.25718.emacs-orgmode@gnu.org>
@ 2023-06-21  7:53 ` libreville
  2023-06-21 10:26   ` Ihor Radchenko
  0 siblings, 1 reply; 7+ messages in thread
From: libreville @ 2023-06-21  7:53 UTC (permalink / raw)
  To: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Offline documentation (Org Manual info file) of org hooks is misleading
  2023-06-21  7:53 ` Offline documentation (Org Manual info file) of org hooks is misleading libreville
@ 2023-06-21 10:26   ` Ihor Radchenko
  2023-06-21 11:17     ` libreville
  0 siblings, 1 reply; 7+ messages in thread
From: Ihor Radchenko @ 2023-06-21 10:26 UTC (permalink / raw)
  To: libreville; +Cc: emacs-orgmode

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>


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: Offline documentation (Org Manual info file) of org hooks is misleading
  2023-06-21 10:26   ` Ihor Radchenko
@ 2023-06-21 11:17     ` libreville
  2023-06-21 11:35       ` Ihor Radchenko
  0 siblings, 1 reply; 7+ messages in thread
From: libreville @ 2023-06-21 11:17 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

[-- 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


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: Offline documentation (Org Manual info file) of org hooks is misleading
  2023-06-21 11:17     ` libreville
@ 2023-06-21 11:35       ` Ihor Radchenko
  2023-06-21 11:41         ` [PATCH] " libreville
  0 siblings, 1 reply; 7+ messages in thread
From: Ihor Radchenko @ 2023-06-21 11:35 UTC (permalink / raw)
  To: libreville; +Cc: emacs-orgmode

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>


^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH] Re: Offline documentation (Org Manual info file) of org hooks is misleading
  2023-06-21 11:35       ` Ihor Radchenko
@ 2023-06-21 11:41         ` libreville
  2023-06-21 11:58           ` Ihor Radchenko
  0 siblings, 1 reply; 7+ messages in thread
From: libreville @ 2023-06-21 11:41 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

[-- 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


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH] Re: Offline documentation (Org Manual info file) of org hooks is misleading
  2023-06-21 11:58           ` Ihor Radchenko
@ 2023-06-21 11:57             ` libreville
  0 siblings, 0 replies; 7+ messages in thread
From: libreville @ 2023-06-21 11:57 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

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


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] Re: Offline documentation (Org Manual info file) of org hooks is misleading
  2023-06-21 11:41         ` [PATCH] " libreville
@ 2023-06-21 11:58           ` Ihor Radchenko
  2023-06-21 11:57             ` libreville
  0 siblings, 1 reply; 7+ messages in thread
From: Ihor Radchenko @ 2023-06-21 11:58 UTC (permalink / raw)
  To: libreville; +Cc: emacs-orgmode

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>


^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2023-06-21 11:58 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
     [not found] <mailman.0.1687332940.25718.emacs-orgmode@gnu.org>
2023-06-21  7:53 ` Offline documentation (Org Manual info file) of org hooks is misleading libreville
2023-06-21 10:26   ` Ihor Radchenko
2023-06-21 11:17     ` libreville
2023-06-21 11:35       ` Ihor Radchenko
2023-06-21 11:41         ` [PATCH] " libreville
2023-06-21 11:58           ` Ihor Radchenko
2023-06-21 11:57             ` libreville

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).