From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Re: A simpler way to write literal examples? Date: Wed, 1 Jun 2011 09:29:18 +0200 Message-ID: <4B55F606-7151-4F20-A51E-DF6D5F6DEB0D@gmail.com> References: Mime-Version: 1.0 (Apple Message framework v1084) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([140.186.70.92]:49516) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRfrq-0006NT-U6 for emacs-orgmode@gnu.org; Wed, 01 Jun 2011 03:29:27 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QRfrn-0006Wm-Ei for emacs-orgmode@gnu.org; Wed, 01 Jun 2011 03:29:26 -0400 Received: from mail-ey0-f169.google.com ([209.85.215.169]:38964) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRfrn-0006Wc-AV for emacs-orgmode@gnu.org; Wed, 01 Jun 2011 03:29:23 -0400 Received: by eyd9 with SMTP id 9so2128908eyd.0 for ; Wed, 01 Jun 2011 00:29:21 -0700 (PDT) In-Reply-To: List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Steven Haryanto Cc: emacs-orgmode@gnu.org On 25.5.2011, at 11:43, Steven Haryanto wrote: > I plan to document some parts of Perl source code (more specifically, = description in subroutine Sub::Spec specification, = http://search.cpan.org/dist/Sub-Spec) using Org format instead of the = canonical POD, hoping to have better table support, more customizable = links, and overall markups that are nicer to look at (IMO). >=20 > However, one of the nice things of POD (and Wiki, Markdown, etc) for = documenting source code is the relative simplicity of writing literal = examples: an indented paragraph. In Org we either have to use the = colon+space prefix syntax: >=20 > : this is an example > : another line > : another line >=20 > or the example block: >=20 > #+BEGIN_EXAMPLE > this is an example > another line > another line > #+END_EXAMPLE >=20 > Is there an alternative syntax? If there isn't, would people consider = an alternative syntax (e.g. say a setting which toggles parsing an = indented paragraph as a literal example)? No, since indentation has other uses in org (for example for list = structure). I find it often helps to write #+begin_example instead of = #+BEGIN_EXAMPLE. I guess one could set up font-lock to hide the #+begin and #+end lines, = but how would you then change them. The bug advantage in Org is that you can say #+begin_src perl to get correct indentation and syntax highlighting to the language of = the snippet..... - Carsten