Re: [PATCH] docs/core-api: make mm-api.rst more structured

[Jonathan Corbet]

On Wed, 28 Nov 2018 16:45:44 +0200
Mike Rapoport  wrote:

> The mm-api.rst covers variety of memory management APIs under "More Memory
> Management Functions" section. The descriptions included there are in a
> random order there are quite a few of them which makes the section too
> long.
> 
> Regrouping the documentation by subject and splitting the long "More Memory
> Management Functions" section into several smaller sections makes the
> generated html more usable.
> 
> Signed-off-by: Mike Rapoport 

Applied, thanks.

jon

Re: [PATCH 1/1] scripts/kernel-doc: Fix struct and struct field attribute processing

[Jonathan Corbet]

On Thu, 22 Nov 2018 13:06:04 +0200
Sakari Ailus  wrote:

> The kernel-doc attempts to clear the struct and struct member attributes
> from the API documentation it produces. It falls short of the job in the
> following respects:
> 
> - extra whitespaces are left where __attribute__((...)) was removed,
> 
> - only a single attribute is removed per struct,
> 
> - attributes (such as aligned) containing numbers were not removed,
> 
> - attributes are only cleared from struct fields, not structs themselves.
> 
> This patch addresses these issues by removing the attributes.
> 
> Signed-off-by: Sakari Ailus 

That does indeed seem to improve things.  I'm waiting for the pile of
regexes to fall over and hurt somebody, but I guess we're not there yet.
Applied, thanks.

jon

Re: [PATCH v2] docs/admin-guide/mm/concepts.rst: grammar and style fixups

[Jonathan Corbet]

On Sun, 11 Nov 2018 11:24:23 +0200
Mike Rapoport  wrote:

> Signed-off-by: Mike Rapoport 
> Reviewed-by: Randy Dunlap 
> ---
> 
> v2: address Matthew's feedback
> 
>  Documentation/admin-guide/mm/concepts.rst | 51 
> ---
>  1 file changed, 26 insertions(+), 25 deletions(-)

Applied, thanks.

jon

Re: [PATCH] docs/mm: update kmalloc kernel-doc description

[Jonathan Corbet]

On Sun, 11 Nov 2018 18:48:44 +0200
Mike Rapoport  wrote:

> Add references to GFP documentation and the memory-allocation.rst and remove
> GFP_USER, GFP_DMA and GFP_NOIO descriptions.
> 
> While on it slightly change the formatting so that the list of GFP flags
> will be rendered as "description" in the generated html.
> 
> Signed-off-by: Mike Rapoport 
> ---
> 
> Probably this should go via the -mm tree as it touches include/linux/slab.h

A week and some later it's not there - Andrew is even slower than me, it
seems! :)  So I went ahead and applied it, fixing the conflict over the
addition of the memory_allocation label while I was at it.

Thanks,

jon

Re: [PATCH] Link the memory allocation guide from the MM docs

[Jonathan Corbet]

On Mon, 19 Nov 2018 08:00:49 -0800
Matthew Wilcox  wrote:

> I just went looking for the memory allocation guide in the MM docs instead
> of in the core API.  For the benefit of the next person who makes that
> mistake, link to it from the MM docs.
> 
> Signed-off-by: Matthew Wilcox 

Applied, thanks.

jon

Re: [PATCH v2] doc: tracing: Fix a number of typos

[Jonathan Corbet]

On Thu,  1 Nov 2018 09:57:17 -0400
Amir Livneh  wrote:

> Trivial fixes to spelling mistakes in ftrace.rst
> 
> v2: tripple -> triple
> 
> Signed-off-by: Amir Livneh 

Applied, thanks.

jon

Re: [PATCH] doc: fix a typo in adding-syscalls.rst

[Jonathan Corbet]

On Thu, 18 Oct 2018 17:47:50 +0200
cor...@poussif.eu wrote:

> There was a typo in adding-syscalls.rst that could mislead developers
> to add a C filename in a makefile instead of an object filename.
> This error, while not keeping developers from contributing could slow
> the development process down by introducing build errors.
> 
> Signed-off-by: Guillaume Dore 

Applied, thanks.

jon

Re: [PATCH v2 00/22] xfs-4.20: major documentation surgery

[Jonathan Corbet]

On Mon, 15 Oct 2018 02:55:49 -0700
Christoph Hellwig  wrote:

> > OK, I've had a long conversation with the LF lawyer, and she said clearly
> > that we really should not be introducing CC-SA material into the kernel
> > source tree.  It's a pain; I really do like CC-SA better for
> > documentation, but it's not GPL-compatible, and that creates a problem for
> > the processed docs.  
> 
> That was exactly my concern with this patchset.
> 
> Btw, I think we have the same issue with idr.rst, and unless we can
> relicense it we should drop it from the tree, as it actually includes
> kernel source files.

...and a significant DOC section at that, not just function prototypes.

I'd already asked Willy [CC'd] about this once, haven't gotten an answer
yet.  Hopefully we can address this once he comes back around.

Thanks,

jon

Re: [PATCH v2 00/22] xfs-4.20: major documentation surgery

[Jonathan Corbet]

On Sat, 6 Oct 2018 10:51:54 +1000
Dave Chinner  wrote:

> Can you let us know whether the CC-by-SA 4.0 license is acceptible
> or not? That's really the only thing that we need clarified at this
> point - if it's OK I'll to pull this into the XFS tree for the 4.20
> merge window. If not, we'll go back to the drawing board

OK, I've had a long conversation with the LF lawyer, and she said clearly
that we really should not be introducing CC-SA material into the kernel
source tree.  It's a pain; I really do like CC-SA better for
documentation, but it's not GPL-compatible, and that creates a problem for
the processed docs.

Sorry,

jon

Re: [PATCH] docs: improve readability for people with poorer eyesight

[Jonathan Corbet]

On Thu, 4 Oct 2018 18:06:03 -0700
"Darrick J. Wong"  wrote:

> o my eyesight still hasn't fully recovered, so in the meantime it's
> been difficult to read the online documentation.  Here's some stylesheet
> overrides I've been using to make it easier for me to read them:
> https://djwong.org/docs/kdoc/index.html
> 
> ---
> From: Darrick J. Wong 
> 
> My eyesight is not in good shape, which means that I have difficulty
> reading the online Linux documentation.  Specifically, body text is
> oddly small compared to list items and the contrast of various text
> elements is too low for me to be able to see easily.
> 
> Therefore, alter the HTML theme overrides to make the text larger and
> increase the contrast for better visibility, and trust the typeface
> choices of the reader's browser.
> 
> For the PDF output, increase the text size, use a sans-serif typeface
> for sans-serif text, and use a serif typeface for "roman" serif text.
> 
> Signed-off-by: Darrick J. Wong 

I've been wanting to find some time to work on our stylesheets for years;
what we have now is far from ideal (or attractive) IMO.  This is a good
step in the right direction - applied, thanks.

jon

Re: [PATCH 2/2] docs/vm: split memory hotplug notifier description to Documentation/core-api

[Jonathan Corbet]

On Fri,  5 Oct 2018 01:11:01 +0300
Mike Rapoport  wrote:

> The memory hotplug notifier description is about kernel internals rather
> than admin/user visible API. Place it appropriately.
> 
> Signed-off-by: Mike Rapoport 

One little nit...

>  Documentation/admin-guide/mm/memory-hotplug.rst| 83 -
>  Documentation/core-api/index.rst   |  2 +
>  Documentation/core-api/memory-hotplug-notifier.rst | 84 
> ++
>  3 files changed, 86 insertions(+), 83 deletions(-)
>  create mode 100644 Documentation/core-api/memory-hotplug-notifier.rst
> 
> diff --git a/Documentation/admin-guide/mm/memory-hotplug.rst 
> b/Documentation/admin-guide/mm/memory-hotplug.rst
> index a33090c..0b9c83e 100644
> --- a/Documentation/admin-guide/mm/memory-hotplug.rst
> +++ b/Documentation/admin-guide/mm/memory-hotplug.rst
> @@ -31,7 +31,6 @@ be changed often.
>  6.1 Memory offline and ZONE_MOVABLE
>  6.2. How to offline memory
>7. Physical memory remove
> -  8. Memory hotplug event notifier
>9. Future Work List

That leaves a gap in the numbering here.

In general, the best solution to this sort of issue is to take the TOC out
entirely and let Sphinx worry about generating it.  People tend not to
think about updating the TOC when they make changes elsewhere, so it often
goes out of sync with the rest of the document anyway.

I'll apply these, but please feel free to send a patch to fix this up.

Thanks,

jon

Re: [PATCH 2/2] docs: promote the ext4 data structures book to top level

[Jonathan Corbet]

On Fri, 5 Oct 2018 19:49:52 -0400
"Theodore Y. Ts'o"  wrote:

> On Thu, Oct 04, 2018 at 05:59:44PM -0700, Darrick J. Wong wrote:
> > From: Darrick J. Wong 
> > 
> > Move the ext4 data structures book to Documentation/filesystems/ext4/
> > since the administrative information moved elsewhere.
> > 
> > Signed-off-by: Darrick J. Wong   
> 
> Thanks, applied and pushed out to the ext4.git tree.
> 
> Randy, Jon: the original patch didn't make it past vger.kernel.org
> because it was too large (it was moving a lot of files around).  It
> looked fine to me, but if you want to take a look it should be on the
> dev branch of the ext4.git tree.

FWIW, from a quick look it seems fine to me.

   Acked-by: Jonathan Corbet 

(though I expect it's too late to add that).

jon

Re: [PATCH v2 00/22] xfs-4.20: major documentation surgery

[Jonathan Corbet]

On Sat, 6 Oct 2018 06:29:51 -0700
Matthew Wilcox  wrote:

> I had an informal chat with Bradley Kuhn at LinuxCon Japan about using
> CC-BY-SA-4.0 and he indicated that I was probably better off using the
> GPL-2(+) for documentation.  I've changed the XArray documentation from
> CC-BY-SA-4.0 to GPL-2+.

Would you consider doing the same for Documentation/core-api/idr.rst?
That's the only CC-SA SPDX tag in the kernel now, and it's a clear
example of just what I'm worried about: it pulls in a nice DOC section
from the code when you run Sphinx on it, so we're not just talking
function prototypes here.  I was likely to come knocking on your door
after my upcoming conversation anyway...:)

Thanks,

jon

Re: [PATCH v2 00/22] xfs-4.20: major documentation surgery

[Jonathan Corbet]

On Sat, 6 Oct 2018 10:51:54 +1000
Dave Chinner  wrote:

> Can you let us know whether the CC-by-SA 4.0 license is acceptible
> or not? That's really the only thing that we need clarified at this
> point - if it's OK I'll to pull this into the XFS tree for the 4.20
> merge window. If not, we'll go back to the drawing board

I remain pretty concerned about it, to tell the truth.  Rather than
continue to guess, though, I've called for help, and will be talking with
the LF lawyer about this next Thursday.  Before then, I can't say anything
except "I don't think this works..."

Will let you know what I hear.

jon

Re: [PATCH] doc: Fix acronym "FEKEK" in ecryptfs

[Jonathan Corbet]

On Mon, 17 Sep 2018 11:34:48 +0200
Felix Eckhofer  wrote:

> "FEFEK" was incorrectly used as acronym for "File Encryption Key
> Encryption Key". This replaces all occurences with "FEKEK".
> 
> Signed-off-by: Felix Eckhofer 
> ---
>  Documentation/security/keys/ecryptfs.rst | 8 
>  1 file changed, 4 insertions(+), 4 deletions(-)

Applied, thanks.

jon

Re: nodocs in 4.19-rcX

[Jonathan Corbet]

On Mon, 10 Sep 2018 15:51:20 -0700
Randy Dunlap  wrote:

> 4.19-rc contains some users of :nodocs: but that is not recognized yet,
> so we get:
> 
> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:78: ERROR: Error in 
> "kernel-doc" directive:
> unknown option: "nodocs".
> 
> .. kernel-doc:: mm/bootmem.c
>:nodocs:
> 
> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:91: ERROR: Error in 
> "kernel-doc" directive:
> unknown option: "nodocs".
> 
> .. kernel-doc:: mm/memblock.c
>:nodocs:
> 
> 
> Do you plan to merge the patch(es) for :nodocs: ?

:nodocs" was v1 of the patch set:

  
https://lwn.net/ml/linux-doc/1529328996-16247-1-git-send-email-rppt%40linux.vnet.ibm.com/

In the end, I merged v3, which changed things (and did not contain
the :nodocs: directive:

  
https://lwn.net/ml/linux-doc/1530306311-10510-1-git-send-email-rppt%40linux.vnet.ibm.com/

So I'm guessing that anything that snuck in with :nodocs: didn't get
updated.  Somehow I missed that.  Adding CC: Mike, since his
fingerprints are on all aspects of this...:)

jon

Re: [PATCH 2/2] MAINTAINERS: add i2c to the excludes for Documentation

[Jonathan Corbet]

On Fri,  7 Sep 2018 12:30:22 +0200
Wolfram Sang  wrote:

> I'll handle these myself but thanks for providing the fallback!
> 
> Signed-off-by: Wolfram Sang 
> ---
>  MAINTAINERS | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 2698ee553008..39c39dd6fba6 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -4487,6 +4487,7 @@ F:  scripts/kernel-doc
>  X:   Documentation/ABI/
>  X:   Documentation/acpi/
>  X:   Documentation/devicetree/
> +X:   Documentation/i2c/
>  X:   Documentation/media/
>  X:   Documentation/power/
>  X:   Documentation/spi/

Both patches applied, thanks.  Looking forward to less email! :)

jon

Re: Italian translations and broken links

[Jonathan Corbet]

On Fri, 24 Aug 2018 13:51:18 +0200
Federico Vaga  wrote:

> Since there are many documents, this take time and perhaps we can already 
> push 
> the ones which are ready.
> 
> My big dilemma is (which is more general): what about broken references? Do 
> we 
> keep broken links which we know they will be correct in the future? Or, do we 
> remove all broken links and we add them back only when they work (if we 
> remember)?

We want the kernel to be as close to release-ready as it can be at any
time, that includes the docs.  So please no broken links.  It's a bit
more work to keep things coherent, but it's what we need to do in the
long run.

Thanks,

jon

Re: [PATCH] Remove gendered language from management style documentation

[Jonathan Corbet]

On Tue,  7 Aug 2018 19:47:51 +0100
Fox Foster  wrote:

> This small commit replaces gendered pronouns for neutral ones.
> 
> Signed-off-by: Fox Foster 

Applied, thanks.

jon

Re: [PATCH v2] scripts/kernel-doc: Escape all literal braces in regexes

[Jonathan Corbet]

On Sun, 5 Aug 2018 17:41:09 +0100
Ben Hutchings  wrote:

> Commit 720ac2ef479d ("PATCH scripts/kernel-doc") fixed the two
> instances of literal braces that Perl 5.28 warns about, but there are
> still more than it doesn't warn about.
> 
> Escape all left braces that are treated as literal characters.  Also
> escape literal right braces, for consistency and to avoid confusing
> bracket-matching in text editors.
> 
> Signed-off-by: Ben Hutchings 

Applied (with the commit hash corrected), 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] scripts/kernel-doc: Escape all literal braces in regexes

[Jonathan Corbet]

On Sun, 5 Aug 2018 17:41:09 +0100
Ben Hutchings  wrote:

> Commit 720ac2ef479d ("PATCH scripts/kernel-doc") fixed the two
> instances of literal braces that Perl 5.28 warns about, but there are
> still more than it doesn't warn about.

So where can I find this commit of which you speak?  I can't find it in
mainline, -next, or -stable...  

The patch looks good, I'd like to get it in this coming merge window if
possible.

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 v1] doc: translation for block queue into Chinese

[Jonathan Corbet]

On Fri, 27 Jul 2018 10:41:19 +0800
Norman  wrote:

> Translate block/queue-sysfs.txt into Chinese
> 
> Signed-off-by: Norman Kern 

Unfortunately, this patch has been white-space mangled by your mailer.
Please fix your mailer (Documentation/process/email-clients.rst has
useful hints to that end) then 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: [PATCH] zh_CN:translation for block queue into Chinese

[Jonathan Corbet]

On Fri, 20 Jul 2018 10:27:06 +0800
Norman  wrote:

> Translate block/queue-sysfs.txt into Chinese
> 
> Signed-off-by: Norman Kern 
> ---
>   .../translations/zh_CN/block/queue-sysfs.md    | 205 
> +

So...are you translating this into markdown format?  Please don't do
that, we don't need another documentation format in the kernel.  If you
want to convert this document to structured markup, the ideal approach
would be to convert the source document to RST first, then translate the
result.

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]:Involved in Linux doc translation for Chinese

[Jonathan Corbet]

On Thu, 19 Jul 2018 18:20:52 +0800
Norman  wrote:

> 'Documentation/translations/'  has been discarded or not ? I found few 
> translations there :(

It certainly has not been discarded.  But it also cannot grow in the
absence of contributions from interested developers — I certainly can't
fill it 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] Documentation : Update relay function types

[Jonathan Corbet]

On Sun, 8 Jul 2018 20:19:32 +0200
Yohan Pipereau  wrote:

> This patch updates two callback functions provided as an example in
> relay API documentation : subbuf_start and create_buf_file_handler.
> 
> These functions were using older and incorrect types causing an
> "initialization from incompatible pointer type".

Heh, nobody has seriously touched that file in ten years.  Patch applied,
but...

> diffstat for this patch is:
>  relay.txt |4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Please include information like this after the "---" line so I don't have
to edit it out of the changelog manually.  

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 1/2] Documentation/sphinx: allow "functions" with no parameters

[Jonathan Corbet]

On Sat, 30 Jun 2018 17:59:27 +0300
Mike Rapoport  wrote:

> > 
> > Is this the right syntax?  Should we rather have:
> > 
> > .. kernel-doc:: lib/idr.c
> >:functions: *  
> 
> IMHO :functions: with no parameters is simpler.

What I would really like to have there, actually, is a regex match (or,
probably better, a shell-glob match).  It would be easy to add, I've just
never gotten around to it.  That would make the above syntax just work for
those who preferred it.

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 0/2] Documentation/sphinx: add kind of "nodocs" directive

[Jonathan Corbet]

On Fri, 29 Jun 2018 15:07:34 -0600
Jonathan Corbet  wrote:

> > These patches allow passing "-no-doc-sections" option to scripts/kernel-doc
> > from the sphinx generator.
> > 
> > This allows to avoid duplicated DOC: sections when "kernel-doc:" directive
> > is used without explicit selection of functions or function types. For
> > instance, [1] has "IDA description" and "idr synchronization" twice.
> > 
> > v3 changes:
> > * add description for empty "functions" directive to
> > Documentation/doc-guide/kernel-doc.rst  
> 
> Actually, I applied the previous set this morning...any chance you could
> send me the docs update separately?

Never mind...I realized I hadn't pushed that work, so I just switched over
to the newer version, sorry for the noise.

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 0/2] Documentation/sphinx: add kind of "nodocs" directive

[Jonathan Corbet]

On Sat, 30 Jun 2018 00:05:09 +0300
Mike Rapoport  wrote:

> These patches allow passing "-no-doc-sections" option to scripts/kernel-doc
> from the sphinx generator.
> 
> This allows to avoid duplicated DOC: sections when "kernel-doc:" directive
> is used without explicit selection of functions or function types. For
> instance, [1] has "IDA description" and "idr synchronization" twice.
> 
> v3 changes:
> * add description for empty "functions" directive to
> Documentation/doc-guide/kernel-doc.rst

Actually, I applied the previous set this morning...any chance you could
send me the docs update separately?

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 1/2] Documentation/sphinx: allow "functions" with no parameters

[Jonathan Corbet]

On Wed, 20 Jun 2018 11:49:12 +0300
Mike Rapoport  wrote:

> > Looks good to me. Though I do realize now that I overlooked that this
> > applies to not only functions, but also to other non-DOC documentation
> > comments. I guess up to Jon to decide.  
>  
> We can name it "everything-except-doc-sections" ;-)

I suppose it could be :code: or :declarations: or some such.  But I think
I'm inclined to just apply the patches as they are.  The handling of
structs and such has always been a bit bolted onto the side, this doesn't
really change anything.

(Sorry for my absence in general - took some much-needed offline time).

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] docs/vm: move ksm and transhuge from "user" to "internals" section.

[Jonathan Corbet]

On Tue, 29 May 2018 13:13:38 +0300
Mike Rapoport  wrote:

> After the userspace interface description for KSM and THP was split to
> Documentation/admin-guide/mm, the remaining parts belong to the section
> describing MM internals.
> 
> Signed-off-by: Mike Rapoport 

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: doc: Italian translation

[Jonathan Corbet]

On Sun, 27 May 2018 16:55:55 +0200
Federico Vaga  wrote:

> here the doc-guide translated in Italian. This set of patches includes
> some minor changes to the main one. The idea of this first set of patches
> is also to adjust the structure and our expectations.

I've only done a quick scan so far.  It looks reasonable, but I have a
couple of requests:

 - Please include a proper changelog with each patch describing what the
   patch does and why.  Otherwise I'll have to fill them in, and that
   makes me grumpy...:)

 - You might as well add a MAINTAINERS entry.  The other translations
   don't have them, but they should.

 - For extra credit: it's time to move the translations out of the
   top-level index into an index.rst in the translations directory.  Then
   the top-level file can have a single pointer to the translations.

> We tried to translate everything in **Italian**; which means that we avoided
> imported English words wherever there is the possibility to use the Italian
> ones. Of course, this is not always possible, or worst doing the translation
> make it less clear, for example the word "file".

"We"?  Is there somebody else's work represented here too?  If so, they
should appear in the signoff chain (or as a Co-developed-by credit).

> Another point. I noticed that the disclaimer for other translations is
> in English, so I did the same. But actually shouldn't be in Italian, since
> that page will be read by Italian speakers?

Perhaps, though part of the idea is to give the English speakers, too,
some vague clue of what they're looking at.

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] docs: update kernel versions and dates in tables

[Jonathan Corbet]

On Wed, 23 May 2018 15:20:14 -0700
Tim Bird  wrote:

> Every once in a while, we should update the examples
> to reflect more recent kernel versions.
> 
> Update the tables describing kernel releases, the merge window,
> and current longterm maintained kernel, from 2.6-era kernels
> to 4.x.

I dunno...it's only been since 2011...aren't you being a little hasty?

:)

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: Documentation/translations: Italian

[Jonathan Corbet]

On Mon, 21 May 2018 22:54:18 +0200
Federico Vaga  wrote:

> I'm writing you because I would like to start an effort to translate the 
> Documentation in Italian. I would like also to express the idea of providing 
> guide lines for translations.

Mi sembra un'ottima idea! :)

> I know that there are already translations for Asian languages but I am not 
> able to find the history of them. I do not know if translations in European 
> languages are going to be accepted (perhaps there is the assumption that 
> everyone knows English in the European continent and it is a waste of energy 
> to do translations[?]). For example, even if French and Germans are quite 
> active there are not translations yet in their language: is there a 
> particular 
> reason or simply nobody did it?

Nobody has done it.  There certainly is no policy against translations to
any specific language - that would be hard to justify, to say the least.

OK, I might draw the line at Klingon.  But the discussion of error handling
in Klingon could actually be a lot of fun.

I'm happy to accept new translations of stuff in the documentation
directory.  In general, I've had two concerns about translations: they are
generally impossible for me to review, and there needs to be somebody
committed to keeping the translations current as the documentation
changes.  For Italian, the first problem doesn't exist, but the second is
always there. What are your intentions for maintaining the translations in
the long term?

> If you agree with the need to support different translations, I would like to 
> do the Italian one. But first I would like to open a little discussion about 
> translations  "how to write translations"; this discussion should produce a 
> document (in English) with guide lines for translator (e.g. Documentation/
> translation/howto.rst): what to translate first, what to NOT translate, how 
> to 
> structure it.
> Once this is defined I will start the Italian translation (I already have 
> some 
> documents translated).

This can be a fine plan, assuming we're convinced that the guidelines
document is really needed.  I guess I'm not yet convinced of that.  But you
might also consider gaining some experience in writing, merging, and
maintaining a translation before trying to lay down rules for everybody
else.  In other words, I think you might want to do things in the opposite
order.

> How to do translations (IMHO)
> -
> Here my personal guide lines for translations
> 
> - Translate only sphinx-ready documents, do not translate documents which are 
> not yet sphinx. We should avoid useless double work; at some point, I guess, 
> everything will be sphinx.

I wouldn't insist on that.  But a better idea in any case would be: if a
document you want to translate isn't yet in RST, just do the conversion.
The amount of work required is usually quite small.

> - Include in all documents a disclaimer saying that English is the main 
> reference (use sphinx directive 'include' to include it).
> - Include in all documents a reference to the English version. So it will be 
> easy jump to the original document.

Remember that the docs need to be readable *without* Sphinx processing.
Better to just name the source document in a quick line at the top, IMO.

> - Translate in order: non-technical documents (they are stable, useful for a 
> wider group of people (developers and managers): process/, doc-guide/ ), 
> technical documents about key concepts (they are stable, and important for 
> new-comers), subsystems (the big picture is stable, typically they do not 
> describe all little details that may change), and then other documents

If you want to work in that order, that is more than fine.  Others have
agreed - the process docs tend to get translated first.  But if somebody
else wants to start elsewhere, I wouldn't try to tell them not to.

Anyway, thanks for wanting to help improve the documentation!  If you have
some of this work already done, you might want to consider going ahead and
posting some patches.

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/3] docs/vm: transhuge: split userspace bits to admin-guide/mm

[Jonathan Corbet]

On Mon, 14 May 2018 11:13:37 +0300
Mike Rapoport  wrote:

> Here are minor updates to transparent hugepage docs. Except from minor
> formatting and spelling updates, these patches re-arrange the transhuge.rst
> so that userspace interface description will not be interleaved with the
> implementation details and it would be possible to split the userspace
> related bits to Documentation/admin-guide/mm, which is done by the third
> patch.

Looks good, I've applied the set, after adding a changelog for #3.

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] coresight: documentation: update sysfs section

[Jonathan Corbet]

On Mon, 14 May 2018 12:19:59 -0500
Kim Phillips  wrote:

> - Align and show updated ls devices output from the TC2, based on
>   current driver
> 
> - Provide an example from an ETMv4 based system (Juno)
> 
> - Reflect changes to the way the RAM write pointer is accessed since
>   it got changed in commit 7d83d17795ef ("coresight: tmc: adding sysFS
>   management entries").

So I was going to apply this, but it's been pretty badly corrupted by
your mailer.  Could I ask you to retry, please?

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: gpio: driver: Fix a typo and some odd grammar

[Jonathan Corbet]

On Wed, 16 May 2018 14:08:00 +0200
Jonathan Neuschäfer  wrote:

> Signed-off-by: Jonathan Neuschäfer 

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: [PATCH v2 00/11] Fix some doc build warnings/errors and broken links

[Jonathan Corbet]

On Wed,  9 May 2018 10:18:43 -0300
Mauro Carvalho Chehab  wrote:

> Patches 1 to 5 on this series contain the patches that weren't yet
> applied from the past patch series and touch only at Documentation.
> There are two changes there:
>   patch 2: fixed the description and added a c/c to cgroup maintainers;
>   patch 4: rewritten according with Louis request, droping several hunks.

Of these, I've applied 2, 4, and 6.  The networking and crypto folks like
to apply their own documentation fixes; I assume they'll pick these up.

> Patch 6 rewrites scripts/documentation-file-ref-check on Perl,
> adding an auto-fix feature.

Applied this one.

> Patches 7 and 8 fix things that would cause troubles for the
> automatic autocorrection tool.

#7 is applied.  #8 doesn't apply, though; I'm not sure which tree you made
it against?  In any case, I've stopped here for now.

> Patch 9 touches a lot of random places (including MAINTAINERS)
> that contain broken links and can be auto-fixed. It could be
> broken into one patch per touched file, but I think that is
> overkill. 

Let's keep this one (and the ones that follow) aside.  I'm happy to apply
them, but I think they are best applied as an end-of-merge-window thing.  I
envision lots of conflicts, and I already have a pile of those to explain
to Linus this time around.

Sound good?

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 -mm] mm, THP, doc: Add document for thp_swpout/thp_swpout_fallback

[Jonathan Corbet]

On Wed,  9 May 2018 16:23:41 +0800
"Huang, Ying"  wrote:

> From: Huang Ying 
> 
> Add document for newly added thp_swpout, thp_swpout_fallback fields in
> /proc/vmstat.
> 
> Signed-off-by: "Huang, Ying" 
> Cc: "Kirill A. Shutemov" 
> Cc: Andrea Arcangeli 
> Cc: Johannes Weiner 

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: [PATCH] Documentation/process/posting: wrap text at 80 cols

[Jonathan Corbet]

On Thu, 10 May 2018 20:37:37 +0100
Justin Skists  wrote:

> Trivial patch to adjust the text formatting to wrap at 80 columns. No
> actual content has changed.
> 
> Signed-off-by: Justin Skists 

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: [PATCH v2 02/11] docs: admin-guide: add cgroup-v2 documentation

[Jonathan Corbet]

On Thu, 10 May 2018 11:40:18 -0700
Tejun Heo  wrote:

> On Wed, May 09, 2018 at 10:18:45AM -0300, Mauro Carvalho Chehab wrote:
> > The cgroup-v2.txt is already in ReST format. So, move it to the
> > admin-guide, where it belongs.
> > 
> > Cc: Tejun Heo 
> > Cc: Li Zefan 
> > Cc: Johannes Weiner 
> > Signed-off-by: Mauro Carvalho Chehab   
> 
> Acked-by: Tejun Heo 

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: [RFC PATCH 1/2] scripts/kernel-doc: Auto-detect common code-blocks

[Jonathan Corbet]

On Thu, 10 May 2018 09:34:56 -0700
Matthew Wilcox  wrote:

> I think this is a bit fragile.  Why not just search for ':\n'?  Is
> there ever a case where we want to write:
> 
> /**
>  * foo is a bar:
>  * wibble
>  */
> and have wibble not be a code-block?

Yeah, we might want to write something like:

 - Leading off a bulleted list

 1) or a numbered list

for example.  That's why I was thinking of looking for explicit markers
for such lists.

It'll take some playing around with to have a hope of getting right,
methinks.

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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 11:21:13 -0300
Mauro Carvalho Chehab  wrote:

> The problem with a hint-based mechanism is that it will generate
> false hints. If added, we may end by needing to add extra tags to
> disable the hints mechanism where it gets wrong, or to periodically
> do code changes at kernel-doc comments in order to make the hints
> logic happy.
> 
> So, IMO, we should provide non-hints based mechanism, like forcing the
> string that prepends the colon to have a keyword that will make it to
> parse the block as literal, where expressions like:
> 
>   See the code-block foo:
>   See the following code example:
>   See the following flow diagram:
>   See the following artwork:
> 
> Is the best alternative to avoid "::", as on the enclosed patch.

But this, too, is a hint-based mechanism.  Thanks for the patches, I'll
keep them around, but I would like an opportunity to try to do better
before applying them.  I fear that using magic words in this way will
lead to a constant stream of surprises, and I'd like to avoid that if
possible...

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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 07:30:12 -0600
Jonathan Corbet <cor...@lwn.net> wrote:

> > (Peter said):  
> > > Independent of any philosophical discussion not allowing a setence to
> > > end with a single ':' is completely idiotic.  Please fix the tooling
> > > instead to allow it, as it is very important for being able to just
> > > write understandable comments.

*Sigh*.  Of course, Christoph said that, not Peter.  Time for more coffee.

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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 06:38:05 -0300
Mauro Carvalho Chehab  wrote:

> (Peter said):
> > Independent of any philosophical discussion not allowing a setence to
> > end with a single ':' is completely idiotic.  Please fix the tooling
> > instead to allow it, as it is very important for being able to just
> > write understandable comments.  

FWIW, there's no problem with a sentence ending with a single colon.
It's only an issue if you want to flag a special interpretation for the
text that follows that sentence.  Just to be precise.

> Patches are welcome, although I don't see any easy way to solve it.

I could envision some sort of heuristic that would recognize an indented
block containing code.  Probably we could go simpler and force the
"literal block" treatment for any indented block that lacks explicit
enumeration markers.  So:

this->would_be("a literal block");

but:

  - This would not be

Such a thing would likely be a bit fragile (people feel, rightly, that
they can put anything into normal text) but it might just work well
enough.  For best results, it should probably be done as part of Sphinx
itself, rather than yet another ugly hack in the kerneldoc script.

This particular problem may be solvable, and I'll look into it, but not
right away.  The offline world is being rather insistently obnoxious
these days...

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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Thu, 10 May 2018 14:23:35 +0200
Andrea Parri  wrote:

> only
> remember that other people (including some developers running into the
> "disadventure" of opening an RST doc. from their preferred text editor
> and being brought to conclude:  "WTH!  I need to open a web browser, I
> guess...") _use_ such doc. and _do care_ about it, and that what might
> be an improvement for some people might look as "vandalizing" to others.

If you have an example of a place where use of a web browser has been
made mandatory, please point it out.  Avoiding that was at the top of the
list of explicit requirements.  Surely an extra colon is not going to
force you to run screaming to the protective embrace of Firefox...?

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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Wed, 9 May 2018 17:20:26 +0200
Peter Zijlstra  wrote:

> The whole rst wankery is detrimental to that interface in order to
> pander to something else.. I don't see the value. I've objected before,
> and I suppose I'll object again.

One person's wankery is another's integrated, browsable, and searchable
documentation that shows some signs of having actually been thought about,
I guess.

> > It's a simple colon.  It goes along with the /** marker for kerneldoc
> > comments and the @ markers found within them, both of which you seem to
> > have found a way to live with.  
> 
> Barely, and personally I tend to not bother with kerneldoc much. Most of
> the comments I write lack the extra *, and I note that the other fix to
> this problem it to drop that spurious * here as well.

Perhaps you'd like to post a patch removing the kerneldoc mechanism?  It
would make my life a lot easier...:)

> The @arg thing is okay, it clearly distinguishes arguments/variable
> names from regular text. But "::" is the C++ class member syntax, not
> the start of an English enumeration or the like.

Not sure what C++ has to do with anything, unless we want to bring in
$LANGUAGE_WE_DISRESPECT spuriously.  I'm sure it's the Perl
do-five-different-things-magically syntax too.  It's probably an entire
natural-language processing system in Haskell.  It also happens to be the
Sphinx "start literal block" syntax.

> > You're not the only consumer of the docs.  You may not appreciate the
> > improvements that have come, but others certainly do.  I do hope that you
> > can find it in youself to avoid vandalizing things for everybody else ...?  
> 
> Why should I care for people not using text editors to write code?

The set of "people using text editors to write code" is a superset
of the set containing only Peter Zijlstra.  Many of the people who have
used text editors to write the very code we all work on find a minimally
structured documentation system to be useful.  Out of respect for them, if
nothing else, I'll ask again, please, that you suffer the substantial
cognitive drain of skipping over an extra colon.

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 13/18] wait: wait.h: Get rid of a kernel-doc/Sphinx warnings

[Jonathan Corbet]

On Wed, 9 May 2018 10:41:20 +0200
Peter Zijlstra  wrote:

> > This is easily done by using "::" instead of just ":".  
> 
> And I'll voice my objection once again. This makes a regular comment
> worse. This rst stuff is utter shit for making normal text files less
> readable in your favourite text editor.
> 
> If this gets merged, I'll simply remove that spurious ':' the next time
> I'm near that comment.

Seriously, Peter?

It's a simple colon.  It goes along with the /** marker for kerneldoc
comments and the @ markers found within them, both of which you seem to
have found a way to live with.

The RST work was discussed for a year before we even started.  It has
brought in the efforts of a large number of developers, all of whom see
the value in actually caring about our documentation and making it
accessible to a much larger group of readers.  And it has all happened
while preserving the primacy of the plain-text documentation.

You're not the only consumer of the docs.  You may not appreciate the
improvements that have come, but others certainly do.  I do hope that you
can find it in youself to avoid vandalizing things for everybody else ...?

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 18/18] w1: w1_io.c: fix a kernel-doc warning

[Jonathan Corbet]

On Wed, 9 May 2018 09:32:18 -0300
Mauro Carvalho Chehab  wrote:

> > Looks good to me, thank you!
> > What tree should this be forwarded to, or folks from linux doc will pick it 
> > up?
> > 
> > Acked-by: Evgeniy Polyakov   
> 
> Jon prefers if this could go via the usual maintainer's tree.
> 
> So, could you send it via yours?

With the ack I can pick it up, no worries.  I somehow missed this when I
went through the set.

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: refcount-vs-atomic: Update reference to LKMM doc.

[Jonathan Corbet]

On Fri,  4 May 2018 23:11:49 +0200
Andrea Parri  wrote:

> The LKMM project has moved to 'tools/memory-model/'.
> 
> Signed-off-by: Andrea Parri 

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: [PATCH 00/18] Fix some build warnings/errors with Sphinx

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:36 -0300
Mauro Carvalho Chehab  wrote:

> I decided to give a try with Sphinx last stable version
> (1.17.4), and noticed several issues. The worse one was
> with the networking book: a non-standard footnote there
> with [*] instead of a number causes it to break PDF building.
> 
> So, I took some spare time to address some warnings all over
> the tree, and moved a few text documents to a book. 

OK, I've applied the ones that seem to make sense for me to take now.
There's comments on the firmware one, and I'd rather have Tejun's OK for
the cgroup one.  The code-comment changes should probably go via the
usual maintainers.

> I with
> I had more time to move the other ones and to solve other
> warnings.

You and me both - but each step helps!

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 08/18] docs: driver-api: add clk documentation

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:44 -0300
Mauro Carvalho Chehab  wrote:

> The clk.rst is already in ReST format. So, move it to the
> driver-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

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: [PATCH 07/18] docs: core-api: add circular-buffers documentation

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:43 -0300
Mauro Carvalho Chehab  wrote:

> The circular-buffers.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

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: [PATCH 05/18] docs: core-api: add cachetlb documentation

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:41 -0300
Mauro Carvalho Chehab  wrote:

> The cachetlb.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

I think we could do a better job of this by integrating it with the
kerneldoc comments.  Meanwhile, though, this is a step in the right
direction, so I've applied it, 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 04/18] docs: admin-guide: add bcache documentation

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:40 -0300
Mauro Carvalho Chehab  wrote:

> The bcache.txt is already in ReST format. So, move it to the
> admin guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

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: [PATCH 03/18] docs: */index.rst: Add newer documents to their respective index.rst

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:39 -0300
Mauro Carvalho Chehab  wrote:

> A number of new docs were added, but they're currently not on
> the index.rst from the session they're supposed to be, causing
> Sphinx warnings.
> 
> Add them.
> 
> Signed-off-by: Mauro Carvalho Chehab 

I've applied this one, 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 06/18] docs: core-api: add cgroup-v2 documentation

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:42 -0300
Mauro Carvalho Chehab  wrote:

> The cgroup-v2.txt is already in ReST format. So, move it to the
> core-api guide, where it belongs.
> 
> Signed-off-by: Mauro Carvalho Chehab 

Honestly, this seems to me like sysadmin material, so I think it should
go into the admin guide instead.

Actually, looking at the patch, it seems you agree - it's just the
changelog that's wrong :)

I could fix that, but it should probably be posted with a CC to Tejun
first.

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/3] docs/vm: move numa_memory_policy.rst to admin-guide/mm

[Jonathan Corbet]

On Tue,  8 May 2018 10:02:07 +0300
Mike Rapoport  wrote:

> These patches include minor formatting and spelling updates to
> Documentation/vm/numa_memory_policy.rst and move this file to
> Documentation/admin-guide/mm.

Set 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 PATCH v3 0/6] Documentation/features: Provide and apply 'features-refresh.sh'

[Jonathan Corbet]

On Mon,  7 May 2018 12:43:37 +0200
Andrea Parri  wrote:

> This series provides the script 'features-refresh.sh', which operates on
> the arch support status files, and it applies this script to refresh the
> status files in place; previous discussions about this series are at [1].

Looks good, I've applied the set, 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: block: cmdline-partition.txt fixes and additions

[Jonathan Corbet]

On Sun, 6 May 2018 11:50:29 -0700
Randy Dunlap  wrote:

> Make the description of the kernel command line option "blkdevparts"
> a bit more flowing and readable.
> 
> Fix a few typos.
> Add the optional  and  suffixes.
> Note that size can be "-" to indicate all of the remaining space.
> 
> Signed-off-by: Randy Dunlap 

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: [PATCH] vfio: fix documentation

[Jonathan Corbet]

On Mon, 7 May 2018 11:02:10 +0800
"dongbo (E)"  wrote:

> Update vfio_add_group_dev description to match the current API.
> 
> Signed-off-by: Dong Bo 

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: [PATCH] doc: botching-up-ioctls: Make it clearer why structs must be padded

[Jonathan Corbet]

On Wed,  2 May 2018 09:51:06 +0200
Daniel Vetter  wrote:

> This came up in discussions when reviewing drm patches.

Applied, thanks.

> Aside: I wonder whether we shouldn't move this to some other place and
> rst-ify it? Any good suggestions?

For the moment, probably in Documentation/process, next to
volatile-considered-harmful.rst and such.  Even better, of course, would
be to have some nice document on designing user-space APIs in general...
one can always dream ... :)

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 resend] VFS: simplify seq_file iteration code and interface

[Jonathan Corbet]

On Mon, 30 Apr 2018 11:50:04 +1000
NeilBrown <ne...@suse.com> wrote:

> This patch simplifies the interface for first/next iteration and
> simplifies the code, while maintaining complete backward
> compatability.  Now:
> 
> - if ->start() is given a pos of zero, it should return an iterator
>   placed at the start of the sequence
> - if ->start() is given a non-zero pos, it should return the iterator
>   in the same state it was after the last ->start or ->next.
> 
> This is particularly useful for interators which walk the multiple
> chains in a hash table, e.g. using rhashtable_walk*. See
> fs/gfs2/glock.c and drivers/staging/lustre/lustre/llite/vvp_dev.c

For the docs part:

Acked-by: Jonathan Corbet <cor...@lwn.net>

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/7] docs/vm: update KSM documentation

[Jonathan Corbet]

On Tue, 24 Apr 2018 09:40:21 +0300
Mike Rapoport  wrote:

> These patches extend KSM documentation with high level design overview and
> some details about reverse mappings and split the userspace interface
> description to Documentation/admin-guide/mm.
> 
> The description of some KSM sysfs attributes is changed so that it won't
> include implementation detail. The description of these implementation
> details are moved to the new "Design" section.
> 
> The last patch in the series depends on the patchset that create
> Documentation/admin-guide/mm [1], all the rest applies cleanly to the
> current docs-next.

I've applied the set, 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: driver-api: fix device_connection.rst kernel-doc error

[Jonathan Corbet]

On Thu, 26 Apr 2018 18:29:41 -0700
Randy Dunlap  wrote:

> Using incorrect :functions: syntax (extra space) causes an odd kernel-doc
> warning, so fix that.
> 
> Documentation/driver-api/device_connection.rst:42: ERROR: Error in 
> "kernel-doc" directive:

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: [PATCH] documentation: core-api: rearrange a few kernel-api chapters and sections

[Jonathan Corbet]

On Thu, 26 Apr 2018 18:11:02 -0700
Randy Dunlap  wrote:

> Rearrange some kernel-api chapters and sections to group them
> together better.
> 
> - move Bit Operations from Basic C Library Functions to Basic
>   Kernel Library Functions (now adjacent to Bitmap Operations since
>   they are not typical C library functions)
> 
> - move Sorting from Math Functions to Basic Kernel Library Functions
>   since sort functions are more Basic than Math Functions
> 
> - move Text Searching from Math Functions to Basic Kernel Library
>   Functions (keep Sorting and Searching close to each other)
> 
> - combine CRC and Math functions together into the (newly named)
>   CRC and Math Functions chapter

The changes look good.  But ... grr... some of the stuff you are moving
around was introduced in -rc2 via the networking tree.  That kind of thing
makes life harder than it needs to be.  I've sorted it out and applied the
patch, 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/7] docs/vm: start moving files do Documentation/admin-guide`

[Jonathan Corbet]

On Wed, 18 Apr 2018 11:07:43 +0300
Mike Rapoport  wrote:

> These pacthes begin categorizing memory management documentation.  The
> documents that describe userspace APIs and do not overload the reader with
> implementation details can be moved to Documentation/admin-guide, so let's
> do it :)

Looks good, set 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: [PATCH v2 0/3] coresight: Refresh documenation

[Jonathan Corbet]

On Tue, 17 Apr 2018 10:08:04 -0600
Mathieu Poirier  wrote:

> Now that the perf tools CoreSight support is upstream this set adds
> documentation to go with it and move things around so that topics 
> are located together.

I've applied the set, 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] doc: dev-tools: kselftest.rst: update contributing new tests

[Jonathan Corbet]

On Thu, 19 Apr 2018 12:28:25 +0200
Anders Roxell  wrote:

> Add a description that the kernel headers should be used as far as it is
> possible and then the system headers.
> 
> Signed-off-by: Anders Roxell 

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: [PATCH v3] docs: kernel-parameters.txt: Fix whitespace

[Jonathan Corbet]

On Wed, 18 Apr 2018 20:51:39 +0200
Thymo van Beers  wrote:

> Some lines used spaces instead of tabs at line start.
> This can cause mangled lines in editors due to inconsistency.
> 
> Replace spaces for tabs where appropriate.

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: [PATCH] linux-next: ftrace/docs: Fix spelling typos in ftrace-users.rst

[Jonathan Corbet]

On Fri, 27 Apr 2018 18:17:09 -0400
Steven Rostedt  wrote:

> I just noticed that this was never applied.
> 
> Jon, can you take this?

Wow...from November.  Not sure what happened...applied 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

Re: [PATCH v2] Documentation: typec.rst: Use literal-block element with ascii art

[Jonathan Corbet]

On Wed, 25 Apr 2018 16:47:01 +0300
Jani Nikula  wrote:

> On Fri, 06 Apr 2018, Heikki Krogerus  wrote:
> > Using reStructuredText literal-block element with ascii-art.
> > That prevents the ascii art from being processed as
> > reStructuredText.
> >
> > Reported-by: Masanari Iida 
> > Fixes: bdecb33af34f ("usb: typec: API for controlling USB Type-C 
> > Multiplexers")
> > Signed-off-by: Heikki Krogerus   
> 
> Jon, this fixes a documentation build failure in v4.17-rc1. It's not
> just a warning, it's a complete fail. Our docs builder at 01.org is
> failing, apparently the same at kernel.org. Please pick it up soon.

Sorry, I'd seen the attached and was assuming Greg would ship it
Linusward.  I'll get it upstream soon.

jon

From: Greg KH 
To: changbin...@intel.com
Cc: cor...@lwn.net, linux-doc@vger.kernel.org, 
linux-ker...@vger.kernel.org
Subject: Re: [PATCH] Documentation: fix reST markup error in  
driver-api/usb/typec.rst
Date: Sun, 8 Apr 2018 09:19:58 +0200
Sender: linux-kernel-ow...@vger.kernel.org

On Sun, Apr 08, 2018 at 10:47:12AM +0800, changbin...@intel.com wrote:
> From: Changbin Du 
> 
> There is an format error in driver-api/usb/typec.rst that breaks sphinx
> docs building.
> 
> reST markup error:
> /home/changbin/work/linux/Documentation/driver-api/usb/typec.rst:215: 
> (SEVERE/4) Unexpected section title or transition.
> 
> 
> Documentation/Makefile:68: recipe for target 'htmldocs' failed
> make[1]: *** [htmldocs] Error 1
> Makefile:1527: recipe for target 'htmldocs' failed
> make: *** [htmldocs] Error 2
> 
> Signed-off-by: Changbin Du 
> ---
>  Documentation/driver-api/usb/typec.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)  

Thanks, someone else already sent this, sorry.  I'll be sending it
onward after 4.17-rc1 is out.

greg k-h
--
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] docs: ip-sysctl.txt: fix name of some ipv6 variables

[Jonathan Corbet]

On Wed, 18 Apr 2018 12:31:34 +0200
Olivier Gayot  wrote:

> The name of the following proc/sysctl entries were incorrectly
> documented:
> 
> /proc/sys/net/ipv6/conf//max_dst_opts_number
> /proc/sys/net/ipv6/conf//max_hbt_opts_number
> /proc/sys/net/ipv6/conf//max_dst_opts_length
> /proc/sys/net/ipv6/conf//max_hbt_length
> 
> Their name was set to the name of the symbol in the .data field of the
> control table instead of their .proc name.

The patch seems good, but can I suggest resending it to netdev?  Davem
likes to handle networking docs patches himself.

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 00/32] docs/vm: convert to ReST format

[Jonathan Corbet]

On Sun, 15 Apr 2018 20:36:56 +0300
Mike Rapoport  wrote:

> I didn't mean we should keep it as unorganized jumble of stuff and I agree
> that splitting the documentation by audience is better because developers
> are already know how to find it :)
> 
> I just thought that putting the doc into the place should not be done
> immediately after mechanical ReST conversion but rather after improving the
> contents.

OK, this is fine.  I'll go ahead and apply the set, but then I'll be
watching to see that the other improvements come :)

In applying the set, there was a significant set of conflicts with
vm/hmm.rst; hopefully I've sorted those out properly.

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] docs: kernel-parameters.txt: Fix whitespace

[Jonathan Corbet]

On Mon, 16 Apr 2018 17:45:01 +0200
Thymo van Beers  wrote:

> Some lines used spaces instead of tabs at line start.
> This can cause mangled lines in editors due to inconsistency.
> 
> Replace spaces for tabs where appropriate.

Seems like a fine idea.  The patch doesn't apply, though; can you please
make a version against current docs-next?  (Or against 4.17-rc1 will work
too).

Also...

>   domain
> -   Isolate from the general SMP balancing and scheduling
> -   algorithms. Note that performing domain isolation 
> this way
> -   is irreversible: it's not possible to bring back a 
> CPU to
> -   the domains once isolated through isolcpus. It's 
> strongly
> -   advised to use cpusets instead to disable scheduler 
> load
> -   balancing through the "cpuset.sched_load_balance" 
> file.
> -   It offers a much more flexible interface where CPUs 
> can
> -   move in and out of an isolated set anytime.
> -
> -   You can move a process onto or off an "isolated" CPU 
> via
> -   the CPU affinity syscalls or cpuset.
> -begins at 0 and the maximum value is
> -   "number of CPUs in system - 1".
> + Isolate from the general SMP balancing and 
> scheduling
> + algorithms. Note that performing domain 
> isolation this way
> + is irreversible: it's not possible to bring 
> back a CPU to
> + the domains once isolated through isolcpus. 
> It's strongly
> + advised to use cpusets instead to disable 
> scheduler load
> + balancing through the 
> "cpuset.sched_load_balance" file.
> + It offers a much more flexible interface where 
> CPUs can
> + move in and out of an isolated set anytime.
> +
> + You can move a process onto or off an "isolated" CPU via
> + the CPU affinity syscalls or cpuset.
> +  begins at 0 and the maximum value is
> + "number of CPUs in system - 1".

This would appear to have changed the indentation of some of the text?

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 .txt to .rst in Documentation/sound/*.rst

[Jonathan Corbet]

On Wed, 11 Apr 2018 18:33:26 +0200
Christina Quast  wrote:

> Here is a small fixup for the documentation. Unless it's too trivial to
> change it.

Applied, thanks.

In the future, though, please send patches inline rather than as
attachments; that way I don't have to clean things up to apply them.

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 00/32] docs/vm: convert to ReST format

[Jonathan Corbet]

Sorry for the silence, I'm pedaling as fast as I can, honest...

On Sun, 1 Apr 2018 09:38:58 +0300
Mike Rapoport  wrote:

> My thinking was to start with mechanical RST conversion and then to start
> working on the contents and ordering of the documentation. Some of the
> existing files, e.g. ksm.txt, can be moved as is into the appropriate
> places, others, like transhuge.txt should be at least split into admin/user
> and developer guides.
> 
> Another problem with many of the existing mm docs is that they are rather
> developer notes and it wouldn't be really straight forward to assign them
> to a particular topic.

All this sounds good.

> I believe that keeping the mm docs together will give better visibility of
> what (little) mm documentation we have and will make the updates easier.
> The documents that fit well into a certain topic could be linked there. For
> instance:

...but this sounds like just the opposite...?  

I've had this conversation with folks in a number of subsystems.
Everybody wants to keep their documentation together in one place - it's
easier for the developers after all.  But for the readers I think it's
objectively worse.  It perpetuates the mess that Documentation/ is, and
forces readers to go digging through all kinds of inappropriate material
in the hope of finding something that tells them what they need to know.

So I would *really* like to split the documentation by audience, as has
been done for a number of other kernel subsystems (and eventually all, I
hope).

I can go ahead and apply the RST conversion, that seems like a step in
the right direction regardless.  But I sure hope we don't really have to
keep it as an unorganized jumble of stuff...

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: ftrace: clarify filters with dynamic ftrace and graph

[Jonathan Corbet]

On Fri, 13 Apr 2018 11:54:03 -0400
Steven Rostedt  wrote:

> Jon, you want to take it in your tree?

Sure, I'll grab it.

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] Fixed typo in onewire generic doc

[Jonathan Corbet]

On Mon, 09 Apr 2018 02:56:49 +0300
Evgeniy Polyakov  wrote:

> Hi everyone
> 
> I'm really sorry for that long delay.
> 
> Was this patch accepted or should I push it upstream?
> 
> 20.12.2017, 22:09, "Gergo Huszty" :
> > Onewire devices has 6 byte long unique serial numbers, 1 byte family
> > code and 1 byte CRC. Linux sysfs presents the device folder in the
> > form of familyID-deviceID, so CRC is not shown. The consequence is
> > that the device serial number is always a 12 long hex-string, but
> > doc says 13 in one place. This is corrected by this change.
> > Reference: https://en.wikipedia.org/wiki/1-Wire

Commit d6f44b3bd870ff5946fcd4293b4c07029d8d93c9, merged for 4.16.

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

[Jonathan Corbet]

The following changes since commit
7928b2cbe55b2a410a0f5c1f154610059c57b1b2:

  Linux 4.16-rc1 (2018-02-11 15:04:29 -0800)

are available in the Git repository at:

  git://git.lwn.net/linux.git tags/docs-4.17

for you to fetch changes up to 86afad7d87f535ebb1a0e978bc32a8c58ac99268:

  Documentation/process: update FUSE project website (2018-03-29 15:49:18 -0600)


There's been a fair amount of activity in Documentation/ this time around:

 - Lots of work aligning Documentation/ABI with reality, done by Aishwarya
   Pant.

 - The trace documentation has been converted to RST by Changbin Du

 - I thrashed up kernel-doc to deal with a parsing issue and to try to make
   the code more readable.  It's still a 20+-year-old Perl hack, though.

 - Lots of other updates, typo fixes, and more.

Expect some annoying merge conflicts with ftrace - changes in
Documentation/trace were made independently of the RST conversion.
Probably the conversion should have gone through that tree as well, in
retrospect.  The resolution in linux-next seems good.

Aaro Koskinen (1):
  documentation: add my name to kernel driver statement

Aishwarya Pant (13):
  Documentation/ABI: clean up sysfs-class-pktcdvd
  Documentation/ABI: add sysfs interface for s6e63m0 lcd driver
  aoe: document sysfs interface
  Documentation/ABI: update infiniband sysfs interfaces
  block/loop: add documentation for sysfs interface
  backlight: lm3639: document sysfs attributes
  backlight: adp5520: document sysfs attributes
  backlight: adp8860: document sysfs attributes
  Documentation: rapidio: move sysfs interface to ABI
  block: rbd: update sysfs interface
  acpi: nfit: document sysfs interface
  char/bsr: add sysfs interface documentation
  Input: trackpoint: document sysfs interface

Andy Shevchenko (3):
  dmaengine: Add note to dmatest documentation about supported channels
  dmaengine: Make dmatest.rst indeed reST compatible
  dmaengine: Fix spelling for parenthesis in dmatest documentation

Changbin Du (17):
  Documentation: add Linux tracing to Sphinx TOC tree
  trace doc: convert trace/ftrace-design.txt to rst format
  trace doc: add ftrace-uses.rst to doc tree
  trace doc: convert trace/tracepoint-analysis.txt to rst format
  trace doc: convert trace/ftrace.txt to rst format
  trace doc: convert trace/kprobetrace.txt to rst format
  trace doc: convert trace/uprobetracer.txt to rst format
  trace doc: convert trace/tracepoints.txt to rst format
  trace doc: convert trace/events.txt to rst format
  trace doc: convert trace/events-kmem.txt to rst format
  trace doc: convert trace/events-power.txt to rst format
  trace doc: convert trace/events-nmi.txt to rst format
  trace doc: convert trace/events-msr.txt to rst format
  trace doc: convert trace/mmiotrace.txt to rst format
  trace doc: convert trace/hwlat_detector.txt to rst fromat
  trace doc: convert trace/intel_th.txt to rst format
  trace doc: convert trace/stm.txt to rst format

Dave Hansen (1):
  docs: clarify security-bugs disclosure policy

Dominik Brodowski (1):
  Documentation/process: Co-developed-by instead of Co-Developed-by

Eric Engestrom (1):
  Documentation/sparse: fix typo

Gary R Hook (1):
  Documentation/CodingStyle: Add an example for braces

Joel Stanley (1):
  Documentation: Mention why %p prints ptrval

Jonathan Corbet (12):
  docs: kernel-doc: Get rid of xml_escape() and friends
  docs: kernel-doc: Rename and split STATE_FIELD
  docs: kernel-doc: Move STATE_NORMAL processing into its own function
  docs: kernel-doc: Move STATE_NAME processing into its own function
  docs: kernel-doc: Move STATE_BODY processing to a separate function
  docs: kernel-doc: Move STATE_PROTO processing into its own function
  docs: kernel-doc: Finish moving STATE_* code out of process_file()
  docs: kernel-doc: Don't mangle literal code blocks in comments
  docs: Add an SPDX header to kernel-doc
  Merge branch 'kerneldoc2' into docs-next
  docs: ftrace: fix a few formatting issues
  Docs: Added a pointer to the formatted docs to README

Jonathan Neuschäfer (2):
  Documentation/process/howto: Remove outdated info about bugzilla mailing 
lists
  admin-guide: Fix list formatting in tained-kernels.html

Martin Kepplinger (4):
  README: Improve documentation descriptions
  Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig 
commands
  Documentation: magic-numbers: Fix typo
  Documentation/process: update FUSE project website

Masanari Iida (2):
  linux-next: SLIMbus: doc: Fix a warning "Title underline too short"
  xfs: Change URL for the project in xfs.txt

Matthew Wilcox (7):
  Add documentation for Conte

Re: [PATCH] syscalls: define and explain goal to not call syscalls in the kernel

[Jonathan Corbet]

On Sun, 25 Mar 2018 18:25:27 +0200
Dominik Brodowski  wrote:

> As there have been multiple inquiries on the rationale of my patchsets
> removing in-kernel calls to sys_xyzzy(), here is an updated patch 01/NN
> which I will push upstream for v4.17-rc1. I will also include a reference
> to this mail (and therefore to the explanation below) in all related
> patches of the series. Any improvements, hints, suggestions, spelling
> fixes, and/or objections?

I have no objections to the text, but I do wonder about the placement.
The "adding syscalls" document isn't about *invoking* them; I suspect that
few people will see it there.  The coding-style document isn't quite right
either, but I wonder if it might not be a better place in the short term?

What we may really need is an "assorted rules" document that sits near
coding style; we can put stuff like this text, "volatile considered
harmful", and so on 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

Re: [PATCH] Documentation/wimax: Point dead link to working copy

[Jonathan Corbet]

On Wed, 28 Mar 2018 22:47:07 +0800
Sanjeev Gupta  wrote:

> The linuxwimax.org domain, registered by the Linux Foundation,
> no longer has any DNS entries.  Locate a copy on archive.org and
> update the documentation.

Hmm...I worry a bit about pointing into archive.org; it's not a sign that
we're giving our readers current information.  Did anybody ask the LF what
happened to that page?

More to the point, though:

> Signed-off-by: Sanjeev Gupta 
> ---
>  Documentation/wimax/README.i2400m | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/wimax/README.i2400m 
> b/Documentation/wimax/README.i2400m
> index 7dffd8919cb0..d11502d17818 100644
> --- a/Documentation/wimax/README.i2400m
> +++ b/Documentation/wimax/README.i2400m
> @@ -61,8 +61,9 @@ $ make KDIR=/path/to/kernel/dev/tree
>  
>  3. Installing the firmware
>  
> -   The firmware can be obtained from http://linuxwimax.org or might have
> -   been supplied with your hardware.
> +   The firmware can be obtained from
> +   https://web.archive.org/web/20101224002849/http://linuxwimax.org/
> +   or might have been supplied with your hardware.

If you go into that page, you find that they don't appear to have archived
any of the tarballs, so the promised firmware isn't actually there.  So
we're not really helping people by pointing there.  It does appear that
this firmware can be found in the linux-firmware repository, though.  So
that seems like where we should be pointing people...?

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/process: update FUSE project website

[Jonathan Corbet]

On Tue, 27 Mar 2018 14:59:50 +0200
Martin Kepplinger  wrote:

> According to the old project site, https://sourceforge.net/projects/fuse/
> the project has moved to https://github.com/libfuse/ so we update the
> link to point to the latest libfuse release.

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: [PATCH] docs: kernel-doc: fix parsing of arrays

[Jonathan Corbet]

On Thu, 29 Mar 2018 10:58:59 -0400
Mauro Carvalho Chehab  wrote:

> The logic with parses array has a bug that prevents it to
> parse arrays like:
>   struct {
>   ...
>   struct {
>   u64 msdu[IEEE80211_NUM_TIDS + 1];
>   ...
>   ...
> 
> Fix the parser to accept it.

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: [PATCH 00/32] docs/vm: convert to ReST format

[Jonathan Corbet]

On Wed, 21 Mar 2018 21:22:16 +0200
Mike Rapoport  wrote:

> These patches convert files in Documentation/vm to ReST format, add an
> initial index and link it to the top level documentation.
> 
> There are no contents changes in the documentation, except few spelling
> fixes. The relatively large diffstat stems from the indentation and
> paragraph wrapping changes.
> 
> I've tried to keep the formatting as consistent as possible, but I could
> miss some places that needed markup and add some markup where it was not
> necessary.

So I've been pondering on these for a bit.  It looks like a reasonable and
straightforward RST conversion, no real complaints there.  But I do have a
couple of concerns...

One is that, as we move documentation into RST, I'm really trying to
organize it a bit so that it is better tuned to the various audiences we
have.  For example, ksm.txt is going to be of interest to sysadmin types,
who might want to tune it.  mmu_notifier.txt is of interest to ...
somebody, but probably nobody who is thinking in user space.  And so on.

So I would really like to see this material split up and put into the
appropriate places in the RST hierarchy - admin-guide for administrative
stuff, core-api for kernel development topics, etc.  That, of course,
could be done separately from the RST conversion, but I suspect I know
what will (or will not) happen if we agree to defer that for now :)

The other is the inevitable merge conflicts that changing that many doc
files will create.  Sending the patches through Andrew could minimize
that, I guess, or at least make it his problem.  Alternatively, we could
try to do it as an end-of-merge-window sort of thing.  I can try to manage
that, but an ack or two from the mm crowd would be nice to have.

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/CodingStyle: Add an example for braces

[Jonathan Corbet]

On Mon, 26 Mar 2018 11:28:03 -0500
Gary R Hook  wrote:

> Submitting a v3 because the example could better illuminate the options 
> by using loop construct inside of an if, addressing Jani's point but 
> without opening the door to later criticism.
> 
> I also like the verbage in v2/3 better, but I'll let Jonathan make the call.

As I told you, I was applying the first version; I did that last week.

> BTW which tree should these be developed against? I used torvalds, but 
> I'm not entirely sure that was the proper one?

The MAINTAINERS file will (almost) always answer that question for
you:

T:  git git://git.lwn.net/linux.git docs-next

For a patch like this it doesn't matter, since there's is no other work on
the file to conflict with.

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: magic-numbers: Fix typo

[Jonathan Corbet]

On Fri, 23 Mar 2018 08:32:31 +0100
Martin Kepplinger  wrote:

> This fixes a little then / them confusion.
> 
> Signed-off-by: Martin Kepplinger 
> ---
>  Documentation/process/magic-number.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/process/magic-number.rst 
> b/Documentation/process/magic-number.rst
> index c74199f60c6c..00cecf1fcba9 100644
> --- a/Documentation/process/magic-number.rst
> +++ b/Documentation/process/magic-number.rst
> @@ -14,7 +14,7 @@ passing pointers to structures via a void * pointer.  The 
> tty code,
>  for example, does this frequently to pass driver-specific and line
>  discipline-specific structures back and forth.
>  
> -The way to use magic numbers is to declare then at the beginning of
> +The way to use magic numbers is to declare them at the beginning of
>  the structure, like so::
>  
>   struct tty_ldisc {

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: [PATCH] Documentation: admin-guide: add kvmconfig, xenconfig and tinyconfig commands

[Jonathan Corbet]

On Thu, 22 Mar 2018 13:06:56 +0100
Martin Kepplinger  wrote:

> Add kvmconfig, xenconfig and tinyconfig to the list of alternative
> configuration commands. Descriptions are directly taken from the Makefile.

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] Input: alps - Update documentation for trackstick v3 format

[Jonathan Corbet]

On Wed, 21 Mar 2018 21:03:36 +0100
Pali Rohár  wrote:

> Bits for M, R and L buttons are already processed in alps. Other newly
> documented bits not yet.
> 
> Signed-off-by: Pali Rohár 
> ---
> This is based on information which Masaki Ota provided to us.

In the absence of screams of agony I'll assume that the change is
correct.  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: Mention why %p prints ptrval

[Jonathan Corbet]

On Thu, 22 Mar 2018 15:53:36 +1030
Joel Stanley  wrote:

> When debugging recent kernels, people will see '(ptrval)' but there
> isn't much information as to what that means. Briefly describe why it's
> there.

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: [PATCH v2 0/2] COPYING: create a new file with points to the Kernel license files

[Jonathan Corbet]

On Fri, 23 Mar 2018 06:51:04 -0300
Mauro Carvalho Chehab  wrote:

> The contents of COPYING file is now duplicated at two other
> files under LICENSE:
>   LICENSES/preferred/GPL-2.0
>   LICENSES/exceptions/Linux-syscall-note
> 
> Also, a new file was added, with describes how SPDX should work at
> the Kernel source files:
>   Documentation/process/license-rules.rst
> 
> Instead fo having it copying the contents of two files, and not
> even mentioning the third one, replace it by a file whose content
> points to the other tree files, preserving the Kernel's license.
> 
> Adjust license-rules.rst accordingly.

It looks like we're about there with these, so I went ahead and applied
them.

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] Input: trackpoint: document sysfs interface

[Jonathan Corbet]

On Fri, 2 Mar 2018 23:00:19 +0530
Aishwarya Pant  wrote:

> Descriptions have been collected from git commit logs, code commits and
> the TrackPoint System Version 4.0 Engineering Specification.

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] xfs: Change URL for the project in xfs.txt

[Jonathan Corbet]

On Fri,  2 Mar 2018 22:30:13 +0900
Masanari Iida  wrote:

> The oss.sgi.com doesn't exist any more.
> Change it to current project URL, https://xfs.wiki.kernel.org/

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] HID: ntrig: document sysfs interface

[Jonathan Corbet]

On Wed, 21 Mar 2018 09:28:05 -0600
Jonathan Corbet <cor...@lwn.net> wrote:

> > Add sysfs documentation for N-Trig touchscreens under Documentation/ABI.
> > Descriptions have been collected from code comments.  
> 
> Applied to the docs tree, thanks.

Oops, I thought I'd checked to see whether Jiri had picked these up, but I
evidently haven't had enough coffee yet.  Since they're taken care of,
I'll unapply them; sorry for the noise.

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] HID: logitech-hidpp: document sysfs interface

[Jonathan Corbet]

On Fri, 2 Mar 2018 18:46:53 +0530
Aishwarya Pant  wrote:

> Descriptions have been collected from git commit logs.

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] HID: ntrig: document sysfs interface

[Jonathan Corbet]

On Fri, 2 Mar 2018 11:00:17 +0530
Aishwarya Pant  wrote:

> Add sysfs documentation for N-Trig touchscreens under Documentation/ABI.
> Descriptions have been collected from code comments.

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] char/bsr: add sysfs interface documentation

[Jonathan Corbet]

On Thu, 1 Mar 2018 23:55:59 +0530
Aishwarya Pant  wrote:

> Descriptions have collected from code comments and by reading through
> code.

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: [trivial PATCH] Documentation/sparse: fix typo

[Jonathan Corbet]

On Tue, 13 Mar 2018 11:10:58 +
Eric Engestrom  wrote:

>  If the function enters and exits without the lock held, acquiring and
>  releasing the lock inside the function in a balanced way, no
> -annotation is needed.  The tree annotations above are for cases where
> +annotation is needed.  The three annotations above are for cases where
>  sparse would otherwise report a context imbalance.

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/CodingStyle: Add an example for braces

[Jonathan Corbet]

On Thu, 15 Mar 2018 15:04:02 -0500
Gary R Hook  wrote:

> +Do use braces when a body is more complex than a single simple statement:
> +
> +.. code-block:: c
> +
> + if (condition) {
> + if (another_condition)
> + do_something();
> + }

Somebody is sure to complain at some point that this should really be:

if (condition && another_condition)
do_something();

To head that off, I think I'll apply your first version instead, sorry
Jani.

In general I'm pretty reluctant to apply coding-style patches for the
simple reason that I sure don't want to be the arbitrator of proper kernel
style.  This one seems to fit well within the accepted norms, though.

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] docs/vm: update 00-INDEX

[Jonathan Corbet]

On Wed, 21 Mar 2018 17:05:23 +0200
Mike Rapoport  wrote:

> Several files were added to Documentation/vm without updates to 00-INDEX.
> Fill in the missing documents

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: [PATCH] kernel-doc: Remove __sched markings

[Jonathan Corbet]

On Thu, 15 Mar 2018 05:06:23 -0700
Matthew Wilcox  wrote:

> I find the __sched annotations unaesthetic in the kernel-doc.  Remove
> them like we remove __inline, __weak, __init and so on.

Makes sense, 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