emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

* seeking good practices for writing about org using org
@ 2016-08-03 23:50 Cook, Malcolm
  2016-08-04  2:15 ` Charles C. Berry
  0 siblings, 1 reply; 7+ messages in thread
From: Cook, Malcolm @ 2016-08-03 23:50 UTC (permalink / raw)
  To: 'emacs-orgmode@gnu.org'

Hi,

I am seeking good practices for writing about org using , erhm, well, org itself.  (doh!)

I'd use these practices, for example, when writing examples of using org, or lessons in using org, or bug reports about org.

I reached of ob-org thinking this is what it was for, and wrote the following

--------------------------------------- (beginning of example)
Here is simple org book structure with chapters and a table of
contents at the end:

#+BEGIN_SRC org :exports both :results value

* chapter one

Fa la la

* chapter two

La di di

* table of contents

#+TOC:

#+END_SRC
--------------------------------------- (end of example)

My dashed expectations were that when executed and exported, this would produce a block of the org source, appropriately quoted, followed be the RESULTS, being, well, the rendered org.  

Are your expectations the same as mine?

What do YOU do in such cases? 

Are there good practices for this?

Am I off by a level in my meta-thinking?

Thanks!

Malcolm Cook - Kansas City

^ permalink raw reply	[flat|nested] 7+ messages in thread

• * Re: seeking good practices for writing about org using org
    2016-08-03 23:50 seeking good practices for writing about org using org Cook, Malcolm
  @ 2016-08-04  2:15 ` Charles C. Berry
    2016-08-04  2:47   ` Cook, Malcolm
    2016-08-04  2:54   ` Cook, Malcolm
    0 siblings, 2 replies; 7+ messages in thread
  From: Charles C. Berry @ 2016-08-04  2:15 UTC (permalink / raw)
    To: Cook, Malcolm; +Cc: 'emacs-orgmode@gnu.org'
  
  On Wed, 3 Aug 2016, Cook, Malcolm wrote:
  
  > Hi,
  >
  > I am seeking good practices for writing about org using , erhm, well, 
  > org itself.  (doh!)
  >
  > I'd use these practices, for example, when writing examples of using 
  > org, or lessons in using org, or bug reports about org.
  >
  > I reached of ob-org thinking this is what it was for, and wrote the 
  > following
  >
  > --------------------------------------- (beginning of example)
  > Here is simple org book structure with chapters and a table of
  > contents at the end:
  >
  > #+BEGIN_SRC org :exports both :results value
  >
  > * chapter one
  >
  > Fa la la
  >
  > * chapter two
  >
  > La di di
  >
  > * table of contents
  >
  > #+TOC:
  >
  > #+END_SRC
  > --------------------------------------- (end of example)
  >
  > My dashed expectations were that when executed and exported, this would 
  > produce a block of the org source, appropriately quoted, followed be the 
  > RESULTS, being, well, the rendered org.
  >
  > Are your expectations the same as mine?
  >
  
  No. Run `M-x org-lint RET' and you will see that this is malformed. The 
  org code needs to be escaped.
  
  > What do YOU do in such cases?
  
  Edit the src block in an edit buffer. You'll need to kill the contents of 
  that src block first, then C-c ' to open the src edit buffer, then yank, then C-c ' 
  again. The resulting buffer will be properly escaped.
  
  See (info "(org) Literal examples"), especially footnote 4.
  
  --
  
  Then specify `:results replace' to override `:results silent' which
  `org-babel-default-header-args:org' sets.
  
  --
  
  Then the export should be what you expect.
  
  HTH,
  
  Chuck
  
  ^ permalink raw reply	[flat|nested] 7+ messages in thread

• • * Re: seeking good practices for writing about org using org
      2016-08-04  2:15 ` Charles C. Berry
    @ 2016-08-04  2:47   ` Cook, Malcolm
      2016-08-04 16:24     ` Charles C. Berry
      2016-08-04  2:54   ` Cook, Malcolm
      1 sibling, 1 reply; 7+ messages in thread
    From: Cook, Malcolm @ 2016-08-04  2:47 UTC (permalink / raw)
      To: 'Charles C. Berry'; +Cc: 'emacs-orgmode@gnu.org'
    
    
    [-- Attachment #1.1: Type: text/plain, Size: 2971 bytes --]
    
    Thanks.  Much closer.  Still some issues.  Mind taking another gander....  (hoping the attached jpeg of the webpage rendered comes through as an attachment)....
    
    If my emacs buffer holds...
    ----------------------------------------------
    #+BEGIN_SRC org :exports both :results value ascii
    
    ,* Acknowledgments
      [[mailto:mywife@example.com][my wife]]
    
    ,* Chapter one
    
    Fa la la ls
    
    ,* Chapter two
    
    La di di
    
    ,* Finally, here is a table of contents!
    
    ,#+TOC:
    
    #+END_SRC
    ----------------------------------------------
    
    ....Then exporting to html gives me a webpage with what I think are still a few issues:
    *       I would expect the 2nd line not to display as an emacs link text.  I am trying to display the contents of the emacs buffer.
    *       There is not table of contents.
    
       As in this screen shot.
    
    Thanks for you TIPS!
    
     > -----Original Message-----
     > From: Charles C. Berry [mailto:ccberry@ucsd.edu]
     > Sent: Wednesday, August 03, 2016 9:16 PM
     > To: Cook, Malcolm <MEC@stowers.org>
     > Cc: 'emacs-orgmode@gnu.org' <emacs-orgmode@gnu.org>
     > Subject: Re: seeking good practices for writing about org using org
     >
     > On Wed, 3 Aug 2016, Cook, Malcolm wrote:
     >
     > > Hi,
     > >
     > > I am seeking good practices for writing about org using , erhm, well,
     > > org itself.  (doh!)
     > >
     > > I'd use these practices, for example, when writing examples of using
     > > org, or lessons in using org, or bug reports about org.
     > >
     > > I reached of ob-org thinking this is what it was for, and wrote the
     > > following
     > >
     > > --------------------------------------- (beginning of example)
     > > Here is simple org book structure with chapters and a table of
     > > contents at the end:
     > >
     > > #+BEGIN_SRC org :exports both :results value
     > >
     > > * chapter one
     > >
     > > Fa la la
     > >
     > > * chapter two
     > >
     > > La di di
     > >
     > > * table of contents
     > >
     > > #+TOC:
     > >
     > > #+END_SRC
     > > --------------------------------------- (end of example)
     > >
     > > My dashed expectations were that when executed and exported, this
     > would
     > > produce a block of the org source, appropriately quoted, followed be the
     > > RESULTS, being, well, the rendered org.
     > >
     > > Are your expectations the same as mine?
     > >
     >
     > No. Run `M-x org-lint RET' and you will see that this is malformed. The
     > org code needs to be escaped.
     >
     > > What do YOU do in such cases?
     >
     > Edit the src block in an edit buffer. You'll need to kill the contents of
     > that src block first, then C-c ' to open the src edit buffer, then yank, then C-c
     > '
     > again. The resulting buffer will be properly escaped.
     >
     > See (info "(org) Literal examples"), especially footnote 4.
     >
     > --
     >
     > Then specify `:results replace' to override `:results silent' which
     > `org-babel-default-header-args:org' sets.
     >
     > --
     >
     > Then the export should be what you expect.
     >
     > HTH,
     >
     > Chuck
    
    
    [-- Attachment #1.2: Type: text/html, Size: 5353 bytes --]
    
    [-- Attachment #2: Picture (Device Independent Bitmap) 1.jpg --]
    [-- Type: image/jpeg, Size: 43993 bytes --]
    
    ^ permalink raw reply	[flat|nested] 7+ messages in thread

  • • * Re: seeking good practices for writing about org using org
        2016-08-04  2:47   ` Cook, Malcolm
      @ 2016-08-04 16:24     ` Charles C. Berry
        2016-08-04 20:56       ` Cook, Malcolm
        0 siblings, 1 reply; 7+ messages in thread
      From: Charles C. Berry @ 2016-08-04 16:24 UTC (permalink / raw)
        To: Cook, Malcolm; +Cc: 'emacs-orgmode@gnu.org'
      
      On Wed, 3 Aug 2016, Cook, Malcolm wrote:
      
      > Thanks.  Much closer.  Still some issues.  Mind taking another 
      > gander....  (hoping the attached jpeg of the webpage rendered comes 
      > through as an attachment)....
      >
      > If my emacs buffer holds...
      > ----------------------------------------------
      > #+BEGIN_SRC org :exports both :results value ascii
      
      ...............................................^^^^^
      
      what is the `ascii' doing?
      
      Can you provide a link to documentation in the manual or a 
      docstring describing its function?
      
      Why don't you have 'replace' in the :results args?
      
      >
      > ,* Acknowledgments
      
      This bit behaves as you might expect in plain text export, markdown, and 
      latex export:
      
      >  [[mailto:mywife@example.com][my wife]]
      
      but in html it does create `<a href="mailto:...'.
      
      That is because of what `org-babel-exp-code-template' leads 
      `org-html-src-block' to do. You might try dropping `%lang' from the 
      template, but a better solution is to rewrite `org-html-src-block' and 
      create a derived exporter.
      
      
      >
      > ,* Chapter one
      >
      > Fa la la ls
      >
      > ,* Chapter two
      >
      > La di di
      >
      > ,* Finally, here is a table of contents!
      >
      > ,#+TOC:
      
      What does this idiom do?
      
      Precisely, where does the documentation say what
      
      #+TOC:
      
      read as "<hash> <plus> T O C <colon> <newline>"
      
      should create??
      
      ---
      
      Re your next post, I suggest spending some time reading
      
      (info "(org) results")
      
      to grasp what the various options actually do. It is probably a good idea 
      to execute src blocks to see the RESULTS before you try to export them.
      
      Reading
      
      (info "(org) wrap")
      
      might also help and certainly a quick breeze thru
      
      (info "(org) Specific header arguments")
      
      to remind yourself of what all the possibilities are is something I have 
      to do from time to time.
      
      HTH,
      
      Chuck
      
      ^ permalink raw reply	[flat|nested] 7+ messages in thread

    • • * Re: seeking good practices for writing about org using org
          2016-08-04 16:24     ` Charles C. Berry
        @ 2016-08-04 20:56       ` Cook, Malcolm
          2016-08-05  3:05         ` Charles C. Berry
          0 siblings, 1 reply; 7+ messages in thread
        From: Cook, Malcolm @ 2016-08-04 20:56 UTC (permalink / raw)
          To: 'Charles C. Berry'; +Cc: 'emacs-orgmode@gnu.org'
        
        
        [-- Attachment #1.1: Type: text/plain, Size: 6126 bytes --]
        
        Hi Charles,
        
        
        
        > On Wed, 3 Aug 2016, Cook, Malcolm wrote:
        
        >
        
         > > Thanks.  Much closer.  Still some issues.  Mind taking another
        
        > > gander....  (hoping the attached jpeg of the webpage rendered comes
        
        > > through as an attachment)....
        
        > >
        
        > > If my emacs buffer holds...
        
        > > ----------------------------------------------
        
        > > #+BEGIN_SRC org :exports both :results value ascii
        
        >
        
         > ...............................................^^^^^
        
        >
        
         > what is the `ascii' doing?
        
        >
        
         > Can you provide a link to documentation in the manual or a
        
        > docstring describing its function?
        
        
        
        I cannot!  I learned this from reading the code.  In ob-org.el we find provision for this  as well as `html' and `latex'
        
        
        
        (defun org-babel-execute:org (body params)
        
          "Execute a block of Org code with.
        
        This function is called by `org-babel-execute-src-block'."
        
          (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
        
                        (body (org-babel-expand-body:org
        
                               (replace-regexp-in-string "^," "" body) params)))
        
            (cond
        
             ((member "latex" result-params)
        
              (org-export-string-as (concat "#+Title: \n" body) 'latex t))
        
             ((member "html" result-params) (org-export-string-as  body 'html t))
        
             ((member "ascii" result-params) (org-export-string-as body 'ascii t))
        
             (t body)
        
             )))
        
        
        
        
        
        This is all undocumented.  I think it is a 'nod in the direction' of what I am trying to accomplish, allowing to see as "results" the org markup transcoded into the markup of a backend.  See below for my hack extension on this idea.
        
        
        
        >
        
         > Why don't you have 'replace' in the :results args?
        
        
        
        Oops.  Of course.  While trying to understand all this, I had done this to similar effect instead:
        
        
        
        (setq  org-babel-default-header-args:org nil) ; fix bug? NOT silent
        
        
        
        
        
        > >
        
        > > ,* Acknowledgments
        
        >
        
         > This bit behaves as you might expect in plain text export, markdown, and
        
        > latex export:
        
        >
        
         > >  [[mailto:mywife@example.com][my wife]]
        
        >
        
         > but in html it does create `<a href="mailto:...'.
        
        >
        
         > That is because of what `org-babel-exp-code-template' leads
        
        > `org-html-src-block' to do. You might try dropping `%lang' from the
        
        > template, but a better solution is to rewrite `org-html-src-block' and
        
        > create a derived exporter.
        
        >
        
         >
        
         > >
        
        > > ,* Chapter one
        
        > >
        
        > > Fa la la ls
        
        > >
        
        > > ,* Chapter two
        
        > >
        
        > > La di di
        
        > >
        
        > > ,* Finally, here is a table of contents!
        
        > >
        
        > > ,#+TOC:
        
        >
        
         > What does this idiom do?
        
        >
        
         > Precisely, where does the documentation say what
        
        >
        
         > #+TOC:
        
        >
        
         > read as "<hash> <plus> T O C <colon> <newline>"
        
        >
        
         > should create??
        
        
        
        I though (apparently incorrectly) it was the same as `#+TOC: headlines 2' which does contrive to relocate a Table of Contents to that location.
        
        
        
        > ---
        
        >
        
         > Re your next post, I suggest spending some time reading
        
        >
        
         > (info "(org) results")
        
        >
        
         > to grasp what the various options actually do. It is probably a good idea
        
        > to execute src blocks to see the RESULTS before you try to export them.
        
        >
        
         > Reading
        
        >
        
         > (info "(org) wrap")
        
        >
        
         > might also help and certainly a quick breeze thru
        
        >
        
         > (info "(org) Specific header arguments")
        
        >
        
         > to remind yourself of what all the possibilities are is something I have
        
        > to do from time to time.
        
        
        
        Thanks for these suggestions.  I have had better results after doing so.
        
        
        
        I played with extending org-babel-execute:org to allow including MULTIPLE transcoded markdown results using screwy variant syntax of `:results  +ascii +html +latex` with some success.
        
        
        
        For example, `:results +ascii +latex' exported html which renders as:
        
        [cid:image001.png@01D1EE68.BBAEA750]
        
        
        
        
        
        I now think perhaps I want additional options on a source block allowing to be included in the exported RESULTS:
        
          1) transcoded markdown, appropriately escaped for the current backend
        
          1) the source block itself (including the #+BEGIN/END directives)  (as distinct from :results code, which omits the directives)
        
        
        
        Injecting this kind of logic into org-babel-execute:org  as I did is mis-placing the logic and only muddles further my thinking about this.
        
        
        
        FWIW - here is the re-definition, if you care to play with or critique it.
        
        
        
        (defun org-babel-execute:org (body params)
        
          "Execute a block of Org code with.
        
        This function is called by `org-babel-execute-src-block'."
        
          (let* ((result-params (split-string (or (cdr (assoc :results params)) "")))
        
                        (body (org-babel-expand-body:org
        
                                        (replace-regexp-in-string "^," "" body) params))
        
                        (val (cond
        
                               ((member "latex" result-params)
        
                                        (org-export-string-as (concat "#+Title: \n" body) 'latex t))
        
                               ((member "html" result-params) (org-export-string-as  body 'html t))
        
                               ((member "ascii" result-params) (org-export-string-as body 'ascii t))
        
                               (t body)
        
                               )))
        
            ;; HACK: output protected versions of each of latex,html,ascii,md transcoded markup as requested with +{latex,html,ascii,md} in header-args
        
            (when (member "+latex" result-params)
        
              (setq val (format "#+BEGIN_EXAMPLE\n%s\n#+END_EXAMPLE\n%s" (org-export-string-as  body 'latex t) val)))
        
            (when (member "+html" result-params)
        
              (setq val (format "#+BEGIN_EXAMPLE\n%s\n#+END_EXAMPLE\n%s" (org-export-string-as  body 'html t) val)))
        
            (when (member "+ascii" result-params)
        
              (setq val (format "#+BEGIN_EXAMPLE\n%s\n#+END_EXAMPLE\n%s" (org-export-string-as  body 'ascii t) val)))
        
            (when (member "+md" result-params)
        
              (setq val (format "#+BEGIN_EXAMPLE\n%s\n#+END_EXAMPLE\n%s" (org-export-string-as  body 'md t) val)))
        
            val)
        
        )
        
        
        
        Cheers,
        
        
        
        Malcolm
        
        
        
        >
        
         > HTH,
        
        >
        
         > Chuck
        
        [-- Attachment #1.2: Type: text/html, Size: 18445 bytes --]
        
        [-- Attachment #2: image001.png --]
        [-- Type: image/png, Size: 57004 bytes --]
        
        ^ permalink raw reply	[flat|nested] 7+ messages in thread

      • • * Re: seeking good practices for writing about org using org
            2016-08-04 20:56       ` Cook, Malcolm
          @ 2016-08-05  3:05         ` Charles C. Berry
            0 siblings, 0 replies; 7+ messages in thread
          From: Charles C. Berry @ 2016-08-05  3:05 UTC (permalink / raw)
            To: Cook, Malcolm; +Cc: 'emacs-orgmode@gnu.org'
          
          On Thu, 4 Aug 2016, Cook, Malcolm wrote:
          
          > Hi Charles,
          >> On Wed, 3 Aug 2016, Cook, Malcolm wrote:
          >>
          > > > Thanks.  Much closer.  Still some issues.  Mind taking another
          >>> gander....  (hoping the attached jpeg of the webpage rendered comes
          >>> through as an attachment)....
          >>> If my emacs buffer holds...
          >>> ----------------------------------------------
          >>> #+BEGIN_SRC org :exports both :results value ascii
          >
          >>
          > > ...............................................^^^^^>>
          > > what is the `ascii' doing?
          >>
          > > Can you provide a link to documentation in the manual or a
          >> docstring describing its function?
          >
          > I cannot!  I learned this from reading the code.  In ob-org.el we
          > find provision for this as well as `html' and `latex'
          >
          >
          > (defun org-babel-execute:org (body params)
          >  "Execute a block of Org code with.
          > This function is called by `org-babel-execute-src-block'."
          >  (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
          >                (body (org-babel-expand-body:org
          >                       (replace-regexp-in-string "^," "" body) params)))
          >    (cond
          >     ((member "latex" result-params)
          >      (org-export-string-as (concat "#+Title: \n" body) 'latex t))
          >     ((member "html" result-params) (org-export-string-as  body 'html t))
          >     ((member "ascii" result-params) (org-export-string-as body 'ascii t))
          >     (t body)
          >     )))
          >
          >
          > This is all undocumented.  I think it is a 'nod in the direction' of
          > what I am trying to accomplish, allowing to see as "results" the org
          > markup transcoded into the markup of a backend.  See below for my
          > hack extension on this idea.
          
          Argh! Not even a mention in the docstring!
          
          I think there was a plea a while back for updates for the
          missing entries in
          
          ./worg/org-contrib/babel/languages.org
          
          but I see `org' has nothing. Sigh!
          
          >
          >>
          > > Why don't you have 'replace' in the :results args?
          >
          > Oops.  Of course.  While trying to understand all this, I had done this to similar effect instead:
          >
          > (setq  org-babel-default-header-args:org nil) ; fix bug? NOT silent
          
          If this is set as a default, it is deliberate. But you can just set
          it as a property in the buffer.
          
          [stuff deleted]
          
          > I played with extending org-babel-execute:org to allow including
          >  MULTIPLE transcoded markdown results using screwy variant syntax of
          >  `:results +ascii +html +latex` with some success.
          
          [Malcolm's extension of `org-babel-execute:org' deleted]
          
          Writing a custom org-babel-execute:org is one way to go.
          
          Or slurp the code into another babel block, format it there, and wrap
          the results accordingly. This might be best for your purposes. You can
          write a block to format the original code, one to format it as latex,
          one as html, one as markdown, etc. Put them in your personal
          library-of-babel and ingest them. Then #+CALL lines will create the
          markup you need for any src block (which you will mark `:exports none'
          so all formatting is done by #+CALL's).
          
          HTH,
          
          Chuck
          
          ^ permalink raw reply	[flat|nested] 7+ messages in thread

  • * Re: seeking good practices for writing about org using org
      2016-08-04  2:15 ` Charles C. Berry
      2016-08-04  2:47   ` Cook, Malcolm
    @ 2016-08-04  2:54   ` Cook, Malcolm
      1 sibling, 0 replies; 7+ messages in thread
    From: Cook, Malcolm @ 2016-08-04  2:54 UTC (permalink / raw)
      To: 'Charles C. Berry'; +Cc: 'emacs-orgmode@gnu.org'
    
    Hi,
    
    Additionally, if I change to
    
    #+BEGIN_SRC org :exports both :results value html
    
    I do not want the html rendered in the browser when I export to html.  Rather, I want to see the html that was created.  Actually, having the option to see BOTH would be ideal.
    
    Similarly, if I change to
    
    #+BEGIN_SRC org :exports both :results value latex
    
    I want to see the generated latex in the browser (when I export to html) or the generaled latex in the pdf (when I go that route).  
    
    I suppose my actual goal is to be able to write org, and generate a document which display the org (:results code), display the markup (:results value), and possibly optionally additionally shows (an image) of how the markup renders (possibly using node to render html to an image or something else to render latex as an image).
    
    Any insights into straightening out this thinking much welcome....
    
    Cheers,
    
    Malcolm
    
    ^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2016-08-05  3:05 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-08-03 23:50 seeking good practices for writing about org using org Cook, Malcolm
2016-08-04  2:15 ` Charles C. Berry
2016-08-04  2:47   ` Cook, Malcolm
2016-08-04 16:24     ` Charles C. Berry
2016-08-04 20:56       ` Cook, Malcolm
2016-08-05  3:05         ` Charles C. Berry
2016-08-04  2:54   ` Cook, Malcolm

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).