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>

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>

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>

This reverts commit b44158b1.  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>

Install the man pages with mode 644 instead of 755

Signed-off-by: Jim Davis <jim.epost@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>

The commit ec3fadd6 (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>

Signed-off-by: Masahiro Yamada <yamada.m@jp.panasonic.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>

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>

This patch addresses several issues pointed by Randy Dunlap
<rdunlap@xenotime.net> at changeset ece722c:

- In the generated index.html file, "media" is listed first, but it
  should be listed in alphabetical order, not first.

- The generated files are (hidden) in .tmpmedia/

- The link from the top-level index.html file to "media" is to
  media/index.html, but the file is actually in .tmpmedia/media/index.html

- Please build docs with and without using "O=builddir" and test that.

- Would it be possible for media to have its own Makefile instead of
  merging into this one?

Due to the way cleandocs target works, I had to rename the media DocBook
to media_api, otherwise cleandocs would remove the /media directory.

Thanks-to: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Auto-generate the videodev2.h.xml,frontend.h.xml and the indexes.

Some logic at the Makefile helps us to identify when a symbol is missing,
like for example:

Error: no ID for constraint linkend: V4L2-PIX-FMT-JPGL.

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Move docproc from scripts/basic to scripts so it is only built for *doc
targets instead of every time the kernel is built.

DocBook/v4l/ no longer has any *.png files, so the 'cp' command fails,
breaking the build.  Drop the *.png cp.

  cp: cannot stat `linux-2.6.38-git18/Documentation/DocBook/v4l/*.png': No such file or directory

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Add a userspace API to get, set and enumerate the media format on a
subdev pad.

The format at the output of a subdev usually depends on the format at
its input(s). The try format operation is thus not suitable for probing
format at individual pads, as it can't modify the device state and thus
can't remember the format tried at the input to compute the output
format.

To fix the problem, pass an extra argument to the get/set format
operations to select the 'try' or 'active' format.

The try format is used when probing the subdev. Setting the try format
must not change the device configuration but can store data for later
reuse. Data storage is provided at the file-handle level so applications
probing the subdev concurently won't interfere with each other.

The active format is used when configuring the subdev. It's identical to
the format handled by the usual get/set operations.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Stanimir Varbanov <svarbanov@mm-sol.com>
Signed-off-by: Sakari Ailus <sakari.ailus@iki.fi>
Acked-by: Hans Verkuil <hverkuil@xs4all.nl>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

This moves mac80211 documentation into a new
802.11 bookset and also adds a cfg80211 book
to the set. All of this is rather incomplete,
but it's easier to work with big code moving
as a separate patch.

Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: John W. Linville <linville@tuxdriver.com>

$ rm -rf build
$ mkdir build
$ cp .config build
$ make O=build htmldocs
...
xmlto: linux-2.6/build/Documentation/DocBook/media.xml
does not validate (status 3)
xmlto: Fix document syntax or use --skip-validation option
linux-2.6/build/Documentation/DocBook/media.xml:4:
warning: failed to load external entity
"linux-2.6/build/Documentation/DocBook/media-entities.tmpl"

We need the xmldoclinks built for any document types built from the
XML sources.

Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Acked-by: Andy Whitcroft <apw@canonical.com>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

'make htmldocs' produces errors due to missing a supporting media
file, so add 'xmldoclinks' to the htmldocs dependencies so that the
needed supporting file will be present.

  Documentation/DocBook/media.xml:4: warning: failed to load external entity "Documentation/DocBook/media-entities.tmpl"

Signed-off-by: Randy Dunlap <randy.dunlap@oracle.com>
Acked-by: Mauro Carvalho Chehab <mchehab@redhat.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

Add a DRM DocBook providing basic information about DRM interfaces, including
TTM, GEM, KMS and vblank infrastructure.  Intended to provide information to
new and existing developers about how to perform driver initialization,
implement mode setting and other DRM features.

Signed-off-by: Jesse Barnes <jbarnes@virtuousgeek.org>
Signed-off-by: Dave Airlie <airlied@redhat.com>

Example is outdated, it still uses old ->read_proc interfaces and "fb"
example is plain racy.  There are better examples all over the tree.

Docbook itself says almost nothing about /proc and contain quite a number
of simply wrong facts, e.g.  device nodes support.  What it does is
describing at great length interface which are going to be removed.

There are Documentation/filesystems/seq_file.txt in exchange.

Signed-off-by: Alexey Dobriyan <adobriyan@gmail.com>
Acked-by: Erik Mouw <mouw@nl.linux.org>
Cc: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

If docs are being built in a separate directory, xmlto and xsltproc
can't find included sources.  Make links back to the source directory.

I would much prefer to have xmlto and xsltproc look in the source
directory for included entities but couldn't see how to do that.  This
needs to be solved in some way for 2.6.32, even if this patch isn't the
right way to do it.

Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

The rule for %.html removes the output directory, so there is no point
in copying images before building HTML.

Documentation/DocBook/Makefile |   10 +++++-----

Signed-off-by: Ben Hutchings <ben@decadent.org.uk>
Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

The V4L and DVB API's are there for a long time. however, up to now,
no efforts were done to merge them to kernel DocBook.

This patch adds the current versions of the specs as an unique compendium.

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>