Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1487945

Re: [PATCH v4 00/29] Create a book for Kernel development

Show all headers | View raw

Em Tue, 20 Sep 2016 18:44:54 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon, 19 Sep 2016 08:07:34 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > That's the 4th version of this series. It also contains a second patch series
> > with more ReST conversions and documentation improvements.
> > This patchset merges the content of a second patch series:
> > 
> > 	[PATCH 00/17] Improve documentation for the development-process
> >   
> 
> OK, I'm applying these through 28; I'm going to hold off on #29.  Thanks
> for separating that part out so nicely.
> 
> > I opted to keep the patch changing the  kernel-docs.txt changes
> > (patch 21/29). The patch is already written and another patch
> > (patch 22/29)  depends on it, because there are references to
> > this file at Documentation/HOWTO.
> >
> > It shouldn't be hard  to get rid of it, but I'm not sure if worths
> > the effort. As I commented, people might find useful to update
> > it to point to more modern documents. If people won't do it,
> > it can still be removed from the Kernel a the next Kernel version.  
> 
> I'll take them for now, since there seems to be interest in doing something
> with this document.  I kept the applying-patches one as well.  But I do
> think that we need to start being a bit more willing to get rid of musty
> old docs.  We don't carry unused code because "it might be useful to
> somebody"; I think we should take the same approach to docs.  Out-of-date
> or irrelevant docs are a maintenance burden, and they impose a heavy burden
> on the people the docs are most meant to help...
> 
> A few notes:
> 
> #1 didn't apply, I had to do it by hand.  I suspect my late application of
> Marcus's work got in the way there.
> 
> #2 had this:
> 
> > Content-Type: text/plain; charset=true  
> 
> ...which threw git am for a loop; I had to fix it manually.  What gives
> there?

That's really weird! I did only the usual stuff here... patches created
with git format-patch and C/C added via get_maintainers.pl. The
resulting patch is sent via:
	git send-email patches/tmp

I double-checked: the patches created are without any Content-Type:.
It is git send-email (git-2.7.4-2.fc24.x86_64) that added those:

	Content-Type: text/plain; charset=true
	Content-Transfer-Encoding: 8bit

I'll try to investigate what's wrong there or otherwise check if
the upstream version from git's repository works better.

> 
> #4 didn't apply and had to be done by hand.
> 
> #10 (CodingStyle) has a lot of ".. code-block:: c" constructs.  Why are
> those needed?  We're still using C by default for literal blocks, right?

I opted to keep the code-block there, because, at least on one of the
blocks, we had to use:

	.. code-block:: none

Because pygments were doing weird highlights on it. So, for coherency,
I ended by keeping it all along.

> 
> #15 (SecurityBugs) leaves the section numbers in place; did you intend
> that?

Yes. Since we remove the :numbered:, and this document had already
the sections numbered manually, I opted to preserve.

Yet, I don't see anything special there that would justify
numbering. So, I guess we can just remove it.

> #21 (kernel-docs.txt) had the charset=true weirdness
> 
> #28 actually, I balked at applying this one, since it assumes that
>     the great renaming is taking place, and that hasn't happened yet.

Oh! Ok, I'll fix this one, removing the rename stuff from the
conversion and resend.

> So actually I only went through #27, but that took a long time - seemingly
> longer than it takes you to create them! :)

Sorry for that. I'll try to make it easier for you next time.

> A few of the patches still have the bare "::" lines in them; I think I'll
> just add a patch to fix those up real quick.

OK.

Thanks,
Mauro

Back to linux.kernel | Previous | Next — Previous in thread | Find similar | Unroll thread

Thread

[PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 09/29] Documentation/Changes: add minimal requirements for documentation build Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 01/29] doc-rst: add CSS styles for :kbd: and :menuselection: Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 08/29] Documentation/Changes: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 03/29] doc: development-process: rename files to rst Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 04/29] docs-rst: create a book for the development process Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 05/29] Documentation/HOWTO: convert to ReST notation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 06/29] Documentation/applying-patches.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
  [PATCH v4 28/29] Documentation/email-clients.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 25/29] Documentation/HOWTO: adjust external link references Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 11/29] Documentation/CodingStyle: use the proper tag for verbatim font Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 14/29] Documentation/ManagementStyle: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
    Re: [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert  it to ReST markup Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
  [PATCH v4 12/29] Documentation/CodingStyle: replace underline markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 27/29] Documentation/SubmitChecklist: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 02/29] doc: development-process: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 16/29] Documentation/stable_api_nonsense.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 20/29] Documentation/SubmittingPatches: enrich the Sphinx output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 07/29] Documentation/applying-patches.txt: Update the information there Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 10/29] Documentation/CodingStyle: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 24/29] Documentation/HOWTO: improve some markups to make it visually better Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 13/29] Documentation/CodingStyle: use the .. note:: markup where needed Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 23/29] Documentation/HOWTO: update information about generating documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
    Re: [PATCH v4 22/29] Documentation/HOWTO: add cross-references to  other documents Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
  [PATCH v4 26/29] Documentation/SubmitChecklist: update kernel-doc task Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 15/29] Documentation/SecurityBugs: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 19/29] Documentation/SubmittingPatches: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  [PATCH v4 18/29] Documentation/SubmittingDrivers: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
  Re: [PATCH v4 00/29] Create a book for Kernel development Jonathan Corbet <corbet@lwn.net> - 2016-09-21 02:50 +0200
    Re: [PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-21 11:30 +0200

csiph-web