Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\))
Subject: Re: make xmldocs failed with error after 4.17 merge period
From:   Markus Heiser <markus.heiser@darmarit.de>
In-Reply-To: <20180406091126.GC21589@kuha.fi.intel.com>
Date:   Fri, 6 Apr 2018 12:03:55 +0200
Cc:     Greg KH <gregkh@linuxfoundation.org>,
        Masanari Iida <standby24x7@gmail.com>,
        linux-kernel@vger.kernel.org,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        Jonathan Corbet <corbet@lwn.net>, linux-usb@vger.kernel.org
Content-Transfer-Encoding: 8BIT
Message-Id: <2A917B38-AFF6-44DC-A4A9-796B2BE560E2@darmarit.de>
References: <CALLJCT0MFg6b+dG50cqe_hv6hxmQDj-ZM066BOtQt_wOiC8ENA@mail.gmail.com>
 <20180406075109.GA21589@kuha.fi.intel.com> <20180406075734.GA16728@kroah.com>
 <20180406081555.GB21589@kuha.fi.intel.com> <20180406083010.GA20174@kroah.com>
 <20180406091126.GC21589@kuha.fi.intel.com>
To:     Heikki Krogerus <heikki.krogerus@linux.intel.com>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk


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