Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752736AbeADK2N convert rfc822-to-8bit (ORCPT + 1 other); Thu, 4 Jan 2018 05:28:13 -0500 Received: from smtp1.goneo.de ([85.220.129.30]:53162 "EHLO smtp1.goneo.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752467AbeADK2L (ORCPT ); Thu, 4 Jan 2018 05:28:11 -0500 Content-Type: text/plain; charset=utf-8 Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\)) Subject: Re: [PATCH] doc: memory-barriers: reStructure Text From: Markus Heiser In-Reply-To: <20180104035948.GB3782@afzalpc> Date: Thu, 4 Jan 2018 11:27:55 +0100 Cc: Boqun Feng , linux-kernel@vger.kernel.org, Linux Doc Mailing List , "Paul E. McKenney" , Will Deacon , Ingo Molnar , Peter Zijlstra , Stan Drozd , Palmer Dabbelt , Mauro Carvalho Chehab , Jonathan Corbet Content-Transfer-Encoding: 8BIT Message-Id: <9DBB839D-975D-4E45-A4E2-A8010A55D361@darmarit.de> References: <20180103093436.16704-1-afzal.mohd.ma@gmail.com> <20180104014850.GB31392@tardis> <20180104035948.GB3782@afzalpc> To: afzal mohammed X-Mailer: Apple Mail (2.3273) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: > Am 04.01.2018 um 04:59 schrieb afzal mohammed : > > 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 : > > 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 --