[Reportbug-maint] Bug#759026: Should provide working examples of reportbug.d.o usage

[Eduard Bloch]

reopen 759026
thanks

Hallo,
* Sandro Tosi [Thu, Nov 06 2014, 11:56:27AM]:

> > What I mean? The only hint is the very last paragraph in README.Users.gz
> > so one has to finde it first. There is no overview/TOC at the start of
> > this file.
> 
> searching in the file would work, as you often have to do in manpages,
> web documentations, etc.

What does this readme want to be?

A manpage? Then it should contain a SEE ALSO section and have
cross-references to different chapters when there is valuable
information to expect.

Something web-documentation like? Then it should have a TOC. And also
have relevant cross-references.

> > The file is also not really wellcomoing, it should start with
> > an abstract which explains in short what is required in order to report
> > a bug.
> 
> No, that's not the purpose of that document, for that there is
> HowToReportGoodBugs.txt

So would you please add a hyperlink or a reference in SEE ALSO section
in README.Users.gz?

> > Second, if you read the last part in an unbiased way, you will see that
> > it's not a howto. It tells you what is not to be done but it doesn't
> > explain how to make sure that it doesn't happen. For example, it tells
> 
> because it's not its purpose, it is there because we want to inform
> the user of this possibility, we don't provide an entry on "How to
> change the SMTP host in your configuration" simply because there are
> other documents about it, like the manpage

Add a reference to the correct manpage. Or do you expect the user to
read this file plus reportbug(1) plus reportbug.conf(5) before writting
a bug report?

> > you that X-Debbugs-CC has to be used. Which triggers two questions:
> >  * do I need to set it in some config file? Or via parameter? (There is no
> > --header parameter in the manpage, for example)
> 
> exactly explained in a paragraph above, "How To Specify Pseudo-Headers"

This is README.Users.gz, not README.nerds.gz. Do you expect the user to
guess that X-Debbugs-CC is a "header something" just by looking at the
string format?

> also
> 
> $ man reportbug | grep -A2 -- "-H HEADER"

Where is the reference to the manpage? I don't say that it's not
possible to find this information, it's just expects a learning curve
which is more steep than it needs to be.

> >  * does the programm still try to send a mail Cc: header? If yes, will
> >    the message be blocked? Or how am I supposed to prevent that?
> 
> if you configure reportbug to do so, yes it will.

The original text says: "The last rule, in particular, doesn't allow to
send a carbon-copy of the report to the submitter (the same email sent
to the BTS to open the bug)"

Why should a regular user expect that the server will eventually bounce
the mail, instead of simply not delivering to Cc'ed address? How should
a user know that the default config is sending CCs?

If you want to make it clear that use an appropriate wording, like:

The last rule, in particular, is that bugreports with carbon-copy (which
is the default configuration) are not delivered. To provide a contact
address, add an X-Debugs-CC header using the -H option or configuration
files (see manpage).

> > Ideally, reportbug should ship an example config which the user can just
> > copy to ~/.reportbugrc and it should just work.
> 
> Have you looked at that file? how do you expect to populate the bare

Which one?

> minimal parameters (like name, proxies, mode, etc) without /asking/
> the user? and that is done the first time reportbug is execute (ie no
> ~/.reportbugrc) or when you run it with --configure switch.

Why not, actually? It already detects the case and runs the "novice"
mode, maybe it should also ask whether the user has an established SMTP
configuration capable of sending mail via /usr/sbin/sendmail (with "in
doubt, say no").

> I'm sorry, but I found really few value in your report, except for a
> lot of complaining. If you have some real/valid suggestions (maybe

Excuse me? The subject says it all: please provide a working example,
something copy-paste friendly for ~/.reportbugrc. Is it that hard?

Or what do you want me to do, rewrite documentation? I could do that,
just tell me.

Regards,
Eduard.