Re: Re: Worg needs some reorganizing

[Dan Davison <dandavison7@gmail.com>]

On Thu, Jan 20, 2011 at 5:02 PM, Jeff Horn <jrhorn424@gmail.com> wrote:
>
> On Thu, Jan 20, 2011 at 6:22 AM, Dan Davison <dandavison7@gmail.com> wrote:
> > I strongly second this. In fact I'll stick my neck out more: Worg is
> > great, but for tutorials on org-mode, HTML export is often the wrong
> > format for obvious reasons (i.e. unless you go to some trouble, it
> > conceals a lot of the org syntax). I'm tempted to suggest that htmlized
> > output should be the default format for many org tutorials on Worg.
>
> I respectfully disagree with your assertion. When someone writes a
> document "properly", i.e. in a literate fashion, i.e. using org source
> blocks, the right syntax is shown at the right time.

So I think we both have babel documents in mind -- i.e. ones with
active code blocks. The trouble with using org source blocks to render
the org syntax in HTML is that the content must be duplicated. I know
from experience that it is easy to let the pedagogical org block get
out of sync with its functional counterpart. I did try to choose my
words carefully -- I said "tutorials", by which I meant the sort of
documents demonstrating Org syntax that can be played with in the org
source version. Not talking about the whole of Worg.

>
> Please see the
> manual as an example.

Hmm? The manual is written in texinfo.

>
> Now, I'm no fan of nerfing choices in order to force anyone to do
> things "The Right Way (tm)", but it bears mentioning.
>
> I see no harm in publishing using org-publish-org-to-org with htmlize.
> We could even add a link in the footer or header of each page that
> links to the htmlized source. I do *not* agree in making it the
> "default format" for any page.

To see examples of a document that would work better in htmlized
format, look no further than

http://orgmode.org/worg/org-contrib/babel/intro.html

Scroll down to the ditaa section and infelicities start to appear.
Someone (Eric or Tom) has done a good job of trying to make sure that
an org src counterpart exists for each source block, but that is (a)
hard work, (b) error prone and (c) cumbersome (what's the point of the
non org src version?).

And in the places which they missed, the document doesn't work well.
E.g. look at the "Capturing the Results of Code Evaluation" section.
Those two blocks are formatted in HTML only and its all a bit baffling
as they appear the same (can't see the header args, which are the
whole point of the example).

All of which could be solved with some effort. My point is: what does
the HTML export of this document really offer over the verbatim
htmlized one?

Dan

>
> --
> Jeffrey Horn
> http://www.failuretorefrain.com/jeff/