With the conversion of the documentation to Sphinx, the old DocBook is
now stale.
Signed-off-by: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Convert the tracepoint docbook template to RST and add it to the core-api
manual. No changes to the actual text beyond the mechanical formatting
conversion.
Cc: Jason Baron <jbaron@redhat.com>
Cc: William Cohen <wcohen@redhat.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
A couple of the most minor heading tweaks, otherwise no changes to the text
itself beyond the mechanical conversion.
Note that the inclusion of the kerneldoc comments from the source has never
worked, since exported symbols were asked for and none of those functions
are exported to modules. It doesn't work here either :)
Cc: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is a conversion of the USB documentation to the Sphinx format.
No content was altered or reformatted.
Signed-off-by: Oliver <oneukum@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Another simple conversion from DocBook to ReST.
This required a few manual fixups and reformats, but the most of
contents are kept as is.
Signed-off-by: Takashi Iwai <tiwai@suse.de>
A simple conversion of alsa-driver-api document from DocBook to ReST.
It's moved to the new Documentation/sound/kernel-api subdirectory that
will contain other ALSA kernel API documents.
The GPL legal note was removed, as it's superfluous (and doesn't fit
with ReST kernel docs pretty well).
Signed-off-by: Takashi Iwai <tiwai@suse.de>
Removes intermediate 'Documentation/DocBook/.*.xml.cmd' files
Changes since v1:
- Reduce the patch to DocBook cleandocs
References: http://lkml.kernel.org/r/CA+r1Zhjr5SCVAroREBv84t9bxDVu5jVJ_Fu=BbVDGNNABdQOuQ@mail.gmail.com
Reported-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is just a very basic conversion, I've split up the original
multi-book template, and also split up the multi-part mac80211
part in the original book; neither of those were handled by the
automatic pandoc conversion.
Fix errors that showed up, resulting in a much nicer rendering,
at least for the interface combinations documentation.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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.
Sphinx supports LaTeX output. Sometimes, it is interesting to
call it directly, instead of also generating a PDF. As it comes
for free, add a target for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add a generic way to build only a reST sub-folder with or
without a individual *build-theme*.
* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF
Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::
make SPHINXDIRS="media gpu" htmldocs
To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::
make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs
With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
"make help" if sphinx isn't present.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJXo8sIAAoJEI3ONVYwIuV6po0P/0ZZo+YF0GrPvOHr7uuUqAND
0+4WRfSsT74z5Rn/W3apeX6CM7IGBMSR2zM89E2nWmbE2Uo7bIbrwj6C+Y6gMMfd
aws0Xi9899Jr6hVkeFVZ9foze+M2yc3tE1vFBby035uW3Zwyz2XHzaU/9vyLOLkJ
c7jhqCWebqFEqOSWtw2FZYegt2oHSjUsQgGCh3kk2pCU+DzLHntwbblJLeMuTy+h
zPVxTTBcBkUZcIjpkSvhqc/oCLCiWKLElmwxPBwfpNU9UlE0rol2Lx1eLClxadFl
QVlb1UAIjPcLnHQoM8dL9NR0tkfGopIDuNCL26GU5ie9N4zurOj5a6hj+G5mZKLB
tsMqIw+N7ig5FnaQhaCx3oN/VMZ0djxURu9XvKsHBmOCd2Bp8SDoqpCkTwCqCxcN
DVdUjpS1WUT9w2A1jhH32mx+23eRwJa5oaTFpM3Y0z7Bl9N40ScY2WJcgBKWqHgx
LRROJAzNOPojbBkwTDNsRValwgtutCcqaRw5mNQTp3YjjmltmqylCvJH3AST+z5r
CmMDO96O3rUGsCZYoBhxafC2FUUh5RkUwQq/Cy8nrioMookE3Yd5A9DN6wWQ2pTt
tev/z6s3ov8dygeF6u3noOHCa8GPUpSHO62FyHUKYnn6Tl8xh3x7rmUkUqrJZi5a
dnXOZzp34eVhev5xDeDN
=iD7L
-----END PGP SIGNATURE-----
Merge tag 'doc-4.8-fixes' of git://git.lwn.net/linux
Pull documentation fixes from Jonathan Corbet:
"Three fixes for the docs build, including removing an annoying warning
on 'make help' if sphinx isn't present"
* tag 'doc-4.8-fixes' of git://git.lwn.net/linux:
DocBook: use DOCBOOKS="" to ignore DocBooks instead of IGNORE_DOCBOOKS=1
Documenation: update cgroup's document path
Documentation/sphinx: do not warn about missing tools in 'make help'
Instead of a separate ignore flag, use the obvious DOCBOOKS="" to ignore
all DocBook files. This is also in line with the Sphinx build being
ignored if a non-empty DOCBOOKS make variable is specified on the make
command line.
This replaces the IGNORE_DOCBOOKS introduced in
commit 547218864a
Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Date: Sat Jul 9 13:12:45 2016 -0300
doc-rst: add an option to ignore DocBooks when generating docs
and aligns with
commit 6387872c86
Author: Jani Nikula <jani.nikula@intel.com>
Date: Fri Jul 1 15:24:44 2016 +0300
Documentation/sphinx: skip build if user requested specific DOCBOOKS
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJXoxLYAAoJEAhfPr2O5OEVZJgP/A6/98y7RgBXKr7gSgw3tgrw
LohxiFq7PbOR4z5cKY1hJVxlEeRakDw+R1Xr0Sd2HhjoHYhQajJZrP+IvBr4tpVd
dL+C8qtNlVNbg1sfdKgdsM1oPwQVW3Nr5GBoEq+HttJMnD4nBc1N6LxrNP3imhGZ
JpEHJ9L+Bl7+4i4tF1r3K3ZHiQJ7sWYJcXno+To4ckUn4Obg30msk6dmYa8yD0ok
Oc2hSX8rXHPATh43nXKz6+pLFgvl+J2vOxmZJ8rC/tXXU7TKfS7jTsUAJcoc1SW9
3qHpStPmzScG1qNgSI051xhl0uO2zxFa51oPwFT2fVgoX7x80rzpX2RI/QInoEFP
T73y/vRyX1zDlnKsk/pn5kpyYIWdPGAIJ9sO3vM4Yxyjb78yyRVWi+1H2R6tn/+z
hl11as2J3z+Vw6ShG0AJaCUFc7UmWKflzA1LQ1aF49kxLh5OZIphDebadHb1oMdx
B1FMHEOJ+K6eELQBFqbNCipJu0OoHAjiFzdIBzeBKqrDPceo2ouGqq0StldZuR+n
lhhf/M7JO/HrH+yYgclcIj16J29V+rTX6g7osGr9cKtoxcdkt3E/UaR25H89h61x
xmrQk+t5RxaRo04Ohh7orxijVRlabLImB3lQOfy67bMkv6KNXvRe2oc+dbTUHNRM
a9TlOv+X8G9XE8C5V4Oc
=odtg
-----END PGP SIGNATURE-----
Merge tag 'media/v4.8-5' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media DocBook removal and some fixups from Mauro Carvalho Chehab:
- removal of the media DocBook (since it's all in Sphinx now)
- videobuf2: Fix an allocation regression
- a few fixes related to the CEC drivers
* tag 'media/v4.8-5' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media:
[media] cec: fix off-by-one memset
[media] staging: add MEDIA_SUPPORT dependency
[media] vivid: don't handle CEC_MSG_SET_STREAM_PATH
[media] media: adv7180: Fix broken interrupt register access
[media] vb2: Fix allocation size of dma_parms
[media] vim2m: copy the other colorspace-related fields as well
[media] adv7511: fix VIC autodetect
doc-rst: Remove the media docbook
Merge drm updates from Dave Airlie:
"This is the main drm pull request for 4.8.
I'm down with a cold at the moment so hopefully this isn't in too bad
a state, I finished pulling stuff last week mostly (nouveau fixes just
went in today), so only this message should be influenced by illness.
Apologies to anyone who's major feature I missed :-)
Core:
Lockless GEM BO freeing
Non-blocking atomic work
Documentation changes (rst/sphinx)
Prep for new fencing changes
Simple display helpers
Master/auth changes
Register/unregister rework
Loads of trivial patches/fixes.
New stuff:
ARM Mali display driver (not the 3D chip)
sii902x RGB->HDMI bridge
Panel:
Support for new panels
Improved backlight support
Bridge:
Convert ADV7511 to bridge driver
ADV7533 support
TC358767 (DSI/DPI to eDP) encoder chip support
i915:
BXT support enabled by default
GVT-g infrastructure
GuC command submission and fixes
BXT workarounds
SKL/BKL workarounds
Demidlayering device registration
Thundering herd fixes
Missing pci ids
Atomic updates
amdgpu/radeon:
ATPX improvements for better dGPU power control on PX systems
New power features for CZ/BR/ST
Pipelined BO moves and evictions in TTM
GPU scheduler improvements
GPU reset improvements
Overclocking on dGPUs with amdgpu
Polaris powermanagement enabled
nouveau:
GK20A/GM20B volt and clock improvements.
Initial support for GP100/GP104 GPUs, GP104 will not yet support
acceleration due to NVIDIA having not released firmware for them as of yet.
exynos:
Exynos5433 SoC with IOMMU support.
vc4:
Shader validation for branching
imx-drm:
Atomic mode setting conversion
Reworked DMFC FIFO allocation
External bridge support
analogix-dp:
RK3399 eDP support
Lots of fixes.
rockchip:
Lots of small fixes.
msm:
DT bindings cleanups
Shrinker and madvise support
ASoC HDMI codec support
tegra:
Host1x driver cleanups
SOR reworking for DP support
Runtime PM support
omapdrm:
PLL enhancements
Header refactoring
Gamma table support
arcgpu:
Simulator support
virtio-gpu:
Atomic modesetting fixes.
rcar-du:
Misc fixes.
mediatek:
MT8173 HDMI support
sti:
ASOC HDMI codec support
Minor fixes
fsl-dcu:
Suspend/resume support
Bridge support
amdkfd:
Minor fixes.
etnaviv:
Enable GPU clock gating
hisilicon:
Vblank and other fixes"
* tag 'drm-for-v4.8' of git://people.freedesktop.org/~airlied/linux: (1575 commits)
drm/nouveau/gr/nv3x: fix instobj write offsets in gr setup
drm/nouveau/acpi: fix lockup with PCIe runtime PM
drm/nouveau/acpi: check for function 0x1B before using it
drm/nouveau/acpi: return supported DSM functions
drm/nouveau/acpi: ensure matching ACPI handle and supported functions
drm/nouveau/fbcon: fix font width not divisible by 8
drm/amd/powerplay: remove enable_clock_power_gatings_tasks from initialize and resume events
drm/amd/powerplay: move clockgating to after ungating power in pp for uvd/vce
drm/amdgpu: add query device id and revision id into system info entry at CGS
drm/amdgpu: add new definition in bif header
drm/amd/powerplay: rename smum header guards
drm/amdgpu: enable UVD context buffer for older HW
drm/amdgpu: fix default UVD context size
drm/amdgpu: fix incorrect type of info_id
drm/amdgpu: make amdgpu_cgs_call_acpi_method as static
drm/amdgpu: comment out unused defaults_staturn_pro static const structure to fix the build
drm/amdgpu: enable UVD VM only on polaris
drm/amdgpu: increase timeout of IB test
drm/amdgpu: add destroy session when generate VCE destroy msg.
drm/amd: fix deadlock of job_list_lock V2
...
Now that all media documentation was converted to Sphinx, we
should get rid of the old DocBook one, as we don't want people
to submit patches against the old stuff.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Sometimes, we want to do a partial build, instead of building
everything. However, right now, if one wants to build just
Sphinx books, it will build also the DocBooks.
Add an option to allow to ignore all DocBooks when building
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
While there's slight overlap with the DocBook help now, this can stay
intact when the DocBook help goes away.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Add basic configuration and makefile to build documentation from any
.rst files under Documentation using Sphinx. For starters, there's just
the placeholder index.rst.
At the top level Makefile, hook Sphinx documentation targets alongside
(but independent of) the DocBook toolchain, having both be run on the
various 'make *docs' targets.
All Sphinx processing is placed into Documentation/Makefile.sphinx. Both
that and the Documentation/DocBook/Makefile are now expected to handle
all the documentation targets, explicitly ignoring them if they're not
relevant for that particular toolchain. The changes to the existing
DocBook Makefile are kept minimal.
There is graceful handling of missing Sphinx and rst2pdf (which is
needed for pdf output) by checking for the tool and python module,
respectively, with informative messages to the user.
If the Read the Docs theme (sphinx_rtd_theme) is available, use it, but
otherwise gracefully fall back to the Sphinx default theme, with an
informative message to the user, and slightly less pretty HTML output.
Sphinx can now handle htmldocs, pdfdocs (if rst2pdf is available),
epubdocs and xmldocs targets. The output documents are written into per
output type subdirectories under Documentation/output.
Finally, you can pass options to sphinx-build using the SPHINXBUILD make
variable. For example, 'make SPHINXOPTS=-v htmldocs' for more verbose
output from Sphinx.
This is based on the original work by Jonathan Corbet, but he probably
wouldn't recognize this as his own anymore.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
When make htmldocs is called on non-verbose mode, it will still be
verbose with index.html generation for no good reason, printing:
rm -rf Documentation/DocBook/index.html; echo '<h1>Linux Kernel HTML Documentation</h1>' >> Documentation/DocBook/index.html && echo '<h2>Kernel Version: 4.4.0-rc1</h2>' >> Documentation/DocBook/index.html && cat Documentation/DocBook/iio.html >> Documentation/DocBook/index.html
Instead, use the standard non-verbose mode, using:
HTML Documentation/DocBook/index.html
if not called with V=1.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There's no build_images function to call. So remove it.
This is just a cleanup patch, with doesn't affect the build.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sometimes, it is needed to compile only a subset of the possible
DocBooks. This is supported by the building system, but it is not
docummented. Add a documentation for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Pull drm updates from Dave Airlie:
"I Was Almost Tempted To Capitalise Every Word, but then I decided I
couldn't read it myself!
I've also got one pull request for the sti driver outstanding. It
relied on a commit in Greg's tree and I didn't find out in time, that
commit is in your tree now so I might send that along once this is
merged.
I also had the accidental misfortune to have access to a Skylake on my
desk for a few days, and I've had to encourage Intel to try harder,
which seems to be happening now.
Here is the main drm-next pull request for 4.4.
Highlights:
New driver:
vc4 driver for the Rasberry Pi VPU.
(From Eric Anholt at Broadcom.)
Core:
Atomic fbdev support
Atomic helpers for runtime pm
dp/aux i2c STATUS_UPDATE handling
struct_mutex usage cleanups.
Generic of probing support.
Documentation:
Kerneldoc for VGA switcheroo code.
Rename to gpu instead of drm to reflect scope.
i915:
Skylake GuC firmware fixes
HPD A support
VBT backlight fallbacks
Fastboot by default for some systems
FBC work
BXT/SKL workarounds
Skylake deeper sleep state fixes
amdgpu:
Enable GPU scheduler by default
New atombios opcodes
GPUVM debugging options
Stoney support.
Fencing cleanups.
radeon:
More efficient CS checking
nouveau:
gk20a instance memory handling improvements.
Improved PGOB detection and GK107 support
Kepler GDDR5 PLL statbility improvement
G8x/GT2xx reclock improvements
new userspace API compatiblity fixes.
virtio-gpu:
Add 3D support - qemu 2.5 has it merged for it's gtk backend.
msm:
Initial msm88896 (snapdragon 8200)
exynos:
HDMI cleanups
Enable mixer driver byt default
Add DECON-TV support
vmwgfx:
Move to using memremap + fixes.
rcar-du:
Add support for R8A7793/4 DU
armada:
Remove support for non-component mode
Improved plane handling
Power savings while in DPMS off.
tda998x:
Remove unused slave encoder support
Use more HDMI helpers
Fix EDID read handling
dwhdmi:
Interlace video mode support for ipu-v3/dw_hdmi
Hotplug state fixes
Audio driver integration
imx:
More color formats support.
tegra:
Minor fixes/improvements"
[ Merge fixup: remove unused variable 'dev' that had all uses removed in
commit 4e270f088011: "drm/gem: Drop struct_mutex requirement from
drm_gem_mmap_obj" ]
* 'drm-next' of git://people.freedesktop.org/~airlied/linux: (764 commits)
drm/vmwgfx: Relax irq locking somewhat
drm/vmwgfx: Properly flush cursor updates and page-flips
drm/i915/skl: disable display side power well support for now
drm/i915: Extend DSL readout fix to BDW and SKL.
drm/i915: Do graphics device reset under forcewake
drm/i915: Skip fence installation for objects with rotated views (v4)
vga_switcheroo: Drop client power state VGA_SWITCHEROO_INIT
drm/amdgpu: group together common fence implementation
drm/amdgpu: remove AMDGPU_FENCE_OWNER_MOVE
drm/amdgpu: remove now unused fence functions
drm/amdgpu: fix fence fallback check
drm/amdgpu: fix stoping the scheduler timeout
drm/amdgpu: cleanup on error in amdgpu_cs_ioctl()
drm/i915: Fix locking around GuC firmware load
drm/amdgpu: update Fiji's Golden setting
drm/amdgpu: update Fiji's rev id
drm/amdgpu: extract common code in vi_common_early_init
drm/amd/scheduler: don't oops on failure to load
drm/amdgpu: don't oops on failure to load (v2)
drm/amdgpu: don't VT switch on suspend
...
DRM is a lot more than a direct rendering manager nowadays, and there's
also a bunch of things worth documenting for gpu driver developers
outside of drivers/gpu/drm, like vgaarb, vga_switcheroo or the various
hardware buses like host1x and ipu-v3.
To avoid further confusion let's rename the top-level to reflect
reality.
And yes I'm already looking forward to when we need to replace the G
in GPU with a * ;-)
Inspired by a thread with Lukas since he refused to include the
vga_switcheroo docs into the drm docs because it's not drm.
Cc: Lukas Wunner <lukas@wunner.de>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
[Lukas: Drop BUG() easter egg in i915_gem_execbuffer.c spotted by Jani
and fix typos in commit message.]
Signed-off-by: Lukas Wunner <lukas@wunner.de>
Acked-by: Dave Airlie <airlied@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Currently the encoding of documents generated by DocBook depends on
the current locale. Make the output reproducible independently of
the locale, by setting the encoding to UTF-8 (LC_CTYPE=C.UTF-8) by
preference, or ASCII (LC_CTYPE=C) as a fallback.
LC_CTYPE can normally be overridden by LC_ALL, but the top-level
Makefile unsets that.
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
[jc: added check-lc_ctype to .gitignore]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
including:
- Support for reproducible document builds, from Ben Hutchings and
company.
- The ability to automatically generate cross-reference links within a
single DocBook book and embedded descriptions for large structures.
From Danilo Cesar Lemes de Paula.
- A new document on how to add a system call from David Drysdale.
- Chameleon bus documentation from Johannes Thumshirn.
...plus the usual collection of improvements, typo fixes, and more.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJV4/B0AAoJEI3ONVYwIuV6Y1UQAIpU1TSPCuRcgPLgKhuEty9w
nMKA/Rn2Wye0608HbZ1FhpUXTS914kYOF0zA6f4xS1kOGoqqgSOfkP/bXfdZP67P
aH1onug5xFIfMUTGT2tAHabPymbGCZARVe/1YYKPTTh7hu4ZnPd7HULelp/KHa7Y
9yl/VQzggu4ASWXTKU89vZmoNSvUf+e73sCB+ZQ69QgY2JAnK9HaWDjOpWesev21
ZSZneWrvVWngupWAsw8Wy+QVbqEEIMd5+XC7hN+GEPZInuRGr5oAuyUgmO90JiER
WmFH5D4vRi3KG5XLmvHdUA5lhOqGM3cZC8W9Xw7byf86NVdWoN9rVs4IhBJjC7PC
v0foIuORKbuxqXJ/bn2pMXuWEq9EU80mvs+Hot7cMTP06syXY2/ROcSaReJ9TjcU
yw9uY8tOiR5Pq7tfqDylBbsJKlgYSatdsZKacLG5rCuUwLhsxlTaxG+yyg4zIfeb
EBvsRZBUTElzBELHxTwsOmUJf98QvUEuq8EHfGhUIR0IAnzzSwe2rccCtzohI2je
Sk0R3W9kKZdrgOr8vBehPEXxUYFDoWx+6MgpJhD7eSMhuL6510Gp5AV7Fj/+tTgE
8aTfubk2CGES5Aiwnyi8+Jf+LelPcWpKU4p3rsbsjnrbREV7YzxFHwtlCGtFYBhG
xWCMG47K4Wx8ynKyUE5m
=pQ1H
-----END PGP SIGNATURE-----
Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6
Pull documentation updates from Jonathan Corbet:
"There's been a fair amount going on in the docs tree this time around,
including:
- Support for reproducible document builds, from Ben Hutchings and
company.
- The ability to automatically generate cross-reference links within
a single DocBook book and embedded descriptions for large
structures. From Danilo Cesar Lemes de Paula.
- A new document on how to add a system call from David Drysdale.
- Chameleon bus documentation from Johannes Thumshirn.
...plus the usual collection of improvements, typo fixes, and more"
* tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (39 commits)
Documentation, add kernel-parameters.txt entry for dis_ucode_ldr
Documentation/x86: Rename IRQSTACKSIZE to IRQ_STACK_SIZE
Documentation/Intel-IOMMU.txt: Modify definition of DRHD
docs: update HOWTO for 3.x -> 4.x versioning
kernel-doc: ignore unneeded attribute information
scripts/kernel-doc: Adding cross-reference links to html documentation.
DocBook: Fix non-determinstic installation of duplicate man pages
Documentation: minor typo fix in mailbox.txt
Documentation: describe how to add a system call
doc: Add more workqueue functions to the documentation
ARM: keystone: add documentation for SoCs and EVMs
scripts/kernel-doc Allow struct arguments documentation in struct body
SubmittingPatches: remove stray quote character
Revert "DocBook: Avoid building man pages repeatedly and inconsistently"
Documentation: Minor changes to men-chameleon-bus.txt
Doc: fix trivial typo in SubmittingPatches
MAINTAINERS: Direct Documentation/DocBook/media properly
Documentation: installed man pages don't need to be executable
fix Evolution submenu name in email-clients.txt
Documentation: Add MCB documentation
...
Functions, Structs and Parameters definitions on kernel documentation
are pure cosmetic, it only highlights the element.
To ease the navigation in the documentation we should use <links> inside
those tags so readers can easily jump between methods directly.
This was discussed in 2014[1] and is implemented by getting a list
of <refentries> from the DocBook XML to generate a database. Then it looks
for <function>,<structnames> and <paramdef> tags that matches the ones in
the database. As it only links existent references, no broken links are
added.
[1] - lists.freedesktop.org/archives/dri-devel/2014-August/065404.html
Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Some kernel-doc sections are included in multiple DocBook files. This
means the mandocs target will generate the same manual page multiple
times with different metadata (author name/address and manual title,
taken from the including DocBook file). If it's invoked in a parallel
build, the output is non-determinstic.
Build the manual pages in a separate subdirectory per DocBook file,
then sort and de-duplicate when installing them (which is serialised).
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
[jc: fixed conflicts with the docs tree]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is intended to help developers faster find their way
inside the Industrial I/O core and reduce time spent on IIO
drivers development.
Signed-off-by: Daniel Baluta <daniel.baluta@intel.com>
Acked-by: Crt Mori <cmo@melexis.com>
Reviewed-by: Lars-Peter Clausen <lars@metafoo.de>
Signed-off-by: Jonathan Cameron <jic23@kernel.org>
Ben Hutchings writes:
As part of the reproducible builds project, Jérémy Bobbio identified
several time-dependent and non-deterministic functions in the document
build process (htmldocs, mandocs targets). This patch series should fix
all of those.
I ended up reverting one patch that introduced problems.
This reverts commit b44158b170. This commit
introduced warnings and possibly inconsistent results into the doc build
process. The goal is good but it will need to be achieved another way.
Reported-by: Masanari Iida <standby24x7@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Some kernel-doc sections are included in multiple DocBook files. This
means the mandocs target will generate the same manual page multiple
times with different metadata (author name/address and manual title,
taken from the including DocBook file). If it's invoked in a parallel
build, the output is nondeterminstic.
For each section that is duplicated, mark the less specific manual's
inclusion as 'extra' and exclude it during conversion to manual pages.
Use xmlif for this, as that is bundled with xmlto which we already
use.
I would have preferred to use more conventional markup for this, but
each of the following approaches failed:
1. Wrap the extra inclusions with a new element and add a template to
the stylesheet to include/exclude them. Unfortunately DocBook XSL
doesn't seem to support foreign elements at an intermediate level
in the document tree.
2. Use DocBook profiling. This works but requires passing an absolute
path to the profile stylesheet to xmlto, so it's not portable.
3. Use SGML marked sections. docbook2x can handle these but xmlto
chokes on them.
Reported-by: Jérémy Bobbio <lunar@debian.org>
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The mtime on a man page is the build time. As gzip stores the mtime
and original name in the compressed file by default, this makes
compressed man pages unreproducible. Neither of these are important
metadata in this case, so turn this off.
Reported-by: Jérémy Bobbio <lunar@debian.org>
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Use find + xargs to compress the generated manpages. Without this patch,
the build can fail with
gzip -f Documentation/DocBook/man/*.9
/bin/bash: /usr/bin/gzip: Argument list too long
This happened with qemu user mode emulation on aarch64.
Signed-off-by: Michal Marek <mmarek@suse.cz>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add the crypto API documentation into the DocBook Makefile to allow it
being compiled
Signed-off-by: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
Document the process of writing an musb glue layer by taking the
Ingenic JZ4740 glue layer as an example, as it seems more simple than
most glue layers due to the basic feature set of the JZ4740 USB device
controller.
Signed-off-by: Apelete Seketeli <apelete@seketeli.net>
Signed-off-by: Felipe Balbi <balbi@ti.com>
Pull kbuild changes from Michal Marek:
- cleanups in the main Makefiles and Documentation/DocBook/Makefile
- make O=... directory is automatically created if needed
- mrproper/distclean removes the old include/linux/version.h to make
life easier when bisecting across the commit that moved the version.h
file
* 'kbuild' of git://git.kernel.org/pub/scm/linux/kernel/git/mmarek/kbuild:
kbuild: docbook: fix the include error when executing "make help"
kbuild: create a build directory automatically for out-of-tree build
kbuild: remove redundant '.*.cmd' pattern from make distclean
kbuild: move "quote" to Kbuild.include to be consistent
kbuild: docbook: use $(obj) and $(src) rather than specific path
kbuild: unconditionally clobber include/linux/version.h on distclean
kbuild: docbook: specify KERNELDOC dependency correctly
kbuild: docbook: include cmd files more simply
kbuild: specify build_docproc as a phony target
The commit ec3fadd64b (kbuild: docbook: use $(obj) and $(src) rather
than specific path) replaces the specific path with $(src). But when
executing "make help", the $(src) is null and then causes an include
error. Fix it by restoring the specific path.
Signed-off-by: Kevin Hao <haokexin@gmail.com>
Signed-off-by: Michal Marek <mmarek@suse.cz>
It is not a good idea to describe
%.xml: %.tmpl FORCE
...
and
$(BOOKS): $(KERNELDOC)
separately. This cannot detect missing template files.
For example, add something to DOCBOOKS variable:
DOCBOOKS += foobar.xml
and run
make xmldocs
It will succeed even if Documention/DocBook/foobar.tmpl
does not exist.
Signed-off-by: Masahiro Yamada <yamada.m@jp.panasonic.com>
Signed-off-by: Michal Marek <mmarek@suse.cz>
Switch the code documentation format style to DocBook format, enable
DocBook documentation generation, and fix some comments.
Signed-off-by: David Fries <David@Fries.net>
Acked-by: Evgeniy Polyakov <zbr@ioremap.net>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Two concurrent calls to cmd_db2man may attempt to compress manual
pages generated by each other. gzip can then fail due to an input
file having already been compressed and removed.
Move the gzip command to the top-level mandocs target.
Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Cc: Bastian Blank <waldi@debian.org>
Acked-by: Rob Landley <rob@landley.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
Trying to generate xhtml causes all functions to show up with a prefix
of "fsfunc" in the output, so just back off to html until someone
fixes the toolchain.
Note that this is not a problem with kernel-doc, it's an issue with
however "xmlto" renders xhtml output.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Acked-by: Rob Landley <rob@landley.net>
Signed-off-by: Jiri Kosina <jkosina@suse.cz>
Hardware with MCA bus is limited to 386 and 486 class machines
that are now 20+ years old and typically with less than 32MB
of memory. A quick search on the internet, and you see that
even the MCA hobbyist/enthusiast community has lost interest
in the early 2000 era and never really even moved ahead from
the 2.4 kernels to the 2.6 series.
This deletes anything remaining related to CONFIG_MCA from core
kernel code and from the x86 architecture. There is no point in
carrying this any further into the future.
One complication to watch for is inadvertently scooping up
stuff relating to machine check, since there is overlap in
the TLA name space (e.g. arch/x86/boot/mca.c).
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: James Bottomley <JBottomley@Parallels.com>
Cc: x86@kernel.org
Acked-by: Ingo Molnar <mingo@elte.hu>
Acked-by: H. Peter Anvin <hpa@zytor.com>
Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com>
The patch utility doesn't work with non-binary files. This causes some
tools to break, like generating tarball targets and the scripts that
generate diff patches at http://www.kernel.org/pub/linux/kernel/v2.6/.
So, let's convert all binaries to ascii using base64, and add a
logic at Makefile to convert them back into binaries at runtime.
Reported-by: Randy Dunlap <randy.dunlap@oracle.com>
Reported-by: Andrew Morton <akpm@linux-foundation.org>
Reviewed-by: Michal Marek <mmarek@suse.cz>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Stephan Mueller