make xmldocs failed with error after 4.17 merge period

make xmldocs failed with error after 4.17 merge period

[Masanari Iida]

After merge following patch during 4.17 merger period,
make xmldocs start to fail with error.

 [bdecb33af34f79cbfbb656661210f77c8b8b5b5f]
usb: typec: API for controlling USB Type-C Multiplexers

Error messages.
reST markup error:
/home/iida/Repo/linux-2.6/Documentation/driver-api/usb/typec.rst:215:
(SEVERE/4) Unexpected section title or transition.

------------------------
Documentation/Makefile:93: recipe for target 'xmldocs' failed
make[1]: *** [xmldocs] Error 1
Makefile:1527: recipe for target 'xmldocs' failed
make: *** [xmldocs] Error 2

$

An ascii graphic in typec.rst cause the error.

Masanari Iida

Re: make xmldocs failed with error after 4.17 merge period

[Heikki Krogerus]

On Fri, Apr 06, 2018 at 12:38:42PM +0900, Masanari Iida wrote:
> After merge following patch during 4.17 merger period,
> make xmldocs start to fail with error.
> 
>  [bdecb33af34f79cbfbb656661210f77c8b8b5b5f]
> usb: typec: API for controlling USB Type-C Multiplexers
> 
> Error messages.
> reST markup error:
> /home/iida/Repo/linux-2.6/Documentation/driver-api/usb/typec.rst:215:
> (SEVERE/4) Unexpected section title or transition.
> 
> ------------------------
> Documentation/Makefile:93: recipe for target 'xmldocs' failed
> make[1]: *** [xmldocs] Error 1
> Makefile:1527: recipe for target 'xmldocs' failed
> make: *** [xmldocs] Error 2
> 
> $
> 
> An ascii graphic in typec.rst cause the error.

Thanks for the report. I'm going to propose that we fix this by
marking the ascii art as comment:

diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
index feb31946490b..972c11bf4141 100644
--- a/Documentation/driver-api/usb/typec.rst
+++ b/Documentation/driver-api/usb/typec.rst
@@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those.

 Illustration of the muxes behind a connector that supports an alternate mode:

-                     ------------------------
+..                   ------------------------
                      |       Connector      |
                      ------------------------
                             |         |

I hope that works.


Br,

-- 
heikki

Re: make xmldocs failed with error after 4.17 merge period

[Greg KH]

On Fri, Apr 06, 2018 at 10:51:09AM +0300, Heikki Krogerus wrote:
> On Fri, Apr 06, 2018 at 12:38:42PM +0900, Masanari Iida wrote:
> > After merge following patch during 4.17 merger period,
> > make xmldocs start to fail with error.
> > 
> >  [bdecb33af34f79cbfbb656661210f77c8b8b5b5f]
> > usb: typec: API for controlling USB Type-C Multiplexers
> > 
> > Error messages.
> > reST markup error:
> > /home/iida/Repo/linux-2.6/Documentation/driver-api/usb/typec.rst:215:
> > (SEVERE/4) Unexpected section title or transition.
> > 
> > ------------------------
> > Documentation/Makefile:93: recipe for target 'xmldocs' failed
> > make[1]: *** [xmldocs] Error 1
> > Makefile:1527: recipe for target 'xmldocs' failed
> > make: *** [xmldocs] Error 2
> > 
> > $
> > 
> > An ascii graphic in typec.rst cause the error.
> 
> Thanks for the report. I'm going to propose that we fix this by
> marking the ascii art as comment:
> 
> diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
> index feb31946490b..972c11bf4141 100644
> --- a/Documentation/driver-api/usb/typec.rst
> +++ b/Documentation/driver-api/usb/typec.rst
> @@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those.
> 
>  Illustration of the muxes behind a connector that supports an alternate mode:
> 
> -                     ------------------------
> +..                   ------------------------
>                       |       Connector      |
>                       ------------------------
>                              |         |
> 
> I hope that works.

Try it and see!  :)

Re: make xmldocs failed with error after 4.17 merge period

[Heikki Krogerus]

On Fri, Apr 06, 2018 at 09:57:34AM +0200, Greg KH wrote:
> On Fri, Apr 06, 2018 at 10:51:09AM +0300, Heikki Krogerus wrote:
> > On Fri, Apr 06, 2018 at 12:38:42PM +0900, Masanari Iida wrote:
> > > After merge following patch during 4.17 merger period,
> > > make xmldocs start to fail with error.
> > > 
> > >  [bdecb33af34f79cbfbb656661210f77c8b8b5b5f]
> > > usb: typec: API for controlling USB Type-C Multiplexers
> > > 
> > > Error messages.
> > > reST markup error:
> > > /home/iida/Repo/linux-2.6/Documentation/driver-api/usb/typec.rst:215:
> > > (SEVERE/4) Unexpected section title or transition.
> > > 
> > > ------------------------
> > > Documentation/Makefile:93: recipe for target 'xmldocs' failed
> > > make[1]: *** [xmldocs] Error 1
> > > Makefile:1527: recipe for target 'xmldocs' failed
> > > make: *** [xmldocs] Error 2
> > > 
> > > $
> > > 
> > > An ascii graphic in typec.rst cause the error.
> > 
> > Thanks for the report. I'm going to propose that we fix this by
> > marking the ascii art as comment:
> > 
> > diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
> > index feb31946490b..972c11bf4141 100644
> > --- a/Documentation/driver-api/usb/typec.rst
> > +++ b/Documentation/driver-api/usb/typec.rst
> > @@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those.
> > 
> >  Illustration of the muxes behind a connector that supports an alternate mode:
> > 
> > -                     ------------------------
> > +..                   ------------------------
> >                       |       Connector      |
> >                       ------------------------
> >                              |         |
> > 
> > I hope that works.
> 
> Try it and see!  :)

It will fix this issue. I was just wondering if use of ascii art is
acceptable in general with the .rst files? But then again, why
wouldn't it be.

Sorry for the noise. I'll just send that patch.


Thanks,

-- 
heikki

Re: make xmldocs failed with error after 4.17 merge period

[Greg KH]

On Fri, Apr 06, 2018 at 11:15:55AM +0300, Heikki Krogerus wrote:
> On Fri, Apr 06, 2018 at 09:57:34AM +0200, Greg KH wrote:
> > On Fri, Apr 06, 2018 at 10:51:09AM +0300, Heikki Krogerus wrote:
> > > On Fri, Apr 06, 2018 at 12:38:42PM +0900, Masanari Iida wrote:
> > > > After merge following patch during 4.17 merger period,
> > > > make xmldocs start to fail with error.
> > > > 
> > > >  [bdecb33af34f79cbfbb656661210f77c8b8b5b5f]
> > > > usb: typec: API for controlling USB Type-C Multiplexers
> > > > 
> > > > Error messages.
> > > > reST markup error:
> > > > /home/iida/Repo/linux-2.6/Documentation/driver-api/usb/typec.rst:215:
> > > > (SEVERE/4) Unexpected section title or transition.
> > > > 
> > > > ------------------------
> > > > Documentation/Makefile:93: recipe for target 'xmldocs' failed
> > > > make[1]: *** [xmldocs] Error 1
> > > > Makefile:1527: recipe for target 'xmldocs' failed
> > > > make: *** [xmldocs] Error 2
> > > > 
> > > > $
> > > > 
> > > > An ascii graphic in typec.rst cause the error.
> > > 
> > > Thanks for the report. I'm going to propose that we fix this by
> > > marking the ascii art as comment:
> > > 
> > > diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
> > > index feb31946490b..972c11bf4141 100644
> > > --- a/Documentation/driver-api/usb/typec.rst
> > > +++ b/Documentation/driver-api/usb/typec.rst
> > > @@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those.
> > > 
> > >  Illustration of the muxes behind a connector that supports an alternate mode:
> > > 
> > > -                     ------------------------
> > > +..                   ------------------------
> > >                       |       Connector      |
> > >                       ------------------------
> > >                              |         |
> > > 
> > > I hope that works.
> > 
> > Try it and see!  :)
> 
> It will fix this issue. I was just wondering if use of ascii art is
> acceptable in general with the .rst files? But then again, why
> wouldn't it be.

There are ways to do this, look at how the v4l2 and I think the drm
subsystems handle ascii art such that "real" drawings end up being
produced.

thanks,

greg k-h

Re: make xmldocs failed with error after 4.17 merge period

[Heikki Krogerus]

On Fri, Apr 06, 2018 at 10:30:10AM +0200, Greg KH wrote:
> On Fri, Apr 06, 2018 at 11:15:55AM +0300, Heikki Krogerus wrote:
> > On Fri, Apr 06, 2018 at 09:57:34AM +0200, Greg KH wrote:
> > > On Fri, Apr 06, 2018 at 10:51:09AM +0300, Heikki Krogerus wrote:
> > > > On Fri, Apr 06, 2018 at 12:38:42PM +0900, Masanari Iida wrote:
> > > > > After merge following patch during 4.17 merger period,
> > > > > make xmldocs start to fail with error.
> > > > > 
> > > > >  [bdecb33af34f79cbfbb656661210f77c8b8b5b5f]
> > > > > usb: typec: API for controlling USB Type-C Multiplexers
> > > > > 
> > > > > Error messages.
> > > > > reST markup error:
> > > > > /home/iida/Repo/linux-2.6/Documentation/driver-api/usb/typec.rst:215:
> > > > > (SEVERE/4) Unexpected section title or transition.
> > > > > 
> > > > > ------------------------
> > > > > Documentation/Makefile:93: recipe for target 'xmldocs' failed
> > > > > make[1]: *** [xmldocs] Error 1
> > > > > Makefile:1527: recipe for target 'xmldocs' failed
> > > > > make: *** [xmldocs] Error 2
> > > > > 
> > > > > $
> > > > > 
> > > > > An ascii graphic in typec.rst cause the error.
> > > > 
> > > > Thanks for the report. I'm going to propose that we fix this by
> > > > marking the ascii art as comment:
> > > > 
> > > > diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
> > > > index feb31946490b..972c11bf4141 100644
> > > > --- a/Documentation/driver-api/usb/typec.rst
> > > > +++ b/Documentation/driver-api/usb/typec.rst
> > > > @@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those.
> > > > 
> > > >  Illustration of the muxes behind a connector that supports an alternate mode:
> > > > 
> > > > -                     ------------------------
> > > > +..                   ------------------------
> > > >                       |       Connector      |
> > > >                       ------------------------
> > > >                              |         |
> > > > 
> > > > I hope that works.
> > > 
> > > Try it and see!  :)
> > 
> > It will fix this issue. I was just wondering if use of ascii art is
> > acceptable in general with the .rst files? But then again, why
> > wouldn't it be.
> 
> There are ways to do this, look at how the v4l2 and I think the drm
> subsystems handle ascii art such that "real" drawings end up being
> produced.

Thanks. I did not actually find anything else except use of tables and
code-blocks in v4l documentation. Is that what you were referring?

I was propsed to use something called "Literal Block" with ascii art.
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks

Unless you object, that's what I will use.


Thanks,

-- 
heikki

Re: make xmldocs failed with error after 4.17 merge period

[Markus Heiser]

> Am 06.04.2018 um 11:11 schrieb Heikki Krogerus <heikki.krogerus@linux.intel.com>:
[...]

>>>>>> An ascii graphic in typec.rst cause the error.
>>>>> 
>>>>> Thanks for the report. I'm going to propose that we fix this by
>>>>> marking the ascii art as comment:
>>>>> 
>>>>> diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
>>>>> index feb31946490b..972c11bf4141 100644
>>>>> --- a/Documentation/driver-api/usb/typec.rst
>>>>> +++ b/Documentation/driver-api/usb/typec.rst
>>>>> @@ -212,7 +212,7 @@ port drivers can use USB Role Class API with those.
>>>>> 
>>>>> Illustration of the muxes behind a connector that supports an alternate mode:
>>>>> 
>>>>> -                     ------------------------
>>>>> +..                   ------------------------
>>>>>                     |       Connector      |
>>>>>                     ------------------------
>>>>>                            |         |
>>>>> 
>>>>> I hope that works.
>>>> 
>>>> Try it and see!  :)
>>> 
>>> It will fix this issue. I was just wondering if use of ascii art is
>>> acceptable in general with the .rst files? But then again, why
>>> wouldn't it be.

[...]

> I was propsed to use something called "Literal Block" with ascii art.
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks

about *ASCII-art*: see fix from Jani ...

 https://www.mail-archive.com/linux-doc@vger.kernel.org/msg19302.html

where the '::' is a short-markup for a literal-block.


>> There are ways to do this, look at how the v4l2 and I think the drm
>> subsystems handle ascii art such that "real" drawings end up being
>> produced.
> 
> Thanks. I did not actually find anything else except use of tables and
> code-blocks in v4l documentation. Is that what you were referring?

If it is about *figures*: we have a directive named 'kernel-figure',
which is a full replacement of the 'figure' directive from Sphinx-Doc.
In addition it supports *inline* SVG and DOT markups. Read:

 https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#figures-images

-- Markus --

Re: make xmldocs failed with error after 4.17 merge period

[Heikki Krogerus]

Hi Markus,

On Fri, Apr 06, 2018 at 12:03:55PM +0200, Markus Heiser wrote:
> >> There are ways to do this, look at how the v4l2 and I think the drm
> >> subsystems handle ascii art such that "real" drawings end up being
> >> produced.
> > 
> > Thanks. I did not actually find anything else except use of tables and
> > code-blocks in v4l documentation. Is that what you were referring?
> 
> If it is about *figures*: we have a directive named 'kernel-figure',
> which is a full replacement of the 'figure' directive from Sphinx-Doc.
> In addition it supports *inline* SVG and DOT markups. Read:
> 
>  https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#figures-images

Thanks for the info.

I don't want to use for example dot language in kernel documentation.
I want to be able to clearly see the figure also from the plain text
file. That's why I prefer ascii art.

Isn't there a way we could render ascii art as svg diagram?


Br,

-- 
heikki

Re: make xmldocs failed with error after 4.17 merge period

[Markus Heiser]

> Am 06.04.2018 um 12:51 schrieb Heikki Krogerus <heikki.krogerus@linux.intel.com>:
> 
> Hi Markus,
> 
> On Fri, Apr 06, 2018 at 12:03:55PM +0200, Markus Heiser wrote:
>>>> There are ways to do this, look at how the v4l2 and I think the drm
>>>> subsystems handle ascii art such that "real" drawings end up being
>>>> produced.
>>> 
>>> Thanks. I did not actually find anything else except use of tables and
>>> code-blocks in v4l documentation. Is that what you were referring?
>> 
>> If it is about *figures*: we have a directive named 'kernel-figure',
>> which is a full replacement of the 'figure' directive from Sphinx-Doc.
>> In addition it supports *inline* SVG and DOT markups. Read:
>> 
>> https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#figures-images
> 
> Thanks for the info.
> 
> I don't want to use for example dot language in kernel documentation.
> I want to be able to clearly see the figure also from the plain text
> file. That's why I prefer ascii art.
> 
> Isn't there a way we could render ascii art as svg diagram?

Sorry, not yet. Johannes started a discussion about this. Its a long
time ago and I do not have any new ideas yet :/ see:

  https://www.mail-archive.com/linux-doc@vger.kernel.org/msg07035.html

-- Markus --

Re: make xmldocs failed with error after 4.17 merge period

[Johannes Berg]

On Fri, 2018-04-06 at 13:38 +0200, Markus Heiser wrote:
> 
> Sorry, not yet. Johannes started a discussion about this. Its a long
> time ago and I do not have any new ideas yet :/ see:
> 
>   https://www.mail-archive.com/linux-doc@vger.kernel.org/msg07035.html

I still think the tools themselves don't matter all that much, as long
as there aren't totally onerous requirements. I'd argue pretty much
everything available on a modern distro would be OK provided we have a
reasonable fallback (e.g. to ASCII as I had even written), along with
some sort of documentation of dependencies, or perhaps better, some
command line option to gather the info dynamically.

But then again, I've already said pretty much this a year and a half ago
and most people seemed more interested in some kind of purity argument
than having better documentation :-)

johannes