SPHINXDIRS is useful when you want to test build only those
documents affected by your changes.

Mention it in the "Sphinx Build" section.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Maciej W. Rozycki <macro@orcam.me.uk>
Link: https://lore.kernel.org/r/50d6f0bc-030d-9529-0665-e2b3e7c792d8@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

I tried running `make pdfdocs` on NixOS, but it failed because
get_feat.pl uses a shebang line with /usr/bin/perl, and that file path
doesn't exist on NixOS. Using the more portable /usr/bin/env perl fixes
the problem.
Signed-off-by: David Reaver <me@davidreaver.com>
Link: https://lore.kernel.org/r/20220625211548.1200198-1-me@davidreaver.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Translate locking/mutex-design.rst into Chinese.
Signed-off-by: Tang Yizhou <yizhou.tang@shopee.com>
Reviewed-by: Alex Shi <alexs@kernel.org>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/20220629013240.65386-3-yizhou.tang@shopee.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Last time I forgot to edit locking/index.rst so the Chinese translation
of spinlocks hasn't been shown on web yet.
Signed-off-by: Tang Yizhou <yizhou.tang@shopee.com>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/20220629013240.65386-2-yizhou.tang@shopee.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

kernel-doc.rst has two 1st level section titles of "Writing
kernel-doc comments" and "Including kernel-doc comments".

Therefore, rather than using the first one, put a meta title
of "Kernel-doc comments" for the title of the resulting HTML
page by using the "title" directive.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/15636c13-7fa2-f973-6d3d-361222b839ef@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

With kernel releases v5.18 and later, if you have Inkscape, images
embedded in PDF documents are of vector graphics, not the raster
images as are the case with pre-v5.18 releases.
Even with pre-5.18 releases, having Inkscape would improve images
converted from some of SVG files which are not fully covered by the
limited capability of rsvg-convert(1) [1].

Add a footnote mentioning the expected improvements of such images.

Link: https://gitlab.gnome.org/GNOME/librsvg#non-goals-of-librsvg [1]
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/81cddbde-bc28-bec1-fca4-3c8fe2df502f@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Improve and add instructions to add new tests. Add build commands to
test before sending the new test patch.
Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
Reviewed-by: Shuah Khan <skhan@linuxfoundation.org>
Link: https://lore.kernel.org/r/20220521073651.4191910-1-usama.anjum@collabora.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

* update to commit f35cf1a5 ("Documentation: kernel-hacking: minor
  edits for style")

* fix a homophone typo reported by Li Feng
Reported-by: Li Feng <felixlee868@icloud.com>
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/Yp41+eTjoPRa4hrl@bobwxc.mipcSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Translate .../vm/vmalloced-kernel-stacks.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/01de54c7ecfd1999a636ee59ac40b79917251af2.1654585011.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Translate .../vm/page_migration.rst into Chinese.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/44bc4486e5019f689bcbec20a629a9f7800ece33.1654585011.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 9d19f2b5
("Documentation: riscv: Add sv48 description to VM layout")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/10cd6a241a0266d1d19ee5f0b2177d7d14d17ed2.1654685338.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from the following:

[1]: commit 23b1f183("Documentation: riscv:
     Remove the old documentation")

[2]: commit 8933e7f2 ("Documentation: riscv: remove
     non-existent directory from table of contents")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/6fe45d69210300a6c065262470bce963f8dc0ec3.1654685338.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Fix the invalid url about Semantic Patch Language
Signed-off-by: Dongliang Mu <mudongliangabcd@gmail.com>
Link: https://lore.kernel.org/r/20220613071243.12961-1-dzm91@hust.edu.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Since commit c6140415 ("f2fs: introduce FI_COMPRESS_RELEASED
instead of using IMMUTABLE bit"), we no longer use the IMMUTABLE
bit to prevent writing data for compression. Let's correct the
corresponding documentation.

BTW, this patch fixes some alignment issues in the compress
metadata layout.
Signed-off-by: Chao Liu <liuchao@coolpad.com>
Link: https://lore.kernel.org/r/20220613020800.3379482-1-chaoliu719@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

update to commit 481cc973 ("mm,doc: Add new
documentation structure")

Note: There are some empty files that do not need to be updated for now,
they are:

bootmem,
oom,
page_allocation,
page_cache,
page_reclaim,
page_tables,
physical_memory
process_addrs,
shmfs,
slab,
vmalloc,
swap.
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/35d10864fb9b57bf288d4efa5642f93a60079029.1655362610.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

update to commit d1ed51fc ("docs: vm/page_owner: tweak
literal block in STANDARD FORMAT SPECIFIERS")
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/e96557b73b036c33a9fa5abdab0c541704235e92.1655362610.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

update to commit 110bf7a5 ("Documentation/vm: rework
"Temporary Virtual Mappings" section")
Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/76c418554d9b8d395f7e8331e8e3b89d1b7beff0.1655362610.git.siyanteng@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Replace 'absense' with 'absence'.
Signed-off-by: Steven Lung <1030steven@gmail.com>
Link: https://lore.kernel.org/r/20220621072910.4704-1-1030steven@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit ac23d1a9
("XArray: Document the locking requirement for the xa_state")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/b7d5f3ca914667ec14ba35a7c0db3ec3506e670d.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit f9eaaa82
("workqueue: doc: Call out the non-reentrance conditions")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/d045cb5623b5ae703c2296d3caa05017d5d225bd.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 6a7ca80f
("vsprintf: Update %pGp documentation about that it prints hex value")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/2ba15ab2aa46bfdd400d1c043eecc12bc6154836.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 7d9e2661
("printk: Move the printk() kerneldoc comment to its new home")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/56c6d212d6835029b4adf19cf78eec49c7a126d6.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from the following commits(Latest in front):

[1]: commit 84dacdbd("mm: document and polish read-ahead code")

[2]: commit 2f52578f("mm/util: Add folio_mapping() and
     folio_file_mapping()")

[3]: commit 889a3747("mm/lru: Add folio LRU functions")

[4]: commit c24016ac("mm: Add folio reference count functions")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/0bd7b03a5d38dd1599715343360bef4289b7c0fb.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 640d1930
("block: Add bio_for_each_folio_all()")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Link: https://lore.kernel.org/r/9173878562404f4518fecc7c55032fe815f87fd9.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from the following commits(Latest in front):

[1]: commit 0953fb26("irq: remove handle_domain_{irq,nmi}()")

[2]: commit 0ddc5e55("Documentation: Fix irq-domain.rst build warning")

[3]: commit 991007ba("Documentation: Update
     irq_domain.rst with new lookup APIs")

[4]: commit 405e94e9("irqdomain: Kill irq_domain_add_legacy_isa")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/eb82606f323c4c25e497a01a060e1e76f18be72f.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit c9871c80
("Documentation: core-api/cpuhotplug: Rewrite the API section")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/9a123a1938a09f883db0b429396954e0792c84c1.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Synchronous translation from upstream commit 08b0b005
("mm: Add flush_dcache_folio()")
Signed-off-by: Binbin Zhou <zhoubinbin@loongson.cn>
Reviewed-by: Yanteng Si<siyanteng@loongson.cn>
Reviewed-by: Wu XiangCheng <bobwxc@email.cn>
Link: https://lore.kernel.org/r/d1fe8dfa3cfc3fe38c7caf8b5cf3b3482b5bddf8.1655863769.git.zhoubinbin@loongson.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Correct some simple spelling mistakes in consumer.rst, driver.rst
and using-gpio.rst.
Signed-off-by: Tom Schwindl <schwindl@posteo.de>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/YrTdAv3YPlCiDr2u@posteo.deSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Delete duplicate words of "the".
Signed-off-by: Deming Wang <wangdeming@inspur.com>
Link: https://lore.kernel.org/r/20220624014605.2007-1-wangdeming@inspur.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Text in ``literal`` markup must be separated by word separators, so text
like ``lowwater``% renders incorrectly.  Add the suggested "\ " after two
problematic occurrences.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Link: https://lore.kernel.org/r/20220624110230.595740-1-steve@sk2.org
[jc: tweaked to use "\ "]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

The convention for help text indentation seems to be a single tab followed
by two whitespaces. Do that.

While at it, remove a stray empty line.
Signed-off-by: Juerg Haefliger <juergh@canonical.com>
Link: https://lore.kernel.org/r/20220517140837.331298-1-juergh@canonical.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Update zh_CN/admin-guide/reporting-issues.rst to newest English version

commit 247097e2 ("docs: reporting-issues.rst: link new document
                       about regressions")
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alexs@kernel.org>
Link: https://lore.kernel.org/r/YoRlDOUl/eg+h/Cc@bobwxc.mipcSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add a series of blank lines to this document to get consistend rendering as
an RST description list.
Signed-off-by: Martin Liska <mliska@suse.cz>
Link: https://lore.kernel.org/r/d0e576ab-6121-b7d7-da5b-7750f05ca7f4@suse.czSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Some warnings do not increment the warnings counter making the behavior
of running kernel-doc with -Werror unlogical as some warnings will be
generated but not treated as errors.

Fix this by creating a helper function that always incrementing the
warnings counter every time a warning is emitted. There is one location
in get_sphinx_version() where a warning is not touched as it concerns
the execution environment of the kernel-doc and not the documentation
being processed.

Incrementing the counter only have effect when running kernel-doc in
either verbose mode (-v or environment variable KBUILD_VERBOSE) or when
treating warnings as errors (-Werror or environment variable
KDOC_WERROR). In both cases the number of warnings printed is printed to
stderr and for the later the exit code of kernel-doc is non-zero if
warnings where encountered.

Simple test case to demo one of the warnings,

    $ cat test.c
    /**
     * foo() - Description
     */
    int bar();

    # Without this change
    $ ./scripts/kernel-doc -Werror -none test.c
    test.c:4: warning: expecting prototype for foo(). Prototype was for
    bar() instead

    # With this change
    $ ./scripts/kernel-doc -Werror -none test.c
    test.c:4: warning: expecting prototype for foo(). Prototype was for
    bar() instead
    1 warnings as Errors
Signed-off-by: Niklas Söderlund <niklas.soderlund@corigine.com>
Link: https://lore.kernel.org/r/20220613090510.3088294-1-niklas.soderlund@corigine.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Merge tag 'platform-drivers-x86-v5.19-2' of git://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86

Pull x86 platform driver fixes from Hans de Goede:
 "Highlights:

   - Fix hp-wmi regression on HP Omen laptops introduced in 5.18

   - Several hardware-id additions

   - A couple of other tiny fixes"

* tag 'platform-drivers-x86-v5.19-2' of git://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86:
  platform/x86/intel: hid: Add Surface Go to VGBS allow list
  platform/x86: hp-wmi: Use zero insize parameter only when supported
  platform/x86: hp-wmi: Resolve WMI query failures on some devices
  platform/x86: gigabyte-wmi: Add support for B450M DS3H-CF
  platform/x86: gigabyte-wmi: Add Z690M AORUS ELITE AX DDR4 support
  platform/x86: barco-p50-gpio: Add check for platform_driver_register
  platform/x86/intel: pmc: Support Intel Raptorlake P
  platform/x86/intel: Fix pmt_crashlog array reference
  platform/mellanox: Add static in struct declaration.
  platform/mellanox: Spelling s/platfom/platform/

Pull workqueue fixes from Tejun Heo:
 "Tetsuo's patch to trigger build warnings if system-wide wq's are
  flushed along with a TP type update and trivial comment update"

* tag 'wq-for-5.19-rc1-fixes' of git://git.kernel.org/pub/scm/linux/kernel/git/tj/wq:
  workqueue: Switch to new kerneldoc syntax for named variable macro argument
  workqueue: Fix type of cpu in trace event
  workqueue: Wrap flush_workqueue() using a macro

Merge tag 'kbuild-fixes-v5.19' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild

Pull Kbuild fixes from Masahiro Yamada:

 - Make the *.mod build rule portable for POSIX awk

 - Fix regression of 'make nsdeps'

 - Make scripts/check-local-export working for older bash versions

 - Fix scripts/gdb to extract the .config data from vmlinux

* tag 'kbuild-fixes-v5.19' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild:
  scripts/gdb: change kernel config dumping method
  scripts/check-local-export: avoid 'wait $!' for process substitution
  scripts/nsdeps: adjust to the format change of *.mod files
  kbuild: avoid regex RS for POSIX awk

Pull cifs client fixes from Steve French:
 "Three reconnect fixes, all for stable as well.

  One of these three reconnect fixes does address a problem with
  multichannel reconnect, but this does not include the additional
  fix (still being tested) for dynamically detecting multichannel
  adapter changes which will improve those reconnect scenarios even
  more"

* tag '5.19-rc1-smb3-client-fixes' of git://git.samba.org/sfrench/cifs-2.6:
  cifs: populate empty hostnames for extra channels
  cifs: return errors during session setup during reconnects
  cifs: fix reconnect on smb3 mount types

Pull random number generator fixes from Jason Donenfeld:

 - A fix for a 5.19 regression for a case in which early device tree
   initializes the RNG, which flips a static branch.

   On most plaforms, jump labels aren't initialized until much later, so
   this caused splats. On a few mailing list threads, we cooked up easy
   fixes for arm64, arm32, and risc-v. But then things looked slightly
   more involved for xtensa, powerpc, arc, and mips. And at that point,
   when we're patching 7 architectures in a place before the console is
   even available, it seems like the cost/risk just wasn't worth it.

   So random.c works around it now by checking the already exported
   `static_key_initialized` boolean, as though somebody already ran into
   this issue in the past. I'm not super jazzed about that; it'd be
   prettier to not have to complicate downstream code. But I suppose
   it's practical.

 - A few small code nits and adding a missing __init annotation.

 - A change to the default config values to use the cpu and bootloader's
   seeds for initializing the RNG earlier.

   This brings them into line with what all the distros do (Fedora/RHEL,
   Debian, Ubuntu, Gentoo, Arch, NixOS, Alpine, SUSE, and Void... at
   least), and moreover will now give us test coverage in various test
   beds that might have caught the above device tree bug earlier.

 - A change to WireGuard CI's configuration to increase test coverage
   around the RNG.

 - A documentation comment fix to unrelated maintainerless CRC code that
   I was asked to take, I guess because it has to do with polynomials
   (which the RNG thankfully no longer uses).

* tag 'random-5.19-rc2-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/crng/random:
  wireguard: selftests: use maximum cpu features and allow rng seeding
  random: remove rng_has_arch_random()
  random: credit cpu and bootloader seeds by default
  random: do not use jump labels before they are initialized
  random: account for arch randomness in bits
  random: mark bootloader randomness code as __init
  random: avoid checking crng_ready() twice in random_init()
  crc-itu-t: fix typo in CRC ITU-T polynomial comment