linux-kernel - Re: make xmldocs failed with error after 4.17 merge period

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Fri, 6 Apr 2018 12:03:55 +0200
From:   Markus Heiser <markus.heiser@...marit.de>
To:     Heikki Krogerus <heikki.krogerus@...ux.intel.com>
Cc:     Greg KH <gregkh@...uxfoundation.org>,
        Masanari Iida <standby24x7@...il.com>,
        linux-kernel@...r.kernel.org,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Jonathan Corbet <corbet@....net>, linux-usb@...r.kernel.org
Subject: Re: make xmldocs failed with error after 4.17 merge period


> Am 06.04.2018 um 11:11 schrieb Heikki Krogerus <heikki.krogerus@...ux.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 --