Re: [PATCH 40/41] Documentation: x86: fix spelling mistakes

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:37:06 +0100
Eric Engestrom  wrote:

>  Documentation/x86/intel_mpx.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Applied to the docs tree, 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

Re: [PATCH 41/41] Documentation: xillybus: fix spelling mistake

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:37:07 +0100
Eric Engestrom  wrote:

>  Documentation/xillybus.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied to the docs tree, 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

Re: [PATCH 32/41] Documentation: pps: fix spelling mistake

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:36:58 +0100
Eric Engestrom  wrote:

>  Documentation/pps/pps.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Applied to the docs tree, 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

Re: [PATCH 39/41] Documentation: vm: fix spelling mistakes

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:37:05 +0100
Eric Engestrom  wrote:

>  Documentation/vm/transhuge.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)

Applied to the docs tree, 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

Re: [PATCH 35/41] Documentation: scsi: fix spelling mistakes

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:37:01 +0100
Eric Engestrom  wrote:

>  Documentation/scsi/ChangeLog.megaraid_sas | 16 
>  1 file changed, 8 insertions(+), 8 deletions(-)

Applied to the docs tree (after fixing trailing whitespace errors - the
new and the old ones).

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 34/41] Documentation: robust-futexes: fix spelling mistakes

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:37:00 +0100
Eric Engestrom  wrote:

>  Documentation/robust-futexes.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)

Applied to the docs tree, 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

Re: [PATCH 27/41] Documentation: laptops: fix spelling mistake

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:36:53 +0100
Eric Engestrom  wrote:

> -laptops, being called "Toshiba HDD Protection - Shock Sensor" officialy,
> +laptops, being called "Toshiba HDD Protection - Shock Sensor" officially,

Applied to the docs tree, 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

Re: [PATCH 29/41] Documentation: lzo: fix spelling mistakes

[Jonathan Corbet]

On Mon, 25 Apr 2016 07:36:55 +0100
Eric Engestrom  wrote:

>  Documentation/lzo.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Applied to the docs tree, 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

Re: [PATCH v2] hrtimers: doc cleanup

[Jonathan Corbet]

On Thu, 21 Apr 2016 21:39:15 +0800
Cao jin  wrote:

> It has:
> a tense correction(led->leads);
> a typo(unevitably->inevitably);

I've applied this to the docs tree, 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

Re: [PATCH] Changed the path from to the incorrect drivers/char/sysrq.c to drivers/tty/sysrq.c

[Jonathan Corbet]

On Fri, 22 Apr 2016 21:17:23 +0200
René Nyffenegger  wrote:

> This is my first patch submission. Please let me know if I have made a 
> mistake anywhere.

Thank you for improving the documentation!

Unfortunately, the patch was corrupted by your mail client and does not
apply.  Could I please ask you to have a look at
Documentation/email-clients.txt for information on how to send patches so
that they arrive intact at the other end?  A good approach is to email
the patch to yourself and ensure that the result applies before trying
again.

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

Re: [PATCH v2 0/2] moves samples out of Documentation directory

[Jonathan Corbet]

On Mon, 25 Apr 2016 18:03:07 +0200
Arnd Bergmann  wrote:

> As suggested by Nicolas Pitre, here is a resend of two patches to
> move the kernel modules from Documentation/*/ to samples/*/.
> 
> With Nico's changes in place, it's no longer necessary to do this,
> but it seems like a good idea anyway for consistency.
> Not sure who would be the best person to pick up the patches, I'd
> probably either the Documentation or the kbuild maintainers.
> 
>   Arnd
> 
> [PATCH v2 1/2] samples: connector: from Documentation to samples
> [PATCH v2 2/2] samples: v4l: from Documentation to samples directory

I can take them through the docs tree.

Hans [added], are you OK with moving v4l2-pci-skeleton.c over to
the samples directory?

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

Re: [PATCH] Mark "Out of Date" addresses as undeliverable

[Jonathan Corbet]

On Thu, 21 Apr 2016 23:04:26 +0800
Zhigang Gao  wrote:

>  Chinese maintainer for help.  Contact the Chinese maintainer, if this
>  translation is outdated or there is problem with translation.
>  
> -Chinese maintainer: Zhang Le 
> +Chinese maintainer: Zhang Le  

So this makes me a little uncomfortable...the document now says to
contact somebody who cannot be contacted.  It's a promise of help that is
empty.  If Zhang Le has truly vanished, and nobody else is willing to
fill in, I think it would be better to simply delete this text.

> -   Li Zefan 
> -   Wang Chen 
> +   Li Zefan  
> +   Wang Chen  

Zefan, at least, is trivially findable at his new address (copied);
Zefan, I assume you would like things updated here?  Which address would
you like to use?

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

Re: [PATCH] hrtimers: doc cleanup

[Jonathan Corbet]

On Thu, 21 Apr 2016 18:25:41 +0800
Cao jin  wrote:

> > This change is incorrect - "unacceptable" is exactly what the writer
> > wanted to say here.
> >  
> *it cannot be 'designed out' without inevitably degrading other portions 
> of the timers.c code in an unacceptable way*
> 
> equals
> 
> *it can be 'designed out' ... in an acceptable way*, I think.
> 
> So, just from semantics, my feeling is, *it cannot be 'designed out' in 
> an acceptable way* is the reason why integration is hard. Am I still wrong?

The original author, clearly, was talking about the degradation being
unacceptable.  It seems clear enough, I don't think that change should be
made.

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

Re: [PATCH] hrtimers: doc cleanup

[Jonathan Corbet]

On Thu, 21 Apr 2016 17:09:54 +0800
Cao jin  wrote:

> -  wheel concept, it cannot be 'designed out' without unevitably
> -  degrading other portions of the timers.c code in an unacceptable way.
> +  wheel concept, it cannot be 'designed out' without inevitably
> +  degrading other portions of the timers.c code in an acceptable way.

This change is incorrect - "unacceptable" is exactly what the writer
wanted to say here.

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] documentation: trivial typo: adding-syscalls.txt: s/statat/fstatat/

[Jonathan Corbet]

On Mon, 18 Apr 2016 20:30:56 +0300
Askar Safin  wrote:

> -page; for an example of AT_EMPTY_PATH, see the statat(2) man page.)
> +page; for an example of AT_EMPTY_PATH, see the fstatat(2) man page.)

Applied to the docs tree, 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

Re: [PATCH] Documentatio: HOWTO: remove regression postings info from translations

[Jonathan Corbet]

On Sat, 16 Apr 2016 09:18:46 +0900
SeongJae Park  wrote:

> Obsolete info about regression postings were removed by commit
> 5645a717c6ee61e67d38aa9f15cb9db074e1e99d ("Documentation: HOWTO: remove
> obsolete info about regression postings") but not applied to
> translations.  This commit applies the change to translations.

I've applied both patches to the docs tree, 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

Re: [PATCH 4/4] serial: doc: .break_ctl() may sleep

[Jonathan Corbet]

On Fri, 15 Apr 2016 15:31:30 -0700
Peter Hurley  wrote:

> The only caller of the uart driver's break_ctl() method is
> uart_break_ctl(), which is serial core's proxy tty driver break_ctl()
> method. uart_break_ctl() claims the struct tty_port::mutex to prevent
> concurrent tiocmset().
> 
> Thus, the uart driver's break_ctl() method won't be called in atomic
> context.

I'm missing something here.  I can fully believe that uart_break_ctl()
won't call break_ctl() in atomic context, but the fact that it holds a
mutex in no way guarantees that.  If uart_break_ctl() makes that promise
we should just say so.

Sorry to be obnoxious, but I'd rather not put confusing stuff into the
changelog if possible.

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 4/4] serial: doc: .break_ctl() may sleep

[Jonathan Corbet]

On Thu, 14 Apr 2016 11:08:11 +0200
Geert Uytterhoeven  wrote:

> As mutex_lock() must not be called with interrupts disabled,
> .break_ctl() may sleep.

So I've applied the first three to the docs tree, but this one stopped
me.  The changelog doesn't really say why the patch is correct; what we
really need to know is that break_ctl() won't be called in atomic
context.  I'm assuming that's the case, but if it truly is, can I get a
version with a changelog saying that?

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

Re: [PATCH v2 2/5] Documentation: update Michael K. Johnson's work

[Jonathan Corbet]

On Thu, 31 Mar 2016 12:10:30 +0100
Luis de Bethencourt  wrote:

> The URL for "Writing Linux Device Drivers" hasn't been available in some
> time. Updating the entry to Michael K. Johnson's "Linux Kernel Hackers'
> Guide"

OK, I've applied this one to the docs tree.

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

Re: [PATCH v3] ARM64: ACPI: Update documentation for latest specification version

[Jonathan Corbet]

On Mon, 28 Mar 2016 18:06:42 -0600
Al Stone  wrote:

> This patch reflects going back through and examining the specs in detail
> and updating content appropriately.  Whilst there, a few odds and ends of
> typos were caught as well.  This brings the documentation up to date with
> ACPI 6.1 for arm64.

So I'll happily pull this into the docs tree if that seems like the right
place for it.  I'd really like to see an ack or two first, though, since
I'm not really in a position to review it properly myself.

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

Re: [PATCH 0/9] serial: doc: Low Level Serial API Documentation Improvements

[Jonathan Corbet]

On Mon, 14 Mar 2016 16:16:08 +0100
Geert Uytterhoeven  wrote:

> This patch series contains improvements to the low level serial driver
> API documentation.

Hearing no objections, I've applied the set to the docs tree, 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

Re: [RFC v2] Documentation: mmc: Add the introduction for mmc-utils

[Jonathan Corbet]

On Wed, 16 Mar 2016 20:02:49 +0800
Baolin Wang  wrote:

> This patch introduces one mmc test tools called mmc-utils, which is convenient
> if someone wants to exercise and test MMC/SD devices from userspace.

I've applied this to the docs tree, 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

Re: [PATCH 2/5] Documentation: update URL for Michael K. Johnson's articles

[Jonathan Corbet]

On Sat, 19 Mar 2016 12:51:21 +
Luis de Bethencourt  wrote:

> The URL for "Writing Linux Device Drivers" hasn't been available in some
> time. Updating it to the URL of Michael K. Johnson's "Linux Kernel Hackers'
> Guide"

But that's a different work, I don't think it makes sense to just
substitute in the URL.  It would be better, I think, to turn this into an
entry for the KHG if we really want that.

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

Re: [PATCH 1/5] Documentation: add Linux Kernel Development book

[Jonathan Corbet]

On Sat, 19 Mar 2016 12:51:20 +
Luis de Bethencourt  wrote:

> The Linux Kernel Development book by Robert Love has been recommended to me
> by multiple kernel hackers. Worth having in the list of books in
> kernel-docs.txt for newbies looking for good learning resources.

Applied to the docs tree, 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

Re: [PATCH] Documentation: update missing index files in block/00-INDEX

[Jonathan Corbet]

On Mon, 21 Mar 2016 19:42:19 +0800
Wei Fang  wrote:

> Update missing index files in block/00-INDEX.

Applied to the docs tree, 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

Re: [PATCH] Documentation/IRQ-domain.txt: Document irq_domain_create_{linear, tree}

[Jonathan Corbet]

On Sun, 27 Mar 2016 11:51:20 +0800
Jianyu Zhan  wrote:

> They have the same functionalities as irq_domain_add_{linear, tree},
> except fro accepting different first argument.
> 
> Signed-off-by: Jianyu Zhan 
> ---
> v1->v2:
>Fix spelling error.

Applied to the docs tree, 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

[PULL] Documentation for 4.6

[Jonathan Corbet]

The following changes since commit
92e963f50fc74041b5e9e744c330dca48e04f08d:

  Linux 4.5-rc1 (2016-01-24 13:06:47 -0800)

are available in the git repository at:

  git://git.lwn.net/linux.git tags/docs-for-linus

for you to fetch changes up to abfa6cd8cda71b9071191e72711bd474e539b1b2:

  modsign: Fix documentation on module signing enforcement parameter. 
(2016-03-12 01:48:11 -0700)


Another relatively boring cycle for the docs tree: typo fixes, translation
updates, etc.


Diego Viola (1):
  README: cosmetic fixes

Fu Wei (2):
  Documentation:Update Documentation/zh_CN/arm64/booting.txt
  Documentation: Chinese translation of arm64/silicon-errata.txt

Jakub Wilk (1):
  SubmittingPatches: fix spelling of "git send-email"

James Johnston (1):
  modsign: Fix documentation on module signing enforcement parameter.

Javi Merino (1):
  doc: fix grammar

Mahesh Khanwalkar (1):
  Documentation: Fix int/unsigned int comparison

Masanari Iida (5):
  Doc: DocBook: Fix a typo in device-drivers.tmpl
  Doc: i2c: Fix typo in Documentation/i2c
  Doc: ja_JP: Fix a typo in HOWTO
  Doc: ARM: Fix a typo in clksrc-change-registers.awk
  Doc: nfs: Fix typos in Documentation/filesystems/nfs

Peter Loeffler (1):
  Documentation: HOWTO: remove obsolete info about regression postings

Philippe Loctaux (1):
  Documentation: Howto: Fixed subtitles style

SeongJae Park (1):
  Documentation/ko_KR: update maintainer information

Thomas Gardner (1):
  Documentation/CodingStyle: add space before parenthesis in example macro

Zhiyi Sun (1):
  Documentation: kselftest: Remove duplicate word

dcg (1):
  Remove "arch" usage in Documentation/features/list-arch.sh

 Documentation/CodingStyle  |  2 +-
 Documentation/DocBook/device-drivers.tmpl  |  2 +-
 Documentation/HOWTO| 15 ++--
 Documentation/SubmittingPatches|  2 +-
 .../arm/Samsung/clksrc-change-registers.awk|  2 +-
 Documentation/features/list-arch.sh|  2 +-
 Documentation/filesystems/nfs/fault_injection.txt  |  4 +-
 Documentation/filesystems/nfs/nfs-rdma.txt |  2 +-
 Documentation/filesystems/nfs/nfsroot.txt  |  2 +-
 Documentation/filesystems/nfs/pnfs.txt |  6 +-
 Documentation/filesystems/nfs/rpc-server-gss.txt   |  2 +-
 Documentation/filesystems/sharedsubtree.txt|  8 +-
 Documentation/i2c/dev-interface|  2 +-
 Documentation/i2c/slave-eeprom-backend |  4 +-
 Documentation/ja_JP/HOWTO  |  2 +-
 Documentation/ko_KR/HOWTO  |  4 +-
 Documentation/ko_KR/stable_api_nonsense.txt|  4 +-
 Documentation/kselftest.txt|  2 +-
 Documentation/mic/mpssd/mpssd.c|  4 +-
 Documentation/module-signing.txt   |  2 +-
 .../prctl/disable-tsc-ctxt-sw-stress-test.c|  2 +-
 .../prctl/disable-tsc-on-off-stress-test.c |  2 +-
 Documentation/prctl/disable-tsc-test.c |  2 +-
 Documentation/ptp/testptp.c|  3 +-
 Documentation/timers/hpet_example.c|  2 +-
 Documentation/zh_CN/arm64/booting.txt  | 93 ++
 Documentation/zh_CN/arm64/silicon-errata.txt   | 74 +
 README | 14 ++--
 28 files changed, 179 insertions(+), 86 deletions(-)
 create mode 100644 Documentation/zh_CN/arm64/silicon-errata.txt
--
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] modsign: Fix documentation on module signing enforcement parameter.

[Jonathan Corbet]

On Thu, 10 Mar 2016 03:38:48 -
"James Johnston"  wrote:

> My mail client is determined to embarrass me.  :(  Trying again...

Worked this time!  Applied to the docs tree, 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

Re: [PATCH] Doc: nfs: Fix typos in Documentation/filesystems/nfs

[Jonathan Corbet]

On Thu, 18 Feb 2016 12:26:13 +0900
Masanari Iida  wrote:

> This patch fix spelling typos found in Documentation/filesystems/nfs

I've applied this to the docs tree.  I fixed the two "reacquire"
instances that Randy pointed out; it would have been nice to get an
updated patch so I didn't have to do that.

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

Re: [PATCH] doc: fix grammar

[Jonathan Corbet]

On Thu, 25 Feb 2016 11:19:56 +
Javi Merino  wrote:

> Some minor typos:
> 
>   - make is unbindable -> make it unbindable
>   - a underlying -> an underlying
>   - different version -> different versions

Applied to the docs tree, 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

Re: [PATCH] Documentation: Howto: Fixed subtitles style

[Jonathan Corbet]

On Mon,  7 Mar 2016 02:36:18 +0100
Philippe Loctaux  wrote:

> Fixed subtitles style, aligned them with their header.

Applied to the docs tree, 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

Re: [PATCH] modsign: Fix documentation on module signing enforcement parameter.

[Jonathan Corbet]

On Mon, 7 Mar 2016 01:45:17 -
"James Johnston"  wrote:

> Modify the documentation to match the actual parameter as implemented in
> kernel/module.c:273.

So I was going to apply this to the docs tree, but it's been white-space
mangled.  Care to fix your mail client and resend?

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

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Thu, 3 Mar 2016 14:34:25 +
One Thousand Gnomes  wrote:

> We only have docbook because it was the tool of choice rather a lot of
> years ago to then get useful output formats. It was just inherited when
> borrowed the original scripts from Gnome/Gtk. It's still the most
> effective way IMHO of building big structured documents out of the kernel.

...except that we haven't used it that way.  Instead, we make a whole
bunch of smaller, partially structured document silos.

> The Gtk people long ago rewrote the original document script into a real
> tool so they have some different and maintained tools that are close to
> equivalent and already have some markdown support. Before we go off and
> re-invent the wheel it might be worth just borrowing their wheel and
> tweaking it as needed ? In particular they can generate help indexes so
> that the entire output becomes nicely browsable with an HTML based help
> browser.

Well, not inventing the wheel was kind of the motivation behind much of
this effort; I got kind of worried watching us trying to cobble more
functionality into our existing house-of-cards documentation system.

Sphinx is a well-established, heavily used, and well supported system;
using it would not be an exercise in wheel reinvention.  As far as I can
tell, it does everything we need (with some open questions about table
support), lets us drop the whole DocBook toolchain dependency, and move to
a much better-supported setup than we have now.  Plus we get much nicer
output, index generation, cross-references between documents, and the
ability to write documents in a lightweight markup language.  Seems like a
win.

I assume you're referring to gtk-doc?  It's web page
(http://www.gtk.org/gtk-doc/) starts by noting that it's "a bit awkward to
setup and use"; they recommend looking at Doxygen instead.  So I guess I'm
not really sure what it offers that merits throwing another option into
the mix now?  What am I missing?

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

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Thu, 03 Mar 2016 16:03:14 +0200
Jani Nikula  wrote:

> This stalled a bit, but the waters are still muddy...

I've been dealing with real-world obnoxiousness, something which won't
come to an immediate end, unfortunately.  But I have been taking some time
to mess with things, and hope to have some more POC patches to send out
soon.

> Is the Sphinx/reStructuredText table support adequate for media/v4l
> documentation?

That's perhaps the biggest question.  My sense is "yes", but this needs a
bit more assurance than that.

> Are the Sphinx output formats adequate in general? Specifically, is the
> lack of DocBook support, and the flexibility it provides, a blocker?

DocBook is a means to an end; nobody really wants DocBook itself as far
as I can tell. I've been messing with rst2pdf a bit; it's not hard to get
reasonable output, and, with some effort, we could probably get really
nice output. HTML and EPUB are easily covered, still haven't really played
around with man pages yet.  And there's LaTeX if we really need it.  I
kind of think we're covered there, unless I've missed something?

> Otherwise, I think Sphinx is promising.
> 
> Jon, I think we need a roll of dice, err, a well-thought-out decision
> from the maintainer to go with one or the other, so we can make some
> real progress.

My inclination at the moment is very much in the Sphinx direction.  I had
some vague thoughts of pushing a throwaway experimental directory with a
couple of docs for 4.6 that would just let people play with it easily;
then we'd see how many screams we get.  We'll see if the world lets me get
there.

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

V4L docs and docbook

[Jonathan Corbet]

Hey, Mauro,

There's been a conversation going on that I keep meaning to bring you
into.  In short, there's a fair amount of interest in improving our
formatted kernel documentation, and, in particular, making it easier to
write; I'd like to be sure that work doesn't leave media behind.

Work pushed by Daniel Vetter and company has been aiming toward the
ability to use a lightweight markup language in the in-source kerneldoc
comments.  Initially Markdown was targeted; the most likely choice now
looks like ReStructuredText, though no decision has been made.  I've been
pushing for moving all of our formatted documentation to whatever markup
we use, leaving DocBook behind.  There are, I think, a lot of good
reasons to want to do that, including consistency between the template
files and the in-source comments, ease of authoring, and a less unwieldy
toolchain.

Various proof-of-concept patches have gone around showing that this idea
seems to be feasible.  The latest discussion is at:

http://thread.gmane.org/gmane.linux.documentation/35773

The media community has a lot of investment in DocBook documentation.
Converting to another markup form is relatively easy, and it's something
I would be willing to help with when the time comes.  But it occurred to
me that I should probably ask what you all think of this.

There is no flag day here; there's no reason to rip out the current
DocBook-based build infrastructure as long as somebody's using it.  But
it would be nice to get rid of it eventually and work toward the creation
of a more integrated set of kernel documentation.

So...is this an idea that fills you with horror, or does it maybe have
some appeal?  Do you have any questions?

One other question I had for you was: which of the allegedly supported
output formats are important to you?

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

Re: [PATCH] Documentation/ko_KR: update maintainer information

[Jonathan Corbet]

On Sun, 14 Feb 2016 11:51:23 +0900
SeongJae Park  wrote:

> Maintainer informations of Documentation/ko_KR is outdated. This commit
> update the informations to the latest ones.

Applied to the docs tree, 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

Re: [PATCH v2] Documentation: Chinese translation of arm64/silicon-errata.txt

[Jonathan Corbet]

On Tue, 16 Feb 2016 16:40:39 +0800
w...@redhat.com wrote:

> This is a Chinese translated version of Documentation/arm64/silicon-errata.txt

Applied to the docs tree, 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

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Tue, 16 Feb 2016 10:25:49 +0200
Jani Nikula  wrote:

> However I didn't think Sphinx could produce docbook, and a quick search
> doesn't convince me otherwise. Do you have some links to back this up?

Somehow I was really sure of it, but I'm not finding it now.  There is an
extension out there, but it warns about being a "work in progress," so
I'm not sure we can count it.

Whether this is a show-stopper is indeed a good question.  I doubt many
people wanted the DocBook for its own sake, it's a matter of where you
can go from there.  But yes, it would be good to be sure on this point.

> Sphinx might offer a way to drop docproc through the extension
> mechanism, without resorting to the "separate-file approach". It might
> be a more sensible approach as a whole.

There's a certain elegance to it that I like, but it is an idea that
needs to actually be demonstrated.  It could also come later on, though,
with the docproc or include mechanisms used for now.

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

Kernel docs: muddying the waters a bit

[Jonathan Corbet]

So I fear you all are going to hate me for this...

Asciidoc is a credible solution to the formatted documentation problem,
but it's not the only such; I'd like to be sure that we pick the right
one.  I worry that asciidoc seems to be aimed mostly at small documents,
and that the project itself seems a little lifeless - it's not a good
sign when your main page's link to the repository has been dead for a long
time.  (Asciidoctor seems more active, with the Github folks behind it,
but that means bringing Ruby into the picture).

An alternative we haven't really looked at yet is ReStructuredText (or
"RST") and the Sphinx system (sphinx-doc.org) built on top of it.  RST is
YA simple markup scheme, remarkably similar to Markdown or Asciidoc;
Sphinx is a fairly sophisticated documentation system that uses RST.

I spent a few hours reworking the asciidoc patches to do RST instead, then
built a few template files' worth of docs.  The result can be seen at:

http://static.lwn.net/kerneldoc/

It's very much a POC (however you might want to define the term), there's
lots of glitches, I chose a theme pretty much at random, etc.  But it
shows that it can be done.

Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain
requirements there.  It produces integrated, multi-file HTML natively,
with a TOC, an index, cross-file cross references, and more.  It can make
things like function indexes.  It claims output in epub, docbook, and man
(I've not yet messed with those).  The path to PDF is via latex; clearly
the docbook path could be used too.

I used my same docproc hack to extract the comments here, mostly because I
had it at hand.  We could go with Jani's separate-file approach if we
wanted.  There's also a tool out there (called "breathe") that's meant to
turn doxygen-style comments into RST; I haven't had a chance to mess with
it.  We *could* also write an extension to pull the comments directly in
Sphinx if there were a compelling reason to do so.

If anybody's curious, the work done to get this far is in:

git://git.lwn.net/linux.git doc/sphinx

but it looks suspiciously like the previous asciidoc patches, and, in any
case, it would have to be thrown out, publicly disowned, and replaced
before going any further with this, should that be what we decide to do.

So can we discuss?  I'm not saying we have to use Sphinx, but, should we
choose not to, we should do so with open eyes and good reasons for the
course we do take.  What do you all think?

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] Doc: ja_JP: Fix a typo in HOWTO

[Jonathan Corbet]

On Mon,  1 Feb 2016 13:03:27 +0900
Masanari Iida  wrote:

> This patch fix a typo witin HOWTO, which was translated in Japanese.
> Replace a word "kernlehacker" with "kernelhacker".

Wouldn't want to misspell Mr. Kernelhacker's name!

Applied, 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

Re: [RFC] A first shot at asciidoc-based formatted docs

[Jonathan Corbet]

On Wed, 10 Feb 2016 09:07:22 +0100
Daniel Vetter  wrote:

> I think for 4.6 it'd be best to go with the hybrid asciidoc->docbook
> toolchain, since that's less disruptive. And with that we can also
> fully concentrating on the frontend, and how it'll look and behave.

That can be fine, I'd just like to have the end goal in mind.  For the near
future we should go with what actually works, definitely.

> >  - Asciidoc templates and processing should happen in a new directory
> >(perhaps imaginatively called "asciidoc"); having them in a directory
> >called "DocBook" seems a little weird.  More importantly, though, I'd
> >like to separate them out as a fresh start, and not mess with the
> >existing DocBook templates until we decide we don't need them anymore.
> >If we could end up with a cleaner, simpler makefile in the process,
> >that would be a bonus.  
> 
> For the long term dream plan of including other .txt files from the
> existing pile of unstructured docs, do we really want a separate
> asciidoc directory? Or just .asciidoc as a special extension?

That's a good question.  I can certainly see the value of mixing the
templates with the rest, but that's a longer-term thing.  I'd sure like to
clean up the main Documentation/ directory before we start scattering
asciidoc stuff around there.  For the moment, I think my preference is
still to focus this work in one place where it's easily found and played
with.  Straightening out this directory is going to involve a fair amount
of moving stuff around, adding a few template files to that debt isn't
going to change the situation much.

> >  - I'm not sold on the new inclusion mechanism.  Creating thousands of
> >little files and tracking them for dependencies and such doesn't seem
> >like a simplification or a path toward better performance.  I would
> >like to at least consider keeping the direct-from-source inclusion.  
> 
> The motivation behind the new inclusion mechanism isn't the speed-up
> due to parallelization, but being able to use native asciidoc
> includes. With those you can pass options to e.g. shift the hierarchy.
> With that you can do subheadings in DOC: sections and then seamlessly
> include them. Or similar stuff.
> 
> The speed-up due to parallelization is just a small bonus.
> 
> Also generating thousands of files is totally not unheard of in the kernel:
> 
> $ find include/config | wc -l
> 2623
> 
> None of those are in git.

Well, we are talking about an order of magnitude more files...  Still, I
said "not sold on" rather than "violently opposed to".  It does seem that
there are some good reasons for doing things this way, including, as Jani
said, getting rid of docproc and not mixing in a weird alien include
syntax.  I'm still not 100% sold, but I'll not hold up a working patch on
this point.

> >  - Insisting on EXPORT_SYMBOL being in the same file doesn't seem like
> >it's going to work for now; that could maybe change after Al's work
> >goes in, which could be fairly soon.  
> 
> Hm, assuming Al gets his stuff into 4.6 could we just assume this? It
> holds true for gpu docs already I think, and most other subsystems.
> The trouble iirc is all around asm and similar stuff, and we can't
> kerneldoc asm afaik.

asm stuff and things built into libraries.  But it does seem that this is
well on the way toward being fixed.

> One more thing we discussed: Did you ping kbuild folks already? Or
> want to get some agreement on the overall build process first?

Not yet.  It's worth doing...it would be nice, someday, if docs makefiles
could just have lines like:

  adoc-y += drm.txt ...

but I think we should work out how the pieces fit together before we get
too worried about the details of the build system.  What we have now isn't
particularly well integrated, we're not likely to make it all that much
worse...

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

Re: [PATCH] kernel-doc: add support for asciidoc output

[Jonathan Corbet]

On Mon, 18 Jan 2016 10:41:17 +0200
Jani Nikula  wrote:

> Add new -asciidoc option to produce asciidoc output from kernel-doc. The
> output is formatted internally, with no dependencies on external
> tools. Any asciidoc formatting present in kernel-doc will naturally be
> present in the resulting asciidoc as well.

As you may have seen, I took this and sort of ran with it - thanks!  I'm
not sure I want to merge this functionality without an in-kernel user, but
we're on the way toward having that now.

> I tested this mostly on drm/i915. I had to drop a few totally bogus
> kernel-doc comments for everything to work cleanly, series at
> http://patchwork.freedesktop.org/series/2581/.

Aside from all of this, could I prevail upon you to submit those?  They
are worth having regardless.

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

[PATCH 3/4] Docs: Makefile tweaks for asciidoc templates

[Jonathan Corbet]

This is a hatchet job, but it's something to start with.  Generalize some
of the string manipulation to not assume that templates have a ".tmpl"
suffix, and add rules to translate asciidoc templates to HTML.  Nothing for
any other output formats at this point.

Signed-off-by: Jonathan Corbet <cor...@lwn.net>
---
 Documentation/DocBook/Makefile | 72 +-
 1 file changed, 43 insertions(+), 29 deletions(-)

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index d70f9b6..f04e8c8 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -6,16 +6,16 @@
 # To add a new book the only step required is to add the book to the
 # list of DOCBOOKS.
 
-DOCBOOKS := z8530book.xml device-drivers.xml \
-   kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
-   writing_usb_driver.xml networking.xml \
-   kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
-   gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
-   genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
-   80211.xml debugobjects.xml sh.xml regulator.xml \
-   alsa-driver-api.xml writing-an-alsa-driver.xml \
-   tracepoint.xml gpu.xml media_api.xml w1.xml \
-   writing_musb_glue_layer.xml crypto-API.xml iio.xml
+DOCBOOKS := z8530book device-drivers \
+   kernel-hacking kernel-locking deviceiobook \
+   writing_usb_driver networking \
+   kernel-api filesystems lsm usb kgdb \
+   gadget libata mtdnand librs rapidio \
+   genericirq s390-drivers uio-howto scsi \
+   80211 debugobjects sh regulator \
+   alsa-driver-api writing-an-alsa-driver \
+   tracepoint gpu media_api w1 \
+   writing_musb_glue_layer crypto-API iio
 
 include Documentation/DocBook/media/Makefile
 
@@ -39,21 +39,21 @@ PHONY += xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs 
installmandocs cleando
 
 targets += $(DOCBOOKS)
 BOOKS := $(addprefix $(obj)/,$(DOCBOOKS))
-xmldocs: $(BOOKS)
+xmldocs: $(addsuffix .xml, $(BOOKS))
 sgmldocs: xmldocs
 
-PS := $(patsubst %.xml, %.ps, $(BOOKS))
+PS := $(addsuffix .ps, $(BOOKS))
 psdocs: $(PS)
 
-PDF := $(patsubst %.xml, %.pdf, $(BOOKS))
+PDF := $(addsuffix .pdf, $(BOOKS))
 pdfdocs: $(PDF)
 
-HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS)))
+HTML := $(sort $(addsuffix .html, $(BOOKS)))
 htmldocs: $(HTML)
$(call cmd,build_main_index)
$(call install_media_images)
 
-MAN := $(patsubst %.xml, %.9, $(BOOKS))
+MAN := $(addsuffix .9, $(BOOKS))
 mandocs: $(MAN)
find $(obj)/man -name '*.9' | xargs gzip -nf
 
@@ -103,6 +103,19 @@ endef
 # Tell kbuild to always build the programs
 always := $(hostprogs-y)
 
+#
+# asciidoc stuff.
+#
+quiet_cmd_ad2html = ASCIIDOC   $@
+  cmd_ad2html = asciidoc -b html $< > $@
+
+%.ad: %.adt $(KERNELDOC) $(DOCPROC) FORCE
+   $(call cmd,docproc)
+
+%.html: %.ad
+   $(call cmd,ad2html)
+
+
 notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
   exit 1
 db2xtemplate = db2TYPE -o $(dir $@) $<
@@ -234,22 +247,23 @@ dochelp:
 
 ###
 # Temporary files left by various tools
-clean-files := $(DOCBOOKS) \
-   $(patsubst %.xml, %.dvi, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.tex, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.log, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.out, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.ps,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.pdf, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.html,$(DOCBOOKS)) \
-   $(patsubst %.xml, %.9,   $(DOCBOOKS)) \
-   $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \
-   $(patsubst %.xml, %.xml.db,  $(DOCBOOKS)) \
-   $(patsubst %.xml, %.xml, $(DOCBOOKS)) \
+clean-files := \
+   $(addsuffix .dvi, $(DOCBOOKS)) \
+   $(addsuffix .aux, $(DOCBOOKS)) \
+   $(addsuffix .tex, $(DOCBOOKS)) \
+   $(addsuffix .log, $(DOCBOOKS)) \
+   $(addsuffix .out, $(DOCBOOKS)) \
+   $(addsuffix .ps,  $(DOCBOOKS)) \
+   $(addsuffix .pdf, $(DOCBOOKS)) \
+   $(addsuffix .html,$(DOCBOOKS)) \
+   $(addsuffix .9,   $(DOCBOOKS)) \
+   $(addsuffix .aux.xml, $(DOCBOOKS)) \
+   $(addsuffix .xml.db,  $(DOCBOOKS)) \
+   $(addsuffix .xml, $(DOCBOOKS)) \
+   $(addsuffix .ad,  $(DOCBOOKS)) \
$(index)
 
-clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man
+clean-dirs := $(DOCBOOKS) man
 
 cleandocs: cleanmediadocs
$(Q)rm -f $(call objectify, $(clean-files))
-- 
2.7.0

--
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