RFC: additions to the article "problem-reports"

[Giorgos Keramidas]

On 2003-05-09 13:17, Mark Linimon <linimon at lonesome.com> wrote:
> Earlier I posted a suggested patch to
> /usr/doc/en_US.ISO8859-1/articles/problem-reports/article.sgml
> to the freebsd-doc newsgroup.  DES suggested that -bugbusters
> would be a more appropriate place for the discussion, so I've
> moved it here.

I noticed that.  I just had no time to write a good reply to you (at
least, as good as the marvellous work you did so far) until now.

> In doing this I've wound up looking at a _lot_ of badly-written PRs,
> and have tried to come up with suggestions on upgrading the howto.

Thanks :)

> The one thing I noticed that isn't really touched on is the diff -u
> thing.  Is it true that -u is the _only_ preferred way?

Yes.  As long as you remember not to fill long lines or reindent text
like you did here:

> -      a command or made a typo in a configuration file (though that in
> -      itself may sometimes be indicative of poor documentation or poor
> -      error handling in the application).  There are still many cases
> -      where submitting a problem report is clearly not the right
> +      a command or made a typographical error in a configuration file
> +      (though that in itself may sometimes be indicative of poor
> +      documentation or poor error handling in the application).  There
> +      are still many cases where submitting a problem report is clearly
> +      <emphasis>not</emphasis> the right

This could have been a lot easier to read as a diff had you written it as:

: @@ -63,10 +63,10 @@
:        engender a problem report.  Of course, nobody is perfect, and
:        there will be times when you are convinced you have found a bug
:        in a program when in fact you have misunderstood the syntax for
: -      a command or made a typo in a configuration file (though that in
: +      a command or made a typographical error in a configuration file (though that in
:        itself may sometimes be indicative of poor documentation or poor
:        error handling in the application).  There are still many cases
: -      where submitting a problem report is clearly not the right
: +      where submitting a problem report is clearly <emphasis>not</emphasis> the right
:        course of action, and will only serve to frustrate you and the
:        developers.  Conversely, there are cases where it might be
:        appropriate to submit a problem report about something else than

In my local version of this I've changed this to the simpler diff
version.  It's ok to let lines grow a bit horizontally if it makes it a
lot easier to read diffs.  We can wrap the long lines in a separate
commit later on, after a lot of changes like this have slipped in, to
amortise the cost stylistic changes have to the CVS tree along a series
of "content update" changes.

> +	<listitem>
> +	  <para><emphasis>Be specific.</emphasis>
> +	    [...]  You do not necessarily
> +	    have to provide your kernel configuration, which ports
> +	    you have available, and a core dump (including these
> +	    by default only tends to fill up the database), but you
> +	    should be prepared to make them available, either
> +	    privately or publicly, if so asked.</para>
> +	</listitem>

Right.  For this sentence alone, I owe you a beer or something!

> +	<listitem>
> +	  <para><emphasis>Make sure no one else has already submitted
> +	    a similar PR.</emphasis>
> +	    Although this has already been mentioned above, it bears
> +	    repeating here.  It only take a minute or two to use the
> +	    <ulink URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
> +	    web-based search engine</ulink>.  (Of course, everyone is
> +	    guilty of forgetting to do this now and then.)</para>
> +	</listitem>

I tend to prefer versions that look good both in print and in HTML.
This part (and similar <ULINK> elements) I rewrote as:

          <para><emphasis>Make sure no one else has already submitted
            a similar PR.</emphasis> Although this has already been
            mentioned above, it bears repeating here.  It only take a
            minute or two to use the web-based search engine at
            <ulink URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>.
            (Of course, everyone is guilty of forgetting to do this
            now and then.)</para> </listitem>

This way the URL appears both in the HTML version of the document
(without having to click on it), and is also rendered in nice format in
our text, ps, pdf and other non-hypertext formats :)

That's all.  I've committed a slightly modified version of this already.
Minor changes like "..." -> <quote>...</quote> and other stuff aren't
worth the bandwidth of all list members.

Great work!  Thank you Mark :-)

- Giorgos