bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Michael Heerdegen]

Hello,

I have some small suggestions to make (info "(emacs) Bugs") even more
complete.

The first I want to say is that, while we are telling a lot of
(technical) details, we are missing a bit to tell what creating a bug
report means practically, how it works in general.  I mean simple things
like these that are trivial for us but still not clear to everybody:

  Basically everything works by using Email.  As the author of the bug
  report you'll be sent a CC copy of every message that belongs to that
  bug [it is important to let people know that e.g. a question of
  somebody is not necessarily addressed to the bug author].

  You can reply normally to any of those messages.  If you do so please
  be sure to keep the address that has been assigned to the bug (it
  looks like 12345@debbugs.gnu.org) in the list of recipients before
  sending your reply because else the bug tracker will not receive your
  message [lot's of people do this wrong!].

[...] parts are comments from me about the text, not part of the text.

Then I wonder if we could say that it is helpful when the author loads
relevant Elisp files before recording an Elisp backtrace [with a short
explanation of what "relevant" means, and how that can be achieved].

Hmm - I think that's already it for now.  You'll probably want to find a
better wording.


TIA,

Michael.


In GNU Emacs 30.0.50 (build 27, x86_64-pc-linux-gnu, cairo version
 1.16.0) of 2023-03-20 built on drachen
Repository revision: aa54a24570e526b5438264caacf405a2370ba9d3
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12011000
System Description: Debian GNU/Linux 11 (bullseye)

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Date: Tue, 21 Mar 2023 06:23:42 +0100
> 
> I have some small suggestions to make (info "(emacs) Bugs") even more
> complete.
> 
> The first I want to say is that, while we are telling a lot of
> (technical) details, we are missing a bit to tell what creating a bug
> report means practically, how it works in general.  I mean simple things
> like these that are trivial for us but still not clear to everybody:

"Bugs" is a catch-all chapter with almost no contents of its own; all
the real contents is in its sections.  Are your comments to that
chapter, or specifically to one of its sections, such as "Checklist"?
It is hard to think about your comments without understanding to which
part(s) of the manual are they alluding.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > The first I want to say is that, while we are telling a lot of
> > (technical) details, we are missing a bit to tell what creating a bug
> > report means practically, how it works in general.  I mean simple things
> > like these that are trivial for us but still not clear to everybody:
>
> "Bugs" is a catch-all chapter with almost no contents of its own; all
> the real contents is in its sections.  Are your comments to that
> chapter, or specifically to one of its sections, such as "Checklist"?
> It is hard to think about your comments without understanding to which
> part(s) of the manual are they alluding.

I'm just missing this kind of information in general.  This was not
intended as a comment to a specific chapter.

But I think this would fit best (and maybe only) into
(info "(emacs) Checklist") indeed.

Maybe we could just insert a short summary text like mine as new third
paragraph?

Michael.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 62320@debbugs.gnu.org
> Date: Wed, 22 Mar 2023 03:21:44 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > The first I want to say is that, while we are telling a lot of
> > > (technical) details, we are missing a bit to tell what creating a bug
> > > report means practically, how it works in general.  I mean simple things
> > > like these that are trivial for us but still not clear to everybody:
> >
> > "Bugs" is a catch-all chapter with almost no contents of its own; all
> > the real contents is in its sections.  Are your comments to that
> > chapter, or specifically to one of its sections, such as "Checklist"?
> > It is hard to think about your comments without understanding to which
> > part(s) of the manual are they alluding.
> 
> I'm just missing this kind of information in general.  This was not
> intended as a comment to a specific chapter.
> 
> But I think this would fit best (and maybe only) into
> (info "(emacs) Checklist") indeed.
> 
> Maybe we could just insert a short summary text like mine as new third
> paragraph?

I've made some changes in that section, please take a look.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> I've made some changes in that section, please take a look.

Wow - quite a few!

I've read the whole chapter again and I found nothing that I could
complain about.  You also have worked in all my suggestions - apart from
the "if you know how please load relevant Elisp source files before
capturing an Elisp backtrace" one - intentionally?

Apart from that everything looks good, but I'm not able to have an
opinion about some things (like the document structure).


I hope that the requirement to read the chapter carefully and follow all
the rules does not scare people too much (my fear is that the competent
people are more likely to be scared than the incompetent but
self-competent).  Dunno if we could try even more to encourage people
without tempting others to spread nonsense.  Maybe we could add a
sentence like "If it is sure that you have found a bug, of course we
want to hear about it even if you are not able to follow all of the
advices strictly for some reason.  Still, please do your best to take
them into account so that our developers are not required to spend more
time than necessary to understand your report."

Anyway, thanks for revising the chapter and for integrating my
suggestions.


Michael.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 62320@debbugs.gnu.org
> Date: Wed, 29 Mar 2023 17:19:03 +0200
> 
> I've read the whole chapter again and I found nothing that I could
> complain about.  You also have worked in all my suggestions - apart from
> the "if you know how please load relevant Elisp source files before
> capturing an Elisp backtrace" one - intentionally?

Maybe not.  Can you tell to which part of the text this was related?

> Apart from that everything looks good, but I'm not able to have an
> opinion about some things (like the document structure).

I've at least explained why the structure is as it is: it follows some
logic, which is now explicitly described, I hope.

> I hope that the requirement to read the chapter carefully and follow all
> the rules does not scare people too much (my fear is that the competent
> people are more likely to be scared than the incompetent but
> self-competent).

Admittedly, the text is very detailed.  I've removed what I thought
was outdated and/or unneeded, but it is still too long.  However, what
is there now is important, so all we can do is to have summaries for
the impatient and order the stuff according to decreasing importance.
If you can suggest some improvements in that direction, please do.

> Dunno if we could try even more to encourage people
> without tempting others to spread nonsense.  Maybe we could add a
> sentence like "If it is sure that you have found a bug, of course we
> want to hear about it even if you are not able to follow all of the
> advices strictly for some reason.  Still, please do your best to take
> them into account so that our developers are not required to spend more
> time than necessary to understand your report."

I'll take another look and see if there's a good place to say
something like that.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > You also have worked in all my suggestions - apart from the "if you
> > know how please load relevant Elisp source files before capturing an
> > Elisp backtrace" one - intentionally?
>
> Maybe not.  Can you tell to which part of the text this was related?

That would be in (info "(emacs) Checklist") - the first item after "If
you are willing to debug Emacs and provide additional information about
the bug, here is some useful advice".

And apart from mentioning loading related Elisp source files, I want to
say that mentioning Edebug in this first paragraph:

     This causes the error to start the Lisp debugger, which shows you a
     backtrace.  Copy the text of the debugger’s backtrace into the bug
     report.  *Note Edebug: (elisp)Edebug, for information on debugging
     Emacs Lisp programs with the Edebug package.

is a bit unfortunate - we should either say that this is a different
debugger, not to be confused with the one that pops up when enabling
`debug-on-error', or just mention Edebug at a different place (in a
footnote maybe?).


Thanks,

Michael.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 62320@debbugs.gnu.org
> Date: Thu, 30 Mar 2023 18:08:08 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > You also have worked in all my suggestions - apart from the "if you
> > > know how please load relevant Elisp source files before capturing an
> > > Elisp backtrace" one - intentionally?
> >
> > Maybe not.  Can you tell to which part of the text this was related?
> 
> That would be in (info "(emacs) Checklist") - the first item after "If
> you are willing to debug Emacs and provide additional information about
> the bug, here is some useful advice".

I remember debating whether it was important enough to have in this
already very long node.  But since now that part is near the end, as a
kind of "Advanced" section, I added that back.

> And apart from mentioning loading related Elisp source files, I want to
> say that mentioning Edebug in this first paragraph:
> 
>      This causes the error to start the Lisp debugger, which shows you a
>      backtrace.  Copy the text of the debugger’s backtrace into the bug
>      report.  *Note Edebug: (elisp)Edebug, for information on debugging
>      Emacs Lisp programs with the Edebug package.
> 
> is a bit unfortunate - we should either say that this is a different
> debugger, not to be confused with the one that pops up when enabling
> `debug-on-error', or just mention Edebug at a different place (in a
> footnote maybe?).

I tried to make it more clear that this is a different debugger.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > > > You also have worked in all my suggestions - apart from the "if
> > > > you know how please load relevant Elisp source files before
> > > > capturing an Elisp backtrace" one - intentionally?

> I remember debating whether it was important enough to have in this
> already very long node.  But since now that part is near the end, as a
> kind of "Advanced" section, I added that back.

Ok, thanks.

> >      This causes the error to start the Lisp debugger, which shows
> >      you a backtrace.  Copy the text of the debugger’s backtrace
> >      into the bug report.  *Note Edebug: (elisp)Edebug, for
> >      information on debugging Emacs Lisp programs with the Edebug
> >      package.
> > 
> > is a bit unfortunate - we should either say that this is a different
> > debugger, not to be confused with the one that pops up when enabling
> > `debug-on-error', or just mention Edebug at a different place (in a
> > footnote maybe?).
>
> I tried to make it more clear that this is a different debugger.

Looks also good to me.

So, thanks for the improvements.  From my side I would say we are done
here.


Michael.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 62320@debbugs.gnu.org
> Date: Thu, 20 Jul 2023 04:26:40 +0200
> 
> So, thanks for the improvements.  From my side I would say we are done
> here.

Thanks, closing.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > > > > You also have worked in all my suggestions - apart from the "if
  > > > > > you know how please load relevant Elisp source files before
  > > > > > capturing an Elisp backtrace" one - intentionally?

  > > I remember debating whether it was important enough to have in this
  > > already very long node.  But since now that part is near the end, as a
  > > kind of "Advanced" section, I added that back.

When a node is very long, that doesn't mean we should leave out
something useful.  Rather, it suggests we should split it up into
several shorter nodes.

Info's navigation is helpful when nodes are reasonable in size.
For long nodes, they are less helpful because they don't help
users find interesting _parts_ of a long node.

I suggest that any node over 50 lines long is a long node, so it is good
to split th enode into several nodes that are reasonable in size.
Or at least close.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, 62320@debbugs.gnu.org
> Date: Thu, 20 Jul 2023 22:42:02 -0400
> 
> I suggest that any node over 50 lines long is a long node, so it is good
> to split th enode into several nodes that are reasonable in size.
> Or at least close.

If the node enumerates a long-enough list of actions or checks that
belong to the same procedure, breaking it into several nodes makes the
reading harder.

But of course, I agree with the general principle.  Although 50 is too
small a number, IME; I think 150 is a better limit.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > If the node enumerates a long-enough list of actions or checks that
  > belong to the same procedure, breaking it into several nodes makes the
  > reading harder.

Splitting a node doesn't have to be done in the simplest way.  In a
case like that, you can divide the actions into categories (purposes?)
that meaningfully belong together, then write a subnode for each
purpose.  This offers a chance to explain them together, which is
often very helpful.


I've done this sort of thing many times, and I aim for 50 lines or
even less.

Give it a try!

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Michael Albinus]

Richard Stallman <rms@gnu.org> writes:

Hi,

> When a node is very long, that doesn't mean we should leave out
> something useful.  Rather, it suggests we should split it up into
> several shorter nodes.
>
> Info's navigation is helpful when nodes are reasonable in size.
> For long nodes, they are less helpful because they don't help
> users find interesting _parts_ of a long node.

In my texinfo files, I use @anchor inside long nodes. This allows better
references to specific information in that node.

See for example (info "(tramp)Quick Start Guide sudoedit method")

Best regards, Michael.

bug#62320: 30.0.50; Thoughts about (info "(emacs) Bugs")

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Info's navigation is helpful when nodes are reasonable in size.
  > > For long nodes, they are less helpful because they don't help
  > > users find interesting _parts_ of a long node.

  > In my texinfo files, I use @anchor inside long nodes. This allows better
  > references to specific information in that node.

I can see that it will help -- but splitting the node is a bigger
improvement.  It takes more work, but we can do it.


-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)