Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

[Jonathan Corbet]

On Mon, 7 Nov 2016 23:13:03 -0200
Mauro Carvalho Chehab  wrote:

> Argh! PDF output is really fragile. I would change it then to:
> 
> .. [#f1] You can, optionally, provide both good and bad arguments at git
>start: ``git bisect start [BAD] [GOOD]``
> 
> Do you want me to write such patch or are you committing one yourself?

I've already made exactly that change - ahead of you for once! :)

I'm trying to track down some other weirdness, though, before I'm ready
to push docs-next.  I may have to give up soon and deal with it tomorrow.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

[Mauro Carvalho Chehab]

Em Mon, 7 Nov 2016 17:39:02 -0700
Jonathan Corbet  escreveu:

> On Mon,  7 Nov 2016 17:03:17 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > +.. [#f1] You can, optionally, provide both good and bad arguments at git
> > +start::
> > +
> > +   git bisect start [BAD] [GOOD]  
> 
> So this, as it turns out, kills the PDF build:
> 
> Markup is unsupported in LaTeX:
> admin-guide/bug-bisect:71: literal blocks in footnotes are not supported by 
> LaTeX
> Documentation/Makefile.sphinx:72: recipe for target 'latexdocs' failed
> 
> Not quite sure why I didn't run into it before, since it's not really new
> with this patch... I'll probably tack on a small fix to make things work
> again.

Argh! PDF output is really fragile. I would change it then to:

.. [#f1] You can, optionally, provide both good and bad arguments at git
 start: ``git bisect start [BAD] [GOOD]``

Do you want me to write such patch or are you committing one yourself?

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

[Mauro Carvalho Chehab]

Em Mon, 7 Nov 2016 16:55:26 -0700
Jonathan Corbet  escreveu:

> On Mon,  7 Nov 2016 17:03:17 -0200
> Mauro Carvalho Chehab  wrote:
> 
> > Better organize the admin guide documentation by moving the
> > bug bisect to a separate file.
> > 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/admin-guide/bug-bisect.rst  | 78 
> > +++
> >  Documentation/admin-guide/bug-hunting.rst | 74 
> > -
> >  Documentation/admin-guide/index.rst   |  1 +
> >  3 files changed, 79 insertions(+), 74 deletions(-)
> >  create mode 100644 Documentation/admin-guide/bug-bisect.rst
> > 
> > diff --git a/Documentation/admin-guide/bug-bisect.rst 
> > b/Documentation/admin-guide/bug-bisect.rst
> > new file mode 100644
> > index ..5682d742017c
> > --- /dev/null
> > +++ b/Documentation/admin-guide/bug-bisect.rst
> > @@ -0,0 +1,78 @@
> > +Bisecting a bug
> > 
> > +
> > +Last updated: 28 October 2016  
> 
> So I wonder if we really need lines like that?  That's what Git is for,
> especially since people often don't update the "last updated" lines...:)

Yeah, I guess we could strip those last updated on ReST files.

> 
> > +Introduction
> > +
> > +
> > +Always try the latest kernel from kernel.org and build from source. If you 
> > are
> > +not confident in doing that please report the bug to your distribution 
> > vendor
> > +instead of to a kernel developer.
> > +
> > +Finding bugs is not always easy. Have a go though. If you can't find it 
> > don't
> > +give up. Report as much as you have found to the relevant maintainer. See
> > +MAINTAINERS for who that is for the subsystem you have worked on.
> > +
> > +Before you submit a bug report read
> > +:ref:`Documentation/admin-guide/reporting-bugs.rst `.
> > +
> > +Devices not appearing
> > +=
> > +
> > +Often this is caused by udev/systemd. Check that first before blaming it
> > +on the kernel.  
> 
> A proper document should, of course, tell the poor user just how they are
> supposed to do that.  

Agreed. Well, we could add some notes here explaining more about
device probing, sysfs (and perhaps lspci), but maybe there's something
already explained on on the remaining docs.

> Anyway, I've applied the set of four.  I'm still not sure about keeping
> some of that stuff around, but the result is clearly better than what we
> had before.

Thanks! Yeah, we can improve the remaining issues later.

> One quick request: could you copy me on the 0/n cover letter when you do a
> series like this?  As it is, I get the patches, but have to go digging
> through the list for the cover.

Ok, I'll do it.

Regards,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

[Jonathan Corbet]

On Mon,  7 Nov 2016 17:03:17 -0200
Mauro Carvalho Chehab  wrote:

> +.. [#f1] You can, optionally, provide both good and bad arguments at git
> +  start::
> +
> + git bisect start [BAD] [GOOD]

So this, as it turns out, kills the PDF build:

Markup is unsupported in LaTeX:
admin-guide/bug-bisect:71: literal blocks in footnotes are not supported by 
LaTeX
Documentation/Makefile.sphinx:72: recipe for target 'latexdocs' failed

Not quite sure why I didn't run into it before, since it's not really new
with this patch... I'll probably tack on a small fix to make things work
again.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] doc-rst: admin-guide: move bug bisect to a separate file

[Jonathan Corbet]

On Mon,  7 Nov 2016 17:03:17 -0200
Mauro Carvalho Chehab  wrote:

> Better organize the admin guide documentation by moving the
> bug bisect to a separate file.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/admin-guide/bug-bisect.rst  | 78 
> +++
>  Documentation/admin-guide/bug-hunting.rst | 74 -
>  Documentation/admin-guide/index.rst   |  1 +
>  3 files changed, 79 insertions(+), 74 deletions(-)
>  create mode 100644 Documentation/admin-guide/bug-bisect.rst
> 
> diff --git a/Documentation/admin-guide/bug-bisect.rst 
> b/Documentation/admin-guide/bug-bisect.rst
> new file mode 100644
> index ..5682d742017c
> --- /dev/null
> +++ b/Documentation/admin-guide/bug-bisect.rst
> @@ -0,0 +1,78 @@
> +Bisecting a bug
> 
> +
> +Last updated: 28 October 2016

So I wonder if we really need lines like that?  That's what Git is for,
especially since people often don't update the "last updated" lines...:)

> +Introduction
> +
> +
> +Always try the latest kernel from kernel.org and build from source. If you 
> are
> +not confident in doing that please report the bug to your distribution vendor
> +instead of to a kernel developer.
> +
> +Finding bugs is not always easy. Have a go though. If you can't find it don't
> +give up. Report as much as you have found to the relevant maintainer. See
> +MAINTAINERS for who that is for the subsystem you have worked on.
> +
> +Before you submit a bug report read
> +:ref:`Documentation/admin-guide/reporting-bugs.rst `.
> +
> +Devices not appearing
> +=
> +
> +Often this is caused by udev/systemd. Check that first before blaming it
> +on the kernel.

A proper document should, of course, tell the poor user just how they are
supposed to do that.  

Anyway, I've applied the set of four.  I'm still not sure about keeping
some of that stuff around, but the result is clearly better than what we
had before.

One quick request: could you copy me on the 0/n cover letter when you do a
series like this?  As it is, I get the patches, but have to go digging
through the list for the cover.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html