From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S935513AbcJXI0v (ORCPT <rfc822;w@1wt.eu>);
        Mon, 24 Oct 2016 04:26:51 -0400
Received: from s3.sipsolutions.net ([5.9.151.49]:49336 "EHLO sipsolutions.net"
        rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP
        id S935047AbcJXI0s (ORCPT <rfc822;linux-kernel@vger.kernel.org>);
        Mon, 24 Oct 2016 04:26:48 -0400
Message-ID: <1477297596.4085.10.camel@sipsolutions.net>
Subject: Re: The downside of math::
From: Johannes Berg <johannes@sipsolutions.net>
To: Jani Nikula <jani.nikula@linux.intel.com>,
        Markus Heiser <markus.heiser@darmarit.de>,
        Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
        LKML Mailing List <linux-kernel@vger.kernel.org>,
        linux-doc@vger.kernel.org
Date: Mon, 24 Oct 2016 10:26:36 +0200
In-Reply-To: <874m42p35u.fsf@intel.com>
References: <20161019170246.339eff9d@lwn.net>
         <20161019222618.154434f3@vento.lan> <877f93qdd2.fsf@intel.com>
         <20161021153806.5c9b5d7b@lwn.net>
         <3D1565DE-2513-4326-9FFC-6DF713238B51@darmarit.de>
         <1477295547.4085.8.camel@sipsolutions.net> <874m42p35u.fsf@intel.com>
Content-Type: text/plain; charset="UTF-8"
X-Mailer: Evolution 3.20.5-1 
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org


> I'd like to refine: Do not add non-trivial hard dependencies. Do not
> add dependencies the lack of which make large parts of generated
> documentation useless.
> 
> Graceful degradation on unmet dependencies is the key here. 

Agree.

> Give a build
> warn about missing dependencies. Try to do something sensible without
> the dependency. For extension directives, all else failing, embed the
> raw directive block contents using in the output, possibly
> accompanied
> by a reStructuredText admonition block [1]. For the math and diagram
> directives, I think this would work just fine.

All of that would be easy to achieve with something like the dummy
plugin I posted the other day :)


But yes, I also agree that we shouldn't add any dependencies where the
input isn't suitable as a fallback, since that also means that the
input is going to be difficult to read and write in the source, which
should remain a reasonable way to read things as well.

johannes