From: tsd@tsdye.com (Thomas S. Dye)
To: "András Major" <andras.g.major@gmail.com>
Cc: emacs-orgmode@gnu.org
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 [thread overview]
Message-ID: <m1wre3z32f.fsf@tsdye.com> (raw)
In-Reply-To: <loom.20110824T082428-852@post.gmane.org> ("András Major"'s message of "Wed, 24 Aug 2011 06:35:10 +0000 (UTC)")
András Major <andras.g.major@gmail.com> 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.
>>
>> Aloha Andras,
>>
>> 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ás
>
>
>
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
--
Thomas S. Dye
http://www.tsdye.com
next prev parent reply other threads:[~2011-08-24 7:22 UTC|newest]
Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-08-23 11:04 Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)] András Major
2011-08-23 11:26 ` Sebastien Vauban
2011-08-23 11:38 ` András Major
2011-08-23 14:23 ` Bastien
2011-08-23 22:35 ` András Major
2011-08-23 14:09 ` Bastien
2011-08-23 14:38 ` Eric Schulte
2011-08-23 15:12 ` András Major
2011-08-23 15:47 ` Eric Schulte
2011-08-23 16:01 ` András Major
2011-08-23 16:18 ` Bastien
2011-08-23 22:44 ` András Major
2011-08-23 23:38 ` Thomas S. Dye
2011-08-24 6:35 ` András Major
2011-08-24 7:22 ` Thomas S. Dye [this message]
2011-08-24 8:28 ` Bastien
2011-08-24 16:41 ` Thomas S. Dye
2011-08-24 8:26 ` Bastien
2011-08-24 8:34 ` Bastien
2011-08-23 17:19 ` Eric Schulte
2011-08-23 22:51 ` András Major
2011-08-23 23:03 ` Nick Dokos
2011-08-23 23:44 ` Eric Schulte
2011-08-24 0:14 ` Thomas S. Dye
2011-08-24 7:41 ` András Major
2011-08-23 16:14 ` Bastien
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m1wre3z32f.fsf@tsdye.com \
--to=tsd@tsdye.com \
--cc=andras.g.major@gmail.com \
--cc=emacs-orgmode@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.