[PATCH 00/13] Get rid of DocBook

[PATCH 00/13] Get rid of DocBook

[Mauro Carvalho Chehab]

As just one book (lsm) was missing conversion, let's convert it
and store as if it were a plain text file under Documentation/lsm.txt,
adding a notice that it requires update.

This way, as everything is now converted, we can get rid of
the DocBook building system and update places that were
mentioning it.

PS.: We could also remove the parts of the kernel-doc script that
produce DocBook outputs, but, as this might still be useful
for someone, for now let's just keep the functionality there.

-

This patch series is based on my past 00/05 and 00/36 patch series
that convert the other DocBooks to ReST, applied on the top of 
docs tree (next branch).

The full patch series is on this tree is at:

   https://git.linuxtv.org//mchehab/experimental.git/log/?h=docbook2

And the HTML output at:

  http://www.infradead.org/~mchehab/kernel_docs/
  https://mchehab.fedorapeople.org/kernel_docs/ 

Mauro Carvalho Chehab (13):
  docs-rst: convert lsm from DocBook to ReST
  docs: remove DocBook from the building system
  docs: update old references for DocBook from the documentation
  MAINTAINERS: update old references for DocBook directory
  ata: update references for libata documentation
  ia64, scsi: update references for the device-io book
  irq: update genericirq book location
  fs: update location of filesystems documentation
  lib: update location of kgdb documentation
  sound: fix the comments that refers to kernel-doc
  fs: fix the location of the kernel-api book
  usb: fix the comment with regards to DocBook
  docs-rst: get rid of Documentation/sphinx/tmplcvt script

 Documentation/00-INDEX                     |   6 +-
 Documentation/DocBook/.gitignore           |  17 --
 Documentation/DocBook/Makefile             | 276 -----------------------------
 Documentation/DocBook/lsm.tmpl             | 265 ---------------------------
 Documentation/DocBook/stylesheet.xsl       |  11 --
 Documentation/Makefile                     | 125 +++++++++++++
 Documentation/Makefile.sphinx              | 130 --------------
 Documentation/PCI/MSI-HOWTO.txt            |   2 +-
 Documentation/admin-guide/README.rst       |   6 -
 Documentation/doc-guide/docbook.rst        |  90 ----------
 Documentation/doc-guide/index.rst          |   1 -
 Documentation/doc-guide/sphinx.rst         |   5 -
 Documentation/fb/api.txt                   |   4 +-
 Documentation/gpu/todo.rst                 |   2 +-
 Documentation/kernel-doc-nano-HOWTO.txt    |  65 ++-----
 Documentation/lsm.txt                      | 201 +++++++++++++++++++++
 Documentation/process/changes.rst          |  26 +--
 Documentation/process/howto.rst            |   8 -
 Documentation/process/kernel-docs.rst      |  34 +---
 Documentation/sphinx/tmplcvt               |  28 ---
 Documentation/translations/ja_JP/howto.rst |   7 -
 Documentation/translations/ko_KR/howto.rst |   7 -
 MAINTAINERS                                |   5 +-
 Makefile                                   |  11 +-
 arch/ia64/include/asm/io.h                 |   2 +-
 arch/ia64/sn/kernel/iomv.c                 |   2 +-
 drivers/ata/acard-ahci.c                   |   2 +-
 drivers/ata/ahci.c                         |   2 +-
 drivers/ata/ahci.h                         |   2 +-
 drivers/ata/ata_piix.c                     |   2 +-
 drivers/ata/libahci.c                      |   2 +-
 drivers/ata/libata-core.c                  |   2 +-
 drivers/ata/libata-eh.c                    |   2 +-
 drivers/ata/libata-scsi.c                  |   2 +-
 drivers/ata/libata-sff.c                   |   2 +-
 drivers/ata/libata.h                       |   2 +-
 drivers/ata/pata_pdc2027x.c                |   2 +-
 drivers/ata/pdc_adma.c                     |   2 +-
 drivers/ata/sata_nv.c                      |   2 +-
 drivers/ata/sata_promise.c                 |   2 +-
 drivers/ata/sata_promise.h                 |   2 +-
 drivers/ata/sata_qstor.c                   |   2 +-
 drivers/ata/sata_sil.c                     |   2 +-
 drivers/ata/sata_sis.c                     |   2 +-
 drivers/ata/sata_svw.c                     |   2 +-
 drivers/ata/sata_sx4.c                     |   2 +-
 drivers/ata/sata_uli.c                     |   2 +-
 drivers/ata/sata_via.c                     |   2 +-
 drivers/ata/sata_vsc.c                     |   2 +-
 drivers/scsi/qla1280.c                     |   2 +-
 drivers/usb/gadget/Kconfig                 |   2 +-
 fs/debugfs/file.c                          |   2 +-
 fs/debugfs/inode.c                         |   2 +-
 include/linux/ata.h                        |   2 +-
 include/linux/debugfs.h                    |   2 +-
 include/linux/libata.h                     |   2 +-
 include/sound/pcm.h                        |   2 +-
 kernel/irq/chip.c                          |   2 +-
 kernel/irq/handle.c                        |   2 +-
 kernel/irq/irqdesc.c                       |   2 +-
 lib/Kconfig.debug                          |   2 +-
 lib/Kconfig.kgdb                           |   2 +-
 scripts/Makefile                           |   9 +-
 scripts/check-lc_ctype.c                   |  11 --
 64 files changed, 396 insertions(+), 1032 deletions(-)
 delete mode 100644 Documentation/DocBook/.gitignore
 delete mode 100644 Documentation/DocBook/Makefile
 delete mode 100644 Documentation/DocBook/lsm.tmpl
 delete mode 100644 Documentation/DocBook/stylesheet.xsl
 delete mode 100644 Documentation/Makefile.sphinx
 delete mode 100644 Documentation/doc-guide/docbook.rst
 create mode 100644 Documentation/lsm.txt
 delete mode 100755 Documentation/sphinx/tmplcvt
 delete mode 100644 scripts/check-lc_ctype.c

-- 
2.9.3


_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

[PATCH 10/13] sound: fix the comments that refers to kernel-doc

[Mauro Carvalho Chehab]

The markup inside the #if 0 comment actually refers to a
kernel-doc markup. As we're getting rid of DocBook update it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
 include/sound/pcm.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/sound/pcm.h b/include/sound/pcm.h
index 361749e60799..bbf97d4c4c17 100644
--- a/include/sound/pcm.h
+++ b/include/sound/pcm.h
@@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
 int snd_pcm_format_linear(snd_pcm_format_t format);
 int snd_pcm_format_little_endian(snd_pcm_format_t format);
 int snd_pcm_format_big_endian(snd_pcm_format_t format);
-#if 0 /* just for DocBook */
+#if 0 /* just for kernel-doc */
 /**
  * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
  * @format: the format to check
-- 
2.9.3

Re: [PATCH 00/13] Get rid of DocBook

[Kees Cook]

On Sun, May 14, 2017 at 8:38 AM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
> As just one book (lsm) was missing conversion, let's convert it
> and store as if it were a plain text file under Documentation/lsm.txt,
> adding a notice that it requires update.

I could probably fold this change into my rst-ification of
Documentation/security/

https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git/log/?h=kspp/rst

Specifically, the new Documentation/security/LSM.rst was rather short.
I think your lsm.txt and this one could be likely merged.

-Kees

-- 
Kees Cook
Pixel Security
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 00/13] Get rid of DocBook

[Mauro Carvalho Chehab]

Em Sun, 14 May 2017 14:05:09 -0700
Kees Cook <keescook@chromium.org> escreveu:

> On Sun, May 14, 2017 at 8:38 AM, Mauro Carvalho Chehab
> <mchehab@s-opensource.com> wrote:
> > As just one book (lsm) was missing conversion, let's convert it
> > and store as if it were a plain text file under Documentation/lsm.txt,
> > adding a notice that it requires update.
> 
> I could probably fold this change into my rst-ification of
> Documentation/security/
> 
> https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git/log/?h=kspp/rst
> 
> Specifically, the new Documentation/security/LSM.rst was rather short.
> I think your lsm.txt and this one could be likely merged.

Yeah, makes sense. I'm not sure what would be the best way to
proceed, as, currently, after removing lsm.tmpl, my patch
series remove DocBook, as everything else was already removed.

I see a few ways for us to proceed:

1) You could submit the patches you have so far to docs -next,
to be merged before my patch series;

2) I could send you a patch based on your tree. I'll need to
rebase this series to be applied on the top of your tree + docs-next, 
with would require that your patch series would be merged before,
at docs -next;

3) we can handle both series independently. When both gets
merged at docs -next, a simple patch, either written by you or
me, could merge both files.

IMO, (3) is simpler, but if you prefer, we can do on some other
way.

Thanks,
Mauro
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

[Takashi Iwai]

On Sun, 14 May 2017 17:38:44 +0200,
Mauro Carvalho Chehab wrote:
> 
> The markup inside the #if 0 comment actually refers to a
> kernel-doc markup. As we're getting rid of DocBook update it.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

I guess you prefer taking it from your tree?  Feel free to take my
ack:
  Reviewed-by: Takashi Iwai <tiwai@suse.de>


thanks,

Takashi

> ---
>  include/sound/pcm.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/sound/pcm.h b/include/sound/pcm.h
> index 361749e60799..bbf97d4c4c17 100644
> --- a/include/sound/pcm.h
> +++ b/include/sound/pcm.h
> @@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
>  int snd_pcm_format_linear(snd_pcm_format_t format);
>  int snd_pcm_format_little_endian(snd_pcm_format_t format);
>  int snd_pcm_format_big_endian(snd_pcm_format_t format);
> -#if 0 /* just for DocBook */
> +#if 0 /* just for kernel-doc */
>  /**
>   * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
>   * @format: the format to check
> -- 
> 2.9.3
> 
> 

Re: [PATCH 00/13] Get rid of DocBook

[Kees Cook]

On Sun, May 14, 2017 at 3:00 PM, Mauro Carvalho Chehab
<mchehab@s-opensource.com> wrote:
> Em Sun, 14 May 2017 14:05:09 -0700
> Kees Cook <keescook@chromium.org> escreveu:
>
>> On Sun, May 14, 2017 at 8:38 AM, Mauro Carvalho Chehab
>> <mchehab@s-opensource.com> wrote:
>> > As just one book (lsm) was missing conversion, let's convert it
>> > and store as if it were a plain text file under Documentation/lsm.txt,
>> > adding a notice that it requires update.
>>
>> I could probably fold this change into my rst-ification of
>> Documentation/security/
>>
>> https://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git/log/?h=kspp/rst
>>
>> Specifically, the new Documentation/security/LSM.rst was rather short.
>> I think your lsm.txt and this one could be likely merged.
>
> Yeah, makes sense. I'm not sure what would be the best way to
> proceed, as, currently, after removing lsm.tmpl, my patch
> series remove DocBook, as everything else was already removed.
>
> I see a few ways for us to proceed:
>
> 1) You could submit the patches you have so far to docs -next,
> to be merged before my patch series;

I sent my series already (it got CCed to linux-doc); it's collected a
few Acks already. I'm not sure what the timing for that means, though.

> 2) I could send you a patch based on your tree. I'll need to
> rebase this series to be applied on the top of your tree + docs-next,
> with would require that your patch series would be merged before,
> at docs -next;
>
> 3) we can handle both series independently. When both gets
> merged at docs -next, a simple patch, either written by you or
> me, could merge both files.

I don't see a reason for us to make the trees depend on each other.
Let's just proceed as-is and whenever we're in a position to merge the
LSM docs, we can do that.

> IMO, (3) is simpler, but if you prefer, we can do on some other
> way.

Agreed.

-Kees

-- 
Kees Cook
Pixel Security
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/dri-devel

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

[Mauro Carvalho Chehab]

Em Mon, 15 May 2017 11:04:26 +0200
Takashi Iwai <tiwai@suse.de> escreveu:

> On Sun, 14 May 2017 17:38:44 +0200,
> Mauro Carvalho Chehab wrote:
> > 
> > The markup inside the #if 0 comment actually refers to a
> > kernel-doc markup. As we're getting rid of DocBook update it.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>  
> 
> I guess you prefer taking it from your tree?  Feel free to take my
> ack:
>   Reviewed-by: Takashi Iwai <tiwai@suse.de>

In the specific case of this patch, it doesn't matter much from what
tree it would be merged, as no other patch depends on it ;)

So, if you prefer, you can merge it directly on your tree. Otherwise,
I'll keep it on my pile of patches to be send to docs -next.


> 
> 
> thanks,
> 
> Takashi
> 
> > ---
> >  include/sound/pcm.h | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/include/sound/pcm.h b/include/sound/pcm.h
> > index 361749e60799..bbf97d4c4c17 100644
> > --- a/include/sound/pcm.h
> > +++ b/include/sound/pcm.h
> > @@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
> >  int snd_pcm_format_linear(snd_pcm_format_t format);
> >  int snd_pcm_format_little_endian(snd_pcm_format_t format);
> >  int snd_pcm_format_big_endian(snd_pcm_format_t format);
> > -#if 0 /* just for DocBook */
> > +#if 0 /* just for kernel-doc */
> >  /**
> >   * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
> >   * @format: the format to check
> > -- 
> > 2.9.3
> > 
> >   



Thanks,
Mauro

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

[Takashi Iwai]

On Tue, 16 May 2017 12:46:53 +0200,
Mauro Carvalho Chehab wrote:
> 
> Em Mon, 15 May 2017 11:04:26 +0200
> Takashi Iwai <tiwai@suse.de> escreveu:
> 
> > On Sun, 14 May 2017 17:38:44 +0200,
> > Mauro Carvalho Chehab wrote:
> > > 
> > > The markup inside the #if 0 comment actually refers to a
> > > kernel-doc markup. As we're getting rid of DocBook update it.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>  
> > 
> > I guess you prefer taking it from your tree?  Feel free to take my
> > ack:
> >   Reviewed-by: Takashi Iwai <tiwai@suse.de>
> 
> In the specific case of this patch, it doesn't matter much from what
> tree it would be merged, as no other patch depends on it ;)
> 
> So, if you prefer, you can merge it directly on your tree. Otherwise,
> I'll keep it on my pile of patches to be send to docs -next.

OK, since the PCM stuff is being changed for 4.13, may be it's safer
that I take this patch in sound git tree.


thanks,

Takashi

> 
> 
> > 
> > 
> > thanks,
> > 
> > Takashi
> > 
> > > ---
> > >  include/sound/pcm.h | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > > 
> > > diff --git a/include/sound/pcm.h b/include/sound/pcm.h
> > > index 361749e60799..bbf97d4c4c17 100644
> > > --- a/include/sound/pcm.h
> > > +++ b/include/sound/pcm.h
> > > @@ -1054,7 +1054,7 @@ int snd_pcm_format_unsigned(snd_pcm_format_t format);
> > >  int snd_pcm_format_linear(snd_pcm_format_t format);
> > >  int snd_pcm_format_little_endian(snd_pcm_format_t format);
> > >  int snd_pcm_format_big_endian(snd_pcm_format_t format);
> > > -#if 0 /* just for DocBook */
> > > +#if 0 /* just for kernel-doc */
> > >  /**
> > >   * snd_pcm_format_cpu_endian - Check the PCM format is CPU-endian
> > >   * @format: the format to check
> > > -- 
> > > 2.9.3
> > > 
> > >   
> 
> 
> 
> Thanks,
> Mauro
> 

Re: [PATCH 10/13] sound: fix the comments that refers to kernel-doc

[Mauro Carvalho Chehab]

Em Tue, 16 May 2017 12:50:55 +0200
Takashi Iwai <tiwai@suse.de> escreveu:

> On Tue, 16 May 2017 12:46:53 +0200,
> Mauro Carvalho Chehab wrote:
> > 
> > Em Mon, 15 May 2017 11:04:26 +0200
> > Takashi Iwai <tiwai@suse.de> escreveu:
> >   
> > > On Sun, 14 May 2017 17:38:44 +0200,
> > > Mauro Carvalho Chehab wrote:  
> > > > 
> > > > The markup inside the #if 0 comment actually refers to a
> > > > kernel-doc markup. As we're getting rid of DocBook update it.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>    
> > > 
> > > I guess you prefer taking it from your tree?  Feel free to take my
> > > ack:
> > >   Reviewed-by: Takashi Iwai <tiwai@suse.de>  
> > 
> > In the specific case of this patch, it doesn't matter much from what
> > tree it would be merged, as no other patch depends on it ;)
> > 
> > So, if you prefer, you can merge it directly on your tree. Otherwise,
> > I'll keep it on my pile of patches to be send to docs -next.  
> 
> OK, since the PCM stuff is being changed for 4.13, may be it's safer
> that I take this patch in sound git tree.

OK! I'll remove from my patch pile :-)

Thanks,
Mauro