From mboxrd@z Thu Jan 1 00:00:00 1970 From: Steven Haryanto Subject: A simpler way to write literal examples? Date: Wed, 25 May 2011 16:43:30 +0700 Message-ID: Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=20cf303b3cc185932b04a416893c Return-path: Received: from eggs.gnu.org ([140.186.70.92]:59814) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QPFrU-0000Vj-Ae for emacs-orgmode@gnu.org; Wed, 25 May 2011 11:19:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QPFrT-00045T-3E for emacs-orgmode@gnu.org; Wed, 25 May 2011 11:19:04 -0400 Received: from mail-gy0-f169.google.com ([209.85.160.169]:40838) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QPFrT-00043t-0Z for emacs-orgmode@gnu.org; Wed, 25 May 2011 11:19:03 -0400 Received: by gyd8 with SMTP id 8so3871079gyd.0 for ; Wed, 25 May 2011 08:18:55 -0700 (PDT) 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: emacs-orgmode@gnu.org --20cf303b3cc185932b04a416893c Content-Type: text/plain; charset=ISO-8859-1 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). 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: : this is an example : another line : another line or the example block: #+BEGIN_EXAMPLE this is an example another line another line #+END_EXAMPLE 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)? -- sh --20cf303b3cc185932b04a416893c Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable I plan to document some parts of Perl source code (more specifically, descr= iption in subroutine Sub::Spec specification,=A0http://search.cpan.org/dist/Sub-Spec) using Org f= ormat instead of the canonical POD, hoping to have better table support, mo= re customizable links, and overall markups that are nicer to look at (IMO).=

However, one of the nice things of POD (and Wiki, Markdown, = etc) for documenting source code is the relative simplicity of writing lite= ral examples: an indented paragraph. In Org we either have to use the colon= +space prefix syntax:

=A0: this is an example
=A0: another line
=A0: another line

or the example block:

=A0#+BEGIN_EXAMPLE
=A0this is an example
=A0another line
=A0another line
=A0#+END_EXAMPLE
<= div>
Is there an alternative syntax? If there isn't, woul= d people consider an alternative syntax (e.g. say a setting which toggles p= arsing an indented paragraph as a literal example)?

--
sh
--20cf303b3cc185932b04a416893c-- From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nick Dokos Subject: Re: A simpler way to write literal examples? Date: Wed, 25 May 2011 11:25:08 -0400 Message-ID: <13042.1306337108@alphaville.dokosmarshall.org> References: Reply-To: nicholas.dokos@hp.com Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([140.186.70.92]:52180) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QPFxn-0003jW-S5 for emacs-orgmode@gnu.org; Wed, 25 May 2011 11:25:37 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QPFxl-0006ev-Sz for emacs-orgmode@gnu.org; Wed, 25 May 2011 11:25:35 -0400 Received: from vms173001pub.verizon.net ([206.46.173.1]:64720) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QPFxl-0006bx-Nx for emacs-orgmode@gnu.org; Wed, 25 May 2011 11:25:33 -0400 Received: from alphaville.dokosmarshall.org ([unknown] [173.76.32.106]) by vms173001.mailsrvcs.net (Sun Java(tm) System Messaging Server 7u2-7.02 32bit (built Apr 16 2009)) with ESMTPA id <0LLR002URC5W1R30@vms173001.mailsrvcs.net> for emacs-orgmode@gnu.org; Wed, 25 May 2011 10:25:14 -0500 (CDT) In-reply-to: Message from Steven Haryanto of "Wed\, 25 May 2011 16\:43\:30 +0700." 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: nicholas.dokos@hp.com, emacs-orgmode@gnu.org Steven Haryanto wrote: > I plan to document some parts of Perl source code (more specifically, des= cription in subroutine > Sub::Spec specification,=C2=A0http://search.cpan.org/dist/Sub-Spec) using= Org format instead of the > canonical POD, hoping to have better table support, more customizable lin= ks, and overall markups > that are nicer to look at (IMO). >=20 > However, one of the nice things of POD (and Wiki, Markdown, etc) for docu= menting source code is the > relative simplicity of writing literal examples: an indented paragraph. I= n Org we either have to use > the colon+space prefix syntax: >=20 > =C2=A0: this is an example > =C2=A0: another line > =C2=A0: another line >=20 > or the example block: >=20 > =C2=A0#+BEGIN_EXAMPLE > =C2=A0this is an example > =C2=A0another line > =C2=A0another line > =C2=A0#+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 ex= ample)? >=20 What is the problem with #+BEGIN_EXAMPLE/#+END_EXAMPLE? IOW, why do you need an alternative syntax? If your answer is "too much typing", check out section 15.2, "Easy templates", in the Org manual. Nick From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Schulte Subject: Re: A simpler way to write literal examples? Date: Wed, 25 May 2011 10:01:05 -0600 Message-ID: <87hb8ihiri.fsf@gmail.com> References: <13042.1306337108@alphaville.dokosmarshall.org> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([140.186.70.92]:57983) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QPGWJ-0002kj-7j for emacs-orgmode@gnu.org; Wed, 25 May 2011 12:01:16 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QPGWH-0008Ei-Nr for emacs-orgmode@gnu.org; Wed, 25 May 2011 12:01:15 -0400 Received: from mail-pw0-f41.google.com ([209.85.160.41]:46042) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QPGWH-0008Di-IA for emacs-orgmode@gnu.org; Wed, 25 May 2011 12:01:13 -0400 Received: by pwi12 with SMTP id 12so4683435pwi.0 for ; Wed, 25 May 2011 09:01:12 -0700 (PDT) In-Reply-To: <13042.1306337108@alphaville.dokosmarshall.org> (Nick Dokos's message of "Wed, 25 May 2011 11:25:08 -0400") 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: nicholas.dokos@hp.com Cc: Steven Haryanto , emacs-orgmode@gnu.org > > What is the problem with #+BEGIN_EXAMPLE/#+END_EXAMPLE? IOW, why do you need > an alternative syntax? If your answer is "too much typing", check out > section 15.2, "Easy templates", in the Org manual. > Also, see the function `org-toggle-fixed-width-section' bound to (C-c :) Best -- Eric -- Eric Schulte http://cs.unm.edu/~eschulte/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Steven Haryanto Subject: Re: A simpler way to write literal examples? Date: Wed, 1 Jun 2011 08:53:16 +0700 Message-ID: References: <13042.1306337108@alphaville.dokosmarshall.org> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary=bcaec5016035c0ffe104a49cc84a Return-path: Received: from eggs.gnu.org ([140.186.70.92]:55226) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRbjV-0003CS-9b for emacs-orgmode@gnu.org; Tue, 31 May 2011 23:04:34 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QRbjT-0003J2-Ud for emacs-orgmode@gnu.org; Tue, 31 May 2011 23:04:33 -0400 Received: from mail-vw0-f41.google.com ([209.85.212.41]:39498) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QRacX-0001Ln-UY for emacs-orgmode@gnu.org; Tue, 31 May 2011 21:53:18 -0400 Received: by vws4 with SMTP id 4so4973798vws.0 for ; Tue, 31 May 2011 18:53:16 -0700 (PDT) In-Reply-To: <13042.1306337108@alphaville.dokosmarshall.org> 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: nicholas.dokos@hp.com Cc: emacs-orgmode@gnu.org --bcaec5016035c0ffe104a49cc84a Content-Type: text/plain; charset=ISO-8859-1 On Wed, May 25, 2011 at 10:25 PM, Nick Dokos wrote: > 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). > > > > 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: > > > > : this is an example > > : another line > > : another line > > > > or the example block: > > > > #+BEGIN_EXAMPLE > > this is an example > > another line > > another line > > #+END_EXAMPLE > > > > 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)? > > > > What is the problem with #+BEGIN_EXAMPLE/#+END_EXAMPLE? IOW, why do you > need > an alternative syntax? If your answer is "too much typing", check out > section 15.2, "Easy templates", in the Org manual. The problem is visual clutter (yes, I guess Emacs can be told to hide the markup, but I'm talking about when text is displayed as-is and/or outside Emacs) and copy-pasteability (especially with the colon syntax). I know Org format is not optimized for fixed width section, but perhaps there is a way? -- sh --bcaec5016035c0ffe104a49cc84a Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
On Wed, May 25, 2011 at 10:25 PM, Nick Dokos <nicholas.dokos@= hp.com> wrote:
Steven Haryanto <stevenharyanto@gmail.com> wrote:

> I plan to document some parts of Perl source code (more specifically, = description in subroutine
> Sub::Spec specification,=A0http://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).
>
> However, one of the nice things of POD (and Wiki, Markdown, etc) for d= ocumenting 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:
>
> =A0: this is an example
> =A0: another line
> =A0: another line
>
> or the example block:
>
> =A0#+BEGIN_EXAMPLE
> =A0this is an example
> =A0another line
> =A0another line
> =A0#+END_EXAMPLE
>
> Is there an alternative syntax? If there isn't, would people consi= der an alternative syntax (e.g.
> say a setting which toggles parsing an indented paragraph as a literal= example)?
>

What is the problem with #+BEGIN_EXAMPLE/#+END_EXAMPLE? IOW, wh= y do you need
an alternative syntax? If your answer is "too much typing", check= out
section 15.2, "Easy templates", in the Org manual.

The problem is visual clutter (yes, I guess Emacs can be = told to hide the markup, but I'm talking about when text is displayed a= s-is and/or outside Emacs) and copy-pasteability (especially with the colon= syntax). I know Org format is not optimized for fixed width section, but p= erhaps there is a way?

--
sh
--bcaec5016035c0ffe104a49cc84a-- 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