Language identifiers

Language identifiers

[François Pinard]

Hello, Org people.

Seeing again the (org) Languages node in the manual, I decided to check
all my #+BEGIN_SRC for language tags, which I too often improvise, for
normalizing them.  I noticed a few things, and wonder if the manual
should be amended, or if I should change my habits instead.

- I was using lower case "c" and "r", while the manual suggests
  upper case "C" and "R" instead.  Both seem to work (in Emacs at
  least).  Should the manual be amended to say that case does not
  matter?  If then, should the manual stick uniformly to lower case?

- The identifier in the left column did not work, but if I change it to
  the identifier in the right column, the content highlights (in
  Emacs).  The manual does not list it.

  | config     | conf     |
  | email      | mail     |
  | make       | makefile |
  | postscript | ps       |

- I was using "elisp" instead of "emacs-lisp" and "javascript" instead
  of "js".  Both seem to work (in Emacs at least).  If there are many
  alternate languages identifiers for a language, should the manual list
  all acceptable identifiers?

- Tag "xml" seems to work nicely (within Emacs).  The manual does not
  list it.

I wonder what "are supported" really means, in the first sentence.
Maybe the fact that Emacs supports a language tag does not mean that Org
supports it?  Maybe exporters would fail to render them nicely?  Maybe a
few more words could be added to the page for explaining what users
should expect, or not expect.  Currently, I do not know whether if the
list is missing a few identifiers, or if I'm not using them properly.

Other tiny details about the table at the beginning of this Info page.
It would be clearer if there was a separating line between the title
line and the table contents.  A vertical line separating both halves
would be welcome too, one has to take a few seconds to understand that
this is a two column table, each column itself holding two columns.
Finally, the sorted entries are presented row wise in this two column
table; the table would be easier to consult if the sorted entries were
presented column wise instead.

François

Re: Language identifiers

[Thomas S. Dye]

Aloha François,

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

> Hello, Org people.
>
> Seeing again the (org) Languages node in the manual, I decided to check
> all my #+BEGIN_SRC for language tags, which I too often improvise, for
> normalizing them.  I noticed a few things, and wonder if the manual
> should be amended, or if I should change my habits instead.
>
> - I was using lower case "c" and "r", while the manual suggests
>   upper case "C" and "R" instead.  Both seem to work (in Emacs at
>   least).  Should the manual be amended to say that case does not
>   matter?  If then, should the manual stick uniformly to lower case?
>
> - The identifier in the left column did not work, but if I change it to
>   the identifier in the right column, the content highlights (in
>   Emacs).  The manual does not list it.
>
>   | config     | conf     |
>   | email      | mail     |
>   | make       | makefile |
>   | postscript | ps       |

"The core Babel functions (viewing, export, tangling, etc…) are language
agnostic and will work even for languages that are not explicitly
supported. Explicit language-specific support is required only for
evaluation of code blocks in a language."  See
http://orgmode.org/worg/org-contrib/babel/languages.html.
>
> - I was using "elisp" instead of "emacs-lisp" and "javascript" instead
>   of "js".  Both seem to work (in Emacs at least).  If there are many
>   alternate languages identifiers for a language, should the manual list
>   all acceptable identifiers?
>
> - Tag "xml" seems to work nicely (within Emacs).  The manual does not
>   list it.
>
> I wonder what "are supported" really means, in the first sentence.
> Maybe the fact that Emacs supports a language tag does not mean that Org
> supports it?  Maybe exporters would fail to render them nicely?  Maybe a
> few more words could be added to the page for explaining what users
> should expect, or not expect.  Currently, I do not know whether if the
> list is missing a few identifiers, or if I'm not using them properly.
>

See above.  Suggested revisions to the sentence are welcome.  I believe
I wrote the sentence, but Eric S. will review and decide whether or not
to make changes.

> Other tiny details about the table at the beginning of this Info page.
> It would be clearer if there was a separating line between the title
> line and the table contents.  A vertical line separating both halves
> would be welcome too, one has to take a few seconds to understand that
> this is a two column table, each column itself holding two columns.
> Finally, the sorted entries are presented row wise in this two column
> table; the table would be easier to consult if the sorted entries were
> presented column wise instead.
>

I totally agree.  Do you know how to do this in texinfo?  Can you
propose a patch?

All the best,
Tom

> François
>
>
>

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

Re: Language identifiers

[François Pinard]

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

> Aloha François,

:-)

> Do you know how to do this in texinfo?

If I had to do this, I would search around to see if there is an Org to
Texinfo exporter, and then blindly / fully rely on it to do various
wonders automatically! ;-) I did not check, but presume that the current
manual original is directly written in Texinfo?

More seriously, I did not write Texinfo in a lot of years, and do not
even remember how we do tables with it.  Tables might have been added
after my time, I'm not sure.  What I would likely do, given the problem,
is merely to format the table myself in fixed font, and use @example /
@end example around it (if I remember well, @example generates <pre>).
Would that be acceptable?

I could offer that simple formatting if it could help, I presume it is
likely a simple job for anybody.  The problem for me is rather to know
what contents should go in there.  Write to me privately if you think I
could be more of an help than a burden. :-)

François

Re: Language identifiers

[Nick Dokos]

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

> If I had to do this, I would search around to see if there is an Org to
> Texinfo exporter, and then blindly / fully rely on it to do various
> wonders automatically! ;-) I did not check, but presume that the current
> manual original is directly written in Texinfo?
> 
That's correct: that's a requirement for being an official emacs package
I believe.

> More seriously, I did not write Texinfo in a lot of years, and do not
> even remember how we do tables with it.  Tables might have been added
> after my time, I'm not sure.  What I would likely do, given the problem,
> is merely to format the table myself in fixed font, and use @example /
> @end example around it (if I remember well, @example generates <pre>).
> Would that be acceptable?
> 
> I could offer that simple formatting if it could help, I presume it is
> likely a simple job for anybody.  The problem for me is rather to know
> what contents should go in there.  Write to me privately if you think I
> could be more of an help than a burden. :-)
> 

You don't really need to know texinfo: just look at relevant place(s)
in doc/org.texi, and munge it until it does what you want :-)

Nick

Re: Language identifiers

[François Pinard]

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

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

>> If I had to do this, I would search around to see if there is an Org to
>> Texinfo exporter, and then blindly / fully rely on it to do various
>> wonders automatically! ;-) I did not check, but presume that the current
>> manual original is directly written in Texinfo?

> That's correct: that's a requirement for being an official emacs package
> I believe.

If the real source of the manual was in Org format, and periodically and
mechanically turned into a Texinfo file, would the requirement be met?

Merely curious,

François

Re: Language identifiers

[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:
> 
> >> If I had to do this, I would search around to see if there is an Org to
> >> Texinfo exporter, and then blindly / fully rely on it to do various
> >> wonders automatically! ;-) I did not check, but presume that the current
> >> manual original is directly written in Texinfo?
> 
> > That's correct: that's a requirement for being an official emacs package
> > I believe.
> 
> If the real source of the manual was in Org format, and periodically and
> mechanically turned into a Texinfo file, would the requirement be met?
> 

Yes, but somebody would have to write a good texinfo exporter.

Nick

Re: Language identifiers

[François Pinard]

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

>> If the real source of the manual was in Org format, and periodically and
>> mechanically turned into a Texinfo file, would the requirement be met?

> Yes, but somebody would have to write a good texinfo exporter.

Oh!  I did not even know that none exist yet.  Well, indeed, that's a
problem! :-)

Ah!  If I only had more time, I would dive right away and start writing
one.  *Still dreaming awake*, that would be a wonderful opportunity for
me to learn the new exporter which, according to what I've read on this
list, fixes an opinion about what is the proper structural analysis of
an Org file.  My usual language is Python, which I came to much prefer
over Emacs Lisp, years ago.  Proof is that I once wrote something so I
can extend Emacs with Python instead of Lisp.  A good way to study the
new exporter's opinion would be for me to write a Python parser which
yields exactly the same analysis.  That parser could usefully replace
many Python scripts here which decipher Org files according to my mental
fuzzy approximations of its syntax.  Second, writing a Texinfo exporter
would be a pleasurable incentive to check its usefulness. :-)

Sigh!

François

Re: Language identifiers

[Bastien]

Hi François,

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

> A good way to study the
> new exporter's opinion would be for me to write a Python parser which
> yields exactly the same analysis.  That parser could usefully replace
> many Python scripts here which decipher Org files according to my mental
> fuzzy approximations of its syntax.

You can start from this existing python parser:
  http://members.optusnet.com.au/~charles57/GTD/orgnode.html

It's referenced here:
  http://orgmode.org/worg/org-tools/index.html

HTH,

-- 
 Bastien

Re: Language identifiers

[Sebastien Vauban]

Hi François and all,

François Pinard wrote:
> - I was using lower case "c" and "r", while the manual suggests
>   upper case "C" and "R" instead.  Both seem to work (in Emacs at
>   least).  Should the manual be amended to say that case does not
>   matter?  If then, should the manual stick uniformly to lower case?
>
> - The identifier in the left column did not work, but if I change it to
>   the identifier in the right column, the content highlights (in
>   Emacs).  The manual does not list it.
>
>   | config     | conf     |
>   | email      | mail     |
>   | make       | makefile |
>   | postscript | ps       |

A small note: FYI, the capitalization is not "optional". For example, for a
Makefile chunk of code, the language must be set to `makefile' (not
`Makefile'!) for correct highlighting to work.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Language identifiers

[Eric Schulte]

>
> - The identifier in the left column did not work, but if I change it to
>   the identifier in the right column, the content highlights (in
>   Emacs).  The manual does not list it.
>
>   | config     | conf     |
>   | email      | mail     |
>   | make       | makefile |
>   | postscript | ps       |
>

For code block fontification, Org-mode looks to see if there exists a
major mode with the name lang-mode.  So, the reason some of the above
work, and some don't is because the right columns all name valid major
modes while the left column does not.

There also exists a variable named `org-src-lang-modes' which may be
used to explicitly associate particular language identifiers with
particular modes, so if for example you prefer to use email to mail you
can simply add the following to your config.

    ;; emacs-lisp
    (add-to-list 'org-src-lang-modes (cons "email" mail))

Best,

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