The script should not generate cross-references inside
literal blocks.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/a590f994f8a5742db333bde69e88241a080e4fe0.1616668017.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Change the description parsing logic in rst mode in order
to parse it line per line.

The end result is the same, but doing line per line allows
to add some code to escape literal blocks when seeking for
cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/d33cfa2e59ecf8f28d4ed7de7402468cf2168921.1616668017.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Currently, there are "What:" symbols for more than just
/sys.

Extend the regex to also cover configfs, /proc /dev and /kvd
symbols.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/a1c7e2b2c37ed6e111dfc8641deb37ed96375a63.1616668017.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

There are some issues with the regex that seeks for What:
cross references: basically, it is mis-identifying the start
and the end boundaries of the regex, which causes :ref: to
be inseerted for the wrong symbols at the wrong places.

Fix it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/79a14d2518499b76931b5f29c50979987108152d.1616668017.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Instead of retrieving just one match at most, ensure that the entire
description will be parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/17019b73e106d1b1b353b8880ed189bad3604c13.1616668017.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

The parser for the symbols defined on What: doesn't cover all
chars that need to be scaped, like '{' and '}'. Change the logic
to be more generic, and ensure that the same regex will be used
on both What: and when parsing the cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/29cb56def89b508fe605bcd2ba74a4376cc08e35.1616668017.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

I am leaving Alibaba, udpate the old email address to new one.
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: Harry Wei <harryxiyou@gmail.com>
Cc: Alex Shi <alexs@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Link: https://lore.kernel.org/r/1616748571-52058-2-git-send-email-alex.shi@linux.alibaba.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add my kernel.org address for old email address.
Signed-off-by: Alex Shi <alex.shi@linux.alibaba.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Kees Cook <keescook@chromium.org>
Cc: Leon Romanovsky <leon@kernel.org>
Cc: Thomas Bogendoerfer <tsbogend@alpha.franken.de>
Cc: Alexander Lobakin <alobakin@pm.me>
Cc: linux-kernel@vger.kernel.org
Link: https://lore.kernel.org/r/1616748571-52058-1-git-send-email-alex.shi@linux.alibaba.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Reported-by: Hulk Robot <hulkci@huawei.com>
Signed-off-by: He Ying <heying24@huawei.com>
Acked-by: Michael Ellerman <mpe@ellerman.id.au>
Link: https://lore.kernel.org/r/20210326100853.173586-1-heying24@huawei.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Change multiple sys/xyz to /sys/xyz
Signed-off-by: Mark O'Donovan <shiftee@posteo.net>
Link: https://lore.kernel.org/r/20210328152837.73347-1-shiftee@posteo.netSigned-off-by: Jonathan Corbet <corbet@lwn.net>

A pile of small fixes:

- don't quote terms like vanilla, mainline, and stable, unless in they
  occur in places where readers new to the kernel might see them for the
  first time

- make people rule out that vendor patches are interfering if they face
  a regression in a stable or longterm kernel they saw in a vendor
  kernel for the first time

- s/bugs/issues/ in a selected spots

- exchange two headlines that got mixed up somehow

- add a few links to some of the steps in the guide

- Greg mentioned sending reports to the stable mailing list is
  sufficient, so remove the "CC stable maintainers" bits

- fix a few typos and mistakes in the text, with a few very small
  improvements along the way
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/07bca15d8465b8e234537feb8841dd2ff20243bc.1617113469.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Make the TLDR a bit shorter while improving it at the same time by going
straight to the aspects readers are more interested it. The change makes
the process especially more straight-forward for people that hit a
regression in a stable or longterm kernel. Due to the changes the TLDR
now also matches the step by step guide better.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/762ccd7735315d2fdaa79612fccc1f474881118b.1617113469.git.linux@leemhuis.info
[ jc: fixed transposed _` as noted by Thorsten ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Thorsten will keep an eye on the new document about reporting issues
(aka bugs).
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/c8d55ec74d104b90fdb9c155bca3b407e8480fb3.1617113469.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Remove the WIP and two FIXME notes in the text to make it official, as
it's now considered fully ready for consumption. To make sure this
step is okay for people the intent of this change and the latest version
of the text were posted to ksummit-discuss; nobody complained, thus
lets move ahead.

Add a footer to point out people can contact Thorsten directly in case
they find something to improve in the text.

Dear reporting-bugs.rst, I'm sorry to tell you, but that makes you fully
obsolete and we thus have to let you go now. Thank you very much for
your service, you in one form or another have been around for a long
time. I'm sure over the years you got read a lot and helped quite a few
people. But it's time to retire now. Rest in peace.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
CC: Harry Wei <harryxiyou@gmail.com>
CC: Alex Shi <alex.shi@linux.alibaba.com>
CC: Federico Vaga <federico.vaga@vaga.pv.it>
CC: Greg KH <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/49c674c2d304d87e6259063580fda05267e8c348.1617113469.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Commit 1a63f9cc ("docs: Remove make headers_check from checklist")
fixed only the English version.

Let's fix the translated variants too.
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
Link: https://lore.kernel.org/r/20210302141822.504773-1-masahiroy@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Currently, kernel-doc start parsing the comment as a kernel-doc comment if
it starts with '/**', but does not take into account if the content inside
the comment too, adheres with the expected format.
This results in unexpected and unclear warnings for the user.

E.g., running scripts/kernel-doc -none mm/memcontrol.c emits:
"mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead"

Here kernel-doc parses the corresponding comment as a kernel-doc comment
and expects prototype for it in the next lines, and as a result causing
this warning.

Provide a clearer warning message to the users regarding the same, if the
content inside the comment does not follow the kernel-doc expected format.
Signed-off-by: Aditya Srivastava <yashsri421@gmail.com>
Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

The previous attempt to properly handle literal blocks broke parsing of
parameter lines containing colons; fix it by tweaking the regex to
specifically exclude the "::" pattern while accepting lines containing
colons in general.  Add a little documentation to the regex while in the
neighborhood.
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Fixes: 8d295fba ("kernel-doc: better handle '::' sequences")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Right now, if one of the following headers end with a '::', the
kernel-doc script will do the wrong thing:

	description|context|returns?|notes?|examples?

The real issue is with examples, as people could try to write
something like:

	example::

		/* Some C code */

and this won't be properly evaluated. So, improve the regex
to not catch '\w+::' regex for the above identifiers.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/2cf44cf1fa42588632735d4fbc8e84304bdc235f.1616696051.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Provide a shorter and easier process for users that deal with
regressions in stable and longterm kernels, as those should be reported
quickly.

To realize this in the least-confusing way and without having steps
multiple times in different places, split the 'search for existing
reports' into two. That has the additinal benefit that users will search
for them quickly when going through the step by step guide and thus will
save them trouble if the find reports.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
CC: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/d934c15e536bceeff5c40a126930ddf803548e08.1616181657.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

This duplicates two section to make the diff in the next patch a bit
easier to gasp for humans.

Straight copy, no content changes.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/ef85edc8466f035eb243dd6629429ad4fd0565d8.1616181657.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Reorder some steps where the order in which the readers perform them is
not crucial. This is a preparation for a later change that would make
the text much more complex otherwise.

Content just moved, not changed at all in the process.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/8dfc58efde25a05ccf9bf85929826c4b1b9e09c5.1616181657.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Tell users that reporting bugs with vendor kernels which are only
slightly patched can be okay in some situations, but point out there's a
risk in doing so.

Adjust some related sections to make them compatible and a bit clearer.
At the same time make them less daunting: we want users to report bugs,
even if they can't test vanilla mainline kernel.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
CC: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/652ee20eb36228f5d7ca842299faa4cb472feedb.1616181657.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Fix a typo and change "head over" to "scroll down", as suggested by Jon
when reviewing another patch that used the phrase the same way.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Link: https://lore.kernel.org/r/fb845d2f1db6138337203bbfac419c04b5f28053.1616181657.git.linux@leemhuis.infoSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add translation zh_CN/admin-guide/init.rst, and link it to
zh_CN/admin-guide/index.rst while clean its todo entry.
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/cd2fd8d0ea2ad50afc6bd2abe15eba73b6c7940c.1616050069.git.bobwxc@email.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add translation zh_CN/admin-guide/tainted-kernels.rst, and link it to
zh_CN/admin-guide/index.rst while clean its todo entry.
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/189f2403ad168dafb4d5e50847c235064a2acaad.1616050069.git.bobwxc@email.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add translation zh_CN/admin-guide/security-bugs.rst, and link it to
zh_CN/admin-guide/index.rst while clean its todo entry.
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/f4210d304fa3f0b2a6e9eb798f63bf2e267231a0.1616050069.git.bobwxc@email.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add translation zh_CN/admin-guide/bug-hunting.rst, and link it to
zh_CN/admin-guide/index.rst while clean its todo entry.
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/dad9f26205e9cae7254ed21c796688851ca5ebfd.1616050069.git.bobwxc@email.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add translation zh_CN/admin-guide/bug-bisect.rst, and link it to
zh_CN/admin-guide/index.rst while clean its todo entry.
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/b9106f76fdc8e20ce4fcd43aec499f00df411610.1616050069.git.bobwxc@email.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add translation zh_CN/admin-guide/reporting-issues.rst, and link it to
zh_CN/admin-guide/index.rst.
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/13d126d5a210988728c76398436c62f1fb25fb0c.1616050069.git.bobwxc@email.cnSigned-off-by: Jonathan Corbet <corbet@lwn.net>

s/provisoned/provisioned/
Signed-off-by: Bhaskar Chowdhury <unixbhaskar@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: OGAWA Hirofumi <hirofumi@mail.parknet.co.jp>
Link: https://lore.kernel.org/r/20210319015848.19515-1-unixbhaskar@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Change the spelling from "consistend" to "consistent".
Signed-off-by: Dan Carpenter <dan.carpenter@oracle.com>
Link: https://lore.kernel.org/r/YFS5KV7ejNoZmt6H@mwandaSigned-off-by: Jonathan Corbet <corbet@lwn.net>

s/struture/structure/
Signed-off-by: Bhaskar Chowdhury <unixbhaskar@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20210322062237.2971314-1-unixbhaskar@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

All the error message types now have a verbose description.

Also there are two new groups of message types:

- Macros, Attributes and Symbols
- Functions and Variables

Rearrange the message types to fit these new groups as needed.
Signed-off-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
Reviewed-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20210322082139.33822-1-dwaipayanray1@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Add new translations

* Documentation/translations/zh_CN/kernel-hacking/index.rst
* Documentation/translations/zh_CN/kernel-hacking/hacking.rst

And link them to zh_CN/index.rst.
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Reviewed-by: Alex Shi <alex.shi@linux.alibaba.com>
Link: https://lore.kernel.org/r/20210323091651.GA23904@mipcSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Translate this commit to Korean:

    cf6d6fc2 ("docs: process/howto.rst: make sections on bug reporting match practice")
Signed-off-by: SeongJae Park <sjpark@amazon.de>
Link: https://lore.kernel.org/r/20210308075701.23411-1-sj38.park@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Signed-off-by: Bryan Brattlof <hello@bryanbrattlof.com>
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
Link: https://lore.kernel.org/r/20210323145509.139393-1-hello@bryanbrattlof.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

s/maintanence/maintenance/
Signed-off-by: Bhaskar Chowdhury <unixbhaskar@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20210324080046.20709-1-unixbhaskar@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

After commit 8341f2f2 ("sysrq: Use panic() to force a crash"),
a crash was not generated by dereferencing a NULL pointer anymore.

Let's update documentation as well to make it less misleading.
Signed-off-by: Gao Xiang <hsiangkao@redhat.com>
Cc: Matthias Kaehlcke <mka@chromium.org>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Zefan Li <lizefan.x@bytedance.com>
Link: https://lore.kernel.org/r/20210309191550.3955601-1-hsiangkao@redhat.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>

To declutter the top-level table of contents (the side bar), this
patch reduces the architecture-specfic documentation to one top-level
item, "CPU Architectures".
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Link: https://lore.kernel.org/r/20210312152804.2110703-1-j.neuschaefer@gmx.netSigned-off-by: Jonathan Corbet <corbet@lwn.net>

Loadpin cmdline interface "enabled" has been renamed to "enforce"
for a long time, but the User Description Document was not updated.
(Meaning unchanged)

And kernel_read_file* were moved from linux/fs.h to its own
linux/kernel_read_file.h include file. So update that change here.
Signed-off-by: Jiele zhao <unclexiaole@gmail.com>
Link: https://lore.kernel.org/r/20210308020358.102836-1-unclexiaole@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>