From mboxrd@z Thu Jan 1 00:00:00 1970 From: tsd@tsdye.com (Thomas S. Dye) Subject: Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)] Date: Tue, 23 Aug 2011 21:22:32 -1000 Message-ID: References: <87pqjwfb0b.fsf@gmail.com> <87bovgf7tc.fsf@gmail.com> <87sjosxft3.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([140.186.70.92]:44187) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qw7nQ-0007GF-Kj for emacs-orgmode@gnu.org; Wed, 24 Aug 2011 03:22:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Qw7nP-0007sZ-A0 for emacs-orgmode@gnu.org; Wed, 24 Aug 2011 03:22:44 -0400 Received: from oproxy6-pub.bluehost.com ([67.222.54.6]:60856) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1Qw7nO-0007qq-Uj for emacs-orgmode@gnu.org; Wed, 24 Aug 2011 03:22:43 -0400 In-Reply-To: (=?utf-8?Q?=22Andr?= =?utf-8?Q?=C3=A1s?= Major"'s message of "Wed, 24 Aug 2011 06:35:10 +0000 (UTC)") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: =?utf-8?Q?Andr=C3=A1s?= Major Cc: emacs-orgmode@gnu.org Andr=C3=A1s Major writes: > Hi Tom, > >> > To me, the documentation is the leading specification of a piece of >> > software. Anything the software doesn't do that is in the docs is a >> > bug, but likewise anything it does do which the docs don't cover is >> > also a bug. >>=20 >> Aloha Andras, >>=20 >> As an avocational programmer who has had the pleasure of making small >> changes to the Org-mode manual and on-line documentation, this last bit >> seems to raise the bar impractically high. Part of Org-mode's appeal to >> me is that people frequently find new, and at least to me unexpected, >> ways to use it productively. I find it interesting to see how best to >> change the documentation to incorporate the new "discovery." That said, >> the idea that the docs cover *everything* that Org-mode is capable of >> doing is wonderful and I'll be happy to chip in when I can to help you >> achieve that goal. > > I fully agree with you, but it looks like I didn't express my point > clearly enough. I'm talking about very particular behaviour when, for > instance, a certain keyword is encountered. The example in this bug > report is a good illustration: if the tag :noexport: is only supposed > to work in headlines, then I consider it a bug if it works elsewhere, > so the developers must actually make sure that this never happens. > > Otherwise, an unsuspecting new user (like myself) reads the > documentation, and accidentally tries the tag on something other than > what's in the documentation. "Hooray, it works, and what a great > piece of software this is" -- but that doesn't last long since a newer > version of org-mode behaves differently and his undocumented and > unintended "feature" no longer works. As a software user (in this > case), I want to have a clear idea of what works and what doesn't, and > if I try something and it works, I suppose it to be an official way of > doing it. Had I not filed this bug report, I might have carried on > using :noexport: on tables until, one day, suddenly all my documents > break because this "feature" silently goes away. > > By saying that a "feature" must work if and only if it is so > documented I refer to individual features (such as keywords, tags, > keystrokes, etc.), not use cases. > > Andr=C3=A1s > > > Aloha Andras, I think I understand. Would it suffice to add this disclaimer to the documentation for starters? "Features used in ways not explicitly documented here cannot be guaranteed future support." I agree with you that the documentation can be improved. I think it is good now, but look forward to working with you when I can to make it better. All the best, Tom --=20 Thomas S. Dye http://www.tsdye.com