Date: Fri, 5 Jan 2018 09:22:45 +0530
From: afzal mohammed <afzal.mohd.ma@gmail.com>
To: Markus Heiser <markus.heiser@darmarit.de>
Cc: Boqun Feng <boqun.feng@gmail.com>, linux-kernel@vger.kernel.org,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>,
        Will Deacon <will.deacon@arm.com>,
        Ingo Molnar <mingo@kernel.org>,
        Peter Zijlstra <peterz@infradead.org>,
        Stan Drozd <drozdziak1@gmail.com>,
        Palmer Dabbelt <palmer@dabbelt.com>,
        Mauro Carvalho Chehab <mchehab@kernel.org>,
        Jonathan Corbet <corbet@lwn.net>
Subject: Re: [PATCH] doc: memory-barriers: reStructure Text
Message-ID: <20180105035245.GA6780@afzalpc>
References: <20180103093436.16704-1-afzal.mohd.ma@gmail.com>
 <20180104014850.GB31392@tardis>
 <20180104035948.GB3782@afzalpc>
 <9DBB839D-975D-4E45-A4E2-A8010A55D361@darmarit.de>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <9DBB839D-975D-4E45-A4E2-A8010A55D361@darmarit.de>
User-Agent: Mutt/1.5.24 (2015-08-30)
Sender: linux-kernel-owner@vger.kernel.org

Hi,

On Thu, Jan 04, 2018 at 11:27:55AM +0100, Markus Heiser wrote:

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

Thanks for the details.

> I really like them

Initially i was sceptical of rst & once instead of hitting the fly,
hit "make htmldocs" on the keyboard :), and the opinion about it was
changed. It was easy to navigate through various docs & the realized
that various topics (& many) were present (yes, it was there earlier
also, but had to dive inside Documentation & search, while viewing the
toplevel index.html made them standout). It was like earlier you had
to go after docs, but now it was docs coming after you, that is my
opinion.

Later while fighting with memory-barriers.txt, felt that it might be
good for it as well as to be in that company.

And the readability as a text is not hurt as well.

It was thought that rst conversion could be done quickly, but since
this was my first attempt with rst, had to put some effort to get a
not so bad output, even if this patch dies, i am happy to have learnt
rst conversion to some extent.

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

When one of the author of the original document objected, i felt it is
better to backoff. But if there is a consensus, i will proceed.

afzal