Re: [Orgmode] Re: Worg needs some reorganizing

[Dan Davison]

On Thu, Jan 20, 2011 at 5:41 PM, Dan Davison <address@hidden> wrote:
> On Thu, Jan 20, 2011 at 5:02 PM, Jeff Horn <address@hidden> wrote:
>>
>> On Thu, Jan 20, 2011 at 6:22 AM, Dan Davison <address@hidden> 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.

Another possibility is that a new header arg (perhaps ":exports org")
could be added to babel, which would have the effect of wrapping the
block in an org src block on export.

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