emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
@ 2011-08-23 11:04 András Major
  2011-08-23 11:26 ` Sebastien Vauban
                   ` (2 more replies)
  0 siblings, 3 replies; 26+ messages in thread
From: András Major @ 2011-08-23 11:04 UTC (permalink / raw)
  To: emacs-orgmode

Hi,

here is an example that delivers an error "reference 'table1' not
found in this buffer" when trying to export to HTML (others not tried
yet):

  #+tblname: table1       :noexport:
  | n | x |  y1 |   y2 |
  |---+---+-----+------|
  | 0 | 1 | 2.0 |  3.0 |
  | 1 | 2 | 2.1 |  2.0 |
  | 2 | 3 | 2.0 |  0.3 |
  | 3 | 4 | 1.0 |  0.6 |
  | 4 | 5 | 1.4 | -0.1 |
  | 5 | 6 | 1.6 |  1.2 |

  #+begin_src gnuplot :file bug_gnuplot.png :var t=table1
    set size square
    plot t u 2:3 w lp, t u 2:4 w lp
  #+end_src

If I remove the :noexport: tag, everything works fine.

Am I doing something wrong here? I don't think that :noexport: should
affect the use of the table for other purposes.

  András





Emacs  : GNU Emacs 23.2.1 (i486-pc-linux-gnu, GTK+ Version 2.20.0)
 of 2010-12-11 on raven, modified by Debian
Package: Org-mode version 7.7 (release_7.7.167.gfceb)

current state:
==============
(setq
 org-export-latex-after-initial-vars-hook '(org-beamer-after-initial-vars)
 org-speed-command-hook '(org-speed-command-default-hook
org-babel-speed-command-hook)
 org-babel-load-languages '((asymptote . t) (ditaa . t) (dot . t)
(gnuplot . t) (haskell . t) (latex . t)
			    (octave . t) (R . t) (ruby . t) (scheme . t) (sh . t))
 org-metaup-hook '(org-babel-load-in-session-maybe)
 org-after-todo-state-change-hook '(org-clock-out-if-current)
 org-babel-tangle-lang-exts '(("ruby" . "rb") ("latex" . "tex")
("haskell" . "hs") ("asymptote" . "asy")
			      ("emacs-lisp" . "el"))
 org-export-blocks-postblock-hook '(org-exp-res/src-name-cleanup)
 org-export-latex-format-toc-function 'org-export-latex-format-toc-default
 org-tab-first-hook '(org-hide-block-toggle-maybe
org-src-native-tab-command-maybe
		      org-babel-hide-result-toggle-maybe)
 org-src-mode-hook '(org-src-babel-configure-edit-buffer
org-src-mode-configure-edit-buffer)
 org-confirm-shell-link-function 'yes-or-no-p
 org-export-first-hook '(org-beamer-initialize-open-trackers)
 org-agenda-before-write-hook '(org-agenda-add-entry-text)
 org-blank-before-new-entry nil
 org-babel-pre-tangle-hook '(save-buffer)
 org-cycle-hook '(org-cycle-hide-archived-subtrees
org-cycle-hide-drawers org-cycle-show-empty-lines
		  org-optimize-window-after-visibility-change)
 org-export-preprocess-before-normalizing-links-hook
'(org-remove-file-link-modifiers)
 org-mode-hook '(#[nil "\300\301\302\303\304$\207"
		   [org-add-hook change-major-mode-hook org-show-block-all append local] 5]
		 #[nil "\300\301\302\303\304$\207"
		   [org-add-hook change-major-mode-hook org-babel-show-result-all
append local] 5]
		 org-babel-result-hide-spec org-babel-hide-all-hashes)
 org-ctrl-c-ctrl-c-hook '(org-babel-hash-at-point
org-babel-execute-safely-maybe)
 org-confirm-elisp-link-function 'yes-or-no-p
 org-export-interblocks '((lob org-babel-exp-lob-one-liners) (src
org-babel-exp-inline-src-blocks))
 org-clock-out-hook '(org-clock-remove-empty-clock-drawer)
 org-occur-hook '(org-first-headline-recenter)
 org-from-is-user-regexp nil
 org-export-preprocess-before-selecting-backend-code-hook
'(org-beamer-select-beamer-code)
 org-confirm-babel-evaluate nil
 org-export-latex-final-hook '(org-beamer-amend-header
org-beamer-fix-toc org-beamer-auto-fragile-frames
			       org-beamer-place-default-actions-for-lists)
 org-metadown-hook '(org-babel-pop-to-session-maybe)
 org-export-blocks '((src org-babel-exp-src-block nil) (comment
org-export-blocks-format-comment t)
		     (ditaa org-export-blocks-format-ditaa nil) (dot
org-export-blocks-format-dot nil))
 )

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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:09 ` Bastien
  2011-08-23 14:38 ` Eric Schulte
  2 siblings, 1 reply; 26+ messages in thread
From: Sebastien Vauban @ 2011-08-23 11:26 UTC (permalink / raw)
  To: emacs-orgmode-mXXj517/zsQ

Hi András & al.,

András Major wrote:
> here is an example that delivers an error "reference 'table1' not
> found in this buffer" when trying to export to HTML (others not tried
> yet):
>
>   #+tblname: table1       :noexport:
>   | n | x |  y1 |   y2 |
>   |---+---+-----+------|
>   | 0 | 1 | 2.0 |  3.0 |
>   | 1 | 2 | 2.1 |  2.0 |
>   | 2 | 3 | 2.0 |  0.3 |
>   | 3 | 4 | 1.0 |  0.6 |
>   | 4 | 5 | 1.4 | -0.1 |
>   | 5 | 6 | 1.6 |  1.2 |
>
>   #+begin_src gnuplot :file bug_gnuplot.png :var t=table1
>     set size square
>     plot t u 2:3 w lp, t u 2:4 w lp
>   #+end_src
>
> If I remove the :noexport: tag, everything works fine.
>
> Am I doing something wrong here? I don't think that :noexport: should
> affect the use of the table for other purposes.

I will let answer the ones who decide on such things. Though, I am amazed you
put a tag on the table itself.

I'd have expected the noexport tag to be on a section containing the table.

So, my extra question (to the same persons) is: is this an allowed use of a
tag? Or just an undocumented feature which temporarily works? -- euh, or not
even works, in fact...

Best regards,
  Seb

-- 
Sebastien Vauban

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 11:26 ` Sebastien Vauban
@ 2011-08-23 11:38   ` András Major
  2011-08-23 14:23     ` Bastien
  0 siblings, 1 reply; 26+ messages in thread
From: András Major @ 2011-08-23 11:38 UTC (permalink / raw)
  To: emacs-orgmode

Hi Sebastian,

> I will let answer the ones who decide on such things. Though, I am amazed you
> put a tag on the table itself.
> 
> I'd have expected the noexport tag to be on a section containing the table.

I forgot to mention in the report that of course I tried that too: if
I place the table and the code in two sections and tag the section
containing the table with :noexport:, the result is exactly the same.
Omitting the tag makes it work again.

> So, my extra question (to the same persons) is: is this an allowed use of a
> tag? Or just an undocumented feature which temporarily works? -- euh, or not
> even works, in fact...

In my little experience, it work, and I think it's a desirable feature
too.  I'm not really keen on creating a section for a table just so
that I can hide it.

  András

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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 14:09 ` Bastien
  2011-08-23 14:38 ` Eric Schulte
  2 siblings, 0 replies; 26+ messages in thread
From: Bastien @ 2011-08-23 14:09 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 849 bytes --]

Hi András,

András Major <andras.g.major@gmail.com> writes:

> here is an example that delivers an error "reference 'table1' not
> found in this buffer" when trying to export to HTML (others not tried
> yet):
>
>   #+tblname: table1       :noexport:
>   | n | x |  y1 |   y2 |
>   |---+---+-----+------|
>   | 0 | 1 | 2.0 |  3.0 |
>   | 1 | 2 | 2.1 |  2.0 |
>   | 2 | 3 | 2.0 |  0.3 |
>   | 3 | 4 | 1.0 |  0.6 |
>   | 4 | 5 | 1.4 | -0.1 |
>   | 5 | 6 | 1.6 |  1.2 |
>
>   #+begin_src gnuplot :file bug_gnuplot.png :var t=table1
>     set size square
>     plot t u 2:3 w lp, t u 2:4 w lp
>   #+end_src
>
> If I remove the :noexport: tag, everything works fine.
>
> Am I doing something wrong here?

Yes -- :noexport: is to be used on headlines only, not on tables.

If you remove the :noexport: you should get the correct png (see
attached.)

HTH,


[-- Attachment #2: bug_gnuplot.png --]
[-- Type: image/png, Size: 5323 bytes --]

[-- Attachment #3: Type: text/plain, Size: 14 bytes --]


-- 
 Bastien

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 11:38   ` András Major
@ 2011-08-23 14:23     ` Bastien
  2011-08-23 22:35       ` András Major
  0 siblings, 1 reply; 26+ messages in thread
From: Bastien @ 2011-08-23 14:23 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

Hi András,

András Major <andras.g.major@gmail.com> writes:

>> I'd have expected the noexport tag to be on a section containing the table.
>
> I forgot to mention in the report that of course I tried that too: if
> I place the table and the code in two sections and tag the section
> containing the table with :noexport:, the result is exactly the same.

I'm not sure I understand -- does it mean that C-cC-c on #+begin_src 
fails in the example below?

,----
| * Headline :noexport:
| 
|   #+tblname: table1
|   | n | x |  y1 |   y2 |
|   |---+---+-----+------|
|   | 0 | 1 | 2.0 |  3.0 |
|   | 1 | 2 | 2.1 |  2.0 |
|   | 2 | 3 | 2.0 |  0.3 |
|   | 3 | 4 | 1.0 |  0.6 |
|   | 4 | 5 | 1.4 | -0.1 |
|   | 5 | 6 | 1.6 |  1.2 |
| 
|   #+begin_src gnuplot :file bug_gnuplot.png :var t=table1
|     set size square
|     plot t u 2:3 w lp, t u 2:4 w lp
|   #+end_src
`----

It works for me.


> In my little experience, it work, and I think it's a desirable feature
> too.  I'm not really keen on creating a section for a table just so
> that I can hide it.

Tags only have meaning on headlines, whether it's for really tagging the
headlines or for (un)selecting them during the export process.  

If we want export-related function specifically for tables, I'd rather 
use something like #+export_table: and a list of options.  

HTH,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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 14:09 ` Bastien
@ 2011-08-23 14:38 ` Eric Schulte
  2011-08-23 15:12   ` András Major
  2 siblings, 1 reply; 26+ messages in thread
From: Eric Schulte @ 2011-08-23 14:38 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

András Major <andras.g.major@gmail.com> writes:

> Hi,
>
> here is an example that delivers an error "reference 'table1' not
> found in this buffer" when trying to export to HTML (others not tried
> yet):
>
>   #+tblname: table1       :noexport:
>   | n | x |  y1 |   y2 |
>   |---+---+-----+------|
>   | 0 | 1 | 2.0 |  3.0 |
>   | 1 | 2 | 2.1 |  2.0 |
>   | 2 | 3 | 2.0 |  0.3 |
>   | 3 | 4 | 1.0 |  0.6 |
>   | 4 | 5 | 1.4 | -0.1 |
>   | 5 | 6 | 1.6 |  1.2 |
>
>   #+begin_src gnuplot :file bug_gnuplot.png :var t=table1
>     set size square
>     plot t u 2:3 w lp, t u 2:4 w lp
>   #+end_src
>
> If I remove the :noexport: tag, everything works fine.
>
> Am I doing something wrong here? I don't think that :noexport: should
> affect the use of the table for other purposes.
>

This is the first time I've seen a tag applied to a table.  I've updated
the results regular expression so that it will now admit examples like
yours above.  Please let me know if this doesn't work with the latest
Org-mode.

Best -- Eric

>
>   András
>
>
>
>
>
> Emacs  : GNU Emacs 23.2.1 (i486-pc-linux-gnu, GTK+ Version 2.20.0)
>  of 2010-12-11 on raven, modified by Debian
> Package: Org-mode version 7.7 (release_7.7.167.gfceb)
>
> current state:
> ==============
> (setq
>  org-export-latex-after-initial-vars-hook '(org-beamer-after-initial-vars)
>  org-speed-command-hook '(org-speed-command-default-hook
> org-babel-speed-command-hook)
>  org-babel-load-languages '((asymptote . t) (ditaa . t) (dot . t)
> (gnuplot . t) (haskell . t) (latex . t)
> 			    (octave . t) (R . t) (ruby . t) (scheme . t) (sh . t))
>  org-metaup-hook '(org-babel-load-in-session-maybe)
>  org-after-todo-state-change-hook '(org-clock-out-if-current)
>  org-babel-tangle-lang-exts '(("ruby" . "rb") ("latex" . "tex")
> ("haskell" . "hs") ("asymptote" . "asy")
> 			      ("emacs-lisp" . "el"))
>  org-export-blocks-postblock-hook '(org-exp-res/src-name-cleanup)
>  org-export-latex-format-toc-function 'org-export-latex-format-toc-default
>  org-tab-first-hook '(org-hide-block-toggle-maybe
> org-src-native-tab-command-maybe
> 		      org-babel-hide-result-toggle-maybe)
>  org-src-mode-hook '(org-src-babel-configure-edit-buffer
> org-src-mode-configure-edit-buffer)
>  org-confirm-shell-link-function 'yes-or-no-p
>  org-export-first-hook '(org-beamer-initialize-open-trackers)
>  org-agenda-before-write-hook '(org-agenda-add-entry-text)
>  org-blank-before-new-entry nil
>  org-babel-pre-tangle-hook '(save-buffer)
>  org-cycle-hook '(org-cycle-hide-archived-subtrees
> org-cycle-hide-drawers org-cycle-show-empty-lines
> 		  org-optimize-window-after-visibility-change)
>  org-export-preprocess-before-normalizing-links-hook
> '(org-remove-file-link-modifiers)
>  org-mode-hook '(#[nil "\300\301\302\303\304$\207"
> 		   [org-add-hook change-major-mode-hook org-show-block-all append local] 5]
> 		 #[nil "\300\301\302\303\304$\207"
> 		   [org-add-hook change-major-mode-hook org-babel-show-result-all
> append local] 5]
> 		 org-babel-result-hide-spec org-babel-hide-all-hashes)
>  org-ctrl-c-ctrl-c-hook '(org-babel-hash-at-point
> org-babel-execute-safely-maybe)
>  org-confirm-elisp-link-function 'yes-or-no-p
>  org-export-interblocks '((lob org-babel-exp-lob-one-liners) (src
> org-babel-exp-inline-src-blocks))
>  org-clock-out-hook '(org-clock-remove-empty-clock-drawer)
>  org-occur-hook '(org-first-headline-recenter)
>  org-from-is-user-regexp nil
>  org-export-preprocess-before-selecting-backend-code-hook
> '(org-beamer-select-beamer-code)
>  org-confirm-babel-evaluate nil
>  org-export-latex-final-hook '(org-beamer-amend-header
> org-beamer-fix-toc org-beamer-auto-fragile-frames
> 			       org-beamer-place-default-actions-for-lists)
>  org-metadown-hook '(org-babel-pop-to-session-maybe)
>  org-export-blocks '((src org-babel-exp-src-block nil) (comment
> org-export-blocks-format-comment t)
> 		     (ditaa org-export-blocks-format-ditaa nil) (dot
> org-export-blocks-format-dot nil))
>  )
>

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 14:38 ` Eric Schulte
@ 2011-08-23 15:12   ` András Major
  2011-08-23 15:47     ` Eric Schulte
  0 siblings, 1 reply; 26+ messages in thread
From: András Major @ 2011-08-23 15:12 UTC (permalink / raw)
  To: emacs-orgmode

Hi Eric,

> This is the first time I've seen a tag applied to a table.  I've updated
> the results regular expression so that it will now admit examples like
> yours above.  Please let me know if this doesn't work with the latest
> Org-mode.

That's good news!  Well, the bad news is that it doesn't work.  I've
just pulled the current version (release_7.7.174.g63fae) and now the
behaviour is different:

- :noexport: in the #+tblname: has no effect.

- The :noexport: tag in a section including the table still has the
  same effect as before: table1 is not available as an input to the
  code block.

- There are certain subtleties which I will report separately as they
  probably were there before and are unrelated, I just never bumped
  into them.

  András

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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:14       ` Bastien
  0 siblings, 2 replies; 26+ messages in thread
From: Eric Schulte @ 2011-08-23 15:47 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 954 bytes --]

András Major <andras.g.major@gmail.com> writes:

> Hi Eric,
>
>> This is the first time I've seen a tag applied to a table.  I've updated
>> the results regular expression so that it will now admit examples like
>> yours above.  Please let me know if this doesn't work with the latest
>> Org-mode.
>
> That's good news!  Well, the bad news is that it doesn't work.  I've
> just pulled the current version (release_7.7.174.g63fae) and now the
> behaviour is different:
>
> - :noexport: in the #+tblname: has no effect.
>

I'm not sure that it is legal to apply tags to tables, so I'm not sure
if this is a bug.

>
> - The :noexport: tag in a section including the table still has the
>   same effect as before: table1 is not available as an input to the
>   code block.
>

Oh, this was actually due to a slightly different issue, which I've just
fixed.  Specifically the following org-mode file now exports as
successfully.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: noexport-tag.org --]
[-- Type: text/x-org, Size: 252 bytes --]

* top
** not to be exported                                              :noexport:
#+data: something
| 0 |
| 1 |
| 1 |
| 2 |
| 3 |
| 5 |
| 8 |

** to be exported
#+begin_src emacs-lisp :var fib=something :exports results
  (car (nth 4 fib))
#+end_src

[-- Attachment #3: Type: text/plain, Size: 241 bytes --]


>
> - There are certain subtleties which I will report separately as they
>   probably were there before and are unrelated, I just never bumped
>   into them.
>
>   András
>
>
>

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 15:47     ` Eric Schulte
@ 2011-08-23 16:01       ` András Major
  2011-08-23 16:18         ` Bastien
  2011-08-23 17:19         ` Eric Schulte
  2011-08-23 16:14       ` Bastien
  1 sibling, 2 replies; 26+ messages in thread
From: András Major @ 2011-08-23 16:01 UTC (permalink / raw)
  To: emacs-orgmode

Hi Eric,

> > That's good news!  Well, the bad news is that it doesn't work.  I've
> > just pulled the current version (release_7.7.174.g63fae) and now the
> > behaviour is different:
> >
> > - :noexport: in the #+tblname: has no effect.
> 
> I'm not sure that it is legal to apply tags to tables, so I'm not sure
> if this is a bug.

Certainly, I'm just saying that it used to work but now it doesn't.  I
think that anything that works despite being designed and documented
otherwise is confusing to the user and should be considered a bug.
I'm happy that it no longer works and hope that it stays that way.

> > - The :noexport: tag in a section including the table still has the
> >   same effect as before: table1 is not available as an input to the
> >   code block.
> 
> Oh, this was actually due to a slightly different issue, which I've just
> fixed.  Specifically the following org-mode file now exports as
> successfully.

Your file uses #+data: where I use #+tblname: -- which one is the
official one?  I have the impression that it's #+data:, but I haven't
come across that in the manual or elsewhere before.  If #+tblname:
isn't supposed to be used as a target for a variable in the code
block, then we should make sure that it *never* behaves as such.

  András

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 15:47     ` Eric Schulte
  2011-08-23 16:01       ` András Major
@ 2011-08-23 16:14       ` Bastien
  1 sibling, 0 replies; 26+ messages in thread
From: Bastien @ 2011-08-23 16:14 UTC (permalink / raw)
  To: Eric Schulte; +Cc: András Major, emacs-orgmode

Hi Eric,

Eric Schulte <schulte.eric@gmail.com> writes:

> I'm not sure that it is legal to apply tags to tables, so I'm not sure
> if this is a bug.

I confirm tags are for headlines only.  

If we want to add more export options to tables, let's use the usual
"#+[option] syntax -- like #+caption does.

-- 
 Bastien

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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 17:19         ` Eric Schulte
  1 sibling, 1 reply; 26+ messages in thread
From: Bastien @ 2011-08-23 16:18 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

Hi András,

András Major <andras.g.major@gmail.com> writes:

> I think that anything that works despite being designed and documented
> otherwise is confusing to the user and should be considered a bug.
> I'm happy that it no longer works and hope that it stays that way.

I think tags are clearly documented as being properties of the
headlines -- if there is places in the manual that we can improve 
in this respect, please suggest a patch.

I don't think it's reasonable to document the fact that tags are
not meant to be used in tables, blocks, lists, timestamps, etc.
But there are some borderline cases that may happen, and I'm happy 
to fix the doc in these cases.

Also, your question raises again the issue of a full description
of Org's (implicit) syntax -- so let's try to make progress on this.

Best,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 16:01       ` András Major
  2011-08-23 16:18         ` Bastien
@ 2011-08-23 17:19         ` Eric Schulte
  2011-08-23 22:51           ` András Major
  1 sibling, 1 reply; 26+ messages in thread
From: Eric Schulte @ 2011-08-23 17:19 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

>
> Your file uses #+data: where I use #+tblname: -- which one is the
> official one?  I have the impression that it's #+data:, but I haven't
> come across that in the manual or elsewhere before.  If #+tblname:
> isn't supposed to be used as a target for a variable in the code
> block, then we should make sure that it *never* behaves as such.
>

In the interest of backwards compatibility and convenience there are a
number of equivalent options here, see the value of the
`org-babel-data-names' variable for all possible names.

Best -- Eric

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 14:23     ` Bastien
@ 2011-08-23 22:35       ` András Major
  0 siblings, 0 replies; 26+ messages in thread
From: András Major @ 2011-08-23 22:35 UTC (permalink / raw)
  To: emacs-orgmode

Hi Bastien,

> I'm not sure I understand -- does it mean that C-cC-c on #+begin_src 
> fails in the example below?

No, it means that exporting to HTML fails with that error message.  It
should actually evaluate the code and include the resulting PNG in the
output (and that's what it does when :noexport: isn't present).

  András

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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  8:34             ` Bastien
  0 siblings, 2 replies; 26+ messages in thread
From: András Major @ 2011-08-23 22:44 UTC (permalink / raw)
  To: emacs-orgmode

Hi Bastien,

> > I think that anything that works despite being designed and documented
> > otherwise is confusing to the user and should be considered a bug.
> > I'm happy that it no longer works and hope that it stays that way.
> 
> I think tags are clearly documented as being properties of the
> headlines -- if there is places in the manual that we can improve 
> in this respect, please suggest a patch.

I'm not talking about the manual.  In my opinion, if there is a
function that works only on headlines according to the manual, then it
*must not* work in any other place.  Otherwise some users might try
the function they once heard of in a sense not specified in the
documentation (here: in a table) and see that it works, and be
surprised when it no longer does (in a future version of org-mode, or
on a different computer).  Therefore such "ghost features" must
actively be eliminated.

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.

> I don't think it's reasonable to document the fact that tags are
> not meant to be used in tables, blocks, lists, timestamps, etc.

I fully agree.

  András

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 17:19         ` Eric Schulte
@ 2011-08-23 22:51           ` András Major
  2011-08-23 23:03             ` Nick Dokos
  0 siblings, 1 reply; 26+ messages in thread
From: András Major @ 2011-08-23 22:51 UTC (permalink / raw)
  To: emacs-orgmode

Hi Eric,

> > Your file uses #+data: where I use #+tblname: -- which one is the
> > official one?  I have the impression that it's #+data:, but I haven't
> > come across that in the manual or elsewhere before.  If #+tblname:
> > isn't supposed to be used as a target for a variable in the code
> > block, then we should make sure that it *never* behaves as such.
> >
> 
> In the interest of backwards compatibility and convenience there are a
> number of equivalent options here, see the value of the
> `org-babel-data-names' variable for all possible names.

OK, in that case the example still doesn't work for me.  Whether I use
#+data or #+tblname, specifying the :noexport: tag in the section
containing the table causes the HTML export to report the error
"reference 'table1' not found in this buffer".

As Bastien pointed out earlier, I'm not talking about simple
evaluation (C-cC-c) but, specifically, export (HTML and PDF tried so
far).

  András

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 22:51           ` András Major
@ 2011-08-23 23:03             ` Nick Dokos
  2011-08-23 23:44               ` Eric Schulte
  0 siblings, 1 reply; 26+ messages in thread
From: Nick Dokos @ 2011-08-23 23:03 UTC (permalink / raw)
  To: =?utf-8?b?QW5kcsOhcw==?= Major; +Cc: nicholas.dokos, emacs-orgmode

András Major <andras.g.major@gmail.com> wrote:

> Hi Eric,
> 
> > > Your file uses #+data: where I use #+tblname: -- which one is the
> > > official one?  I have the impression that it's #+data:, but I haven't
> > > come across that in the manual or elsewhere before.  If #+tblname:
> > > isn't supposed to be used as a target for a variable in the code
> > > block, then we should make sure that it *never* behaves as such.
> > >
> > 
> > In the interest of backwards compatibility and convenience there are a
> > number of equivalent options here, see the value of the
> > `org-babel-data-names' variable for all possible names.
> 
> OK, in that case the example still doesn't work for me.  Whether I use
> #+data or #+tblname, specifying the :noexport: tag in the section
> containing the table causes the HTML export to report the error
> "reference 'table1' not found in this buffer".
> 
> As Bastien pointed out earlier, I'm not talking about simple
> evaluation (C-cC-c) but, specifically, export (HTML and PDF tried so
> far).
> 

This is probably caused by org-export-preprocess-string: it does things
in a certain order, and it probably kills the :noexport: stuff before it
gets to the evaluation of the source block.

It might be possible to change the order (ISTR a couple of cases, where
behavior was changed by doing exactly this), but it's probably fraught with
peril: approach with caution.

Nick

PS. Warning: the above is a guess: it may have nothing to do with reality.

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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  8:34             ` Bastien
  1 sibling, 1 reply; 26+ messages in thread
From: Thomas S. Dye @ 2011-08-23 23:38 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

András Major <andras.g.major@gmail.com> writes:

> Hi Bastien,
>
>> > I think that anything that works despite being designed and documented
>> > otherwise is confusing to the user and should be considered a bug.
>> > I'm happy that it no longer works and hope that it stays that way.
>> 
>> I think tags are clearly documented as being properties of the
>> headlines -- if there is places in the manual that we can improve 
>> in this respect, please suggest a patch.
>
> I'm not talking about the manual.  In my opinion, if there is a
> function that works only on headlines according to the manual, then it
> *must not* work in any other place.  Otherwise some users might try
> the function they once heard of in a sense not specified in the
> documentation (here: in a table) and see that it works, and be
> surprised when it no longer does (in a future version of org-mode, or
> on a different computer).  Therefore such "ghost features" must
> actively be eliminated.
>
> 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.

All the best,
Tom

>
>> I don't think it's reasonable to document the fact that tags are
>> not meant to be used in tables, blocks, lists, timestamps, etc.
>
> I fully agree.
>
>   András
>
>
>
>

-- 
Thomas S. Dye
http://www.tsdye.com

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  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
  0 siblings, 2 replies; 26+ messages in thread
From: Eric Schulte @ 2011-08-23 23:44 UTC (permalink / raw)
  To: nicholas.dokos; +Cc: András Major, emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 1284 bytes --]

Nick Dokos <nicholas.dokos@hp.com> writes:

> András Major <andras.g.major@gmail.com> wrote:
>
>> Hi Eric,
>> 
>> > > Your file uses #+data: where I use #+tblname: -- which one is the
>> > > official one?  I have the impression that it's #+data:, but I haven't
>> > > come across that in the manual or elsewhere before.  If #+tblname:
>> > > isn't supposed to be used as a target for a variable in the code
>> > > block, then we should make sure that it *never* behaves as such.
>> > >
>> > 
>> > In the interest of backwards compatibility and convenience there are a
>> > number of equivalent options here, see the value of the
>> > `org-babel-data-names' variable for all possible names.
>> 
>> OK, in that case the example still doesn't work for me.  Whether I use
>> #+data or #+tblname, specifying the :noexport: tag in the section
>> containing the table causes the HTML export to report the error
>> "reference 'table1' not found in this buffer".
>> 
>> As Bastien pointed out earlier, I'm not talking about simple
>> evaluation (C-cC-c) but, specifically, export (HTML and PDF tried so
>> far).
>> 
>

Are you /sure/ that this doesn't work for you?  On my system C-c C-e A
in the following attached org-mode file (posted earlier in this thread)

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: noexport.org --]
[-- Type: text/x-org, Size: 252 bytes --]

* top
** not to be exported                                              :noexport:
#+data: something
| 0 |
| 1 |
| 1 |
| 2 |
| 3 |
| 5 |
| 8 |

** to be exported
#+begin_src emacs-lisp :var fib=something :exports results
  (car (nth 4 fib))
#+end_src

[-- Attachment #3: Type: text/plain, Size: 1359 bytes --]


Does export and correctly resolves the variable in the :noexport:'d
section resulting in the following output.

,----
|                                noexport
|                                ========
| 
| Author: Eric Schulte
| Date: 2011-08-23 17:37:28 MDT
| 
| 
| Table of Contents
| =================
| 1 top 
|     1.1 to be exported 
| 
| 
| 1 top 
| ------
| 
| 1.1 to be exported 
| ===================
| 
| 
| 3
| 
`----

>
> This is probably caused by org-export-preprocess-string: it does things
> in a certain order, and it probably kills the :noexport: stuff before it
> gets to the evaluation of the source block.
>
> It might be possible to change the order (ISTR a couple of cases, where
> behavior was changed by doing exactly this), but it's probably fraught with
> peril: approach with caution.
>

The above analysis is correct.  Babel has to deal with this when
resolving header arguments, noweb references and variable expansions.
It does this by resolving these things in the original org-mode buffer
rather than in the temporary export buffer which is often missing
portions which are not to be exported.  See the definition of the
`org-babel-exp-in-export-file' macro for details.

Best -- Eric

>
> Nick
>
> PS. Warning: the above is a guess: it may have nothing to do with reality.
>

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 23:44               ` Eric Schulte
@ 2011-08-24  0:14                 ` Thomas S. Dye
  2011-08-24  7:41                 ` András Major
  1 sibling, 0 replies; 26+ messages in thread
From: Thomas S. Dye @ 2011-08-24  0:14 UTC (permalink / raw)
  To: Eric Schulte; +Cc: András Major, nicholas.dokos, emacs-orgmode

Eric Schulte <schulte.eric@gmail.com> writes:

> Nick Dokos <nicholas.dokos@hp.com> writes:
>
>> András Major <andras.g.major@gmail.com> wrote:
>>
>>> Hi Eric,
>>> 
>>> > > Your file uses #+data: where I use #+tblname: -- which one is the
>>> > > official one?  I have the impression that it's #+data:, but I haven't
>>> > > come across that in the manual or elsewhere before.  If #+tblname:
>>> > > isn't supposed to be used as a target for a variable in the code
>>> > > block, then we should make sure that it *never* behaves as such.
>>> > >
>>> > 
>>> > In the interest of backwards compatibility and convenience there are a
>>> > number of equivalent options here, see the value of the
>>> > `org-babel-data-names' variable for all possible names.
>>> 
>>> OK, in that case the example still doesn't work for me.  Whether I use
>>> #+data or #+tblname, specifying the :noexport: tag in the section
>>> containing the table causes the HTML export to report the error
>>> "reference 'table1' not found in this buffer".
>>> 
>>> As Bastien pointed out earlier, I'm not talking about simple
>>> evaluation (C-cC-c) but, specifically, export (HTML and PDF tried so
>>> far).
>>> 
>>
>
> Are you /sure/ that this doesn't work for you?  On my system C-c C-e A
> in the following attached org-mode file (posted earlier in this thread)
>
> * top
> ** not to be exported                                              :noexport:
> #+data: something
> | 0 |
> | 1 |
> | 1 |
> | 2 |
> | 3 |
> | 5 |
> | 8 |

Hi Eric,

Your example works here, too.  It fails, however, if there is an empty
line between #+data: something and the first row of the table.  Then a
listp, nil error is raised.  Perhaps this is what Andras is seeing?

I haven't gone back to take a specific look at the manual, but in the
past I've thought that the documentation of table naming isn't as good
as it might be.  In fact, I often have a hard time finding it in the
first place :)

hth,
Tom

>
> ** to be exported
> #+begin_src emacs-lisp :var fib=something :exports results
>   (car (nth 4 fib))
> #+end_src
>
>
> Does export and correctly resolves the variable in the :noexport:'d
> section resulting in the following output.
>
> ,----
> |                                noexport
> |                                ========
> | 
> | Author: Eric Schulte
> | Date: 2011-08-23 17:37:28 MDT
> | 
> | 
> | Table of Contents
> | =================
> | 1 top 
> |     1.1 to be exported 
> | 
> | 
> | 1 top 
> | ------
> | 
> | 1.1 to be exported 
> | ===================
> | 
> | 
> | 3
> | 
> `----
>
>>
>> This is probably caused by org-export-preprocess-string: it does things
>> in a certain order, and it probably kills the :noexport: stuff before it
>> gets to the evaluation of the source block.
>>
>> It might be possible to change the order (ISTR a couple of cases, where
>> behavior was changed by doing exactly this), but it's probably fraught with
>> peril: approach with caution.
>>
>
> The above analysis is correct.  Babel has to deal with this when
> resolving header arguments, noweb references and variable expansions.
> It does this by resolving these things in the original org-mode buffer
> rather than in the temporary export buffer which is often missing
> portions which are not to be exported.  See the definition of the
> `org-babel-exp-in-export-file' macro for details.
>
> Best -- Eric
>
>>
>> Nick
>>
>> PS. Warning: the above is a guess: it may have nothing to do with reality.
>>

-- 
Thomas S. Dye
http://www.tsdye.com

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 23:38             ` Thomas S. Dye
@ 2011-08-24  6:35               ` András Major
  2011-08-24  7:22                 ` Thomas S. Dye
  2011-08-24  8:26                 ` Bastien
  0 siblings, 2 replies; 26+ messages in thread
From: András Major @ 2011-08-24  6:35 UTC (permalink / raw)
  To: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-24  6:35               ` András Major
@ 2011-08-24  7:22                 ` Thomas S. Dye
  2011-08-24  8:28                   ` Bastien
  2011-08-24  8:26                 ` Bastien
  1 sibling, 1 reply; 26+ messages in thread
From: Thomas S. Dye @ 2011-08-24  7:22 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

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

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 23:44               ` Eric Schulte
  2011-08-24  0:14                 ` Thomas S. Dye
@ 2011-08-24  7:41                 ` András Major
  1 sibling, 0 replies; 26+ messages in thread
From: András Major @ 2011-08-24  7:41 UTC (permalink / raw)
  To: emacs-orgmode

Eric Schulte <schulte.eric <at> gmail.com> writes:

> Are you /sure/ that this doesn't work for you?  On my system C-c C-e A
> in the following attached org-mode file (posted earlier in this thread)

I've just pulled the code again, now it seems to work.  I'm not sure
what went wrong last night (release_7.7.174.g63fae), but with the
current release_7.7.187.g0019b it appears to work just fine.  Thanks a
lot!

  András

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-24  6:35               ` András Major
  2011-08-24  7:22                 ` Thomas S. Dye
@ 2011-08-24  8:26                 ` Bastien
  1 sibling, 0 replies; 26+ messages in thread
From: Bastien @ 2011-08-24  8:26 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

Hi András,

András Major <andras.g.major@gmail.com> writes:

> I fully agree with you, but it looks like I didn't express my point
> clearly enough.  

Thanks for taking the time to make this clear.

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

Fully agreed.  The right thing to do is to fix it.

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

Yes, let's try to be consistent about this.

Now, taking practically, this is something we can do on a use-case
basis: in the issue your raised, we fix the problem then fix the doc if
necessary.  And we can deal with future similar issues like this.

Thanks again,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-24  7:22                 ` Thomas S. Dye
@ 2011-08-24  8:28                   ` Bastien
  2011-08-24 16:41                     ` Thomas S. Dye
  0 siblings, 1 reply; 26+ messages in thread
From: Bastien @ 2011-08-24  8:28 UTC (permalink / raw)
  To: Thomas S. Dye; +Cc: András Major, emacs-orgmode

Hi Tom,

tsd@tsdye.com (Thomas S. Dye) writes:

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

This is stating the obvious, and this gives a feeling that there might
be a lot of unintentional features -- I doubt this is the case.  I'd
rather concentrate on eliminating those "ghost features" rather than
advertising their possible existence.

Best,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-23 22:44           ` András Major
  2011-08-23 23:38             ` Thomas S. Dye
@ 2011-08-24  8:34             ` Bastien
  1 sibling, 0 replies; 26+ messages in thread
From: Bastien @ 2011-08-24  8:34 UTC (permalink / raw)
  To: András Major; +Cc: emacs-orgmode

Hi András,

András Major <andras.g.major@gmail.com> writes:

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

Yes, a *major documentation bug*.

> but likewise anything it does do which the docs don't cover is
> also a bug.

I would call this a *minor documentation bug* (depending on the
importance of the side-effects, of course).

For example, not all variables get documented in the manual, and each
variable plays a role somewhere, as documented in its docstring -- it
would not be reasonable to try to document each variable in the manual
because it would make it completely unreadable.

So I'd rephrase your statement above:

  "Features that the user needs to know about and is not covered by the
  documentation is a bug."

But again, this is stating the obvious :)

Let's not spend too much time discussing theoretically -- patches
welcome!  :)

Best,

-- 
 Bastien

^ permalink raw reply	[flat|nested] 26+ messages in thread

* Re: Bug: :noexport: tag prevents table functioning as babel code block input [7.7 (release_7.7.167.gfceb)]
  2011-08-24  8:28                   ` Bastien
@ 2011-08-24 16:41                     ` Thomas S. Dye
  0 siblings, 0 replies; 26+ messages in thread
From: Thomas S. Dye @ 2011-08-24 16:41 UTC (permalink / raw)
  To: Bastien; +Cc: András Major, emacs-orgmode

Bastien <bzg@altern.org> writes:

> Hi Tom,
>
> tsd@tsdye.com (Thomas S. Dye) writes:
>
>> 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."
>
> This is stating the obvious, and this gives a feeling that there might
> be a lot of unintentional features -- I doubt this is the case.  I'd
> rather concentrate on eliminating those "ghost features" rather than
> advertising their possible existence.
>
> Best,

Sounds good to me.

Tom

-- 
Thomas S. Dye
http://www.tsdye.com

^ permalink raw reply	[flat|nested] 26+ messages in thread

end of thread, other threads:[~2011-08-24 16:42 UTC | newest]

Thread overview: 26+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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
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

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).