Commit Graph

616124 Commits

Author SHA1 Message Date
Mauro Carvalho Chehab
0cef67aa65 Documentation/SubmitChecklist: update kernel-doc task
Task 11 (kernel-doc) still mentions usage of make manpages, but
this won't work if the API is documented via Sphinx. So, update
it to use either htmldocs or pdfdocs, with are the documentation
targets that work for all.

While here, add ReST reference to the kernel documentation book.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:41:44 -06:00
Mauro Carvalho Chehab
f1eebe92c2 Documentation/HOWTO: adjust external link references
- A few link references were missing http://
- Several sites are now redirecting to https protocol. On such
  cases, just use the https URL.

NOTE: all URLs were checked and they're pointing to the right places.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:41:36 -06:00
Mauro Carvalho Chehab
34fed7e7e0 Documentation/HOWTO: improve some markups to make it visually better
Do a series of minor improvements at the ReST output format:

- Instead of using the quote blocks (::) for quotes, use
italics. That looks nicer on epub (and html) output, as
no scroll bar will be added. Also, it will adjust line
breaks on the text automatically.

- Add a missing reference to SubmittingPatches.rst and use
**foo** instead of _foo_.

- use bold for "The Perfect Patch" by removing a newline.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:41:27 -06:00
Mauro Carvalho Chehab
43fb67a525 Documentation/HOWTO: update information about generating documentation
The description there are pre-Sphinx. Update it to cover the
new way.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:41:22 -06:00
Mauro Carvalho Chehab
609d99a3b7 Documentation/HOWTO: add cross-references to other documents
Add cross references for the documents mentioned at HOWTO and
are under the Documentation/ directory, using the ReST notation.

It should be noticed that HOWTO also mentions the /README file.
We opted to not touch it, for now, as making it build on
Sphinx would require it to be moved to a Documentation/foo
directory.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:41:04 -06:00
Mauro Carvalho Chehab
9e03ea7f68 Documentation/kernel-docs.txt: convert it to ReST markup
This one required lots of manual work, for it to be properly
displayed.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-20 18:40:26 -06:00
Mauro Carvalho Chehab
9b2c76777a Documentation/SubmittingPatches: enrich the Sphinx output
Do a few changes to make the output look better:

- use bullets on trivial patches list;
- use monotonic font for tools name;
- use :manpage:`foo` for man pages;
- don't put all references to maintainer*html at the same line.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:39:31 -06:00
Mauro Carvalho Chehab
5903019b2a Documentation/SubmittingPatches: convert it to ReST markup
- Change the sections to use ReST markup;
- Add cross-references where needed;
- convert aspas to verbatim text;
- use code block tags;
- make Sphinx happy.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:39:17 -06:00
Mauro Carvalho Chehab
ceeb1a5415 Documentation/SubmittingDrivers: convert it to ReST markup
- Change the document title markup to make it on a higher level;
- Add blank lines as needed, to improve the output;
- use italics for the country-code at kernel.org ftp URL.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:39:07 -06:00
Mauro Carvalho Chehab
5fe270a47e Documentation/stable_kernel_rules.txt: convert it to ReST markup
- use ReST markups for section headers;
- add cross-references to the options;
- mark code blocks;
- a few minor changes to make Sphinx happy.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:38:51 -06:00
Mauro Carvalho Chehab
44f9d45e38 Documentation/stable_api_nonsense.txt: convert it to ReST markup
Add markups for it to be properly parsed by Sphinx.

As people browsing this document may not notice that the source
file title is "stable_api_nonsense", I opted to use bold to
the rationale for this document. I also found it better to
add a note when it says that the nonsense applies only to the
kABI/kAPI, and not to uAPI.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:38:22 -06:00
Mauro Carvalho Chehab
1d7078d4e2 Documentation/SecurityBugs: convert it to ReST markup
Add a name for the document and convert the sections to
ReST markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:37:31 -06:00
Mauro Carvalho Chehab
7f2b3c65b9 Documentation/ManagementStyle: convert it to ReST markup
- Convert document name to ReST;
- Convert footnotes;
- Convert sections to ReST format;
- Don't use _foo_, as Sphinx doesn't support underline. Instead,
  use bold;
- While here, remove whitespaces at the end of lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:37:06 -06:00
Mauro Carvalho Chehab
3772ec4adf Documentation/CodingStyle: use the .. note:: markup where needed
There are two places there where there are notes that should
be highlighted. So, use the ReST note markup for such texts.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:37:01 -06:00
Mauro Carvalho Chehab
5d628b4527 Documentation/CodingStyle: replace underline markups
Sphinx doesn't accept underline markups by purpose.
While there are ways to support underline via CSS, this won't
be portable with non-html outputs.

As we want CodingStyle to do emphasis, replace _foo_ by **foo**,
using bold emphasis.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:36:57 -06:00
Mauro Carvalho Chehab
b1a3459b00 Documentation/CodingStyle: use the proper tag for verbatim font
On Sphinx/ReST notation, ``foo`` means that foo will be will be
marked as inline literal, effectively making it to be presented
as a monospaced font.

As we want this document to be parsed by Sphinx, instead of using
"foo", use ``foo`` for the names that are literal, because it is an
usual typographic convention to use monospaced fonts for functions
and language commands on documents, and we're following such
convention on the other ReST books.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:36:53 -06:00
Mauro Carvalho Chehab
d8dbbbc54f Documentation/CodingStyle: Convert to ReST markup
- Fix all chapter identation;
- add c blocks where needed;

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:35:36 -06:00
Mauro Carvalho Chehab
81f10d1998 Documentation/Changes: add minimal requirements for documentation build
As discussed at linux-doc ML, the best is to keep all documents
backward compatible with Sphinx version 1.2, as it is the latest
version found on some distros like Debian.

All books currently support it.

Please notice that, while it mentions the eventual need of
XeLaTex and texlive to build pdf files, this is not a minimal
requirement, as one could just be interested on building html
documents. Also, identifying the minimal requirements for
texlive packages is not trivial, as each distribution seems to
use different criteria on grouping LaTex functionalities.

While here, update the current kernel version to 4.x.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:35:30 -06:00
Mauro Carvalho Chehab
840f6690b0 Documentation/Changes: convert it to ReST markup
- Fix chapter identation inconsistencies;
- Convert table to ReST format;
- use the right tag for bullets;
- Fix bold emphasis;
- mark blocks with :: tags;
- use verbatim font for files;
- make Sphinx happy

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:35:03 -06:00
Mauro Carvalho Chehab
330ae7e99d Documentation/applying-patches.txt: Update the information there
This document is old: it is from Kernel v2.6.12 days.
Update it to the current status, and add a reference for the
linux-next tree.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:34:57 -06:00
Mauro Carvalho Chehab
9299c3e92c Documentation/applying-patches.txt: convert it to ReST markup
- use the correct markup to identify each section;

- Add some blank lines for Sphinx to properly interpret
  the markups;

- Remove a blank space on some paragraphs;

- Fix the verbatim and bold markups;

- Cleanup the remaining errors to make Sphinx happy.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:34:32 -06:00
Mauro Carvalho Chehab
022e04d6f5 Documentation/HOWTO: convert to ReST notation
This document is almost compliant with ReST notation, but some
small adjustments are needed to make it parse properly by
Sphinx (mostly, add blank lines where needed).

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:34:16 -06:00
Mauro Carvalho Chehab
f0ddda3e94 docs-rst: create a book for the development process
Now that the files at Documentation/development-process/
were converted to ReST, make create a book at Sphinx.

As we'll have other books related to the development process,
we'll add it as a sub-book.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:33:46 -06:00
Mauro Carvalho Chehab
88b72c08e8 doc: development-process: rename files to rst
Now that the documents were converted, rename them to .rst, as
this is needed by the Sphinx build logic.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:31:29 -06:00
Mauro Carvalho Chehab
f7c9fe4b1c doc: development-process: convert it to ReST markup
This document is on good shape for ReST: all it was needed was
to fix the section markups, add a toctree, convert the tables
and add a few code/quote blocks.

While not strictly required, I opted to use lowercase for
the titles, just like the other books that were converted
to Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-20 18:30:43 -06:00
Mauro Carvalho Chehab
1414f04888 doc-rst: add CSS styles for :kbd: and :menuselection:
As we're about to use those two markups, add them to the
theme style overrride.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:24:35 -06:00
Zhou Wenjian
ebf137f670 Documentation: kdump: Add description of enable multi-cpus support
Multi-cpu support is useful to improve the performance of kdump in
some cases. So add the description of enable multi-cpu support in
dump-capture kernel.

Signed-off-by: Zhou Wenjian <zhouwj-fnst@cn.fujitsu.com>
Acked-by: Baoquan He <bhe@redhat.com>
Acked-by: Xunlei Pang <xpang@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:02:54 -06:00
Zhou Wenjian
3dfb4c1bf0 Documentation: kdump: Remind user of nr_cpus
nr_cpus can help to save memory. So we should remind user of it.

Signed-off-by: Zhou Wenjian <zhouwj-fnst@cn.fujitsu.com>
Acked-by: Baoquan He <bhe@redhat.com>
Acked-by: Xunlei Pang <xpang@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 18:02:49 -06:00
Andrey Smirnov
be6c30956f Documentation: DMA-API-HOWTO: Fix a typo
Fix a type in example variable name.

Signed-off-by: Andrey Smirnov <andrew.smirnov@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-20 17:58:46 -06:00
Jonathan Corbet
fd5d2b832d Merge branch 'driver-api' into doc/4.9
This short series convers device-drivers.tmpl into the RST format, splits
it up, and sets up the result under Documentation/driver-api/.  For added
fun, I've taken one top-level file (hsi.txt) and folded it into the
document as a way of showing the direction I'm thinking I would like things
to go.  There is plenty more of this sort of work that could be done, to
say the least - this is just a beginning!

The formatted results can be seen at:

    http://static.lwn.net/kerneldoc/driver-api/index.html

As part of the long-term task to turn Documentation/ into less of a horror
movie, I'd like to collect documentation of the driver-specific API here.
Arguably gpu/ and the media API stuff should eventually move here, though
we can discuss the color of that particular shed some other day.
Meanwhile, I'd appreciate comments on the general idea.
2016-09-16 10:04:25 -06:00
Laurent Navet
829f4c362f docs/driver-model: fix typo
No need to be be, just be should be sufficient.

Signed-off-by: Laurent Navet <laurent.navet@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16 10:01:45 -06:00
Christoph Hellwig
e92ae527e7 DMA-API-HOWTO: <asm/generic/scatterlist.h> is no more
So don't mention it.

Signed-off-by: Christoph Hellwig <hch@lst.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16 10:00:25 -06:00
Markus Heiser
56cd869288 doc-rst:c-domain: function-like macros arguments
Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16 09:53:40 -06:00
Markus Heiser
b495360e30 doc-rst:c-domain: fix sphinx version incompatibility
The self.indexnode's tuple has changed in sphinx version 1.4, from a
former 4 element tuple to a 5 element tuple.

e6a5a3a92e

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16 09:53:23 -06:00
Robert Foss
3d8819b761 Documentation/filesystems: Fixed typo
Fixed a -> an typo.

Signed-off-by: Robert Foss <robert.foss@collabora.com>
Acked-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-16 09:51:34 -06:00
Jonathan Corbet
d36bbab661 docs: Don't format internal MPT docs
This is the driver API document, so the internal stuff is just noise here.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 09:15:48 -06:00
Jonathan Corbet
5e99578685 docs: split up serial-interfaces.rst
It never made sense to keep these documents together; move each into its
own file.

Drop the section numbering on hsi.txt on its way to its own file.

Suggested-by: Sebastian Reichel <sre@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 09:14:52 -06:00
Jonathan Corbet
70fc1f547a docs: Pull the HSI documentation together
The HSI subsystem documentation was split across hsi.txt and the
device-drivers docbook.  Now that the latter has been converted to Sphinx,
pull in the HSI document so that it's all in one place.

Acked-by: Sebastian Reichel <sre@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 08:48:07 -06:00
Jonathan Corbet
5219f18aaf docs: Special-case function-pointer parameters in kernel-doc
Add yet another regex to kernel-doc to trap @param() references separately
and not produce corrupt RST markup.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 08:02:49 -06:00
Jonathan Corbet
ef00028b20 docs: make kernel-doc handle varargs properly
As far as I can tell, the handling of "..." arguments has never worked
right, so any documentation provided was ignored in favor of "variable
arguments."  This makes kernel-doc handle "@...:" as documented.  It does
*not* fix spots in kerneldoc comments that don't follow that convention,
but they are no more broken than before.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 08:02:19 -06:00
Lorenzo Stoakes
9d9cce7f10 x86: fix memory ranges in mm documentation
This is a trivial fix to correct upper bound addresses to always be
inclusive. Previously, the majority of ranges specified were inclusive with a
small minority specifying an exclusive upper bound. This patch fixes this
inconsistency.

Signed-off-by: Lorenzo Stoakes <lstoakes@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 06:42:42 -06:00
Finn Thain
2836a2f5bd documentation/scsi: Remove nodisconnect parameter
The driver that used the 'nodisconnect' parameter was removed in
commit 565bae6a4a ("[SCSI] 53c7xx: kill driver"). Related documentation
was cleaned up in commit f37a7238d3 ("[SCSI] 53c7xx: fix removal
fallout"), except for the remaining two mentions that are removed here.

Signed-off-by: Finn Thain <fthain@telegraphics.com.au>
Reviewed-by: Geert Uytterhoeven <geert@linux-m68k.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 06:38:58 -06:00
Laura Abbott
c6517b7815 doc: ioctl: Add some clarifications to botching-up-ioctls
- The guide currently says to pad the structure to a multiple of
  64-bits. This is not necessary in cases where the structure contains
  no 64-bit types. Clarify this concept to avoid unnecessary padding.
- When using __u64 to hold user pointers, blindly trying to do a cast to
  a void __user * may generate a warning on 32-bit systems about a cast
  from an integer to a pointer of different size. There is a macro to
  deal with this which hides an ugly double cast. Add a reference to
  this macro.

Signed-off-by: Laura Abbott <labbott@redhat.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-06 06:00:22 -06:00
Markus Heiser
951499710b doc-rst: define PDF's of the media folder
To build only the PDF of the media folder run::

  make SPHINXDIRS=media pdfdocs

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:49:33 -06:00
Markus Heiser
cd21379b16 doc-rst: generic way to build PDF of sub-folders
This extends the method to build only sub-folders to the targets
"latexdocs" and "pdfdocs". To do so, a conf.py in the sub-folder is
required, where the latex_documents of the sub-folder are
defined. E.g. to build only gpu's PDF add the following to the
Documentation/gpu/conf.py::

  +latex_documents = [
  +    ("index", "gpu.tex", "Linux GPU Driver Developer's Guide",
  +     "The kernel development community", "manual"),
  +]

and run:

  make SPHINXDIRS=gpu pdfdocs

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:49:23 -06:00
Markus Heiser
b62b9d81a0 docs: sphinx-extensions: add metadata parallel-safe
The setup() function of a Sphinx-extension can return a dictionary. This
is treated by Sphinx as metadata of the extension [1].

With metadata "parallel_read_safe = True" a extension is marked as
save for "parallel reading of source". This is needed if you want
build in parallel with N processes. E.g.:

  make SPHINXOPTS=-j4 htmldocs

will no longer log warnings like:

  WARNING: the foobar extension does not declare if it is safe for
  parallel reading, assuming it isn't - please ask the extension author
  to check and make it explicit.

Add metadata to extensions:

* kernel-doc
* flat-table
* kernel-include

[1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:19:02 -06:00
Mauro Carvalho Chehab
82801d065b docs-rst: kernel-doc: fix typedef output in RST format
When using a typedef function like this one:
	typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);

The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.

So, a declaration like:

	.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)

Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.

So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:

	./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
	./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
	./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc

So, change the kernel-doc script to produce a RST output for the
above typedef as:
	.. c:type:: v4l2_check_dv_timings_fnc

	   **Typedef**: timings check callback

	**Syntax**

	  ``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:10:07 -06:00
Mauro Carvalho Chehab
d37c43ce19 docs-rst: improve typedef parser
Improve the parser to handle typedefs like:

	typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-09-01 08:07:22 -06:00
Baoquan He
7c142bfee6 docs: kernel-parameter: Improve the description of nr_cpus and maxcpus
From the old description people still can't get what's the exact
difference between nr_cpus and maxcpus. Especially in kdump kernel
nr_cpus is always suggested if it's implemented in the ARCH. The
reason is nr_cpus is used to limit the max number of possible cpu
in system, the sum of already plugged cpus and hot plug cpus can't
exceed its value. However maxcpus is used to limit how many cpus
are allowed to be brought up during bootup.

Signed-off-by: Baoquan He <bhe@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-25 13:14:53 -06:00
Mauro Carvalho Chehab
6d232c8015 docs-rst: kernel-doc: better output struct members
Right now, for a struct, kernel-doc produces the following output:

	.. c:type:: struct v4l2_prio_state

	   stores the priority states

	**Definition**

	::

	  struct v4l2_prio_state {
	    atomic_t prios[4];
	  };

	**Members**

	``atomic_t prios[4]``
	  array with elements to store the array priorities

Putting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
	item[atomic_t prios\[4\]] array with elements to store the array priorities

Everything inside "item" is non-breakable, with may produce
lines bigger than the column width.

Also, for function members, like:

        int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);

It puts the name of the member at the end, like:

        int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read

With is very confusing.

The best is to highlight what really matters: the member name.
is a secondary information.

So, change kernel-doc, for it to produce the output on a different way:

	**Members**

	``prios[4]``

	  array with elements to store the array priorities

Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.

So, both LaTeX/PDF and HTML outputs will look good.

It should be noticed, however, that the way Sphinx LaTeX output handles
things like:

	Foo
	   bar

is different than the HTML output. On HTML, it will produce something
like:

	**Foo**
	   bar

While, on LaTeX, it puts both foo and bar at the same line, like:

	**Foo** bar

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2016-08-24 15:24:36 -06:00