seeking good practices for writing about org using org

seeking good practices for writing about org using org

[Cook, Malcolm]

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

Re: seeking good practices for writing about org using org

[Charles C. Berry]

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

Re: seeking good practices for writing about org using org

[Cook, Malcolm]

[-- 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 --]

Re: seeking good practices for writing about org using org

[Charles C. Berry]

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

Re: seeking good practices for writing about org using org

[Cook, Malcolm]

[-- 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 --]

Re: seeking good practices for writing about org using org

[Charles C. Berry]

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

Re: seeking good practices for writing about org using org

[Cook, Malcolm]

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