* make xmldocs failed with error after 4.17 merge period @ 2018-04-06 3:38 Masanari Iida 2018-04-06 7:51 ` Heikki Krogerus 0 siblings, 1 reply; 10+ messages in thread From: Masanari Iida @ 2018-04-06 3:38 UTC (permalink / raw) To: linux-kernel, linux-doc, Jonathan Corbet, heikki.krogerus, Greg KH, linux-usb 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 3:38 make xmldocs failed with error after 4.17 merge period Masanari Iida @ 2018-04-06 7:51 ` Heikki Krogerus 2018-04-06 7:57 ` Greg KH 0 siblings, 1 reply; 10+ messages in thread From: Heikki Krogerus @ 2018-04-06 7:51 UTC (permalink / raw) To: Masanari Iida Cc: linux-kernel, linux-doc, Jonathan Corbet, Greg KH, linux-usb 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 7:51 ` Heikki Krogerus @ 2018-04-06 7:57 ` Greg KH 2018-04-06 8:15 ` Heikki Krogerus 0 siblings, 1 reply; 10+ messages in thread From: Greg KH @ 2018-04-06 7:57 UTC (permalink / raw) To: Heikki Krogerus Cc: Masanari Iida, linux-kernel, linux-doc, Jonathan Corbet, linux-usb 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! :) ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 7:57 ` Greg KH @ 2018-04-06 8:15 ` Heikki Krogerus 2018-04-06 8:30 ` Greg KH 0 siblings, 1 reply; 10+ messages in thread From: Heikki Krogerus @ 2018-04-06 8:15 UTC (permalink / raw) To: Greg KH Cc: Masanari Iida, linux-kernel, linux-doc, Jonathan Corbet, linux-usb 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 8:15 ` Heikki Krogerus @ 2018-04-06 8:30 ` Greg KH 2018-04-06 9:11 ` Heikki Krogerus 0 siblings, 1 reply; 10+ messages in thread From: Greg KH @ 2018-04-06 8:30 UTC (permalink / raw) To: Heikki Krogerus Cc: Masanari Iida, linux-kernel, linux-doc, Jonathan Corbet, linux-usb 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 8:30 ` Greg KH @ 2018-04-06 9:11 ` Heikki Krogerus 2018-04-06 10:03 ` Markus Heiser 0 siblings, 1 reply; 10+ messages in thread From: Heikki Krogerus @ 2018-04-06 9:11 UTC (permalink / raw) To: Greg KH Cc: Masanari Iida, linux-kernel, linux-doc, Jonathan Corbet, linux-usb 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 9:11 ` Heikki Krogerus @ 2018-04-06 10:03 ` Markus Heiser 2018-04-06 10:51 ` Heikki Krogerus 0 siblings, 1 reply; 10+ messages in thread From: Markus Heiser @ 2018-04-06 10:03 UTC (permalink / raw) To: Heikki Krogerus Cc: Greg KH, Masanari Iida, linux-kernel, Linux Doc Mailing List, Jonathan Corbet, linux-usb > 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 -- ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 10:03 ` Markus Heiser @ 2018-04-06 10:51 ` Heikki Krogerus 2018-04-06 11:38 ` Markus Heiser 0 siblings, 1 reply; 10+ messages in thread From: Heikki Krogerus @ 2018-04-06 10:51 UTC (permalink / raw) To: Markus Heiser Cc: Greg KH, Masanari Iida, linux-kernel, Linux Doc Mailing List, Jonathan Corbet, linux-usb 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 10:51 ` Heikki Krogerus @ 2018-04-06 11:38 ` Markus Heiser 2018-04-07 19:19 ` Johannes Berg 0 siblings, 1 reply; 10+ messages in thread From: Markus Heiser @ 2018-04-06 11:38 UTC (permalink / raw) To: Heikki Krogerus, johannes Cc: Greg KH, Masanari Iida, LKML, Linux Doc Mailing List, Jonathan Corbet, linux-usb > 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 -- ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: make xmldocs failed with error after 4.17 merge period 2018-04-06 11:38 ` Markus Heiser @ 2018-04-07 19:19 ` Johannes Berg 0 siblings, 0 replies; 10+ messages in thread From: Johannes Berg @ 2018-04-07 19:19 UTC (permalink / raw) To: Markus Heiser, Heikki Krogerus Cc: Greg KH, Masanari Iida, LKML, Linux Doc Mailing List, Jonathan Corbet, linux-usb 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2018-04-07 19:19 UTC | newest] Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2018-04-06 3:38 make xmldocs failed with error after 4.17 merge period Masanari Iida 2018-04-06 7:51 ` Heikki Krogerus 2018-04-06 7:57 ` Greg KH 2018-04-06 8:15 ` Heikki Krogerus 2018-04-06 8:30 ` Greg KH 2018-04-06 9:11 ` Heikki Krogerus 2018-04-06 10:03 ` Markus Heiser 2018-04-06 10:51 ` Heikki Krogerus 2018-04-06 11:38 ` Markus Heiser 2018-04-07 19:19 ` Johannes Berg
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).