A simpler way to write literal examples?

A simpler way to write literal examples?

[Steven Haryanto]

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

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

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

Re: A simpler way to write literal examples?

[Nick Dokos]

Steven Haryanto <stevenharyanto@gmail.com> 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.

Nick

Re: A simpler way to write literal examples?

[Eric Schulte]

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

Re: A simpler way to write literal examples?

[Steven Haryanto]

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

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

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

Re: A simpler way to write literal examples?

[Carsten Dominik]

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

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