linux-kernel - Re: [PATCH] doc: memory-barriers: reStructure Text

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]

Message-Id: <9DBB839D-975D-4E45-A4E2-A8010A55D361@darmarit.de>
Date:   Thu, 4 Jan 2018 11:27:55 +0100
From:   Markus Heiser <markus.heiser@...marit.de>
To:     afzal mohammed <afzal.mohd.ma@...il.com>
Cc:     Boqun Feng <boqun.feng@...il.com>, linux-kernel@...r.kernel.org,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        "Paul E. McKenney" <paulmck@...ux.vnet.ibm.com>,
        Will Deacon <will.deacon@....com>,
        Ingo Molnar <mingo@...nel.org>,
        Peter Zijlstra <peterz@...radead.org>,
        Stan Drozd <drozdziak1@...il.com>,
        Palmer Dabbelt <palmer@...belt.com>,
        Mauro Carvalho Chehab <mchehab@...nel.org>,
        Jonathan Corbet <corbet@....net>
Subject: Re: [PATCH] doc: memory-barriers: reStructure Text


> Am 04.01.2018 um 04:59 schrieb afzal mohammed <afzal.mohd.ma@...il.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@...radead.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 --