- 09 Mar, 2022 7 commits
-
-
Yanteng Si authored
Translate .../Devicetree/usage-model.rst into Chinese. Signed-off-by:
Yanteng Si <siyanteng@loongson.cn> Reviewed-by:
Alex Shi <alexs@kernel.org> Link: https://lore.kernel.org/r/abc4bfa5a8eb438013913bf8ea5f8a29e5730f33.1646642188.git.siyanteng@loongson.cnSigned-off-by:
Jonathan Corbet <corbet@lwn.net>
-
Yanteng Si authored
Translate .../devicetree/index.rst into Chinese. Signed-off-by:
-
Bagas Sanjaya authored
The applying patches document (Documentation/process/applying-patches.rst) mentions incremental stable patches, but there is no example of how to apply them. Describe the process. While at it, remove note about incremental patches and move the external link of 5.x.y incremental patches to "Where can I download patches?" section. Signed-off-by:
Bagas Sanjaya <bagasdotme@gmail.com> Link: https://lore.kernel.org/r/20220307063340.256671-1-bagasdotme@gmail.comSigned-off-by:
-
Yanteng Si authored
Translate .../peci/peci.rst into Chinese. Signed-off-by:
-
Yanteng Si authored
Translate .../pici/index.rst into Chinese Signed-off-by:
-
Yanteng Si authored
Translate .../riscv/vm-layout.rst into Chinese. Signed-off-by:
-
Kees Cook authored
As a follow-up to the UMN incident[1], the TAB took the responsibility to document Researcher Guidelines so there would be a common place to point for describing our expectations as a developer community. Document best practices researchers should follow to participate successfully with the Linux developer community. [1] https://lore.kernel.org/lkml/202105051005.49BFABCE@keescook/Co-developed-by:
Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by:
Stefano Zacchiroli <zack@upsilon.cc> Signed-off-by:
Steven Rostedt <rostedt@goodmis.org> Signed-off-by:
Laura Abbott <labbott@kernel.org> Reviewed-by:
Julia Lawall <julia.lawall@inria.fr> Reviewed-by:
Wenwen Wang <wenwen@cs.uga.edu> Signed-off-by:
Kees Cook <keescook@chromium.org> Link: https://lore.kernel.org/r/20220304181418.1692016-1-keescook@chromium.orgSigned-off-by:
-
- 04 Mar, 2022 2 commits
-
-
Wan Jiabing authored
Fix following 'make htmldocs' warnings: ./Documentation/admin-guide/perf/hisi-pcie-pmu.rst: WARNING: document isn't included in any toctree Fixes: c8602008 ("docs: perf: Add description for HiSilicon PCIe PMU driver") Signed-off-by:
Wan Jiabing <wanjiabing@vivo.com> Reviewed-by:
John Garry <john.garry@huawei.com> Link: https://lore.kernel.org/r/20220228031700.1669086-1-wanjiabing@vivo.comSigned-off-by:
-
Andrew Halaney authored
With PREEMPT_RT the _bh() version of a spinlock leaves preemption enabled, align the doc to say that instead of the opposite. Reported-by:
Leah Leshchinsky <lleshchi@redhat.com> Signed-off-by:
Andrew Halaney <ahalaney@redhat.com> Reviewed-by:
Boqun Feng <boqun.feng@gmail.com> Link: https://lore.kernel.org/r/20220224212312.2601153-1-ahalaney@redhat.comSigned-off-by:
-
- 24 Feb, 2022 22 commits
-
-
Thorsten Leemhuis authored
Make Documentation/admin-guide/reporting-issues.rst point to the newly created document about regressions (Documentation/admin-guide/regressions-regressions.rst). This allows to shorten a few explanations the new document describes better and in more detail. While at it move the copyright hint to the end of the file and remove quotes around links to other places in the documentation. Both issues came up during the review of the new documents about regressions. Signed-off-by:
Thorsten Leemhuis <linux@leemhuis.info> Link: https://lore.kernel.org/r/f20114eaddc356a8c79dd62812a6c7f4ca5d87b9.1644994117.git.linux@leemhuis.infoSigned-off-by:
-
Thorsten Leemhuis authored
Add a section with a few rules of thumb about how quickly developers should address regressions to Documentation/process/handling-regressions.rst; additionally, add a short paragraph about this to the companion document Documentation/admin-guide/reporting-regressions.rst as well. The rules of thumb were written after studying the quotes from Linus found in handling-regressions.rst and especially influenced by statements like "Users are literally the _only_ thing that matters" and "without users, your program is not a program, it's a pointless piece of code that you might as well throw away". The author interpreted those in perspective to how the various Linux kernel series are maintained currently and what those practices might mean for users running into a regression on a small or big kernel update. That for example lead to the paragraph starting with "Aim to get fixes for regressions mainlined within one week after identifying the culprit, if the regression was introduced in a stable/longterm release or the devel cycle for the latest mainline release". Some might see this as pretty high bar, but on the other hand something like that is needed to not leave users out in the cold for too long -- which can quickly happen when updating to the latest stable series, as the previous one is normally stamped "End of Life" about three or four weeks after a new mainline release. This makes a lot of users switch during this timeframe. Any of them thus risk running into regressions not promptly fixed; even worse, once the previous stable series is EOLed for real, users that face a regression might be left with only three options: (1) continue running an outdated and thus potentially insecure kernel version from an abandoned stable series (2) run the kernel with the regression (3) downgrade to an earlier longterm series still supported This is better avoided, as (1) puts users and their data in danger, (2) will only be possible if it's a minor regression that doesn't interfere with booting or serious usage, and (3) might be regression itself or impossible on the particular machine, as the users might require drivers or features only introduced after the latest longterm series branched of. In the end this lead to the aforementioned "Aim to fix regression within one week" part. It's also the reason for the "Try to resolve any regressions introduced in the current development cycle before its end.". Signed-off-by:Lukas Bulwahn <lukas.bulwahn@gmail.com> Link: https://lore.kernel.org/r/a7b717b52c0d54cdec9b6daf56ed6669feddee2c.1644994117.git.linux@leemhuis.infoSigned-off-by:
-
Thorsten Leemhuis authored
Create two documents explaining various aspects around regression handling and tracking; one is aimed at users, the other targets developers. The texts among others describes the first rule of Linux kernel development and what it means in practice. They also explain what a regression actually is and how to report one properly. Both texts additionally provide a brief introduction to the bot the kernel's regression tracker uses to facilitate the work, but mention the use is optional. To sum things up, provide a few quotes from Linus in the document for developers to show how serious we take regressions. Signed-off-by:
-
Jonathan Corbet authored
Commit f7df2b1c ("tools/vm/page_owner_sort.c: count and sort by mem") added a literal text block without the necessary markup, leading to these warnings in the docs build: Documentation/vm/page_owner.rst:92: WARNING: Unexpected indentation. Documentation/vm/page_owner.rst:96: WARNING: Unexpected indentation. Documentation/vm/page_owner.rst:107: WARNING: Unexpected indentation. Add the necessary colons and make the build quieter. Signed-off-by:
-
Akira Yokosawa authored
Use past tense as the fonts can be installed after the fact. Add suggestion to install "Noto Sans CJK" and "Noto Serif CJK" font families. ("Noto Serif CJK" is optional.) Signed-off-by:Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/dfefa601-c58d-c86c-953f-5e4454db9409@gmail.comSigned-off-by:
-
Akira Yokosawa authored
Expand comments in LaTeX code and mention some of important points told in changelogs of conf.py changes. Hopefully they can help future contributors in this area. No code change involved. Signed-off-by:
-
Akira Yokosawa authored
Quote from Jon's remark [1]: I do notice that Documentation/conf.py is getting large and unapproachable. At some future point, it might be nice to pull all of the latex stuff out into a separate file where it won't scare people who stumble into it by accident. Pull LaTeX preamble settings added since commit 3b4c9632 ("docs: conf.py: adjust the LaTeX document output") out into sphinx/kerneldoc-preamble.sty. It will be copied to the build directory by the added "latex_additional_files" setting in conf.py. As a bonus, LaTeX/TeX code can be maintained without escaping backslashes. To compensate the loss of change history in sphinx/kerneldoc-preamble.sty, here is a list of changes made in conf.py: - f7ebe6b7 ("docs: Activate exCJK only in CJK chapters") - 0afd4df0 ("docs: pdfdocs: Prevent column squeezing by tabulary") - 659653c9 ("docs: pdfdocs: Refactor config for CJK document") - e291ff6f ("docs: pdfdocs: Add CJK-language-specific font settings") - 7eb368cc ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible") - 35382965 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations") - 77abc2c2 ("docs: pdfdocs: One-half spacing for CJK translations") - 788d28a2 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts") - 29ac9822 ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks") - 7c5c18bd ("docs: pdfdocs: Fix typo in CJK-language specific font settings") - aa872e06 ("docs: pdfdocs: Adjust \headheight for fancyhdr") - 8716ef41 ("docs: pdfdocs: Tweak width params of TOC") - 66939df5 ("docs: pdfdocs: Switch default CJK font to KR variants") - 7b686a2e ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles") - 5d9158e3 ("docs/translations: Skip CJK contents if suitable fonts not found") - b774cc46 ("docs: pdfdocs: Move CJK monospace font setting to main conf.py") [1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/Suggested-by: -
Naohiro Aota authored
__make_request() and end_that_request_last() do no longer exist. Replace them with the current call-site. Signed-off-by:
Naohiro Aota <naohiro.aota@wdc.com> Reviewed-by:
Chaitanya Kulkarni <kch@nvidia.com> Reviwed-by:
Jens Axboe <axboe@kernel.dk> Reviewed-by:
Christoph Hellwig <hch@lst.de> Link: https://lore.kernel.org/r/20220222012751.1933194-1-naohiro.aota@wdc.comSigned-off-by:
-
Yixuan Cao authored
There are some words that need to be fixed. Thanks for Shuah Khan's constructive suggestions. The text has been fixed as follows. a. So, if you'd like to use it, you need to add "page_owner=on" into your boot cmdline. Here, "into" has been replaced with "to". b. ...page owner is disabled in runtime due to no enabling, boot option, runtime overhead is marginal. Here, "no" has been replaced with "not". Signed-off-by:
Yixuan Cao <caoyixuan2019@email.szu.edu.cn> Acked-by:
Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20220223134104.2663-1-caoyixuan2019@email.szu.edu.cnSigned-off-by:
-
Akira Yokosawa authored
Currently, when there is no FILE argument following a switch such as -man, -rst, or -none, kernel-doc exits with a warning from perl (long msg folded): Use of uninitialized value $ARGV[0] in pattern match (m//) at ./scripts/kernel-doc line 438. , which is unhelpful. Improve the behavior by adding a check at the bottom of parsing loop. If the argument is absent, display help text and exit with the code of 1 (via usage()). Signed-off-by: -
Tomasz Warniełło authored
I wanted to clean up these lines, but in the end decided not to touch the old ones and just add my own about POD. I'll leave the cleanup for lawyers. Signed-off-by:
Tomasz Warniełło <tomasz.warniello@gmail.com> Tested-by:
-
Tomasz Warniełło authored
What for? To improve the script maintainability. 1. License As stated by Jonathan Corbet in the reply to my version 1, the SPDX line is enough. 2. The to-do list comment As suggested by Jonathan Corbet in reply to my version 3, this section doesn't need to be transitioned. And so it is removed for clarity. 3. The historical changelog comments As suggested by Jonathan Corbet in a reply to v3, this section can go. I wanted to keep it, but since it doesn't contain copyright notices, let's just have it clean and simple. 4. The "format of comments" comment block As suggested by Jani Nikula in a reply to my first version of this transformation, Documentation/doc-guide/kernel-doc.rst can serve as the information hub for comment formatting. The section DESCRIPTION already points there, so the original comment block can just be removed. Suggested-by:
Jani Nikula <jani.nikula@linux.intel.com> Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured You can see the results with: $ scripts/kernel-doc -help Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured Notes: - The -help token is added. - The entries are sorted alphbetically. Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured A subsection "reStructuredText only" is added for -enable-lineno. Other notes: - paragraphing correction Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more satisfied, script better structured The plurals in -function and -nosymbol are corrected to singulars. That's how the script works now. I think this describes the syntax better. The plurar suggests multiple FILE arguments might be possible. So this seems more coherent. Other notes: - paragraphing correction - article correction Signed-off-by:
-
Tomasz Warniełło authored
Aim: unified POD, user more happy This section is renamed to "Output format modifiers" to make it simple. To make it even more simple, a subsection is added: "reStructuredText only". Other notes: - paragraphing correction - article correction Signed-off-by:
-
Tomasz Warniełło authored
Another step in the direction of a uniform POD documentation, which will make users happier. Options land at the end of the script, not to clutter the file top. The default output format is corrected to rst. That's what it is now. A POD delimiting comment is added to the script head, which improves the script logical structure. Signed-off-by:
-
Tomasz Warniełło authored
Transition the description section into POD. This is one of the standard documentation sections. This adjustment makes the section available for POD and makes it look better. Notes: - an article addition - paragraphing correction Signed-off-by:
-
Tomasz Warniełło authored
The former usage function is substituted, although not as the -h and -help parameter handler yet. Purpose: Use Pod::Usage to handle documentation printing in an integrated way. Signed-off-by:
-
Tomasz Warniełło authored
The NAME section provides the doc title, while SYNOPSIS contains the basic syntax and usage description, which will be printed in the help document and in the error output produced on wrong script usage. The rationale is to give users simple and succinct enlightment, at the same time structuring the script internally for the maintainers. In the synopsis, Rst-only options are grouped around rst, and the rest is arranged as in the OPTIONS subsections (yet to be translated into POD, check at the end of the series). The third of the basic sections, DESCRIPTION, is added separately. Signed-off-by:
-
Oscar Shiang authored
There are 2 duplicated words found in osnoise tracer documentation. This patch removes them. Signed-off-by:
Oscar Shiang <oscar0225@livemail.tw> Acked-by:
Daniel Bristot de Oliveira <bristot@kernel.org> Link: https://lore.kernel.org/r/TYCP286MB1913117487F390E3BCE38B15A1399@TYCP286MB1913.JPNP286.PROD.OUTLOOK.COMSigned-off-by:
-
- 17 Feb, 2022 1 commit
-
-
Jonathan Corbet authored
Akira says: This series resolves issues listed below: 1. Some of chapter and section counts in Table of Contents (TOC) in large PDF docs collide with chapter/section titles, e.g., Chapters 10, 11, 12, and 13 and Section 10.10 in userspace-api.pdf. 2. In docs of more than 99 pages, page counts in TOC are not aligned properly when maxdepth >= 2 is specified in toctree, e.g., Chapters 10, 12, and 13 in userspace-api.pdf 3. In TOC of Latin-script docs, quotation and apostrophe symbols look too wide, e.g., Section 2.2 in userspace-api.pdf. 4. In TOC of translations, Korean chapter titles lose inter-phrase spaces. 5. On systems without "Noto Sans CJK" fonts, CJK chapters in translations results in full of "TOFU" boxes, with a long build time and a large log file containing lots of missing-font warnings. 6. In translations.pdf built by "make pdfdocs", ascii-art diagrams in CJK are not aligned properly.
-
- 15 Feb, 2022 8 commits
-
-
Akira Yokosawa authored
As LaTeX macros for CJK font settings can have Latin-script font settings as well, settings under Documentation/translations/ can be moved to the main conf.py. By this change, translations.pdf built by top-level "make pdfdocs" can have properly aligned ascii-art diagrams except for Korean ones. For the reason of remaining misalignment in Korean diagrams, see changelog of commit a90dad8f ("docs: pdfdocs: Add conf.py local to translations for ascii-art alignment"). Signed-off-by:
-
Akira Yokosawa authored
On systems without "Noto Sans CJK" fonts, CJK chapters in translations.pdf are full of "TOFU" boxes, with a long build time and a large log file containing lots of missing-font warnings. Avoid such waste of time and resources by skipping CJK chapters when CJK fonts are not available. To skip whole chapters, change the definition of \kerneldocBegin{SC|TC|KR|JP} commands so that they can have an argument to be ignored. This works as far as the argument (#1) is not used in the command. In place of skipped contents, put a note on skipped contents at the beginning of the PDF. Change the call sites in index.rst of CJK translations accordingly. When CJK fonts are available, existing command definitions with no argument just work. LaTeX engine will see additional pairs of "{" and "}", which add a level of grouping without having any effect on typesetting. Signed-off-by: -
Akira Yokosawa authored
Korean (Hangul) titles in Table of Contents of translations.pdf don't have inter-phrase spaces. This is because the CJKspace option of xeCJK is disabled by default. Restore the spaces by enabling the option at the beginning of every document and disable it in the \kerneldocBegin{SC|TC|JP} commands. Signed-off-by: -
Akira Yokosawa authored
xeCJK is enabled in Table of Contents (TOC) so that translations.pdf built by top-level "make pdfdocs" can have its TOC typeset properly. This causes quotation marks and apostrophe symbols appear too wide in Latin-script docs. This is because (1) Sphinx converts ASCII symbols into multi-byte UTF-8 ones in LaTeX and (2) in the SC variant of "Noto CJK" font families, those UTF-8 symbols have full-width glyph. The KR variant of the font families has half-width glyph for those symbols and TOC pages should look nicer when it is used instead. Switch the default CJK font families to the KR variant and teach xeCJK of those symbols' widths. To compensate the switch, teach xeCJK of the width in the SC and TC variants. Signed-off-by:
-
Akira Yokosawa authored
Sphinx has its own set of width parameters of Table of Contents (TOC) for LaTeX defined in its class definition of sphinxmanual.cls. It also inherits parameters for chapter entries from report.cls of original LaTeX base. However, they are optimized assuming small documents with tens of pages and chapters/sections of less than 10. To cope with some of kernel-doc documents with more than 1000 pages and several tens of chapters/sections, definitions of those parameters need to be adjusted. Unfortunately, those parameters are hard coded in the class definitions and need low-level LaTeX coding tricks to redefine. As Sphinx 1.7.9 does not have \sphinxtableofcontentshook, which defines those parameters in later Sphinx versions, for compatibility with both pre-1.8 and later Sphinx versions, empty the hook altogether and redefine \@pnumwidth, \l@chapter, \l@section, and \@subsection commands originally defined in report.cls. Summary of parameter changes: Width of page number (\@pnumwidth): 1.55em -> 2.7em Width of chapter number: 1.5em -> 1.8em Indent of section number: 1.5em -> 1.8em Width of section number: 2.6em -> 3.2em Indent of subsection number: 4.1em -> 5em Width of subsection number: 3.5em -> 4.3em Notes: 1. Parameters for subsection become relevant only when ":maxdepth: 3" is specified under "toctree::" (e.g., RCU/index.rst). They can hold subsection numbers up to 5 digits such as "18.7.13" (in RCU.pdf). 2. Number of chapters in driver-api.pdf is getting closer to 100. When it reaches 100, another set of tweaks will be necessary. 3. The low-level LaTeX trick is mentioned in "Unofficial LaTeX2e reference manual" at: http://latexref.xyz/Table-of-contents-etc_002e.htmlSigned-off-by: -
Ethan Dye authored
This fixes some simple grammar errors in the documentation for zram, specifically errors in the optional feature section of the zram documentation. Signed-off-by:
Ethan Dye <mrtops03@gmail.com> Link: https://lore.kernel.org/r/20220207235442.95090-1-mrtops03@gmail.comSigned-off-by:
-
Tang Yizhou authored
Translate scheduler/sched-energy.rst into Chinese. Signed-off-by:
Tang Yizhou <tangyizhou@huawei.com> Reviewed-by:
-
Tang Yizhou authored
Translate power/energy-model.rst into Chinese. Signed-off-by:
-
