Re: [PATCH v4 00/18] kernel-doc: add supported to document nested structs

[Jonathan Corbet]

On Mon, 18 Dec 2017 10:30:01 -0200
Mauro Carvalho Chehab  wrote:

> This is a rebased version of my patch series that add support for
> nested structs on kernel-doc. With this version, it won't produce anymore
> hundreds of identical warnings, as patch 17 removes the warning
> duplication.
> 
> Excluding warnings about duplicated Note: section at hash.h, before
> this series, it reports 166 kernel-doc warnings. After this patch series,
> it reports 123 kernel-doc warnings, being 51 from DVB. I have already a patch
> series that will cleanup those new DVB warnings due to nested structs.
> 
> So, the net result is that the number of warnings is reduced with
> this version.

This seems like a great set of improvements overall, and I love getting
rid of all that old kernel-doc code.  I will note that it makes a full
htmldocs build take 20-30 seconds longer, which is not entirely
welcome, but so be it.  Someday, I guess, $SOMEBODY should see if there's
some low-hanging optimization fruit there.

Applied, thanks.

jon

Re: [PATCH v2] kernel-doc: parse DECLARE_KFIFO and DECLARE_KFIFO_PTR()

[Jonathan Corbet]

On Fri,  8 Dec 2017 09:05:12 -0500
Mauro Carvalho Chehab  wrote:

> So, teach kernel-doc how to parse DECLARE_KFIFO() and DECLARE_KFIFO_PTR().
> 
> While here, relax at the past DECLARE_foo() macros, accepting a random
> number of spaces after comma.

Applied, thanks.

jon

Re: [PATCH v3 00/17] kernel-doc: add supported to document nested structs/

[Jonathan Corbet]

On Wed,  4 Oct 2017 08:48:38 -0300
Mauro Carvalho Chehab  wrote:

> Right now, it is not possible to document nested struct and nested unions.
> kernel-doc simply ignore them.
> 
> Add support to document them.

So I've finally found some time to actually look at these; sorry for being
so absent from the discussion.  I plead $EXCUSES...

Some overall impressions:

 - Seems like something we want.
 - I love hacking all the cruft out of kernel-doc; I've been meaning to
   do that for a bit.
 - It would sure be nice to restore proper man-page generation rather than
   documenting a hack with a perl script.  Someday.

I have one real complaint, though: with these patches applied, a "make
htmldocs" generates about 5500 (!) more warnings than it did before.  Over
the last couple of months, I put a bit of focused time into reducing
warnings, and managed to get rid of 20-30 of them.  Now I feel despondent.

I really don't want to add that much noise to the docs build; I think it
will defeat any hope of cleaning up the warnings we already have.  I
wonder if we could suppress warnings about nested structs by default, and
add a flag or envar to turn them back on for those who want them?

In truth, now that I look, the real problem is that the warnings are
repeated many times - as in, like 100 times:

> ./include/net/cfg80211.h:4115: warning: Function parameter or member 
> 'wext.ibss' not described in 'wireless_dev'
> ./include/net/cfg80211.h:4115: warning: Function parameter or member 
> 'wext.ibss' not described in 'wireless_dev'
<107 instances deleted...>
> ./include/net/cfg80211.h:4115: warning: Function parameter or member 
> 'wext.ibss' not described in 'wireless_dev'

That's not something that used to happen, and is certainly not helpful.
Figuring that out would help a lot.  Can I get you to take a look at
what's going on here?

Thanks,

jon

Re: [PATCH 09/10] scripts: kernel-doc: parse next structs/unions

[Jonathan Corbet]

On Tue, 26 Sep 2017 17:29:47 -0300
Mauro Carvalho Chehab  wrote:

> This patch actually need a fixup, in order to handle pointer,
> array and bitmask IDs.

Can you send a new series with the fixed patch?

I sure do like the shrinking of kernel-doc that comes with this series!  

Thanks,

jon

Re: [PATCH 1/2] docs: kernel-doc comments are ASCII

[Jonathan Corbet]

On Thu, 31 Aug 2017 10:56:26 -0300
Mauro Carvalho Chehab  wrote:

> It should have something to do with python version and/or to some
> locale info at the system, as neither I or Jon can reproduce it.

I can't reproduce it here, but I have certainly seen situations where
Python 2 wants to run with the ascii codec by default.

Note that the exception happens in our Sphinx extension, not in Sphinx
itself.  We've had other non-ascii text in our docs, so I think Sphinx is
doing the right thing.  The problem is with our own code.  If I could
reproduce it, it shouldn't be too hard to track down - take out that
massive "except anything" block and see where it explodes.

Randy, which distribution are you running, and are you using their version
of Sphinx?

Thanks,

jon

Re: [PATCH 1/2] docs: kernel-doc comments are ASCII

[Jonathan Corbet]

On Wed, 30 Aug 2017 19:15:53 -0300
Mauro Carvalho Chehab  wrote:

> I suspect that the problem is not related to the version, but to
> what you might have set on LANG.
> 
> Maybe if we add something like:
>   LANG=C.utf-8
> 
> to the Documentation/Makefile 

That's worth a try; Randy, can you give it a quick go?

> or adding:
> 
>   .. -*- coding: utf-8; mode: rst -*-
> 
> as the first line on the *.rst file that include the kernel-doc 
> directive would solve the issue.

I guess I don't see how that would help, instead.  Emacs reads that line,
but it's not involved in the problem.

I wish I could reproduce this, then we could see what in that massive
try..except block in kerneldoc.py is throwing the exception.  Putting in
an explicit decode call might be enough to make the problem go away.

Thanks,

jon

Re: [PATCH 2/2] media: dvb-core: fix demux.h non-ASCII characters

[Jonathan Corbet]

On Mon, 28 Aug 2017 16:10:16 -0700
Randy Dunlap  wrote:

> Fix non-ASCII charactes in kernel-doc comment to prevent the kernel-doc
> build warning below.
> 
> WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno 
> ../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec 
> can't decode byte 0xe2 in position 6368: ordinal not in range(128)

I'll leave this one for Mauro to decide on.  My inclination would be to
apply it, though, my previous comments on handling non-ASCII text
notwithstanding.  The weird quotes don't buy us anything here.

Thanks,

jon

Re: [PATCH 1/2] docs: kernel-doc comments are ASCII

[Jonathan Corbet]

On Mon, 28 Aug 2017 16:10:09 -0700
Randy Dunlap  wrote:

> kernel-doc parsing uses as ASCII codec, so let people know that
> kernel-doc comments should be in ASCII characters only.
> 
> WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno 
> ../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec 
> can't decode byte 0xe2 in position 6368: ordinal not in range(128)

So I don't get this error.  What kind of system are you running the docs
build on?  I would really rather that the docs system could handle modern
text if possible, so it would be better to figure out what's going on
here...

Thanks,

jon

Re: [PATCH 0/4] Fix problems on building documentation with Sphinx 1.6

[Jonathan Corbet]

On Sat, 26 Aug 2017 06:28:24 -0300
Mauro Carvalho Chehab  wrote:

> IMHO, the best is if I apply patch 2 on my trees. Please apply
> patches 1 and 3 on your tree.
> 
> Patch 4 can only be applied after  patch 2 gets merged, but it
> is just a cleanup patch that can be applied any time later.

OK, I've applied those two, and stashed 4 aside for later.

Thanks,

jon

Re: [PATCH v2 4/4] docs-rst: Allow Sphinx version 1.6

[Jonathan Corbet]

On Thu, 24 Aug 2017 13:26:28 -0600
Jonathan Corbet <cor...@lwn.net> wrote:

> > -   % To allow adjusting table sizes
> > -   \\usepackage{adjustbox}
> > -
> >   '''
> >  }  
> 
> So this change doesn't quite match the changelog...what's the story there?

Indeed, with that patch applied, I get this:

! LaTeX Error: Environment adjustbox undefined.

See the LaTeX manual or LaTeX Companion for explanation.
Type  H   for immediate help.
 ...  
  
l.4108 \begin{adjustbox}
{width=\columnwidth}

...so methinks something isn't quite right...

jon

Re: [PATCH v2 4/4] docs-rst: Allow Sphinx version 1.6

[Jonathan Corbet]

On Wed, 23 Aug 2017 05:56:57 -0300
Mauro Carvalho Chehab  wrote:

> Now that the PDF building issues with Sphinx 1.6 got fixed,
> update the documentation and scripts accordingly.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/conf.py  | 3 ---
>  Documentation/doc-guide/sphinx.rst | 4 +---
>  scripts/sphinx-pre-install | 1 -
>  3 files changed, 1 insertion(+), 7 deletions(-)
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 8e74d68037a5..0834a9933d69 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -331,9 +331,6 @@ latex_elements = {
>  \\setromanfont{DejaVu Sans}
>  \\setmonofont{DejaVu Sans Mono}
>  
> - % To allow adjusting table sizes
> - \\usepackage{adjustbox}
> -
>   '''
>  }

So this change doesn't quite match the changelog...what's the story there?

Thanks,

jon

Re: [PATCH v2 00/21] Convert USB documentation to ReST format

[Jonathan Corbet]

On Tue, 11 Apr 2017 16:58:40 +0200
Greg Kroah-Hartman  wrote:

> Nope, they don't apply to my tree, it was probably based on yours.  And
> the first two are ones I shouldn't be taking.
> 
> So, feel free to take all of these with a:
>   Acked-by: Greg Kroah-Hartman 
> for the USB-related patches (2-21).

I have now done that.  Thanks, Mauro!

jon

Re: [PATCH v2 00/21] Convert USB documentation to ReST format

[Jonathan Corbet]

On Wed,  5 Apr 2017 10:22:54 -0300
Mauro Carvalho Chehab  wrote:

> Currently, there are several USB core documents that are at either
> written in plain text or in DocBook format. Convert them to ReST
> and add to the driver-api book.

Greg, do you see any reason not to apply these for 4.12?  A few of them
touch comments outside of Documentation/; I'm happy to carry those or
leave them to you, as you prefer.

Thanks,

jon

Re: [PATCH v2 01/22] tmplcvt: make the tool more robust

[Jonathan Corbet]

On Thu, 30 Mar 2017 07:45:35 -0300
Mauro Carvalho Chehab  wrote:

> Currently, the script just assumes to be called at
> Documentation/sphinx/. Change it to work on any directory,
> and make it abort if something gets wrong.
> 
> Also, be sure that both parameters are specified.
> 
> That should avoid troubles like this:
> 
> $ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
> sed: couldn't open file convert_template.sed: No such file or directory

What's the status of this patch set?  I saw that Jani had one comment
that, I think, hasn't been addressed?

Thanks,

jon

Re: [PATCH 0/9] convert genericirq.tmpl and kernel-api.tmpl to DocBook

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:27 -0300
Mauro Carvalho Chehab  wrote:

> This series converts just two documents, adding them to the
> core-api.rst book. It addresses the errors/warnings that popup
> after the conversion.
> 
> I had to add two fixes to scripts/kernel-doc, in order to solve
> some of the issues.

I've applied the set, including the add-on to move some stuff to
driver-api - thanks.

For whatever reason, I had a hard time applying a few of these; "git am"
would tell me this:

> Applying: docs-rst: core_api: move driver-specific stuff to drivers_api
> fatal: sha1 information is lacking or useless 
> (Documentation/driver-api/index.rst).
> Patch failed at 0001 docs-rst: core_api: move driver-specific stuff to 
> drivers_api
> The copy of the patch that failed is found in: .git/rebase-apply/patch

I was able to get around this, but it took some hand work.  How are you
generating these?

Thanks,

jon

Re: [PATCH 5/9] kernel-api.tmpl: convert it to ReST

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:32 -0300
Mauro Carvalho Chehab  wrote:

> Brainless conversion of genericirq.tmpl book to ReST, via
>   Documentation/sphinx/tmplcvt

This one kind of showcases why I'm nervous about bulk conversions.  It's
a bit of a dumping-ground document, with a bit of everything, and I think
we can do better.  And, in particular, this one contains a bunch of stuff
that belongs in the driver-api manual instead.  So, at a minimum, I would
really like to see this template split across those two manuals.

If you promise me a followup patch doing that, maybe I can go ahead and
merge this series now :)

(That's mildly complicated by the fact that you didn't send me parts 6,
8, and 9; I really would rather get the whole series in cases like this.)

Thanks,

jon

Re: [PATCH 3/9] genericirq.tmpl: convert it to ReST

[Jonathan Corbet]

On Thu, 30 Mar 2017 17:11:30 -0300
Mauro Carvalho Chehab  wrote:

[Reordering things a bit]

> +==
> +Linux generic IRQ handling
> +==
> +
> +:Copyright: |copy| 2005-2010: Thomas Gleixner
> +:Copyright: |copy| 2005-2006:  Ingo Molnar

It seems maybe they should have been CC'd on this one?  Adding them now
(and leaving the full patch for their amusement).

> Brainless conversion of genericirq.tmpl book to ReST, via
>   Documentation/sphinx/tmplcvt

In general this seems good, but I have to wonder how current this material
is at this point?  The last substantive change was in 2013 (3.11), and I've
seen a certain amount of IRQ work going by since then.  I'm not opposed to
this move at all, but perhaps if it's outdated we should add a note to that
effect?

Thanks,

jon

> Copyright information inserted manually.
> 
> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/DocBook/Makefile|   2 +-
>  Documentation/DocBook/genericirq.tmpl | 520 
> --
>  Documentation/core-api/genericirq.rst | 445 +
>  Documentation/core-api/index.rst  |   1 +
>  4 files changed, 447 insertions(+), 521 deletions(-)
>  delete mode 100644 Documentation/DocBook/genericirq.tmpl
>  create mode 100644 Documentation/core-api/genericirq.rst
> 
> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
> index 7d94db2b53cd..e0c13655f770 100644
> --- a/Documentation/DocBook/Makefile
> +++ b/Documentation/DocBook/Makefile
> @@ -11,7 +11,7 @@ DOCBOOKS := z8530book.xml  \
>   networking.xml \
>   kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
>   libata.xml mtdnand.xml librs.xml rapidio.xml \
> - genericirq.xml s390-drivers.xml scsi.xml \
> + s390-drivers.xml scsi.xml \
>   sh.xml w1.xml
>  
>  ifeq ($(DOCBOOKS),)
> diff --git a/Documentation/DocBook/genericirq.tmpl 
> b/Documentation/DocBook/genericirq.tmpl
> deleted file mode 100644
> index 59fb5c077541..
> --- a/Documentation/DocBook/genericirq.tmpl
> +++ /dev/null
> @@ -1,520 +0,0 @@
> -
> - - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd; []>
> -
> -
> - 
> -  Linux generic IRQ handling
> -
> -  
> -   
> -Thomas
> -Gleixner
> -
> - 
> -  t...@linutronix.de
> - 
> -
> -   
> -   
> -Ingo
> -Molnar
> -
> - 
> -  mi...@elte.hu
> - 
> -
> -   
> -  
> -
> -  
> -   2005-2010
> -   Thomas Gleixner
> -  
> -  
> -   2005-2006
> -   Ingo Molnar
> -  
> -
> -  
> -   
> - This documentation is free software; you can redistribute
> - it and/or modify it under the terms of the GNU General Public
> - License version 2 as published by the Free Software Foundation.
> -   
> -
> -   
> - This program is distributed in the hope that it will be
> - useful, but WITHOUT ANY WARRANTY; without even the implied
> - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
> - See the GNU General Public License for more details.
> -   
> -
> -   
> - You should have received a copy of the GNU General Public
> - License along with this program; if not, write to the Free
> - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
> - MA 02111-1307 USA
> -   
> -
> -   
> - For more details see the file COPYING in the source
> - distribution of Linux.
> -   
> -  
> - 
> -
> -
> -
> -  
> -Introduction
> -
> - The generic interrupt handling layer is designed to provide a
> - complete abstraction of interrupt handling for device drivers.
> - It is able to handle all the different types of interrupt controller
> - hardware. Device drivers use generic API functions to request, enable,
> - disable and free interrupts. The drivers do not have to know anything
> - about interrupt hardware details, so they can be used on different
> - platforms without code changes.
> -
> -
> - This documentation is provided to developers who want to implement
> - an interrupt subsystem based for their architecture, with the help
> - of the generic IRQ handling layer.
> -
> -  
> -
> -  
> -Rationale
> - 
> - The original implementation of interrupt handling in Linux uses
> - the __do_IRQ() super-handler, which is able to deal with every
> - type of interrupt logic.
> - 
> - 
> - Originally, Russell King identified different types of handlers to
> - build a quite universal set for the ARM interrupt handler
> - implementation in Linux 2.5/2.6. He distinguished between:
> - 
> -   Level type
> -   Edge type
> -   Simple type
> - 
> - During the implementation we identified another type:
> - 
> -   Fast EOI type
> - 
> - In the SMP world of the __do_IRQ() super-handler another type
> - was identified:

Re: [PATCH 02/22] docs-rst: convert usb docbooks to ReST

[Jonathan Corbet]

On Thu, 30 Mar 2017 11:20:14 +0200
Markus Heiser  wrote:

> @Jon: what do you think about a bulk conversion?

I'm a bit leery of it, to tell the truth.  We're trying to create a
better set of kernel docs, and I'm far from convinced that dumping a
bunch of unloved stuff there in a mechanical way will get us there.

Each of those docs needs to be looked at, and, first of all, we need to
decide whether it's worth keeping or not.  Nobody wants to delete docs,
but old and unmaintained stuff doesn't help our users, IMO.  For the
stuff we want to keep, we need to look at how it fits into the new
scheme, probably split it up, etc.

It's a lot slower, but we've been getting rid of 3-6 template files in
each of the last few cycles, so we are getting there.  I don't think we
need to just give up on the rest.

Thanks,

jon

Re: [PATCH] docs-rst: Don't use explicit Makefile rules to build SVG and DOT files

[Jonathan Corbet]

On Thu,  9 Mar 2017 15:14:52 -0300
Mauro Carvalho Chehab  wrote:

> Now that we have an extension to handle images, use it.

Applied, finally - thanks.

jon

Re: [PATCH] doc-rst: fixed cleandoc target when used with O=dir

[Jonathan Corbet]

On Tue, 31 Jan 2017 10:57:41 +0100
Markus Heiser  wrote:

> The cleandocs target won't work if I use a different output folder::
> 
>   $ make O=/tmp/kernel SPHINXDIRS="process" cleandocs
>   make[1]: Entering directory '/tmp/kernel'
>   make[3]: *** No rule to make target 'clean'.  Stop.
>   ... Documentation/Makefile.sphinx:100: recipe for target 'cleandocs' failed

Applied, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Doc: Correct typo, "Introdution" => "Introduction"

[Jonathan Corbet]

On Thu,  1 Dec 2016 23:36:00 +0800
Sanjeev  wrote:

> This corrects a set of spelling mistakes, probably from an
> automated conversion.

That does indeed seem worth fixing.  Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [Ksummit-discuss] Including images on Sphinx documents

[Jonathan Corbet]

On Thu, 17 Nov 2016 08:02:50 -0800
Linus Torvalds  wrote:

> We have makefiles, but more importantly, few enough people actually
> *generate* the documentation, that I think if it's an option to just
> fix sphinx, we should do that instead. If it means that you have to
> have some development version of sphinx, so be it. Most people read
> the documentation either directly in the unprocessed text-files
> ("source code") or on the web (by searching for pre-formatted docs)
> that I really don't think we need to worry too much about the
> toolchain.
> 
> But what we *should* worry about is having the kernel source tree
> contain source.

I would be happy to take a shot at fixing sphinx; we clearly need to
engage more with sphinx upstream in general.  But I guess I still haven't
figured out what "fixing sphinx" means in this case.

I don't know what the ultimate source of these images is (Mauro, perhaps
you could shed some light there?).  Perhaps its SVG for some of the
diagrams, but for the raster images, probably not; it's probably some
weird-ass diagram-editor format.  We could put those in the tree, but
they are likely to be harder to convert to a useful format and will raise
all of the same obnoxious binary patch issues.

Rather than beating our heads against the wall trying to convert between
various image formats, maybe we need to take a step back.  We're trying
to build better documentation, and there is certainly a place for
diagrams and such in that documentation.  Johannes was asking about it
for the 802.11 docs, and I know Paul has run into these issues with the
RCU docs as well.  Might there be a tool or an extension out there that
would allow us to express these diagrams in a text-friendly, editable
form?

With some effort, I bet we could get rid of a number of the images, and
perhaps end up with something that makes sense when read in the .rst
source files as an extra benefit.  But I'm not convinced that we can,
say, sensibly express the differences between different video interlacing
schemes that way.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Including images on Sphinx documents

[Jonathan Corbet]

On Mon, 7 Nov 2016 09:46:48 -0200
Mauro Carvalho Chehab  wrote:

> When running LaTeX in interactive mode, building just the media
> PDF file with:
> 
>   $ cls;make cleandocs; make SPHINXOPTS="-j5" DOCBOOKS="" 
> SPHINXDIRS=media latexdocs 
>   $ PDFLATEX=xelatex LATEXOPTS="-interaction=interactive" -C 
> Documentation/output/media/latex
> 
> I get this:
> 
>   LaTeX Warning: Hyper reference `uapi/v4l/subdev-formats:bayer-patterns' 
> on page
>153 undefined on input line 21373.
> 
>[153]
>   ! Extra alignment tab has been changed to \cr.
>\endtemplate 
> 
>   l.21429 \unskip}\relax \unskip}
>  \relax \\
>   ? 
> 
> This patch fixes the issue:
>   
> https://git.linuxtv.org/mchehab/experimental.git/commit/?h=dirty-pdf=b709de415f34d77cc121cad95bece9c7ef4d12fd
> 
> That means that Sphinx is not generating the right LaTeX output even for
> (some?) PNG images.

So I'm seriously confused.

I can get that particular message - TeX is complaining about too many
columns in the table.  But applying your patch (with a suitable bayer.pdf
provided) does not fix the problem.  Indeed, I can remove the figure with
the image entirely and still not fix the problem.  Are you sure that the
patch linked here actually fixed it for you?

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Including images on Sphinx documents

[Jonathan Corbet]

On Mon, 7 Nov 2016 07:55:24 -0200
Mauro Carvalho Chehab  wrote:

> So, we have a few alternatives:
> 
> 1) copy (or symlink) all rst files to Documentation/output (or to the
>build dir specified via O= directive) and generate the *.pdf there,
>and produce those converted images via Makefile.;
> 
> 2) add an Sphinx extension that would internally call ImageMagick and/or
>inkscape to convert the bitmap;
> 
> 3) if possible, add an extension to trick Sphinx for it to consider the 
>output dir as a source dir too.

So, obviously, I've been letting this go by while dealing with other
stuff...

I really think that 2) is the one we want.  Copying all the stuff and
operating on the copies, beyond being a bit of a hack, just seems like a
recipe for weird build problems in the future.

We should figure out why PNG files don't work.  Maybe I'll give that a
try at some point soon, if I can find a moment.  Working around tools
bugs seems like the wrong approach.

Working from .svg seems optimial, but I don't like the --shell-escape
thing at all.

[Along those lines, we've picked up a lot of lines like this:

 restricted \write18 enabled.

That, too, is shell execution stuff.  I've not been able to figure out
where it came from, but I would sure like to get rid of it...]

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts

[Jonathan Corbet]

On Sat, 22 Oct 2016 08:56:29 -0200
Mauro Carvalho Chehab  wrote:

> The security implications will be the same if either coded as an
> "ioctl()" or as "syscall", the scripts should be audited. Actually,
> if we force the need of a "syscall" for every such script, we have
> twice the code to audit, as both the Sphinx extension and the perl
> script will need to audit, increasing the attack surface.

Just addressing this one part for the moment.  Clearly I've not explained
my concern well.

The kernel-cmd directive makes it possible for *any* RST file to run
arbitrary shell commands.  I'm not concerned about the scripts we add, I
hope we can get those right.  I'm worried about what slips in via a tweak
to some obscure .rst file somewhere.

A quick check says that 932 commits touched Documentation/ since 4.8.  A
lot of those did not come from either my tree or yours; *everybody* messes
around in the docs tree.  People know to look closely at changes to
makefiles and such; nobody thinks to examine documentation changes for
such things. I think there are attackers out there who would like the
opportunity to run commands in the settings where kernels are built; we
need to think pretty hard before we make that easier to do.

See what I'm getting at here?

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts

[Jonathan Corbet]

On Tue, 11 Oct 2016 09:26:48 +0200
Markus Heiser  wrote:

> If the kernel-cmd directive gets acked, I will add a description to
> kernel-documentation.rst and I request Mauro to document the parse-headers.pl
> also.
> 
> But, let's hear what Jon says.

Sigh.

I've been shunting this discussion aside while I dug out from other
things.  Now I've pushed through the whole thing; I'm still not sure what
I think is the best thing to do.

kernel-cmd scares me.  It looks like the ioctl() of documentation
building; people will be able to add all kinds of wild things and it will
take a lot of attention to catch them.  I think we could make things
pretty messy in a real hurry.  And yes, I do think we should consider the
security aspects of it; we're talking about adding another shell
code-execution context in the kernel build, and that can only make things
harder to audit.

OTOH, forcing things into dedicated Sphinx extensions doesn't necessarily
fix the problem.  We're adding system calls rather than ioctl() commands,
let's say, but we're still adding long-term maintenance complications.

How many special-case commands are we going to need to run?  Does it
really need to go beyond what parse-headers is doing now?  Let's really
think about what the other use cases might be and whether we can do
without them. I'm still thoroughly unconvinced about the utility of
incorporating, say, the MAINTAINERS file into the formatted docs, for
example, so I'm not yet convinced that making that easier to do is
something we need.

Not much clarity here, sorry.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Jonathan Corbet]

On Tue, 20 Sep 2016 20:56:35 +0200
Markus Heiser  wrote:

> > I submitted one patch fixing it. Not sure if it got merged by Jon
> > or not.  
> 
> Ups, I might have overseen this patch .. as Jon said, its hard to
> follow you ;)
> 
> I tested the above with Jon's docs-next, so it seems your patch is
> not yet applied. Could you send me a link for this patch? (sorry,
> I can't find it).

Send again, please?  I'll add it to the pile of other stuff, and try not
to lose it again...:)

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Jonathan Corbet]

On Wed,  7 Sep 2016 09:12:55 +0200
Markus Heiser <markus.hei...@darmarit.de> wrote:

> according to your remarks I fixed the first and second patch. The third patch 
> is
> resend unchanged;

OK, I've applied the first two, finally.

> > Am 06.09.2016 um 14:28 schrieb Jonathan Corbet <cor...@lwn.net>:
> >
> > As others have pointed out, we generally want to hide the difference
> > between functions and macros, so this is probably one change we don't
> > want.  
> 
> I read "probably", so there might be a chance to persuade you ;)
> 
> I'm not a friend of *information hiding* and since the index is sorted
> alphabetical it does no matter if the entry is 'FOO (C function)' or 'FOO (C
> macro)'. The last one has the right information e.g. for someone how is 
> looking
> for a macro. FOO is a function-like macro and not a function, if the author
> describes the macro he might use the word "macro FOO" but in the index it is
> tagged as C function.

Information hiding is the only way we can maintain the kernel and stay
sane.  I have a hard time imagining why somebody would be looking for a
macro in particular; the whole idea is that they really shouldn't have to
care.  So my inclination is to leave this one out, sorry.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/47] Fix most of Sphinx warnings in nitpick mode

[Jonathan Corbet]

On Thu,  8 Sep 2016 09:03:22 -0300
Mauro Carvalho Chehab <mche...@s-opensource.com> wrote:

> Please notice that patches 2 and 3 touches at 
> Documentation/sphinx/parse-headers.pl.
> 
> If it is ok for you, I intend to merge those patches (except for patch 1)
> on my tree, including the two patches that touch at the parse-headers.pl
> script, as, currently, the only user for it is media. I'm also OK if you 
> prefer
> to merge patches 2 and 3 on your tree instead.

Go ahead and keep them with the rest.

Acked-by: Jonathan Corbet <cor...@lwn.net>

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/3] doc-rst:c-domain: fix sphinx version incompatibility

[Jonathan Corbet]

On Tue, 6 Sep 2016 14:24:11 +0200
Markus Heiser  wrote:

> Should I send a new patch .. or could you fix it?

Please just regenerate the series and I'll apply it.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 3/3] doc-rst:c-domain: function-like macros index entry

[Jonathan Corbet]

On Wed, 31 Aug 2016 17:29:32 +0200
Markus Heiser  wrote:

> For function-like macros, sphinx creates 'FOO (C function)' entries.
> With this patch 'FOO (C macro)' are created for function-like macros,
> which is the same for object-like macros.

As others have pointed out, we generally want to hide the difference
between functions and macros, so this is probably one change we don't
want.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/3] doc-rst:c-domain: function-like macros arguments

[Jonathan Corbet]

So I'm going into total nit-picking territory here, but since I'm looking
at it and I think the series needs a respin anyway...

On Wed, 31 Aug 2016 17:29:31 +0200
Markus Heiser  wrote:

> +m = c_funcptr_sig_re.match(sig)
> +if m is None:
> +m = c_sig_re.match(sig)
> +if m is None:
> +raise ValueError('no match')

How about we put that second test inside the first if block and avoid the
redundant None test if the first match works?  The energy saved may
prevent a hurricane someday :)

> +
> +rettype, fullname, arglist, _const = m.groups()
> +if rettype or not arglist.strip():
> +return False
> +
> +arglist = arglist.replace('`', '').replace('\\ ', '').strip()  # 
> remove markup
> +arglist = [a.strip() for a in arglist.split(",")]

Similarly, stripping the args three times seems a bit much.  The middle
one is totally redundant and could go at a minimum.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/3] doc-rst:c-domain: fix sphinx version incompatibility

[Jonathan Corbet]

On Wed, 31 Aug 2016 17:29:30 +0200
Markus Heiser  wrote:

> +if major >= 1 and minor < 4:
> +# indexnode's tuple changed in 1.4
> +# 
> https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
> +self.indexnode['entries'].append(
> +('single', indextext, targetname, ''))
> +else:
> +self.indexnode['entries'].append(
> +('single', indextext, targetname, '', None))

So this doesn't seem right.  We'll get the four-entry tuple behavior with
1.3 and the five-entry behavior with 1.4...but what happens when 2.0
comes out?

Did you want maybe:

if major == 1 and minor < 4:

?

(That will fail on 0.x, but we've already stated that we don't support
below 1.2).

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[Jonathan Corbet]

On Thu, 1 Sep 2016 08:53:34 -0600
Jonathan Corbet <cor...@lwn.net> wrote:

> > here is a small patch series which extends the method to build only 
> > sub-folders
> > to the targets "latexdocs" and "pdfdocs".  
> 
> Well this doesn't seem to break anything, so I went ahead and applied
> it :)

By that I mean I applied the first two, of course; I left the
media-specific one for Mauro.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/3] doc-rst: generic way to build PDF of sub-folder

[Jonathan Corbet]

On Wed, 24 Aug 2016 17:36:13 +0200
Markus Heiser  wrote:

> here is a small patch series which extends the method to build only 
> sub-folders
> to the targets "latexdocs" and "pdfdocs".

Well this doesn't seem to break anything, so I went ahead and applied
it :)

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Jonathan Corbet]

On Wed, 24 Aug 2016 15:35:24 +0200
Markus Heiser  wrote:

> 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

A definite improvement; applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/3] Fix kernel-doc parser for typedef functions

[Jonathan Corbet]

On Tue, 30 Aug 2016 20:20:56 -0300
Mauro Carvalho Chehab  wrote:

> The other two patches better fit on your tree, IMHO.
> 
> Mauro Carvalho Chehab (3):
>   docs-rst: improve typedef parser
>   docs-rst: kernel-doc: fix typedef output in RST format

I've just applied them, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] docs-rst: kernel-doc: better output struct members

[Jonathan Corbet]

On Mon, 22 Aug 2016 22:02:57 -0300
Mauro Carvalho Chehab  wrote:

> 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.

OK, I've applied this; let's see if anybody screams :)

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 2/2] Documentation/sphinx: link dma-buf rsts

[Jonathan Corbet]

On Tue, 23 Aug 2016 15:28:55 +0200
Daniel Vetter  wrote:

> I think the more interesting story is, what's your plan with all the
> other driver related subsystem? Especially the ones which already have
> full directories of their own, like e.g. Documentation/gpio/. I think
> those should be really part of the infrastructure section (or
> something equally high-level), together with other awesome servies
> like pwm, regman, irqchip, ... And then there's also the large-scale
> subsystems like media or gpu. What's the plan to tie them all
> together? Personally I'm leaning towards keeping the existing
> directories (where they exist already), but inserting links into the
> overall driver-api section.

To say I have a plan is to overstate things somewhat...

One objective I do have, though, is to declutter Documentation/.
Presenting people looking for docs with a 270-file directory is
unfriendly to say the least.  We don't organize the code that way; the
average in the kernel is <... find | wc -l ... > about 15
files/directory, which is rather more manageable.  Someday I'd like
Documentation/ to look a lot more like the top-level directory.

It seems to me that we have a few basic types of stuff here:

 - Driver API documentation, obviously, is a lot of it, and I would like
   to organize it better and to move it out of the top-level directory.

 - Hardware usage information - module parameters, sysfs files, supported
   hardware information, graphic descriptions of the ancestry of hardware
   engineers, etc.  The readership for this stuff is quite different, and
   I think it should be separate; often it's intertwined with API
   information at the moment.

 - Other usage information - a lot of what's under filesystems/ for
   example, and more.

 - Core API documentation.

 - Kernel development tools - the stuff I started pulling together into
   the dev-tools/ subdirectory.

 - How to deal with this unruly mob - SubmittingPatches, CodingStyle,
   development-process, etc.  There's process stuff, and general
   development documents like volatile-considered-harmful.txt or
   memory-barriers.txt

We can go a long way by organizing this stuff within the formatted
documentation, but I really think we need to organize the directory
structure as well.  I see that as a slow-moving process that will take
years, but I do think it's a direction we should go.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 2/2] Documentation/sphinx: link dma-buf rsts

[Jonathan Corbet]

On Tue, 23 Aug 2016 08:01:35 +0200
Daniel Vetter  wrote:

> I'm also not too sure about whether dma-buf really should be it's own
> subdirectory. It's plucked from the device-drivers.tmpl, I think an
> overall device-drivers/ for all the misc subsystems and support code would
> be better. Then one toc there, which fans out to either kernel-doc and
> overview docs.

I'm quite convinced it shouldn't be.

If you get a chance, could you have a look at the "RFC: The beginning of
a proper driver-api book" series I posted yesterday (yes, I should have
copied more of you, sorry)?  It shows the direction I would like to go
with driver API documentation, and, assuming we go that way, I'd like the
dma-buf documentation to fit into that.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs-rst: kernel-doc: better output struct members

[Jonathan Corbet]

On Sun, 21 Aug 2016 09:11:57 -0300
Mauro Carvalho Chehab  wrote:

> So, change kernel-doc, for it to produce the output on a different way:
> 
>   **Members**
> 
>   ``prios[4]``
> - **type**: ``atomic_t``
> 
> array with elements to store the array priorities
> 
> With such change, the name of the member will be the first visible
> thing, and will be in bold style. The type will still be there, inside
> a list.

OK, I'll confess to not being 100% convinced on this one.  I certainly
sympathize with the problem that drives this change, but I think the
result is a bit on the noisy and visually distracting side.  

I wonder if we might be better off to just leave the "type:" bulleted
line out entirely?  The type information already appears in the structure
listing directly above, so it's arguably redundant here.  If formatting
the type is getting in the way here, perhaps the right answer is just
"don't do that"?

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs-rst: conf.py: adjust the size of .. note:: tag

[Jonathan Corbet]

On Fri, 19 Aug 2016 09:49:38 -0300
Mauro Carvalho Chehab  wrote:

> While the current implementation works well when using as a
> paragraph, it doesn't work properly if inside a table. As we
> have quite a few such cases, fix the logic to take the column
> size into account.

Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] docs-rst: add support for LaTeX output

[Jonathan Corbet]

On Thu, 18 Aug 2016 11:53:39 -0300
Mauro Carvalho Chehab  wrote:

> 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.
> 
Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 0/5] doc-rst: improvements Sphinx's C-domain

[Jonathan Corbet]

On Mon, 15 Aug 2016 16:08:23 +0200
Markus Heiser  wrote:

> this is my approach to eliminate some distortions we have with the c/cpp 
> Sphinx
> domains. The C domain is simple: it assumes that all functions, enums, etc
> are global, e. g. there should be just one function called "ioctl", or "open".
> With the 'name' option e.g.:
> 
> .. c:function:: int ioctl( int fd, int request )
>:name: VIDIOC_LOG_STATUS
> 
> we can rename those functions. Another nice feature around this *global*
> namespace topic is, that the *duplicate C object description* warnings for
> function declarations are moved to the nitpicky mode.

I've applied these to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/7] doc-rst: generic way to build only sphinx sub-folders

[Jonathan Corbet]

On Sat, 13 Aug 2016 16:12:42 +0200
Markus Heiser  wrote:

> 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.

So this patch appears to have had the undocumented effect of moving HTML
output from Documentation/output/html to Documentation/output.  I am
assuming that was not the intended result?

I'm not sure that we actually need the format-specific subfolders, but we
should be consistent across all the formats and in the documentation and,
as of this patch, we're not.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/9] Prepare Sphinx to build media PDF books

[Jonathan Corbet]

On Tue, 16 Aug 2016 13:25:34 -0300
Mauro Carvalho Chehab  wrote:

> I think this patch series belong to docs-next. Feel free to merge them there, 
> if
> you agree. There's one extra patch that touches Documentation/conf.py,
> re-adding the media book to the PDF build, but IMHO this one would be better
> to be merged via the media tree, after the fixes inside the media 
> documentation
> to fix the build.

It's now in docs-next.  I was able to build some nice-looking docs with it
without too much (additional) pain...

The conf.py patch makes me a bit nervous, in that I feel like I spent a
fair amount of time explaining docs merge conflicts to Linus during the
merge window, and would rather not do that again.  Can we keep it aside,
with the idea that one of us will put it in toward the end of the 4.9
merge window?

Meanwhile, let's see how this xelatex thing works out.  Thanks for making
all this work!

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC PATCH 0/5] doc-rst: improvements Sphinx's C-domain

[Jonathan Corbet]

On Mon, 15 Aug 2016 16:08:23 +0200
Markus Heiser  wrote:

> this is my approach to eliminate some distortions we have with the c/cpp 
> Sphinx
> domains. The C domain is simple: it assumes that all functions, enums, etc
> are global, e. g. there should be just one function called "ioctl", or "open".
> With the 'name' option e.g.:
> 
> .. c:function:: int ioctl( int fd, int request )
>:name: VIDIOC_LOG_STATUS
> 
> we can rename those functions. Another nice feature around this *global*
> namespace topic is, that the *duplicate C object description* warnings for
> function declarations are moved to the nitpicky mode.

So these all look reasonable to me.  A lot of it seems aimed at making the
media docs go better; Mauro, have you tried it out and does it, indeed,
have this effect?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/7] doc-rst: sphinx sub-folders & parseheaders directive

[Jonathan Corbet]

On Mon, 15 Aug 2016 10:21:07 +0200
Markus Heiser  wrote:

> Jonathan, we had this already, I gave you the links to "python community
> norms" and tools, please read/use them.
> 
> * https://www.python.org/dev/peps/pep-0008/
> * https://www.pylint.org/
> 
> Some of these norms might be unusual for C developers.

Markus, please.  I'm pretty well familiar with the Python language, have
read and written quite a bit of Python code, and understand the
conventions.  I don't need to be talked down to here.

I just reviewed PEP8.  Nothing I mentioned is sanctioned there; indeed, it
says to limit lines to 79 characters and no space before commas.

Please remember that, when you put code into the kernel, that code is no
longer in your own personal sandbox.  Other developers will have to look
at and understand it, and the community will have to maintain it long
after you have moved on to other things.  We should do everything we can
to make that code accessible to kernel folks, and that includes, IMO, not
flying in the face of the kernel's coding conventions.  

Happily, normal Python conventions don't actually look all that strange to
developers used to the kernel's style - at least to those who understand
Python!  There's no reason why we can't create Python code that looks fine
to Python programmers without putting off kernel developers.  It's not a
matter of "eye candy," it's a real maintenance issue, so could you please
humor me on this?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: customize RTD theme, drop padding of inline literal

[Jonathan Corbet]

On Fri, 5 Aug 2016 11:27:07 +0200
Hans Verkuil  wrote:

> On 08/05/2016 11:19 AM, Markus Heiser wrote:
> > From: Markus Heiser 
> > 
> > Remove the distracting (left/right) padding of inline literals. (HTML
> > ). Requested and discussed in [1].
> > 
> > [1] http://www.spinics.net/lists/linux-media/msg103991.html
> > 
> > Signed-off-by: Markus Heiser   
> 
> Acked-by: Hans Verkuil 
> 
> Thank you! Thank you! Thank you!
> 
> So much better!

Agreed, this one was really needed.  Applied to the 4.8-fixes branch,
thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/7] doc-rst: sphinx sub-folders & parseheaders directive

[Jonathan Corbet]

On Sat, 13 Aug 2016 16:12:41 +0200
Markus Heiser  wrote:

> this series is a consolidation on Jon's docs-next branch. It merges the 
> "sphinx
> sub-folders" patch [1] and the "parseheaders directive" patch [2] on top of
> Jon's docs-next.
> 
> In sense of consolidation, it also includes:
> 
> *  doc-rst: add media/conf_nitpick.py
> 
>Adds media/conf_nitpick.py from mchehab/docs-next [3].
> 
> *  doc-rst: migrated media build to parseheaders directive

OK, I have applied the first five of these, but stopped at parse-header.
At this point, I have a few requests.  These are in approximate order of
decreasing importance, but they're all important, I think.

- The new directive could really use some ... documentation.  Preferably in
  kernel-documentation.rst with the rest.  What is parse-header, how does
  it differ from kernel-doc, why might a kernel developer doing
  documentation want (or not want) to use it?  That's all pretty obscure
  now.  If we want others to jump onto this little bandwagon of ours, we
  need to make sure it's all really clear.

- Along those lines, is parse-header the right name for this thing?
  "Parsing" isn't necessarily the goal of somebody who uses this directive,
  right?  They want to extract documentation information.  Can we come up
  with a better name?

- Can we please try to get the coding style a bit more in line with both
  kernel and Python community norms?  I suspect some people will get grumpy
  if they see this code.  In particular:

- Please try to stick to the 80-column limit when possible.  Python
  makes that a bit harder than C does, and please don't put in
  ridiculous line breaks that make the code worse.  But sticking a bit
  closer to the rule would be good.

- The "#" lines around function/class
  definition lines or other comments are not helpful, please avoid
  them.  Instead, placing a real comment with actual informative text
  above the function/class would be a good thing.  (I could live with
  Python docstrings if you prefer, though I will confess I prefer
  ordinary comments).

- No commas at the beginning of continuation lines, please; that would
  get you yelled at in C code.  If you need to break a function call
  (or whatever), please put the commas at the end of the line as is
  done elsewhere.

  Sorry to poke at nits here, but we want others in the kernel community to
  be able to look at this code, and that will be easier if we stick closer
  to the usual rules.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/3] doc-rst: generic way to build only sphinx sub-folders

[Jonathan Corbet]

On Mon,  8 Aug 2016 15:14:58 +0200
Markus Heiser  wrote:

> Remove the 'DOC_NITPIC_TARGETS' from main $(srctree)/Makefile and add a
> more generic way to build only a reST sub-folder.
> 
> * 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.

So I went to apply these, but this one, at least, doesn't apply.  Could I
get you to respin the series against current mainline (or docs-next)?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

[Jonathan Corbet]

On Thu, 11 Aug 2016 16:17:56 +0530
Sumit Semwal  wrote:

> Convert dma-buf documentation over to sphinx; also cleanup to
> address sphinx warnings.
> 
> While at that, convert dma-buf-sharing.txt as well, and make it the
> dma-buf API guide.

Thanks for working to improve the documentation!  I do have a few overall
comments...

 - The two comment fixes are a separate thing that should go straight to
   the dma-buf maintainer, who is ...  ... evidently somebody
   familiar to you :)  I assume you'll merge those two directly?

 - It looks like you create a new RST document but leave the old one in
   place.  Having two copies of the document around can only lead to
   confusion, so I think the old one should go.

 - I really wonder if we want to start carving pieces out of
   device-drivers.tmpl in this way.  I guess I would rather see the
   conversion of that book and the better integration of the other docs
   *into* it.  One of the goals of this whole thing is to unify our
   documentation, not to reinforce the silos.

Does that make sense?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: parts of media docs sphinx re-building every time?

[Jonathan Corbet]

On Wed, 10 Aug 2016 12:23:16 +0300
Jani Nikula  wrote:

> >> I just noticed running 'make htmldocs' rebuilds parts of media docs
> >> every time on repeated runs. This shouldn't happen. Please investigate.  
> >
> > I was unable to reproduce it here. Are you passing any special options
> > to the building system?  
> 
> Hmh, I can't reproduce this now either. I was able to hit this on
> another machine consistently, even with 'make cleandocs' in
> between. I'll check the environment on the other machine when I get my
> hands on it.

Just FWIW, I've been trying to find a moment to come back to this because
I couldn't reproduce it either...

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/3] doc-rst: more generic way to build only sphinx sub-folders

[Jonathan Corbet]

On Mon,  8 Aug 2016 15:14:57 +0200
Markus Heiser  wrote:

> this is my approach for a more generic way to build only sphinx sub-folders, 
> we
> discussed in [1]. The last patch adds a minimal conf.py to the gpu folder, if
> you don't want to patch the gpu folder drop it.

I haven't had a chance to really mess with this yet, but it seems like a
reasonable solution.  Mauro, does it give you what you need?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] DocBook: use DOCBOOKS="" to ignore DocBooks instead of IGNORE_DOCBOOKS=1

[Jonathan Corbet]

On Thu,  4 Aug 2016 11:48:26 +0300
Jani Nikula  wrote:

> Instead of a separate ignore flag, use the obvious DOCBOOKS="" to ignore
> all DocBook files.

Makes sense, applied.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: Remove the media docbook

[Jonathan Corbet]

On Mon, 1 Aug 2016 08:19:14 -0300
Mauro Carvalho Chehab  wrote:

> My general impression is that it is now a way easier to maintain the
> media documentation and make it more consistent than with DocBook. 

Music to my ears - maybe this whole thing was worth it :)

Seriously, though, this whole thing was kind of dropped on you, many
thanks for how you've run with it and helped to push it forward - much
appreciated.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: Remove the media docbook

[Jonathan Corbet]

On Wed, 27 Jul 2016 06:32:31 -0300
Mauro Carvalho Chehab  wrote:

> This patch should be applied after Linus handle my media documentation
> pull request. Do you prefer to send the patch yourself, or if I do it?

If you want it to go up for 4.8, just go ahead and send it in, no need for
a middleman.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: kernel-doc: fix handling of address_space tags

[Jonathan Corbet]

On Fri, 22 Jul 2016 11:46:36 -0300
Mauro Carvalho Chehab  wrote:

> The RST cpp:function handler is very pedantic: it doesn't allow any
> macros like __user on it:
> [...]
> So, we have to remove it from the function prototype.

Sigh, this is the kind of thing where somehow there's always more moles
to whack.  I feel like there must be a better fix, but I don't know what
it is, so I've applied this, thanks.

I'm trying to get my act together so that the pull request can go in
right away once the merge window opens.  If there's anything else you
think really needs to be there, please do let me know.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/18] Complete moving media documentation to ReST format

[Jonathan Corbet]

On Thu, 21 Jul 2016 16:41:53 +0200
Markus Heiser <markus.hei...@darmarit.de> wrote:

> Am 21.07.2016 um 01:28 schrieb Jonathan Corbet <cor...@lwn.net>:
>
> > I would hope that most people wouldn't have to worry about it, and would
> > be able to just use what their distribution provides - that's the reason
> > for the 1.2 compatibility requirement in the first place.  
> 
> Yes, but this is not what I mean ;) ... if someone use a distro 
> with a version > 1.2 and he use features not in 1.2, you -- the
> maintainer -- will get into trouble. 

Well, that's what we keep maintainers around.  The same holds for any
maintainer if somebody adds a dependency on a too-new version of some other
tool.  Such things happen, we simply fix them when they do.

> IMHO contributors need a reference documentation (e.g. at kernel.org)
> and a reference build environment (like you, see below).

Reference documentation, yes.  But I don't think every developer needs a
Sphinx 1.2 installation, just like they don't need to have gcc 3.2 around.
It's enough that somebody has it and will catch problems.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/18] Complete moving media documentation to ReST format

[Jonathan Corbet]

On Wed, 20 Jul 2016 08:07:54 +0200
Markus Heiser  wrote:

> Jon, what do you think ... could we serve this 1.2 doc 
> on https://www.kernel.org/doc/ as reference?

Seems like a good idea.  I don't really know who controls that directory,
though; I can ping Konstantin and see what can be done there.  Failing
that, I'd be more than happy to put it up on lwn, of course.

> And whats about those who have 1.3 (or any version >1.2) as default 
> in the linux distro? Should they install a virtualenv?  ... it is
> a dilemma.

I would hope that most people wouldn't have to worry about it, and would
be able to just use what their distribution provides - that's the reason
for the 1.2 compatibility requirement in the first place.  I'll make a
point of having a 1.2 installation around that I can test things with;
that should suffice to catch any problems that sneak in.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Jonathan Corbet]

On Wed, 20 Jul 2016 11:41:11 -0300
Mauro Carvalho Chehab  wrote:

> > The thing with that is that a lot of literal blocks *do* have C code, even
> > in kernel-documentation.rst.  Setting that in conf.py would turn off all C
> > highlighting.  I think that might actually be a desirable outcome, but it
> > would be good to make that decision explicitly.  
> 
> Agreed. Assuming "C" as default seems a good idea to me.

"Agreed," but there was an implied question there that, I think, deserves
consideration.  Do we want to have a default highlighting language for
literal blocks at all?  Those blocks will contain ascii art diagrams,
device-tree fragments, error message examples, and who knows what else.
Even if the majority of them are C code, having Sphinx treat all of them
as C is going to lead to a steady stream of warnings and a lot of extra
markup in the text.

Plus I'm not convinced that more color eye candy in code fragments is
actually helpful.

So I think I might actually argue in favor of Markus's suggestion and set
the language to "none" by default.  But others may feel strongly about
having their bikeshed in full syntax-highlighted color.  Opinions on the
matter?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst: get rid of warnings at kernel-documentation.rst

[Jonathan Corbet]

On Wed, 20 Jul 2016 16:23:28 +0200
Markus Heiser  wrote:

> Am 20.07.2016 um 16:11 schrieb Mauro Carvalho Chehab 
> :
> 
> > Sphinx 1.4.5 complains about some literal blocks at
> > kernel-documentation.rst:
> > 
> > Documentation/kernel-documentation.rst:373: WARNING: Could not lex 
> > literal_block as "C". Highlighting skipped.
> > Documentation/kernel-documentation.rst:378: WARNING: Could not lex 
> > literal_block as "C". Highlighting skipped.
> > Documentation/kernel-documentation.rst:576: WARNING: Could not lex 
> > literal_block as "C". Highlighting skipped.
> > 
> > Fix it by telling Sphinx to consider them as "none" type.  
> 
> Hi Mauro,
> 
> IMHO we should better fix this by unsetting the lexers default language 
> in the conf.py  [1] ... currently:
> 
> highlight_language = 'C'  # set this to 'none'
>   
> As far as I know the default highlight_language is also the default
> for literal blocks starting with "::"

The thing with that is that a lot of literal blocks *do* have C code, even
in kernel-documentation.rst.  Setting that in conf.py would turn off all C
highlighting.  I think that might actually be a desirable outcome, but it
would be good to make that decision explicitly.

As it happens, I'd already fixed these particular warnings in docs-next:

http://permalink.gmane.org/gmane.linux.documentation/39806

I took a different approach; using code-block might actually be better.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

On Sun, 17 Jul 2016 10:01:54 -0300
Mauro Carvalho Chehab  wrote:

> 4) There are now several errors when parsing functions. Those seems to
> happen when an argument is a function pointer, like:
> 
> /devel/v4l/patchwork/Documentation/media/kapi/v4l2-core.rst:757: WARNING: 
> Error when parsing function declaration.
> If the function has no return type:
>   Error in declarator or parameters and qualifiers
>   Invalid definition: Expected identifier in nested name, got keyword: int 
> [error at 3]
> int v4l2_ctrl_add_handler (struct v4l2_ctrl_handler * hdl, struct 
> v4l2_ctrl_handler * add, bool (*filter) (const struct v4l2_ctrl *ctrl)
> ---^

So I've been trying to reproduce this one, without success; it seems to
work for me.  As it should; the parsing code really should not have
changed at all.  Is there some particular context in which this happens
for you?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

On Sun, 17 Jul 2016 10:01:54 -0300
Mauro Carvalho Chehab  wrote:

> 3) When there's an asterisk inside the source code, for example, to
> document a pointer, or when something else fails when parsing a
> header file, kernel-doc handler just outputs:
>   /devel/v4l/patchwork/Documentation/media/kapi/mc-core.rst:137: WARNING: 
> Inline emphasis start-string without end-string.
>   /devel/v4l/patchwork/Documentation/media/kapi/mc-core.rst:470: WARNING: 
> Explicit markup ends without a blank line; unexpected unindent.
> 
> pointing to a fake line at the rst file, instead of pointing to the
> line inside the parsed header where the issue was detected, making
> really hard to identify what's the error.
> 
> In this specific case, mc-core.rst has only 260 lines at the time I got
> such error.

This sounds like the same warning issue that Daniel was dealing with.
Hopefully his config change will at least make these easier to deal with.

I wonder, though, if we could make kernel-doc a little smarter about
these things so that the Right Thing happens for this sort of inadvertent
markup?  If we could just recognize and escape a singleton *, that would
make a lot of things work.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

On Sun, 17 Jul 2016 10:01:54 -0300
Mauro Carvalho Chehab  wrote:

> 2) For functions, kernel-doc is now an all or nothing. If not all
> functions are declared, it outputs this warning:
> 
>   ./include/media/media-devnode.h:1: warning: no structured comments
> 
> And give up. No functions are exported, nor it points where it bailed.
> So, we need to manually look into all exported symbols to identify
> what's missing

So could you describe this one in a bit more detail?  An example of a
file with the problem and associated kernel-doc directive would be most
helpful here.  This sounds like something we definitely want to fix.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

On Tue, 19 Jul 2016 12:00:24 +0200
Markus Heiser  wrote:

> I recommend to consider to switch to the python version of the parser.
> I know, that there is a natural shyness about a reimplementation in python
> and thats why I offer to support it for a long time period .. it would
> be a joy for me ;-)
> 
> If you interested in, I could send a RFC patch for this, if not please
> give the reasons why not.

We've had this discussion already...  The problem is not with "python",
it's with "reimplementation".  We have enough moving parts in this
transition already; tossing in a wholesale replacement of a tool that,
for all of its many faults, embodies a couple decades worth of experience
just doesn't seem like the right thing to do at this time.

I will be happy to entertain the idea of a new kernel-doc in the future;
trust me, I have no emotional attachment to the current one.  But please
let's solidify what we have now first.  There's enough stuff to deal with
as it is.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/18] Complete moving media documentation to ReST format

[Jonathan Corbet]

On Tue, 19 Jul 2016 11:53:19 -0300
Mauro Carvalho Chehab  wrote:

> So, I guess we should set the minimal requirement to 1.2.x.

*sigh*.

I hate to do that; things are happening quickly enough with Sphinx that
it would be nice to be able to count on a newer version.  That said, one
of my goals in this whole thing was to make it *easier* for developers to
generate the docs; the DocBook toolchain has always been notoriously
difficult in that regard.  Forcing people to install a newer sphinx by
hand is not the way to get there.

So I guess we need to make sure things work with 1.2 for now.  I'd hope
we could push that to at least 1.3 before too long, though, once the
community distributions are there.  I think we can be a *bit* more
aggressive with the docs than with the kernel as a whole.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Troubles with kernel-doc and RST files

[Jonathan Corbet]

[Back home and trying to get going on stuff for real.  I'll look at the
issues listed in this message one at a time.]

On Sun, 17 Jul 2016 10:01:54 -0300
Mauro Carvalho Chehab  wrote:

> 1) We now need to include each header file with documentation twice,
> one to get the enums, structs, typedefs, ... and another one for the
> functions:
> 
>   .. kernel-doc:: include/media/media-device.h
> 
>   .. kernel-doc:: include/media/media-entity.h
>  :export: drivers/media/media-entity.c

So I'm a little confused here; you're including from two different header
files here.  Did you want media-entity.h in both directives?

If I do a simple test with a single line:

.. kernel-doc:: include/media/media-entity.h

I get everything - structs, functions, etc. - as I would expect.  Are you
seeing something different?

It probably would be nice to have an option for "data structures, doc
sections, and exported functions only" at some point.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] doc-rst: add an option to ignore DocBooks when generating docs

[Jonathan Corbet]

On Sat,  9 Jul 2016 13:12:45 -0300
Mauro Carvalho Chehab  wrote:

> 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.

Seems good, applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Wed, 4 May 2016 14:57:38 -0300
Mauro Carvalho Chehab  wrote:

> Also, media documentation is not just one more documentation. It is
> the biggest one we have, and that has more changes than any other
> documentation under Documentation/DocBook:
> 
> $ git lg --since 01/01/2015 ` ls *.tmpl|grep -v media`|wc -l
> 116
> $ git lg --since 01/01/2015 ` ls *.tmpl|grep media` `find media/ -type f`|wc 
> -l
> 179
> 
> It also is more than twice the size of the other DocBook docs:
> 
> $ wc -l $(ls *.tmpl|grep  media) `find media/ -type f`|tail -1
>   82275 total
> $ wc -l $(ls *.tmpl|grep -v media)|tail -1
>   29568 total
> 
> E. g. media corresponds to 60% of the number of patches and 73% of
> the DocBook stuff.

These numbers are not entirely representative, I have to say.  You're
ignoring the kerneldoc comments - which is what much of the "DocBook"
documents are made of, and which is the focus of much of this activity.  If
you could find a way to count those, you'd get a different picture.

But I don't think that really matters; there doesn't seem to be *that* much
disagreement here.

The media book is important; we want it to be a part of the overall kernel
documentation suite and not stuck in some DocBook ghetto.  I agree that we
should have an idea for a plausible path for *all* of our documentation.
But I'm also concerned about delaying this work yet again; we have
developers trying to push forward with improved documentation, and they've
had to wait a year for this stuff - so far.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Wed, 4 May 2016 13:50:35 -0300
Mauro Carvalho Chehab  wrote:

> Em Wed, 4 May 2016 19:13:21 +0300
> Jani Nikula  escreveu:
> > I think we should go for vanilla sphinx at first, to make the setup step
> > as easy as possible for everyone.  
> 
> Vanilla Sphinx doesn't work, as reST markup language is too limited
> to support the docs we have. So, we should either push the needed
> extensions to Sphinx reST or find a way to put it at Kernel tree
> without causing too much pain for the developers, e. g. as something
> that just doing "make htmldoc" would automatically use such extensions
> without needing to actually install the extensions.

It works for everything except the extended media book, right?  Or is there
something I'm missing here?  I am very much interested in having one system
for *all* our docs, but we wouldn't attempt to convert a document can't be
expressed in sphinx.

> > Even if it means still doing that ugly
> > docproc step to call kernel-doc. We can improve from there, and I
> > definitely appreciate your work on making this work with sphinx
> > extensions.  
> 
> I disagree: We should not cause documentation regressions by
> producing incomplete documentation and losing tables because of
> such conversion.

> The quality of the documentation after the change should be *at least*
> equal to the one we current produce, never worse.

Agreed; that's why I think the existing DocBook mechanism should stay in
place until that document will be improved by the change.  But I'd rather
not hold up the entire process for one book, especially since pushing that
process forward can only help in dealing with those final problems.

> > That said, how would it work to include the kernel-doc extension in the
> > kernel source tree? Having things just work if sphinx is installed is
> > preferred over requiring installation of something extra from pypi. (I
> > know this may sound backwards for a lot of projects, but for kernel I'm
> > pretty sure this is how it should be done.)  
> 
> Yeah, using pypi seems an additional undesired step. Aren't there
> any way to make python to use an additional extension at the
> Kernel tree without needing to install it?

Well, sphinx has to come from somewhere too.  But yes, we should be able to
carry extensions in the kernel tree.  But I would still rather upstream it
(to sphinx) if possible, so we're not stuck trying to maintain it across
several sphinx releases.  I don't know how volatile their interfaces are,
but it would be, in any case, the analog of an out-of-tree module...

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Wed, 04 May 2016 16:41:50 +0300
Jani Nikula  wrote:

> On Wed, 04 May 2016, Markus Heiser  wrote:
> > In reST the directive might look like:
> >
> >  -
> > Device Instance and Driver Handling
> > ===
> >
> > .. kernel-doc::  drivers/gpu/drm/drm_drv.c
> >:doc:  driver instance overview
> >:exported:
> >
> >  -  
> 
> Yes, I think something like this, parsed by sphinx directly (via some
> extension perhaps), should be the end goal. I am not sure if it should
> be the immediate first goal though or whether we should reuse the
> existing docproc for now.

I think all of this makes sense.  It would be really nice to have the
directives in the native sphinx language like that.  I *don't* think we
need to aim for that at the outset; the docproc approach works until we can
properly get rid of it.  What would be *really* nice would be to get
support for the kernel-doc directive into the sphinx upstream.

> >  --
> >
> > Comments with the ":reST:" tag could be exported and pass-through
> > to sphinx.  
> 
> Disagreed on most of the above.

Agreed with the disagreement here.  We can't be adding ":reST:" tags to
comments; I anticipate a wee bit of pushback if we try.  It needs to work
with the comments as they are now.  It seems that should be possible.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Wed, 4 May 2016 16:18:27 +0200
Daniel Vetter  wrote:

> > I'd really like to converge on the markup question, so that we can start
> > using all the cool stuff with impunity in gpu documentations.  
> 
> Aside: If we decide this now I could send in a pull request for the
> rst/sphinx kernel-doc support still for 4.7 (based upon the minimal
> markdown/asciidoc code I still have). That would be really awesome ...

Sorry for my relative absence...I'm still busy dealing with bureaucracy
an ocean away from home.  I hope to begin emerging from this mess in the
near future.

So ... there's the code you have, the work I (+Jani) did, and the work
Markus has done.  Which would you have me push into 4.7?

The sphinx/rst approach does seem, to me, to be the right one, with the
existing DocBook structure remaining in place for those who want/need
it.  I'm inclined toward my stuff as a base to work with, obviously :) But
it's hackish at best and needs a lot of cleaning up.  It's a proof of
concept, but it's hardly finished (one might say it's barely begun...)

In the end, I guess, I feel that anything we might try to push for 4.7 is
going to look rushed and not ready, and Linus might react accordingly.
I'd be more comfortable aiming for 4.8.  I *will* have more time to focus
on things in that time frame...  I suspect you're pretty well fed up with
this stuff being pushed back, and rightly so.  All I can do is apologize.

That said, if you do think there's something out there that is good
enough to consider pushing in a week or two, do tell and we can all take
a look.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Fri, 8 Apr 2016 17:12:27 +0200
Markus Heiser  wrote:

> motivated by this MT, I implemented a toolchain to migrate the kernel’s 
> DocBook XML documentation to reST markup. 
> 
> It converts 99% of the docs well ... to gain an impression how 
> kernel-docs could benefit from, visit my sphkerneldoc project page
> on github:
> 
>   http://return42.github.io/sphkerneldoc/

So I've obviously been pretty quiet on this recently.  Apologies...I've
been dealing with an extended death-in-the-family experience, and there is
still a fair amount of cleanup to be done.

Looking quickly at this work, it seems similar to the results I got.  But
there's a lot of code there that came from somewhere?  I'd put together a
fairly simple conversion using pandoc and a couple of short sed scripts;
is there a reason for a more complex solution?

Thanks for looking into this, anyway; I hope to be able to focus more on
it shortly.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Thu, 03 Mar 2016 16:03:14 +0200
Jani Nikula  wrote:

> This stalled a bit, but the waters are still muddy...

So I've been messing with this a bit; wanted to do a proper patch posting
but I'm fried and mostly out of time for the moment.

The results I'm getting now can be seen at:

http://static.lwn.net/kerneldoc/

I've pulled in a few templates (including gpu.tmpl), converted them, and
built them into some reasonable-looking HTML, modulo a fair number of
glitches. There's lots of details to deal with, but the broad shape of it
is there.  If you look, you'll see that things like cross-file
cross-references, a feature we've never had before, work nicely.

I can also get good EPUB and PDF output - except that rst2pdf is
currently crashing on me, which is a little discouraging.  Man page
output will take more work.

What I have so far can be pulled from:

git://git.lwn.net/linux.git doc/sphinx

It's still based on using docproc because that was easiest (for me).  The
kernel-doc part is Jani's asciidoc stuff, hacked up and made uglier.  I'm
not sure that any of it is worth more than a demonstration of what can be
done; I'm not particularly proud of (or tied to) any of it.  But it's a
start.

I've not looked at the table situation at all; soon.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Thu, 3 Mar 2016 14:34:25 +
One Thousand Gnomes  wrote:

> We only have docbook because it was the tool of choice rather a lot of
> years ago to then get useful output formats. It was just inherited when
> borrowed the original scripts from Gnome/Gtk. It's still the most
> effective way IMHO of building big structured documents out of the kernel.

...except that we haven't used it that way.  Instead, we make a whole
bunch of smaller, partially structured document silos.

> The Gtk people long ago rewrote the original document script into a real
> tool so they have some different and maintained tools that are close to
> equivalent and already have some markdown support. Before we go off and
> re-invent the wheel it might be worth just borrowing their wheel and
> tweaking it as needed ? In particular they can generate help indexes so
> that the entire output becomes nicely browsable with an HTML based help
> browser.

Well, not inventing the wheel was kind of the motivation behind much of
this effort; I got kind of worried watching us trying to cobble more
functionality into our existing house-of-cards documentation system.

Sphinx is a well-established, heavily used, and well supported system;
using it would not be an exercise in wheel reinvention.  As far as I can
tell, it does everything we need (with some open questions about table
support), lets us drop the whole DocBook toolchain dependency, and move to
a much better-supported setup than we have now.  Plus we get much nicer
output, index generation, cross-references between documents, and the
ability to write documents in a lightweight markup language.  Seems like a
win.

I assume you're referring to gtk-doc?  It's web page
(http://www.gtk.org/gtk-doc/) starts by noting that it's "a bit awkward to
setup and use"; they recommend looking at Doxygen instead.  So I guess I'm
not really sure what it offers that merits throwing another option into
the mix now?  What am I missing?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Thu, 03 Mar 2016 16:03:14 +0200
Jani Nikula  wrote:

> This stalled a bit, but the waters are still muddy...

I've been dealing with real-world obnoxiousness, something which won't
come to an immediate end, unfortunately.  But I have been taking some time
to mess with things, and hope to have some more POC patches to send out
soon.

> Is the Sphinx/reStructuredText table support adequate for media/v4l
> documentation?

That's perhaps the biggest question.  My sense is "yes", but this needs a
bit more assurance than that.

> Are the Sphinx output formats adequate in general? Specifically, is the
> lack of DocBook support, and the flexibility it provides, a blocker?

DocBook is a means to an end; nobody really wants DocBook itself as far
as I can tell. I've been messing with rst2pdf a bit; it's not hard to get
reasonable output, and, with some effort, we could probably get really
nice output. HTML and EPUB are easily covered, still haven't really played
around with man pages yet.  And there's LaTeX if we really need it.  I
kind of think we're covered there, unless I've missed something?

> Otherwise, I think Sphinx is promising.
> 
> Jon, I think we need a roll of dice, err, a well-thought-out decision
> from the maintainer to go with one or the other, so we can make some
> real progress.

My inclination at the moment is very much in the Sphinx direction.  I had
some vague thoughts of pushing a throwaway experimental directory with a
couple of docs for 4.6 that would just let people play with it easily;
then we'd see how many screams we get.  We'll see if the world lets me get
there.

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Jonathan Corbet]

On Tue, 17 Nov 2015 08:40:46 -0200
Mauro Carvalho Chehab  wrote:

> The above causes some versions of perl to fail, as keys expect a
> hash argument:
> 
> Execution of .//scripts/kernel-doc aborted due to compilation errors.
> Type of arg 1 to keys must be hash (not private array) at 
> .//scripts/kernel-doc line 2714, near "@highlights) "
> 
> This is happening at linuxtv.org server, with runs perl version 5.10.1.

OK, that's not good.  But I'm not quite sure what to do about it.

Perl 5.10.1 is a little over six years old.  Nobody else has complained
(yet) about this problem.  So it might be best to "fix" this with a
minimum version added to the Changes file.

Or maybe we need to revert the patch.

So I'm far from a Perl expert, so I have no clue what the minimum version
would be if we were to say "5.10.1 is too old."  I don't suppose anybody
out there knows?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2 2/4] scripts/kernel-doc: Replacing highlights hash by an array

[Jonathan Corbet]

On Tue, 17 Nov 2015 13:29:49 -0200
Mauro Carvalho Chehab  wrote:

> The enclosed patch should do the trick. I tested it with perl 5.10 and 
> perl 5.22 it worked fine with both versions.

Indeed it seems to work - thanks!  Applied to the docs tree, I'll get it
upstream before too long.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [RFC] Documentation: dontdiff: remove media from dontdiff

[Jonathan Corbet]

On Fri, 30 Oct 2015 01:15:39 +0800
Wang YanQing  wrote:

> media will hide all the changes in drivers/media.
> 
> Signed-off-by: Wang YanQing 
> ---
>  I don't know whether it is still acceptable to patch dontdiff,
>  so I add Linus to CC list.

As long as the file is there, its contents should make sense, so I've
applied this to the docs tree, thanks.

That said, the fact that it excludes a big driver subsystem and nobody
has said anything suggests it hasn't been used in some time, so we should
consider just deleting it.

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: How to fix DocBook parsers for private fields inside #ifdefs

[Jonathan Corbet]

On Mon, 5 Oct 2015 09:03:48 -0300
Mauro Carvalho Chehab  wrote:

> Patch enclosed.

...and applied, thanks!

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: How to fix DocBook parsers for private fields inside #ifdefs

[Jonathan Corbet]

On Thu, 1 Oct 2015 14:21:07 -0300
Mauro Carvalho Chehab  wrote:

> They're all after a private comment:
>   /* Private: internal use only */
> 
> So, according with Documentation/kernel-doc-nano-HOWTO.txt, they shold
> have been ignored.
> 
> Still, the scripts produce warnings for them:

Sorry, I've been away from the keyboard for a few days and am only now
catching up.

The problem is that kernel-doc is dumb...the test is case-sensitive, so
it needs to be "private:", not "Private:".  I'm sure there's a magic perl
regex parameter to make the test case-insensitive; when I get a chance
I'll figure it out and put it in there.

(Of course, once you fix that glitch, you'll get gripes about the fields
that are marked private but documented anyway.  Like I said, kernel-doc
is dumb.)

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/39] Document the kABI for the media subsystem

[Jonathan Corbet]

On Sat, 22 Aug 2015 14:27:45 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 Jon,
 
 As most of the changes here are inside the media drivers, I
 prefer to merge this series via my tree, if this is ok for
 you.

That's fine, feel free to stick my ack in if you want.  Hopefully we'll
not run into conflicts over device-drivers.tmpl...

Thanks,

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [media] DocBook: Fix typo in intro.xml

[Jonathan Corbet]

On Fri, 24 Jul 2015 10:33:51 +0200
Hans Verkuil hverk...@xs4all.nl wrote:

 Jon, would you mind if I take this patch and let it go through the media
 tree? I'd like to apply a patch on top of this one that removes the mention of
 devfs.

Fine, I'll drop it.

 It makes more sense in general to take patches to Documentation/DocBook/media
 via the media route.

OK.  I'll stick the following into MAINTAINERS so I'm not tempted to grab
them from you :)

jon

MAINTAINERS: Direct Documentation/DocBook/media properly

The media maintainers want DocBook changes to go through their tree;
document that wish accordingly.
---
 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index b9b91566380e..11e2516c2712 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3440,6 +3440,7 @@ X:Documentation/devicetree/
 X: Documentation/acpi
 X: Documentation/power
 X: Documentation/spi
+X: Documentation/DocBook/media
 T: git git://git.lwn.net/linux-2.6.git docs-next
 
 DOUBLETALK DRIVER
-- 
2.4.3

--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Doc: pps: Fix file name in pps.txt

[Jonathan Corbet]

On Mon, 13 Jul 2015 12:29:11 +0900
Masanari Iida standby2...@gmail.com wrote:

 This patch fix a file name of example code.

Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [media] DocBook: Fix typo in intro.xml

[Jonathan Corbet]

On Tue, 14 Jul 2015 08:36:50 +0900
Masanari Iida standby2...@gmail.com wrote:

 This patch fix spelling typos in intro.xml.
 This xml file is not created from comments within source,
 I fix the xml file.

Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Doc: pps: Fix file name in pps.txt

[Jonathan Corbet]

On Mon, 13 Jul 2015 08:23:15 +0200
Rodolfo Giometti giome...@enneenne.com wrote:

 On Mon, Jul 13, 2015 at 12:29:11PM +0900, Masanari Iida wrote:
  This patch fix a file name of example code.
  
  Signed-off-by: Masanari Iida standby2...@gmail.com  
 
 Signed-off-by: Rodolfo Giometti giome...@enneenne.com

Why Signed-off-by?  Did you maybe mean Acked-by here?

Thanks,

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Doc:nfc: Fix typo in nfc-hci.txt

[Jonathan Corbet]

On Fri,  5 Jun 2015 21:38:19 +0900
Masanari Iida standby2...@gmail.com wrote:

 This patch fix a spelling typo in nfc-hci.txt

Applied to the docs tree, thanks.

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/35] Improve DVB frontend API documentation

[Jonathan Corbet]

On Tue, 2 Jun 2015 06:26:13 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 I prefer to send it via my tree, if you don't mind. 

That's fine.

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 02/35] DocBook: add a note about the ALSA API

[Jonathan Corbet]

On Thu, 28 May 2015 18:49:05 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 + paraIt should also be noticed that a media device may also have audio
 +   components, like mixers, PCM capture, PCM playback, etc, with
 +   are controlled via ALSA API./para

How about s/noticed/noted/ and s/with/which/ ?

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 15/35] DocBook: Improve the description of the properties API

[Jonathan Corbet]

A few minor corrections here.

jon

On Thu, 28 May 2015 18:49:18 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 Make the text clearer about what the properties API does.
 
 Signed-off-by: Mauro Carvalho Chehab mche...@osg.samsung.com
 
 diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml 
 b/Documentation/DocBook/media/dvb/dvbproperty.xml
 index 28ea62067af6..c10ed0636d02 100644
 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml
 +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml
 @@ -1,8 +1,35 @@
 -section id=FE_GET_SET_PROPERTY
 -titleconstantFE_GET_PROPERTY/FE_SET_PROPERTY/constant/title
 -paraThis section describes the DVB version 5 extension of the DVB-API, also
 -called S2API, as this API were added to provide support for DVB-S2. It was
 -designed to be able to replace the old frontend API. Yet, the DISEQC and
 +section id=frontend-properties
 +titleDVB Frontend properties/title
 +paraTuning into a Digital TV physical channel and starting decoding it
 +requires to change a set of parameters, in order to control the

requires *changing* as set...

 +tuner, the demodulator, the Linear Low-noise Amplifier (LNA) and to set 
 the
 +antena subsystem via Satellite Equipment Control (SEC), on satellital

antenna

 +systems. The actual parameters are specific to each particular digital
 +TV standards, and may change as the digital TV specs evolutes./para

standard (no s).  s/evolutes/evolves/

 +paraIn the past, the strategy used were to have an union with the 
 parameters

s/were to have an/was to have a/

 +needed to tune for DVB-S, DVB-C, DVB-T and ATSC delivery systems grouped
 +there. The problem is that, as the second generation standards appeared,
 +those structs were not big enough to contain the additional parameters.
 +Also, the union didn't have any space left to be expanded without 
 breaking
 +userspace. So, the decision was to deprecate the legacy union/struct 
 based
 +approach, in favor of a properties set approach./para
 +paraBy using a properties set, it is now possible to extend and support any
 +digital TV without needing to redesign the API/para
 +paraExample: with the properties based approach, in order to set the tuner
 +to a DVB-C channel at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol
 +rate of 5.217 Mbauds, those properties should be sent to
 +link 
 linkend=FE_GET_PROPERTYconstantFE_SET_PROPERTY/constant/link 
 ioctl:/para
 +itemizedlist
 + listitemDTV_FREQUENCY = 65100/listitem
 + listitemDTV_MODULATION = QAM_256/listitem
 + listitemDTV_INVERSION = INVERSION_AUTO/listitem
 + listitemDTV_SYMBOL_RATE = 5217000/listitem
 + listitemDTV_INNER_FEC = FEC_3_4/listitem
 + listitemDTV_TUNE/listitem
 +/itemizedlist
 +paraNOTE: This section describes the DVB version 5 extension of the 
 DVB-API,
 +also called S2API, as this API were added to provide support for DVB-S2. It
 +was designed to be able to replace the old frontend API. Yet, the DISEQC and
  the capability ioctls weren't implemented yet via the new way./para
  paraThe typical usage for the 
 constantFE_GET_PROPERTY/FE_SET_PROPERTY/constant
  API is to replace the ioctl's were the link 
 linkend=dvb-frontend-parameters

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 00/35] Improve DVB frontend API documentation

[Jonathan Corbet]

On Thu, 28 May 2015 18:49:03 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 This is the first series of patches that will improve the DVB
 documentation.

I've done a *quick* pass over these and sent a few comments, but they are
all on the trivial-detail side of things.  Looks good in general.

Would you like me to carry these in the docs tree, or will you sent them
up yourself?  Feel free to add my ack if you want in the latter case.

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 04/35] DocBook: fix emphasis at the DVB documentation

[Jonathan Corbet]

On Thu, 28 May 2015 18:49:07 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 Currently, it is using 'role=tt', but this is not defined at
 the DocBook 4.5 spec. The net result is that no emphasis happens.
 
 So, replace them to bold emphasis.

Nit: I suspect the intent of the emphasis here was to get the code in a
monospace font, which bold is unlikely to do.  Isn't there a
role=code or something useful like that to use?  I'd have to go look.

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 32/35] DocBook: Provide a high-level description for DVB frontend

[Jonathan Corbet]

On Thu, 28 May 2015 18:49:35 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 +Please notice that several statistics require the demodulator to be fully
 +locked (e. g. with FE_HAS_LOCK bit set). See

s/notice/note/

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 08/27] ov7670: check read error also for REG_AECHH on ov7670_s_exp()

[Jonathan Corbet]

On Wed, 29 Apr 2015 20:05:53 -0300
Mauro Carvalho Chehab mche...@osg.samsung.com wrote:

 ov7670_s_exp() checks read error for 2 registers: REG_COM1
 and REG_COM8. But, although it uses the value latter, it
 doesn't check errors on REG_AECHH read. Yet, as it is doing
 a bitmask operation there, the read operation should succeed.
 
 So, fix the code to also check if this succeeded.
 
 This fixes this smatch report:
   drivers/media/i2c/ov7670.c:1366 ov7670_s_exp() warn: inconsistent 
 indenting

That's why I like programming in Python...:)

Silly mistake, good fix.

Acked-by: Jonathan Corbet cor...@lwn.net

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] marvell-ccic: fix RGB444 format

[Jonathan Corbet]

On Fri, 24 Apr 2015 11:52:47 +0200
Hans Verkuil hverk...@xs4all.nl wrote:

 The RGB444 format swapped the red and blue components, fix this.
 
 Rather than making a new BGR444 format (as I proposed initially), Jon prefers
 to just fix this and return the colors in the right order. I think that makes
 sense in this case.
 
 Since the RGB444 pixel format is deprecated due to the ambiguous specification
 of the alpha component we use the XRGB444 pixel format instead (specified as 
 having
 no alpha channel).

Seems good to me.

Acked-by: Jonathan Corbet cor...@lwn.net

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCHv3 00/22] marvell-ccic: drop and fix formats

[Jonathan Corbet]

On Sat, 04 Apr 2015 16:54:42 +0200
Hans Verkuil hverk...@xs4all.nl wrote:

 Jon, ping!
 
 Patch 18 is merged and I have your Ack for patch 19, but I'd like your Ack
 as well for patches 20-22, if possible.

Sorry, I'm traveling and dealing with a bunch of stuff...lots of balls
falling all over the floor.

You can add my ack to those patches, but let me just toss out my thoughts
for consideration.  At one point, the RGB444 format was what the OLPC
XO was going to use for performance reasons.  As I recall, when you
looked recently, that was no longer the case.  So that makes it safe to
fix things without worrying that somebody might just be crazy enough to
put a 4.x kernel on an XO and have their video be messed up.

If, however, we're going to do that, we could also just fix RGB444 to
actually return RGB.  I'd have to go back and look (and I'm far from the
manual at the moment), but I believe it was a pretty simple tweak to flip
the nibbles around.

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [media] marvell-ccic: fix memory leak on failure path in cafe_smbus_setup()

[Jonathan Corbet]

On Sat,  4 Apr 2015 03:16:01 +0300
Alexey Khoroshilov khoroshi...@ispras.ru wrote:

 If i2c_add_adapter() fails, adap is not deallocated.
 
 Found by Linux Driver Verification project (linuxtesting.org).
 
 Signed-off-by: Alexey Khoroshilov khoroshi...@ispras.ru

Actually, the worse thing is that it leaves the IRQ enabled...it's good
you moved that lines down.  Even better, of course, that the failure path
has probably never been run during the life of this driver...:)

Should there be some sort of proper reported-by line for the driver
verification project?

Acked-by: Jonathan Corbet cor...@lwn.net

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/1] DocBook media: fix broken EIA hyperlink

[Jonathan Corbet]

On Sun, 22 Mar 2015 11:35:55 -0700
Michael Opdenacker michael.opdenac...@free-electrons.com wrote:

 This is a fix for the only broken link in kernel documentation,
 at least according to the linkchecker tool that we are running
 on the Free Electrons website once a day.
 
 As kernel documentation is part of our website
 (on http://free-electrons.com/kerneldoc/), I get reminded
 of this broken link once a day!

Applied to the docs tree - hopefully your email will be a little quieter
soon.

Thanks,

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCHv2 00/21] marvell-ccic: drop and fix formats

[Jonathan Corbet]

On Wed, 11 Mar 2015 09:10:24 +0100
Hans Verkuil hverk...@xs4all.nl wrote:

 After some more testing I realized that the 422P format produced
 wrong colors and I couldn't get it to work. Since it never worked and
 nobody complained about it (and it is a fairly obscure format as well)
 I've dropped it.

I'm not sure how that format came in anymore; I didn't add it.  No
objections to its removal.

 I also tested RGB444 format for the first time, and that had wrong colors
 as well, but that was easy to fix. Finally there was a Bayer format
 reported, but it was never implemented. So that too was dropped.

The RGB444 change worries me somewhat; that was the default format on the
XO1 and worked for years.  I vaguely remember some discussions about the
ordering of the colors there, but that was a while ago.  Did you test it
with any of the Sugar apps?

In the end, correctness is probably the right way to go (it usually is!),
but I'd hate to get a regression report from somebody who is crazy enough
to put current kernels on those machines.  Fortunately, such people
should be rare.

Bayer sort-of worked once, honest.  I added it for some academic who
wanted to do stuff, and was never really able to close the loop on
getting it working correctly.  It might be worth removing the alleged
support from ov7670 as well.

In any case, for all of them:

Acked-by: Jonathan Corbet cor...@lwn.net

jon
--
To unsubscribe from this list: send the line unsubscribe linux-media in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html