lkml.org 
[lkml]   [2018]   [Jan]   [4]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH] doc: memory-barriers: reStructure Text
From
Date

> Am 04.01.2018 um 04:59 schrieb afzal mohammed <afzal.mohd.ma@gmail.com>:
>
> Hi,
>
> On Thu, Jan 04, 2018 at 09:48:50AM +0800, Boqun Feng wrote:
>
>>> The location chosen is "Documentation/kernel-hacking", i was unsure
>>> where this should reside & there was no .rst file in top-level directory
>>> "Documentation", so put it into one of the existing folder that seemed
>>> to me as not that unsuitable.
>>>
>>> Other files refer to memory-barrier.txt, those also needs to be
>>> adjusted based on where .rst can reside.
>
>> How do you plan to handle the external references? For example, the
>> following LWN articles has a link this file:
>>
>> https://lwn.net/Articles/718628/
>>
>> And changing the name and/or location will break that link, AFAIK.
>
> If necessary to handle these, symlink might help here i believe.

IMO symlinks are mostly ending in a mess, URLs are never stable.
There is a

https://www.kernel.org/doc/html/latest/objects.inv

to handle such requirements. Take a look at *intersphinx* :

http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

to see how it works: Each Sphinx HTML build creates a file named objects.inv that
contains a mapping from object names to URIs relative to the HTML set’s root.

This means articles from external (like lwn articles) has to be recompiled.
Not perfect, but a first solution.

> Am 04.01.2018 um 00:48 schrieb Peter Zijlstra <peterz@infradead.org>:
>
> So I hate this rst crap with a passion, so NAK from me.

I really like them, factually valuable comments .. please
express your concern so that we have a chance to move on.

> Upon trying to understand memory-barriers.txt, i felt that it might be
> better to have it in PDF/HTML format, thus attempted to convert it to
> rst. And i see it not being welcomed, hence shelving the conversion.

I think that's a pity.

-- Markus --

\
 
 \ /
  Last update: 2018-01-04 11:28    [W:0.263 / U:0.100 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site