[alsa-devel] [PATCH 00/13] Get rid of DocBook
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
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
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
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
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
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
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/r...
Specifically, the new Documentation/security/LSM.rst was rather short. I think your lsm.txt and this one could be likely merged.
-Kees
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/r...
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
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/r...
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:
- 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.
- 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;
- 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
participants (3)
-
Kees Cook -
Mauro Carvalho Chehab -
Takashi Iwai