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

  From: Markus Heiser <markus.heiser@darmarIT.de>

Add a generic way to build only a reST sub-folder with or
without a individual *build-theme*.

* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF

Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::

  make SPHINXDIRS="media gpu" htmldocs

To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::

  make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs

With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/DocBook/Makefile      |  7 ++++++
 Documentation/Makefile.sphinx       | 43 +++++++++++++++++++++++++++++++------
 Documentation/conf.py               |  7 ++++++
 Documentation/sphinx/load_config.py | 33 ++++++++++++++++++++++++++++
 4 files changed, 83 insertions(+), 7 deletions(-)
 create mode 100644 Documentation/sphinx/load_config.py
  

On Sat, 13 Aug 2016 16:12:42 +0200
Markus Heiser <markus.heiser@darmarit.de> 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 majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
  

Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Sat, 13 Aug 2016 16:12:42 +0200
> Markus Heiser <markus.heiser@darmarit.de> 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?

Sorry for being unclear. My intention was to produce a structured output
which could copied 1:1 to a static HTML server.

Since the documentation says: 

  "The generated documentation is placed in ``Documentation/output``."

I thought I'am free to give it a structure. But I haven't clarified
this point / sorry.

The main structure is, that a HTML output is produced without any
folder prefix, so a simple htmldoc target goes to::

  Documentation/output/index.html

Other formats like epub are placed into a format-specific subfolder e.g. 
the epub from target "epubdocs" are placed in::

  Documentation/output/epub/*

If you only compile a subfolder e.g. "SPHINXDIRS=media" you get a
the analogous structure in the Documentation/output/media folder::

  Documentation/output/{subfolder}/{non-html-format}/

With you can place the Documentation/output/{subfolder} on 
your HTTP server including all formats.

Unfortunately at the this time, 

* the pdf goes to the "latex" folder .. since this is WIP
  and there are different solutions conceivable ... I left
  it open for the first.

* in the index.html we miss some links to pdf-/man- etc files
  
The last point needs some discussion. Hopefully, this discussion
starts right here.


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

IMHO a structure where only non-HTML formats are placed in subfolders
(described above) is the better choice.

In the long run I like to get rid of all the intermediate formats
(latex, .doctrees) and build a clear output-folder (with all formats
in) which could be copied 1:1 to a static HTTP-server.

-- Markus --

> jon

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

On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>:
> * the pdf goes to the "latex" folder .. since this is WIP
>   and there are different solutions conceivable ... I left
>   it open for the first.

Mea culpa. As I said, I intended my patches as RFC only.

>
> * in the index.html we miss some links to pdf-/man- etc files
>   
> The last point needs some discussion. Hopefully, this discussion
> starts right here.
>
>
>> 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.
>
> IMHO a structure where only non-HTML formats are placed in subfolders
> (described above) is the better choice.
>
> In the long run I like to get rid of all the intermediate formats
> (latex, .doctrees) and build a clear output-folder (with all formats
> in) which could be copied 1:1 to a static HTTP-server.

When I added the Documentation/output subfolder, my main intention was
to separate the source documents from everything that is generated,
intermediate or final. I suggest you keep the generated files somewhere
under output. This'll be handly also when ensuring O= works.

I set up the format specific subfolders, because I thought people would
want to keep them separated and independent. For me, all the formats
were equal and at the same level in that regard. You're suggesting to
make html the root of everything?


BR,
Jani.
  

Em Thu, 18 Aug 2016 16:35:14 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Sat, 13 Aug 2016 16:12:42 +0200
> Markus Heiser <markus.heiser@darmarit.de> 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.

Agreed. it should either use subfolders or not.

IMHO, the best would be to just output everything at 
Documentation/output, if this is possible. That "fixes" the issue
of generating PDF files at the latex dir, with sounds weird, IMHO.

I guess I mention on a previous e-mail, but SPHINXDIRS= is not working
for PDF files generation.

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

Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>:

> On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
>> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>:
>> * the pdf goes to the "latex" folder .. since this is WIP
>>  and there are different solutions conceivable ... I left
>>  it open for the first.
> 
> Mea culpa. As I said, I intended my patches as RFC only.

I think this is OK for the first. I thought that we first
let finish Mauro's task on making the media PDF and after
this we decide how move from the latex folder to a pdf folder
(one solution see below).

>>> 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.
>> 
>> IMHO a structure where only non-HTML formats are placed in subfolders
>> (described above) is the better choice.
>> 
>> In the long run I like to get rid of all the intermediate formats
>> (latex, .doctrees) and build a clear output-folder (with all formats
>> in) which could be copied 1:1 to a static HTTP-server.
> 
> When I added the Documentation/output subfolder, my main intention was
> to separate the source documents from everything that is generated,
> intermediate or final. I suggest you keep the generated files somewhere
> under output. This'll be handly also when ensuring O= works.

Yes, everything is under output / tested O=..

> I set up the format specific subfolders, because I thought people would
> want to keep them separated and independent. For me, all the formats
> were equal and at the same level in that regard. You're suggesting to
> make html the root of everything?

Yes this was my intention. With some additional work, we can build a 
root index.html where the other formats are linked. Since other
formats *below* index.html, everything is *reachable* from the root
index.html.

Am 19.08.2016 um 15:32 schrieb Mauro Carvalho Chehab <mchehab@infradead.org>:
> 
> Agreed. it should either use subfolders or not.
> 
> IMHO, the best would be to just output everything at 
> Documentation/output, if this is possible. That "fixes" the issue
> of generating PDF files at the latex dir, with sounds weird, IMHO.

Changing the latex/pdf issue should be  just a two-liner (not yet tested).

@@ -71,8 +71,8 @@ ifeq ($(HAVE_PDFLATEX),0)
 	$(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
 	@echo "  SKIP    Sphinx $@ target."
 else # HAVE_PDFLATEX
-	@$(call loop_cmd,sphinx,latex,.,latex,.)
-	$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex
+	@$(call loop_cmd,sphinx,latex,.,pdf,.)
+	$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/pdf
 endif # HAVE_PDFLATEX


> I guess I mention on a previous e-mail, but SPHINXDIRS= is not working
> for PDF files generation.

Not yet, there is a concurrency question to answer, should sub-folder's 
PDFs defined in the main conf.py-file or in the sub-folder conf.py?

I suggest the last one, or in other words: the PDF content of a target
should have the same content as the HTML target even if it is a subfolder
or the whole documentation. But this is only possible if we know, that
all media content can be integrated in the big PDF file.

After said this, what is your suggestion? For me its all equal, these 
are only my 2cent to this discussion :-)
 
-- Markus --

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

Em Fri, 19 Aug 2016 17:52:07 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>:
> 
> > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:  
> >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>:
> >> * the pdf goes to the "latex" folder .. since this is WIP
> >>  and there are different solutions conceivable ... I left
> >>  it open for the first.  
> > 
> > Mea culpa. As I said, I intended my patches as RFC only.  
> 
> I think this is OK for the first. I thought that we first
> let finish Mauro's task on making the media PDF and after
> this we decide how move from the latex folder to a pdf folder
> (one solution see below).

Most of the work is done: the uAPI book. The other books don't use much
tables. So, I guess it should be easier to fix them. I'll look on
the other media books next week.

> 
> >>> 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.  
> >> 
> >> IMHO a structure where only non-HTML formats are placed in subfolders
> >> (described above) is the better choice.
> >> 
> >> In the long run I like to get rid of all the intermediate formats
> >> (latex, .doctrees) and build a clear output-folder (with all formats
> >> in) which could be copied 1:1 to a static HTTP-server.  
> > 
> > When I added the Documentation/output subfolder, my main intention was
> > to separate the source documents from everything that is generated,
> > intermediate or final. I suggest you keep the generated files somewhere
> > under output. This'll be handly also when ensuring O= works.  
> 
> Yes, everything is under output / tested O=..
> 
> > I set up the format specific subfolders, because I thought people would
> > want to keep them separated and independent. For me, all the formats
> > were equal and at the same level in that regard. You're suggesting to
> > make html the root of everything?  
> 
> Yes this was my intention. With some additional work, we can build a 
> root index.html where the other formats are linked. Since other
> formats *below* index.html, everything is *reachable* from the root
> index.html.
> 
> Am 19.08.2016 um 15:32 schrieb Mauro Carvalho Chehab <mchehab@infradead.org>:
> > 
> > Agreed. it should either use subfolders or not.
> > 
> > IMHO, the best would be to just output everything at 
> > Documentation/output, if this is possible. That "fixes" the issue
> > of generating PDF files at the latex dir, with sounds weird, IMHO.  
> 
> Changing the latex/pdf issue should be  just a two-liner (not yet tested).
> 
> @@ -71,8 +71,8 @@ ifeq ($(HAVE_PDFLATEX),0)
>  	$(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.)
>  	@echo "  SKIP    Sphinx $@ target."
>  else # HAVE_PDFLATEX
> -	@$(call loop_cmd,sphinx,latex,.,latex,.)
> -	$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/latex
> +	@$(call loop_cmd,sphinx,latex,.,pdf,.)
> +	$(Q)$(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/pdf
>  endif # HAVE_PDFLATEX

True, but I would still prefer to place everything at $(BUILDDIR), but this
is just my personal preference. Not really against per-format subdir.

> 
> 
> > I guess I mention on a previous e-mail, but SPHINXDIRS= is not working
> > for PDF files generation.  
> 
> Not yet, there is a concurrency question to answer, should sub-folder's 
> PDFs defined in the main conf.py-file or in the sub-folder conf.py?
> 
> I suggest the last one, or in other words: the PDF content of a target
> should have the same content as the HTML target even if it is a subfolder
> or the whole documentation. But this is only possible if we know, that
> all media content can be integrated in the big PDF file.

It can. However, in practice, experienced developers use only the
uAPI book most of the time. So, splitting the media documentation
on 4 books IMHO makes sense.

Yet, the all-in-one media book has only ~3MB. Not big.
	https://mchehab.fedorapeople.org/media.pdf
>
> After said this, what is your suggestion? For me its all equal, these 
> are only my 2cent to this discussion :-)
>  
> -- Markus --
> 
> > 
> > Thanks,
> > Mauro  



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

Em Fri, 19 Aug 2016 17:40:38 -0300
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:

> Em Fri, 19 Aug 2016 17:52:07 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 

> > After said this, what is your suggestion? For me its all equal, these 
> > are only my 2cent to this discussion :-)

Forgot to mention, but I noticed that, sometimes, the building system
doesn't get the cross-references right, and produces a PDF file
(or an HTML file) with no TOC tables. The output files are still
generated.

I didn't try to track the root case.

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

Em Fri, 19 Aug 2016 17:52:07 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>:
> 
> > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:  
> >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>:
> >> * the pdf goes to the "latex" folder .. since this is WIP
> >>  and there are different solutions conceivable ... I left
> >>  it open for the first.  
> > 
> > Mea culpa. As I said, I intended my patches as RFC only.  
> 
> I think this is OK for the first. I thought that we first
> let finish Mauro's task on making the media PDF and after
> this we decide how move from the latex folder to a pdf folder
> (one solution see below).

Finished handling all tables. I'm sending the last 2 patches
right now. Now, all tables fit into the page margins. Yet, I
suspect that flat-table extension causes some troubles when cspan
is used for LaTeX. It would be good if Markus could double check them.

There are just two things that won't fit at the margins of the document:

1) included files with long lines. We might put those includes into
a begingroup and use a smaller font, but IMHO the best is to fix the
few cases on them, as those lines are very likely violating the 80 column
limit;

2) kernel-doc output for big arguments.

We have lots of function argument inside several media structs, like
at:
	struct v4l2_subdev_core_ops.

one of such arguments is this function:

int (* s_io_pin_config) (struct v4l2_subdev *sd, size_t n,struct v4l2_subdev_io_pin_config *pincfg);

When kernel-doc generates the Members description, as the above line is
bigger than 80 columns, it simply truncates its description to:

	Members
	int (*)(struct v4l2_subdev *sd) log_status callback for VIDIOC_LOG_STATUS ioctl handler code.
	int (*)(struct v4l2_subdev *sd,size_t n,struct v4l2_subdev_io_pin_config *pincfg) s_io_pin_con
	...

The LaTeX output for it is:

	\textbf{Members}
	\begin{description}
	\item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd) log\_status}}] \leavevmode
	callback for \sphinxcode{VIDIOC\_LOG\_STATUS} ioctl handler code.

	\item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd, size\_t n,struct v4l2\_subdev\_io\_pin\_config *pincfg) s\_io\_pin\_config}}] \leavevmode
	configure one or more chip I/O pins for chips that
	multiplex different internal signal pads out to IO pins.  This function
	takes a pointer to an array of `n' pin configuration entries, one for
	each pin being configured.  This function could be called at times
	other than just subdevice initialization.

It seems that \sphinxcode{} doesn't allow line breaks. Maybe we can
override it via conf.py. I'll play with it and see if I can find a
solution. Yet, this could have side effects on other places.

Any suggestions about how to fix it?

PS.: if you want to see, it is at:
	https://mchehab.fedorapeople.org/media.pdf

on page 623.

There is one additional issue on LaTeX output: it numbered the
document on a very different way than on html. Also, it has just one
TOC. This is very bad, because, as we had to manually numerate
figures, their number/names look weird on LaTeX output.

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

Em Sat, 20 Aug 2016 09:51:57 -0300
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:

> Em Fri, 19 Aug 2016 17:52:07 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 
> > Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@intel.com>:
> >   
> > > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:    
> > >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@lwn.net>:
> > >> * the pdf goes to the "latex" folder .. since this is WIP
> > >>  and there are different solutions conceivable ... I left
> > >>  it open for the first.    
> > > 
> > > Mea culpa. As I said, I intended my patches as RFC only.    
> > 
> > I think this is OK for the first. I thought that we first
> > let finish Mauro's task on making the media PDF and after
> > this we decide how move from the latex folder to a pdf folder
> > (one solution see below).  
> 
> Finished handling all tables. I'm sending the last 2 patches
> right now. Now, all tables fit into the page margins. Yet, I
> suspect that flat-table extension causes some troubles when cspan
> is used for LaTeX. It would be good if Markus could double check them.
> 
> There are just two things that won't fit at the margins of the document:
> 
> 1) included files with long lines. We might put those includes into
> a begingroup and use a smaller font, but IMHO the best is to fix the
> few cases on them, as those lines are very likely violating the 80 column
> limit;
> 
> 2) kernel-doc output for big arguments.
> 
> We have lots of function argument inside several media structs, like
> at:
> 	struct v4l2_subdev_core_ops.
> 
> one of such arguments is this function:
> 
> int (* s_io_pin_config) (struct v4l2_subdev *sd, size_t n,struct v4l2_subdev_io_pin_config *pincfg);
> 
> When kernel-doc generates the Members description, as the above line is
> bigger than 80 columns, it simply truncates its description to:
> 
> 	Members
> 	int (*)(struct v4l2_subdev *sd) log_status callback for VIDIOC_LOG_STATUS ioctl handler code.
> 	int (*)(struct v4l2_subdev *sd,size_t n,struct v4l2_subdev_io_pin_config *pincfg) s_io_pin_con
> 	...
> 
> The LaTeX output for it is:
> 
> 	\textbf{Members}
> 	\begin{description}
> 	\item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd) log\_status}}] \leavevmode
> 	callback for \sphinxcode{VIDIOC\_LOG\_STATUS} ioctl handler code.
> 
> 	\item[{\sphinxcode{int (*)(struct v4l2\_subdev *sd, size\_t n,struct v4l2\_subdev\_io\_pin\_config *pincfg) s\_io\_pin\_config}}] \leavevmode
> 	configure one or more chip I/O pins for chips that
> 	multiplex different internal signal pads out to IO pins.  This function
> 	takes a pointer to an array of `n' pin configuration entries, one for
> 	each pin being configured.  This function could be called at times
> 	other than just subdevice initialization.
> 
> It seems that \sphinxcode{} doesn't allow line breaks. Maybe we can
> override it via conf.py. I'll play with it and see if I can find a
> solution. Yet, this could have side effects on other places.
> 
> Any suggestions about how to fix it?

The problem is actually because Sphinx uses item[], with doesn't split
into multiple lines. Doing something like:
	\\DeclareRobustCommand{\\sphinxcode}[1]{\\begin{minipage}{\\columnwidth}\\texttt{#1}\\end{minipage}}

Could fix, but, after sleeping into it, I think that the problem is actually
at the way the kernel-doc is output.

Right now, for a struct, it produces the following output:

	.. c:type:: struct v4l2_prio_state

	   stores the priority states

	**Definition**

	::

	  struct v4l2_prio_state {
	    atomic_t prios[4];
	  };

	**Members**

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

Putting everything inside `` is the culprit for having a very big line
there.

Also, IMHO, the best would be to output it on a different way, like:

**Members**

``prios[4]``
  type: ``atomic_t``

  array with elements to store the array priorities

In order to highlight what really matters: the member name. The type
is a secondary information. Also, it is "hidden" in the middle of a
long string in the case of function parameters. The order for function
parameters is also counter-intuitive, as struct member like:

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

Is currently shown as:

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

With sounds weird, at least to my eyes. Also, if the line is too big,
on PDF output, the member name will be missed, with is very bad.

So, I think that the best solution here is to actually patch
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.
Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.

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

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

	Foo
	   bar

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

	**Foo**
	   bar


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

	**Foo** bar


By starting the second line with a dash, both HTML and LaTeX output
will do the same thing.

I'm sending the patch for kernel-doc script in a few.

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