Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]

[tsd@tsdye.com (Thomas S. Dye)]

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