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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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

> Am 19.08.2016 um 14:49 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>:
> 
> > On Fri, 19 Aug 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:  
> >> Am 19.08.2016 um 00:35 schrieb Jonathan Corbet <corbet@xxxxxxx>:
> >> * 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-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux