From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jason Dunsmore Subject: Re: Re: Worg needs some reorganizing Date: Thu, 20 Jan 2011 11:38:58 -0600 Message-ID: <874o93a30t.fsf@riotblast.dunsmor.com> References: <4CAD81B0.6090807@manor-farm.org> <87d3nyuhkw.fsf@altern.org> <87aaj0kggo.fsf@gmail.com> <87zkr0load.fsf@riotblast.dunsmor.com> <87pqrwipjd.fsf@gmail.com> <87oc7glhef.fsf@riotblast.dunsmor.com> <87hbd8ins8.fsf@gmail.com> <87ipxolgji.fsf@riotblast.dunsmor.com> <87aaj0iiff.fsf@gmail.com> <87r5cbk28p.fsf@riotblast.dunsmor.com> <87fwsrtokh.fsf@gnu.org> <87lj2jouz7.fsf@fastmail.fm> <877he2fvw0.fsf@gnu.org> <87fwsqw8u3.fsf@fastmail.fm> <87d3nufa7a.fsf@gmail.com> <87r5cagi6h.fsf@riotblast.dunsmor.com> <4D386F00.2070705@ccbr.umn.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from [140.186.70.92] (port=42130 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PfyTO-00075L-Sy for emacs-orgmode@gnu.org; Thu, 20 Jan 2011 12:39:04 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PfyTM-0001TP-PA for emacs-orgmode@gnu.org; Thu, 20 Jan 2011 12:39:01 -0500 Received: from deathroller.dunsmor.com ([98.129.169.48]:35004) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PfyTM-0001TB-I3 for emacs-orgmode@gnu.org; Thu, 20 Jan 2011 12:39:00 -0500 In-Reply-To: <4D386F00.2070705@ccbr.umn.edu> (Erik Iverson's message of "Thu, 20 Jan 2011 11:21:04 -0600") List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Erik Iverson Cc: Jeff Horn , emacs-orgmode@gnu.org, Dan Davison Erik Iverson writes: > Jeff Horn wrote: >> On Thu, Jan 20, 2011 at 6:22 AM, Dan Davison 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. Please see the >> manual as an example. > > I must admit I ran into this exact problem when writing an org-babel/R > tutorial. The problem came down to the following: I was writing an > interactive org-mode document showing mainly how code blocks work within > org. This of course necessitates that I describe code block arguments. > But these aren't shown in export. I believe the solution would be > to export an "example block" to HTML, but then *also* include a source > code block for interactive org-mode use. > > So my tutorial makes perfect sense when you're following along in org > mode. But the HTML export seems a little odd since only the content > of the code blocks are shown, and not the full code blocks, which is > the point of the tutorial. I see this issue a lot on the Babel pages. What needs to be done is wrap each source/example block in another block with "org" as the language. For example: --8<---------------cut here---------------start------------->8--- #+begin_src org ,#+begin_src sh :results output ls -al ,#+end_src #+end_src --8<---------------cut here---------------end--------------->8--- I think this should be done for all Babel documents to make them more coherent when reading them on the web. I found the babel documentation quite confusing in the beginning because of this. Eric and Dan, Do you agree with this?