Capitalisation and good taste ?

Capitalisation and good taste ?

[François Pinard]

Hi, Org people.

I really have mixed feelings about capitalisation of #+WORDS, and wonder
if some consensus and good taste has developed over time among Org mode
users.  What is the collective wisdom saying as being nicer among:

#+LATEX_HEADER:
#+Latex_Header:
#+LaTeX_HEADER:
#+latex_header:

etc.

I'm just unable to fix myself on any convention, and my own lack of
decision irritates me.  I hate changing my mind so often, and my files
are already a mess on this particular point.

Despite all capitals have the advantage of standing out clearly, I
usually don't like any kind of shouting in my files.  If I was writing
constants in C code, I would tolerate some exceptions of course, but
now, I'm writing documentation.  #+begin_quote and such are just OK in
small letters, they really look like shouting otherwise.

On the other hand, it seems that #+TITLE, #+AUTHOR and #+EMAIL, and all
those things which are high lighted in gray, use capitals only in all
examples I've seen so far.  Maybe the pale high lighting is a
counter-measure so it gets tolerable.

It seems that capitals are also favoured for #+OPTIONS, #+BIND, and many
other things (high lighted in red), yet I got the impression that parts
of the documentation (which look "newer" or "younger" to me on the
average) are getting away from the all capital conventions.  I do not
really know.

The writing "LaTeX" has the nicety of being the proper way to write
LaTeX, which is mandated by Lamport (after TeX has been mandated by
Knuth).  And I will not even speak of the revolutionary iTex, because I
do not have a bell handy! :-) If any of you are not aware of it, make
sure you do not miss http://www.youtube.com/watch?v=eKaI78K_rgA (you
then need half an hour of free time to listen to the video).

Not helping is that the manual and the Wiki are not using capitalisation
consistently between files, and even sometimes in the same area of a
same file.  They are not giving me clear advice about what is proper
style.

Maybe this has already been debated to death?  I do not know for Org
mode files, yet I know that style issues are usually flame-prone.  I'm
surely not trying to start any kind of war.  Nevertheless, I would like
if the manual and the Wiki select and document a preferred convention,
and were amended to be very consistent on it.  So, I'll have a clear
model to follow. :-)

François

Re: Capitalisation and good taste ?

[Bernt Hansen]

pinard@iro.umontreal.ca (François Pinard) writes:

> I really have mixed feelings about capitalisation of #+WORDS, and wonder
> if some consensus and good taste has developed over time among Org mode
> users.  What is the collective wisdom saying as being nicer among:
>
> #+LATEX_HEADER:
> #+Latex_Header:
> #+LaTeX_HEADER:
> #+latex_header:
>
> etc.
>
> I'm just unable to fix myself on any convention, and my own lack of
> decision irritates me.  I hate changing my mind so often, and my files
> are already a mess on this particular point.
>
> Despite all capitals have the advantage of standing out clearly, I
> usually don't like any kind of shouting in my files.  If I was writing
> constants in C code, I would tolerate some exceptions of course, but
> now, I'm writing documentation.  #+begin_quote and such are just OK in
> small letters, they really look like shouting otherwise.
>
> On the other hand, it seems that #+TITLE, #+AUTHOR and #+EMAIL, and all
> those things which are high lighted in gray, use capitals only in all
> examples I've seen so far.  Maybe the pale high lighting is a
> counter-measure so it gets tolerable.
>
> It seems that capitals are also favoured for #+OPTIONS, #+BIND, and many
> other things (high lighted in red), yet I got the impression that parts
> of the documentation (which look "newer" or "younger" to me on the
> average) are getting away from the all capital conventions.  I do not
> really know.
>
> The writing "LaTeX" has the nicety of being the proper way to write
> LaTeX, which is mandated by Lamport (after TeX has been mandated by
> Knuth).  And I will not even speak of the revolutionary iTex, because I
> do not have a bell handy! :-) If any of you are not aware of it, make
> sure you do not miss http://www.youtube.com/watch?v=eKaI78K_rgA (you
> then need half an hour of free time to listen to the video).
>
> Not helping is that the manual and the Wiki are not using capitalisation
> consistently between files, and even sometimes in the same area of a
> same file.  They are not giving me clear advice about what is proper
> style.
>
> Maybe this has already been debated to death?  I do not know for Org
> mode files, yet I know that style issues are usually flame-prone.  I'm
> surely not trying to start any kind of war.  Nevertheless, I would like
> if the manual and the Wiki select and document a preferred convention,
> and were amended to be very consistent on it.  So, I'll have a clear
> model to follow. :-)

Hi François,

A long time ago all capitals was the only way these keywords were
supported.  Since then they have become case insensitive and I use all
lowercase for most of my keywords now (#+begin_src:, #+begin_example:
etc)

With fontification these stand out enough now and the capitalization can
be removed.  I still tend to use allcaps at the top of the file for
things like #+FILETAGS:, #+TITLE:, #+OPTIONS, etc but the blocks
embedded in my text are all lowercase now.

I wouldn't spend too much time agonizing over the 'right' way - do what
works for you :)

HTH,
Bernt

Re: Capitalisation and good taste ?

[Nick Dokos]

Bernt Hansen <bernt@norang.ca> wrote:

> pinard@iro.umontreal.ca (François Pinard) writes:
> 
> > I really have mixed feelings about capitalisation of #+WORDS, and wonder
> > if some consensus and good taste has developed over time among Org mode
> > users.  What is the collective wisdom saying as being nicer among:
> >
> > #+LATEX_HEADER:
> > #+Latex_Header:
> > #+LaTeX_HEADER:
> > #+latex_header:
> >
> > etc.
> >
> > I'm just unable to fix myself on any convention, and my own lack of
> > decision irritates me.  I hate changing my mind so often, and my files
> > are already a mess on this particular point.
> >
> > Despite all capitals have the advantage of standing out clearly, I
> > usually don't like any kind of shouting in my files.  If I was writing
> > constants in C code, I would tolerate some exceptions of course, but
> > now, I'm writing documentation.  #+begin_quote and such are just OK in
> > small letters, they really look like shouting otherwise.
> >
> > On the other hand, it seems that #+TITLE, #+AUTHOR and #+EMAIL, and all
> > those things which are high lighted in gray, use capitals only in all
> > examples I've seen so far.  Maybe the pale high lighting is a
> > counter-measure so it gets tolerable.
> >
> > It seems that capitals are also favoured for #+OPTIONS, #+BIND, and many
> > other things (high lighted in red), yet I got the impression that parts
> > of the documentation (which look "newer" or "younger" to me on the
> > average) are getting away from the all capital conventions.  I do not
> > really know.
> >
> > The writing "LaTeX" has the nicety of being the proper way to write
> > LaTeX, which is mandated by Lamport (after TeX has been mandated by
> > Knuth).  And I will not even speak of the revolutionary iTex, because I
> > do not have a bell handy! :-) If any of you are not aware of it, make
> > sure you do not miss http://www.youtube.com/watch?v=eKaI78K_rgA (you
> > then need half an hour of free time to listen to the video).
> >
> > Not helping is that the manual and the Wiki are not using capitalisation
> > consistently between files, and even sometimes in the same area of a
> > same file.  They are not giving me clear advice about what is proper
> > style.
> >
> > Maybe this has already been debated to death?  I do not know for Org
> > mode files, yet I know that style issues are usually flame-prone.  I'm
> > surely not trying to start any kind of war.  Nevertheless, I would like
> > if the manual and the Wiki select and document a preferred convention,
> > and were amended to be very consistent on it.  So, I'll have a clear
> > model to follow. :-)
> 
> Hi François,
> 
> A long time ago all capitals was the only way these keywords were
> supported.  Since then they have become case insensitive and I use all
> lowercase for most of my keywords now (#+begin_src:, #+begin_example:
> etc)
> 
> With fontification these stand out enough now and the capitalization can
> be removed.  I still tend to use allcaps at the top of the file for
> things like #+FILETAGS:, #+TITLE:, #+OPTIONS, etc but the blocks
> embedded in my text are all lowercase now.
> 
> I wouldn't spend too much time agonizing over the 'right' way - do what
> works for you :)
> 

... and check out "easy templates" to get consistent capitalization
*and* speed up your typing:

(info "(org) Easy Templates")

Nick

Re: Capitalisation and good taste ?

[François Pinard]

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

> ... and check out "easy templates" to get consistent capitalization
> *and* speed up your typing: (info "(org) Easy Templates")

Good advice!  Thanks!

François

P.S. By the way, the node mentions "#+begin_ascii", but the manual does
not tell about what it is.  (Or at least "t s begin_ascii RET s RET" in
the Info node only finds the Easy Templates reference.)

P.P.S. How about amending the manual for consistent capitalization?

Re: Capitalisation and good taste ?

[Nick Dokos]

François Pinard <pinard@iro.umontreal.ca> wrote:

> P.S. By the way, the node mentions "#+begin_ascii", but the manual does
> not tell about what it is.  (Or at least "t s begin_ascii RET s RET" in
> the Info node only finds the Easy Templates reference.)
> 

In general, #+begin_foo ... #+end_foo will include the contents of the
block for foo export but get rid of it for non-foo export. So if you
don't intend to export to ascii, you can use an ascii block to include
comments in your file (and similarly for other formats). Of course, you
can also use #+begin_comment...#+end_comment, but afaict, there is an
inconsistency here: the latter can not be indented, whereas the other blocks
can. I haven't tried this with org-indent-mode though[fn:1].

> P.P.S. How about amending the manual for consistent capitalization?
> 
Knock yourself out! ;-)

Nick

Footnotes:

[fn:1] Here is a test file:

--8<---------------cut here---------------start------------->8---

* foo export

  #+begin_ascii
  This is not exported in anything other than ascii.
  #+end_ascii

  #+begin_comment
  foo
  #+end_comment


  #+begin_example
  This is exported in anything.  
  #+end_example

  #+begin_html
  This is not exported in anything other than html.
  #+end_html

  #+begin_latex
  This is not exported in anything other than latex.
  #+end_latex
--8<---------------cut here---------------end--------------->8---

Re: Capitalisation and good taste ?

[François Pinard]

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

> François Pinard <pinard@iro.umontreal.ca> wrote:
>> P.P.S. How about amending the manual for consistent capitalization?
>> 

> Knock yourself out! ;-)

I've absolutely nothing against doing that little work myself (that one
is easy enough!), besides the idea that I might be working against the
crowd.  If nobody objects that I normalize everything (every #+ thing)
to lower case, I'll happily do it.  If the only result of a patch would
be to start a flame war (or just loosing my time), I'd better stay
quiet...

Always easier to formally ask permission once you informally got it!

François

Re: Capitalisation and good taste ?

[Nick Dokos]

François Pinard <pinard@iro.umontreal.ca> wrote:

> Nick Dokos <nicholas.dokos@hp.com> writes:
> 
> > François Pinard <pinard@iro.umontreal.ca> wrote:
> >> P.P.S. How about amending the manual for consistent capitalization?
> >> 
> 
> > Knock yourself out! ;-)
> 
> I've absolutely nothing against doing that little work myself (that one
> is easy enough!), besides the idea that I might be working against the
> crowd.  If nobody objects that I normalize everything (every #+ thing)
> to lower case, I'll happily do it.  If the only result of a patch would
> be to start a flame war (or just loosing my time), I'd better stay
> quiet...
> 
> Always easier to formally ask permission once you informally got it!
> 

OK - I'm not the one to ask permission from, but I doubt very much that
a flame war will erupt because of a patch to make things in the manual
more uniform (of course, there will have to be a notation somewhere, if
one is not there already, that capitalization does not matter in these
cases: it's easy to infer that when all the examples are in various
forms of capitalization, but harder when everything is uniform - as you
can see, uniformity is not an unmitigated blessing :-) ).

Nick

Re: Capitalisation and good taste ?

[Bastien]

Hi François,

pinard@iro.umontreal.ca (François Pinard) writes:

> P.P.S. How about amending the manual for consistent capitalization?

I've pushed a fix for this.

The manual used mostly uppercase so I fixed the few lowercase 
instances of option/environment keywords.

I made an exception for #+results, which is dynamically used 
with lowercase.

For the historical note: Carsten used uppercase most of the 
time, and Eric introduced lowercase.  To me, uppercase looks
better in the manual, and also means "this is a predefined
keyword (see the other rules for TODO, tags and properties.)

Thanks for raising this,

-- 
 Bastien

Re: Capitalisation and good taste ?

[Eric Schulte]

Bastien <bzg@altern.org> writes:

> Hi François,
>
> pinard@iro.umontreal.ca (François Pinard) writes:
>
>> P.P.S. How about amending the manual for consistent capitalization?
>
> I've pushed a fix for this.
>
> The manual used mostly uppercase so I fixed the few lowercase 
> instances of option/environment keywords.
>
> I made an exception for #+results, which is dynamically used 
> with lowercase.
>
> For the historical note: Carsten used uppercase most of the 
> time, and Eric introduced lowercase.  To me, uppercase looks
> better in the manual, and also means "this is a predefined
> keyword (see the other rules for TODO, tags and properties.)
>
> Thanks for raising this,

Ah! I don't mean to introduce inconsistencies.  I would be happy to
change the dynamic #+results: generation so that it instead inserts
#+RESULTS: into the buffer.  I believe the gain in consistency
out-weights any aesthetic concerns.

That said I'm happy that Org-mode is forgiving enough to allow me to
lowercase most of my keywords locally.

Best,

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

Re: Capitalisation and good taste ?

[Bastien]

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

> That said I'm happy that Org-mode is forgiving enough to allow me to
> lowercase most of my keywords locally.

Actually, I'm thinking of another solution:

- keep one-line option/environment keywords uppercase
  #+NAME
  #+HTML
  #+TITLE
  #+...

- use lowercase for multi-lines environments keywords
  #+begin_ascii
  #+begin_html
  #+results

This is the only good criterium I can think of, and that
way people using easy templates will not be surprised to
see #+begin_xxx in the manual.

Eric, what do you think?

-- 
 Bastien

Re: Capitalisation and good taste ?

[François Pinard]

Bastien <bzg@altern.org> writes:

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

>> That said I'm happy that Org-mode is forgiving enough to allow me to
>> lowercase most of my keywords locally.

> Actually, I'm thinking of another solution:

> - keep one-line option/environment keywords uppercase
>   #+NAME
>   #+HTML
>   #+TITLE
>   #+...

> - use lowercase for multi-lines environments keywords
>   #+begin_ascii
>   #+begin_html
>   #+results

> This is the only good criterium I can think of, and that
> way people using easy templates will not be surprised to
> see #+begin_xxx in the manual.

I surely like this! :-).

Could the highlighting be made consistent as well?  I would suggest that
gray is uniformly kept for all one-line option/environment keywords.
Currently, #+TITLE is gray, #+OPTIONS is red, so #+OPTION would be
rendered the same as #+TITLE.  The gray would counter-balance the
shouting of the capitals, making it more bearable.

For lowercase multi-line environments keywords, red is just fine, and I
did not see exceptions so far (which does not mean there are not any).

François

Re: Capitalisation and good taste ?

[Martyn Jago]

pinard@iro.umontreal.ca (François Pinard) writes:

> Bastien <bzg@altern.org> writes:
>
>> Eric Schulte <eric.schulte@gmx.com> writes:
>
>>> That said I'm happy that Org-mode is forgiving enough to allow me to
>>> lowercase most of my keywords locally.
>
>> Actually, I'm thinking of another solution:
>
>> - keep one-line option/environment keywords uppercase
>>   #+NAME
>>   #+HTML
>>   #+TITLE
>>   #+...
>

[...]

Personally, I would like to be able to do:

** Some code

~~~> emacs-lisp

(some-code goes-here)

<~~~

... which compands to:

** Some code

<~~~> el...

Personally I dislike capitalized labels immensely!

[...]

Best, Martyn

Re: Capitalisation and good taste ?

[Sebastien Vauban]

Hi Bastien,

François Pinard wrote:
> Bastien <bzg-whniv8GeeGkdnm+yROfE0A@public.gmane.org> writes:
>> Eric Schulte <eric.schulte-KK0ffGbhmjU@public.gmane.org> writes:
>
>>> That said I'm happy that Org-mode is forgiving enough to allow me to
>>> lowercase most of my keywords locally.
>
>> Actually, I'm thinking of another solution:
>
>> - keep one-line option/environment keywords uppercase
>>   #+NAME
>>   #+HTML
>>   #+TITLE
>>   #+...
>
>> - use lowercase for multi-lines environments keywords
>>   #+begin_ascii
>>   #+begin_html
>>   #+results
>
>> This is the only good criterium I can think of, and that
>> way people using easy templates will not be surprised to
>> see #+begin_xxx in the manual.
>
> I surely like this! :-).

So do I.

> Could the highlighting be made consistent as well?  I would suggest that
> gray is uniformly kept for all one-line option/environment keywords.
> Currently, #+TITLE is gray, #+OPTIONS is red, so #+OPTION would be
> rendered the same as #+TITLE.  The gray would counter-balance the
> shouting of the capitals, making it more bearable.
>
> For lowercase multi-line environments keywords, red is just fine, and I
> did not see exceptions so far (which does not mean there are not any).

François,

Are you talking of a dark theme or light theme?  Did you take a look at Emacs
color themes, and their customization for Org?  See, for example, mine at
http://orgmode.org/worg/color-themes-screenshot.html#sec-1-4 [1].

In that page, you'll find:

- 6 dark themes
- 1 gray theme
- 1 light theme

Best regards,
  Seb

Footnotes:

[1] I should update my color-theme code and screenshot on Worg, as my color
theme has varied over the last months.

-- 
Sebastien Vauban

Re: Capitalisation and good taste ?

[François Pinard]

"Sebastien Vauban" writes:
> François Pinard wrote:
>> Bastien writes:
>>> Eric Schulte writes:

>> Could the highlighting be made consistent as well?  I would suggest that
>> gray is uniformly kept for all one-line option/environment keywords.
>> Currently, #+TITLE is gray, #+OPTIONS is red, so #+OPTION would be
>> rendered the same as #+TITLE.  The gray would counter-balance the
>> shouting of the capitals, making it more bearable.

> François, Are you talking of a dark theme or light theme?

I do not know, as I do not use themes.  The background is white, if this
is what you mean.

So, I'm merely speaking about Org mode defaults.  My suggestion is that
the default for #+ lines to be consistent (and if it cannot be for some
reason, that these reasons be stated somewhere in the manual).

> Did you take a look at Emacs color themes, and their customization for
> Org?

Following your suggestion, I just took a quick look.  This is far too
complex for my humble needs.  It seems that using themes is opening the
door for a lot of further customization, and I have too much of it
already.

François



P.S. For the record, I have been a long and deep user of Emacs for maybe
15 years (I have fuzzy memory of times), and with years passing by, have
grown a huge, insane Emacs customization (Gnus in particular).  So, I
decided to break out of the addiction (it has been real hard to do so,
then heal!), and switched to Vim, maybe 10 years ago.  I also have other
reasons (http://icule.blogspot.com/2003/12/thoughts-on-editors.html,
section 1).  Org mode was so appealing that I returned to Emacs
recently, but I promised myself that this time through, I will strongly
resist customization bloat.  As I have a lot already for Org mode, I
have to put breaks somewhere!  :-)

Re: Capitalisation and good taste ?

[Sebastien Vauban]

Hi François,

François Pinard wrote:
> "Sebastien Vauban" writes:
>>
>> François, Are you talking of a dark theme or light theme?
>
> I do not know, as I do not use themes. The background is white, if this is
> what you mean.

Yep, that's what I meant.

> So, I'm merely speaking about Org mode defaults. My suggestion is that the
> default for #+ lines to be consistent (and if it cannot be for some reason,
> that these reasons be stated somewhere in the manual).
>
>> Did you take a look at Emacs color themes, and their customization for Org?
>
> Following your suggestion, I just took a quick look. This is far too complex
> for my humble needs. It seems that using themes is opening the door for a
> lot of further customization, and I have too much of it already.

Not really a problem. This is quite short, the following being what I need to
enable my own color theme:

#+begin_src emacs-lisp
;; avoid Emacs hanging for a while changing default font
(modify-frame-parameters nil '((wait-for-wm . nil)))

;; the real color theme functions
(when (require 'color-theme-autoloads)

  ;; initialize the color theme package
  (if (fboundp 'color-theme-initialize)
      (color-theme-initialize))

  ;; color themes will be installed for all frames
  (setq color-theme-is-global t)

  ;; set my default color theme
  (when (try-require 'color-theme-leuven)
    (color-theme-leuven)))
#+end_src

And it simply allows you to decide on every face you want to customize for
yourself.

> P.S. For the record, I have been a long and deep user of Emacs for maybe 15
> years (I have fuzzy memory of times), and with years passing by, have grown
> a huge, insane Emacs customization (Gnus in particular). So, I decided to
> break out of the addiction (it has been real hard to do so, then heal!), and
> switched to Vim, maybe 10 years ago. I also have other reasons
> (http://icule.blogspot.com/2003/12/thoughts-on-editors.html, section 1). Org
> mode was so appealing that I returned to Emacs recently, but I promised
> myself that this time through, I will strongly resist customization bloat.
> As I have a lot already for Org mode, I have to put breaks somewhere! :-)

I know the feeling. I'm using Emacs since 1999, and now have 10,998 lines in
my .emacs file. Though, every line being commented, and having a blank line
between each customization, that represent more or less 3,400 real lines.

That said, it's huge. But it now becomes much more feasible since I've LP'ed[1]
my .emacs file, thanks to Org Babel: now, I can put a lot of comments outside
of my .emacs file, and quickly access what I need to read or update with Org's
sparse trees (`C-c / /').

It is even easy to not tangle parts of Emacs custom, for debug needs, for
example. Or get a nicely printed HTML output. Or... just name it, I can go on
with advantages of using both Emacs and Org-mode, even heavily customized ;-)

Best regards,
  Seb

Footnotes:

[1] Literate Programming (à la NoWeb)

-- 
Sebastien Vauban

Re: Capitalisation and good taste ?

[Bastien]

Hi François,

pinard@iro.umontreal.ca (François Pinard) writes:

> Could the highlighting be made consistent as well?  I would suggest that
> gray is uniformly kept for all one-line option/environment keywords.
> Currently, #+TITLE is gray, #+OPTIONS is red, so #+OPTION would be
> rendered the same as #+TITLE.  The gray would counter-balance the
> shouting of the capitals, making it more bearable.
>
> For lowercase multi-line environments keywords, red is just fine, and I
> did not see exceptions so far (which does not mean there are not any).

As Sébastien suggested, please contribute to this page:
http://orgmode.org/worg/color-themes-screenshot.html

Thanks,

-- 
 Bastien

Re: Capitalisation and good taste ?

[François Pinard]

Bastien <bzg@altern.org> writes:

> Hi François,

>> Could the highlighting be made consistent as well?

> As Sébastien suggested, please contribute to this page:
> http://orgmode.org/worg/color-themes-screenshot.html

Hello, Bastien.  I hope you'll forgive me if I decline this invitation.
My suggestion only pertains to Org mode's defaults.  Learning Emacs (or
Org) themes and further playing in this area would be a non-negligible
distraction for me.

François

P.S. I'm a happy Org mode user, but I do not aspire to become a
maintainer :-).

Re: Capitalisation and good taste ?

[Bastien]

Bastien <bzg@altern.org> writes:

> Actually, I'm thinking of another solution:
>
> - keep one-line option/environment keywords uppercase
>   #+NAME
>   #+HTML
>   #+TITLE
>   #+...
>
> - use lowercase for multi-lines environments keywords
>   #+begin_ascii
>   #+begin_html
>   #+results
>
> This is the only good criterium I can think of, and that
> way people using easy templates will not be surprised to
> see #+begin_xxx in the manual.

I tried this and I find the lowercase #+begin_xxx really
not readable enough in the manual.   So I use #+RESULTS:
and explained this convention in the manual.

-- 
 Bastien

Re: Capitalisation and good taste ?

[Eric Schulte]

Bastien <bzg@altern.org> writes:

> Bastien <bzg@altern.org> writes:
>
>> Actually, I'm thinking of another solution:
>>
>> - keep one-line option/environment keywords uppercase
>>   #+NAME
>>   #+HTML
>>   #+TITLE
>>   #+...
>>
>> - use lowercase for multi-lines environments keywords
>>   #+begin_ascii
>>   #+begin_html
>>   #+results
>>
>> This is the only good criterium I can think of, and that
>> way people using easy templates will not be surprised to
>> see #+begin_xxx in the manual.
>
> I tried this and I find the lowercase #+begin_xxx really
> not readable enough in the manual.   So I use #+RESULTS:
> and explained this convention in the manual.

Sounds good.

While I like the proposed distinction above, I'd just as soon have
Org-mode default to all caps in the manual and in practice.  As noted
before individual users can use lower case at the mercy of their (our)
potentially changing whims.

I'm going to push up a patch which will change to inserting #+RESULTS:
by default as well as a user-configurable variable which can be used to
customize this behavior.

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

Re: Capitalisation and good taste ?

[Eric Schulte]

>
> I'm going to push up a patch which will change to inserting #+RESULTS:
> by default as well as a user-configurable variable which can be used to
> customize this behavior.

Done.  This variable is named `org-babel-results-keyword'

,----
| org-babel-results-keyword's value is "RESULTS"
| 
| Documentation:
| Keyword used to name results generated by code blocks.
| Should be either RESULTS or NAME however any capitalization may
| be used.
| 
| You can customize this variable.
| 
| [back]
`----

Best,

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

[PATCH] Re: Capitalisation and good taste ?

[Thomas S. Dye]

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

Aloha all,

The attached patch to the manual includes information on the RESULTS
keyword.

All the best,
Tom


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Manual patch --]
[-- Type: text/x-patch, Size: 2109 bytes --]

From 7fbabd20ed1477e706633945c98400ee48fb0ab2 Mon Sep 17 00:00:00 2001
From: Thomas Dye <dk@poto.myhome.westell.com>
Date: Wed, 11 Jan 2012 11:23:19 -1000
Subject: [PATCH] * doc/org.texi: #+RESULTS now user-configurable

---
 doc/org.texi |   17 ++++++++++++-----
 1 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index a9f0139..2229358 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -12629,17 +12629,24 @@ of tangled code files.
 @section Evaluating code blocks
 @cindex code block, evaluating
 @cindex source code, evaluating
+@cindex #+RESULTS
 
 Code blocks can be evaluated@footnote{Whenever code is evaluated there is a
 potential for that code to do harm.  Org mode provides safeguards to ensure
 that code is only evaluated after explicit confirmation from the user.  For
 information on these safeguards (and on how to disable them) see @ref{Code
 evaluation security}.} and the results of evaluation optionally placed in the
-Org mode buffer.  By default, the evaluation facility is only enabled for
-Lisp code blocks specified as @code{emacs-lisp}. However, source code blocks
-in many languages can be evaluated within Org mode (see @ref{Languages} for a
-list of supported languages and @ref{Structure of code blocks} for
-information on the syntax used to define a code block).
+Org mode buffer.  The results of evaluation are placed following a line that
+begins by default with @code{#+RESULTS} and optionally a cache identifier
+and/or the name of the evaluated code block.  The default value of
+@code{#+RESULTS} can be changed with the customizable variable
+@code{org-babel-results-keyword}. 
+
+By default, the evaluation facility is only enabled for Lisp code blocks
+specified as @code{emacs-lisp}. However, source code blocks in many languages
+can be evaluated within Org mode (see @ref{Languages} for a list of supported
+languages and @ref{Structure of code blocks} for information on the syntax
+used to define a code block).
 
 @kindex C-c C-c
 There are a number of ways to evaluate code blocks.  The simplest is to press
-- 
1.7.5.4


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


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

>>
>> I'm going to push up a patch which will change to inserting #+RESULTS:
>> by default as well as a user-configurable variable which can be used to
>> customize this behavior.
>
> Done.  This variable is named `org-babel-results-keyword'
>
> ,----
> | org-babel-results-keyword's value is "RESULTS"
> | 
> | Documentation:
> | Keyword used to name results generated by code blocks.
> | Should be either RESULTS or NAME however any capitalization may
> | be used.
> | 
> | You can customize this variable.
> | 
> | [back]
> `----
>
> Best,

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

Re: [PATCH] Re: Capitalisation and good taste ?

[Eric Schulte]

Fantastic, I've just applied this patch, Thanks

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

> Aloha all,
>
> The attached patch to the manual includes information on the RESULTS
> keyword.
>
> All the best,
> Tom
>
>
>
> Eric Schulte <eric.schulte@gmx.com> writes:
>
>>>
>>> I'm going to push up a patch which will change to inserting #+RESULTS:
>>> by default as well as a user-configurable variable which can be used to
>>> customize this behavior.
>>
>> Done.  This variable is named `org-babel-results-keyword'
>>
>> ,----
>> | org-babel-results-keyword's value is "RESULTS"
>> | 
>> | Documentation:
>> | Keyword used to name results generated by code blocks.
>> | Should be either RESULTS or NAME however any capitalization may
>> | be used.
>> | 
>> | You can customize this variable.
>> | 
>> | [back]
>> `----
>>
>> Best,

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

Re: Capitalisation and good taste ?

[Bastien]

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

>> I'm going to push up a patch which will change to inserting #+RESULTS:
>> by default as well as a user-configurable variable which can be used to
>> customize this behavior.
>
> Done.  This variable is named `org-babel-results-keyword'

Great, thanks.  I've also changed the default value of
`org-structure-template-alist' so that easy templates are 
using uppercase by default.  If people prefer lowercase,
please customize this option.

-- 
 Bastien

Re: Capitalisation and good taste ?

[François Pinard]

Bernt Hansen <bernt@norang.ca> writes:

> pinard@iro.umontreal.ca (François Pinard) writes:

>> I really have mixed feelings about capitalisation of #+WORDS, and
>> wonder if some consensus and good taste has developed over time among
>> Org mode users.

> A long time ago all capitals was the only way these keywords were
> supported.

Thanks, Bernt, for the historical perspective!

> I wouldn't spend too much time agonizing over the 'right' way

Truth is that I've been so agonizing for the whole of my computer life!
Each one his sickness, I guess... :-)

Keep happy!

François

P.S. Who, by the way, felt glad and relieved recently, seeing many
commits by Bastien correcting lots of spurious trailing white space. :-)

Should I say, I notice a strong correlation between rotten software and
the lack of attention to such details.  I'm not saying that avoiding
trailing white space is a guarantee of good software.  But I'm saying
that people unwilling to pay attention to details are not prone to pay
attention for a lot of other things, which is not good for software.

Re: Capitalisation and good taste ?

[Tommy Kelly]

Hey François,

bh >> I wouldn't spend too much time agonizing over the 'right' way

fp> Truth is that I've been so agonizing for the whole of my computer
fp >life! Each one his sickness, I guess... :-)

I understand your pain. Have you read "The Paradox of Choice" by Bary
Schwartz? Sounds as if you (like me) are a Maximizer on this kind of
thing :-). As a fellow sufferer, let me put you out of your misery and
choose for you:

First, let's acknowledge the primary raison d'etre of capitals is to
enhance ease of reading by making one class of word stand out in an
environment where -- crucially -- more than one class of word may be
present (e.g. starts of sentences in block of prose, or constants
(say) in code).

So here, it doesn't really matter. Therefore, let's make ease of
"writing" be the deciding factor.

> #+latex_header:

Best (it would be even better if that underscore was a hyphen but we
can't have everything).


> #+LATEX_HEADER:

Next best


> #+Latex_Header:

Worse.


> #+LaTeX_HEADER:

Worst. Yeah, yeah, it's "correct" but I'm not hitting Shift three
times when I can hit it no times :-)

toMmY

Re: Capitalisation and good taste ?

[Eric S Fraga]

pinard@iro.umontreal.ca (François Pinard) writes:

[...]

> Should I say, I notice a strong correlation between rotten software and
> the lack of attention to such details.  I'm not saying that avoiding
> trailing white space is a guarantee of good software.  But I'm saying
> that people unwilling to pay attention to details are not prone to pay
> attention for a lot of other things, which is not good for software.

What is interesting, to me, is that some of these details come down to
style preferences *and* that these preferences can change dramatically
over time.  I have been programming for 35+ years and it's scary to see
how my preferences have changed, sometimes cycling several times with a
period of 5 or more years!

I am thinking especially about things like indentation rules, blank
lines, multi-line versus single line comments, variable names, case
(cf. this thread), etc.  Of course, the language in use affects the
choices available but there are always choices, none of which is
automatically and permanently correct.

cheers,
eric

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.92.1
: using Org-mode version 7.8.03 (release_7.8.03.73.gd2b3d)

Re: Capitalisation and good taste ?

[Sankalp]

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

2012/1/11 Eric S Fraga <e.fraga@ucl.ac.uk>

> pinard@iro.umontreal.ca (François Pinard) writes:
>
> [...]
>
> > Should I say, I notice a strong correlation between rotten software and
> > the lack of attention to such details.  I'm not saying that avoiding
> > trailing white space is a guarantee of good software.  But I'm saying
> > that people unwilling to pay attention to details are not prone to pay
> > attention for a lot of other things, which is not good for software.
>
> What is interesting, to me, is that some of these details come down to
> style preferences *and* that these preferences can change dramatically
> over time.  I have been programming for 35+ years and it's scary to see
> how my preferences have changed, sometimes cycling several times with a
> period of 5 or more years!
>
> I am thinking especially about things like indentation rules, blank
> lines, multi-line versus single line comments, variable names, case
> (cf. this thread), etc.  Of course, the language in use affects the
> choices available but there are always choices, none of which is
> automatically and permanently correct.
>
> cheers,
> eric
>
> --
> : Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.92.1
> : using Org-mode version 7.8.03 (release_7.8.03.73.gd2b3d)
>
>
Thanks for the awesome Donald Knuth Video François, a must watch for folks
who love TeX and its wrappers.

Don't have much to say for the Caps convention, except that the criterion
suggested by Bastien seems fair enough.

Regards,
Sankalp

[-- Attachment #2: Type: text/html, Size: 2752 bytes --]

Re: Capitalisation and good taste ?

[Leo Alekseyev]

> A long time ago all capitals was the only way these keywords were
> supported.  Since then they have become case insensitive and I use all
> lowercase for most of my keywords now (#+begin_src:, #+begin_example:
> etc)
>
> With fontification these stand out enough now and the capitalization can
> be removed.

So I'm kind of late to this party, but like Bernt, I've been favoring
lowercase #+ keywords; I believe it looks cleaner and easier on the
eyes.  However, if functions that autogenerate keywords (e.g.
#+results from code blocks and easy templates) default to a particular
case, forcing a different case as a user becomes unappealing
(consistency trumps aesthetics).

If we want to keep org truly keyword-case-agnostic, then there should
be a user-customized variable that easy templates and org-babel result
blocks would follow.

--Leo

Re: Capitalisation and good taste ?

[Bernt Hansen]

Leo Alekseyev <dnquark@gmail.com> writes:

>> A long time ago all capitals was the only way these keywords were
>> supported.  Since then they have become case insensitive and I use all
>> lowercase for most of my keywords now (#+begin_src:, #+begin_example:
>> etc)
>>
>> With fontification these stand out enough now and the capitalization can
>> be removed.
>
> So I'm kind of late to this party, but like Bernt, I've been favoring
> lowercase #+ keywords; I believe it looks cleaner and easier on the
> eyes.  However, if functions that autogenerate keywords (e.g.
> #+results from code blocks and easy templates) default to a particular
> case, forcing a different case as a user becomes unappealing
> (consistency trumps aesthetics).
>
> If we want to keep org truly keyword-case-agnostic, then there should
> be a user-customized variable that easy templates and org-babel result
> blocks would follow.

I added the following to my .emacs to keep lowercase.

(setq org-babel-results-keyword "results")

(setq org-structure-template-alist
      (quote (("s" "#+begin_src ?\n\n#+end_src" "<src lang=\"?\">\n\n</src>")
	      ("e" "#+begin_example\n?\n#+end_example" "<example>\n?\n</example>")
	      ("q" "#+begin_quote\n?\n#+end_quote" "<quote>\n?\n</quote>")
	      ("v" "#+begin_verse\n?\n#+end_verse" "<verse>\n?\n/verse>")
	      ("c" "#+begin_center\n?\n#+end_center" "<center>\n?\n/center>")
	      ("l" "#+begin_latex\n?\n#+end_latex" "<literal style=\"latex\">\n?\n</literal>")
	      ("L" "#+latex: " "<literal style=\"latex\">?</literal>")
	      ("h" "#+begin_html\n?\n#+end_html" "<literal style=\"html\">\n?\n</literal>")
	      ("H" "#+html: " "<literal style=\"html\">?</literal>")
	      ("a" "#+begin_ascii\n?\n#+end_ascii")
	      ("A" "#+ascii: ")
	      ("i" "#+index: ?" "#+index: ?")
	      ("I" "#+include %file ?" "<include file=%file markup=\"?\">"))))

-Bernt

Re: Capitalisation and good taste ?

[Eric S Fraga]

Bernt Hansen <bernt@norang.ca> writes:


[...]

> I added the following to my .emacs to keep lowercase.

Thanks.  This is a great suggestion!  Two possible typos, by the way,
that would only affect you if you use muse tags:

> 	      ("v" "#+begin_verse\n?\n#+end_verse" "<verse>\n?\n/verse>")
> 	      ("c" "#+begin_center\n?\n#+end_center" "<center>\n?\n/center>")

Missing "<" for closing tag in each case, after last \n.

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.92.1
: using Org-mode version 7.8.03 (release_7.8.03.179.ge760)

Re: Capitalisation and good taste ?

[Bernt Hansen]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Bernt Hansen <bernt@norang.ca> writes:
>
>
> [...]
>
>> I added the following to my .emacs to keep lowercase.
>
> Thanks.  This is a great suggestion!  Two possible typos, by the way,
> that would only affect you if you use muse tags:
>
>> 	      ("v" "#+begin_verse\n?\n#+end_verse" "<verse>\n?\n/verse>")
>> 	      ("c" "#+begin_center\n?\n#+end_center" "<center>\n?\n/center>")
>
> Missing "<" for closing tag in each case, after last \n.

I just took the default setting and lowercased it without actually
looking closely at it -- so I think the problem is in the defcustom in
org.el for org-structure-template-alist too.

Regards,
Bernt

Re: Capitalisation and good taste ?

[Eric S Fraga]

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

Bernt Hansen <bernt@norang.ca> writes:

> Eric S Fraga <e.fraga@ucl.ac.uk> writes:
>
>> Bernt Hansen <bernt@norang.ca> writes:
>>
>>
>> [...]
>>
>>> I added the following to my .emacs to keep lowercase.
>>
>> Thanks.  This is a great suggestion!  Two possible typos, by the way,
>> that would only affect you if you use muse tags:
>>
>>> 	      ("v" "#+begin_verse\n?\n#+end_verse" "<verse>\n?\n/verse>")
>>> 	      ("c" "#+begin_center\n?\n#+end_center" "<center>\n?\n/center>")
>>
>> Missing "<" for closing tag in each case, after last \n.
>
> I just took the default setting and lowercased it without actually
> looking closely at it -- so I think the problem is in the defcustom in
> org.el for org-structure-template-alist too.
>
> Regards,
> Bernt

Indeed.  Attached is a very simple patch to fix these missing "<"s.  Untested.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Add missing angle brackets for muse export style --]
[-- Type: text/x-diff, Size: 585 bytes --]

diff --git a/lisp/org.el b/lisp/org.el
index f6a1160..f47a104 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -11031,9 +11031,9 @@ This function can be used in a hook."
     ("q" "#+BEGIN_QUOTE\n?\n#+END_QUOTE"
          "<quote>\n?\n</quote>")
     ("v" "#+BEGIN_VERSE\n?\n#+END_VERSE"
-         "<verse>\n?\n/verse>")
+         "<verse>\n?\n</verse>")
     ("c" "#+BEGIN_CENTER\n?\n#+END_CENTER"
-         "<center>\n?\n/center>")
+         "<center>\n?\n</center>")
     ("l" "#+BEGIN_LaTeX\n?\n#+END_LaTeX"
          "<literal style=\"latex\">\n?\n</literal>")
     ("L" "#+LaTeX: "

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


-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.90.1
: using Org-mode version 7.8.03 (release_7.8.03.192.g32af.dirty)

Re: Capitalisation and good taste ?

[Bastien]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Indeed.  Attached is a very simple patch to fix these missing
> "<"s.  Untested.

Applied, thanks a lot!

-- 
 Bastien

Re: Capitalisation and good taste ?

[Eric S Fraga]

pinard@iro.umontreal.ca (François Pinard) writes:

> Hi, Org people.
>
> I really have mixed feelings about capitalisation of #+WORDS, and wonder
> if some consensus and good taste has developed over time among Org mode
> users.  What is the collective wisdom saying as being nicer among:

[...]

> Maybe this has already been debated to death?  I do not know for Org
> mode files, yet I know that style issues are usually flame-prone.  I'm
> surely not trying to start any kind of war.  Nevertheless, I would like
> if the manual and the Wiki select and document a preferred convention,
> and were amended to be very consistent on it.  So, I'll have a clear
> model to follow. :-)
>
> François

I have problems with RSI so try to minimise any key-chording, including
capital letters, as much as possible (hence my use of evil-mode in emacs
and extensive use of both completion and abbreviations for acronyms...).

But I am happy for everybody to use what they prefer and I am just happy
that org is case insensitive in general!


-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.92.1
: using Org-mode version 7.8.03 (release_7.8.03.73.gd2b3d)