How to fully control parsing of Org mode links during export

How to fully control parsing of Org mode links during export

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 1721 bytes --]

Hi Org developers:

I could really use some help from Org export experts.  I have
been trying to tweak export link parsing to do what I want
without any success.  Here is a summary of the issues and related
questions I have.

Usinf Org version "9.8-pre":

1. When exporting from an Org file to html, I want this
     [[Emacs#Section-One]] or [[file:Emacs::Section-One]]
   to be converted into this:
     <a href="Emacs.html">Emacs</a>#Section-One
   but instead Org export produces:
     <a href="Emacs.html">Emacs</a>#Section-One

2. When exporting from an Org file to html, I want this
     "[[One Testing]] Three"
   to be converted into this:
     "<a href="One Testing.html">One Testing</a> Three"
   but instead Org export produces:
     "<a href="One.html">One</a> <a href="Testing.html">Testing</a> Three"

3. When exporting from an Org file and I have defined the html export
   syntax for mytype: to html, I want this:
     [[mytype:MyLink]]
     [[Testing]]
   to be converted into this:
     <a href="MyLink.html">MyLink</a>
     <a href="Testing.html">Testing</a>
   but instead Org export produces:
     <a href="<a href="MyLink.html">MyLink</a>.html">mytype:<a
href="Testing.html">Testing</a></a>

My questions are:

1. How can I change `org-element-link-parser' in tandem with
   ox-html.el to output simple HTML links without any of the text
   within double brackets bleeding outside of the HTML link?

2. How can I get the exporter to run in my current Emacs process and
   spawn a new Emacs so that I can easily debug in-process?  I think I have
   turned off the async export option but it still runs async and I can't
   step through the exporter functions.

Thanks very much for any help.

-- rsw

[-- Attachment #2: Type: text/html, Size: 2432 bytes --]

Re: How to fully control parsing of Org mode links during export

[Orm Finnendahl]

Hi,

 this is how I currently do the debugging of html-export (there may be
more elegant ways, but it works well for me):

- Copy (defun org-export-as ...) from ox.el into a local elisp buffer
  of your liking (any buffer with the name .el should do).

- In that function add the line (setq info-debug info) just after the
  comment lines (Lines 2997/2998):

  ;; Eventually transcode TREE.  Wrap the resulting string into
  ;; a template.
  (setq info-debug info)

- Evaluate the new definition of org-export-as and run the export from
  your org file once.

Now you can access the complete parse tree with

(plist-get info-debug :parse-tree)

(make sure just to use a small document, otherwise the output might be
pretty nasty as the parents of all elements are recursively fully
contained in the parse tree).

You can extract all links of your document with:

(setq all-links
  (org-element-map (plist-get info-debug :parse-tree) 'link 'identity))

And you can check the output string of html with this:

(org-html-link (nth 0 all-links) "" info-debug)

You can then check what you have to do to make org-html-link output
the desired string, or redefine org-html-link to do what you need and
later make a derived backend from the html backend replacing the
org-html-link function or simply load the new definition of
org-html-link using a mechanism like #+SETUPFILE: in your header.

HTH,
Orm

Am Sonntag, den 21. Juli 2024 um 13:19:29 Uhr (-0400) schrieb Robert Weiner:
> Hi Org developers:
> 
> I could really use some help from Org export experts.  I have
> been trying to tweak export link parsing to do what I want
> without any success.  Here is a summary of the issues and related
> questions I have.
> 
> Usinf Org version "9.8-pre":
> 
> 1. When exporting from an Org file to html, I want this
>      [[Emacs#Section-One]] or [[file:Emacs::Section-One]]
>    to be converted into this:
>      <a href="Emacs.html">Emacs</a>#Section-One
>    but instead Org export produces:
>      <a href="Emacs.html">Emacs</a>#Section-One
> 
> 2. When exporting from an Org file to html, I want this
>      "[[One Testing]] Three"
>    to be converted into this:
>      "<a href="One Testing.html">One Testing</a> Three"
>    but instead Org export produces:
>      "<a href="One.html">One</a> <a href="Testing.html">Testing</a> Three"
> 
> 3. When exporting from an Org file and I have defined the html export
>    syntax for mytype: to html, I want this:
>      [[mytype:MyLink]]
>      [[Testing]]
>    to be converted into this:
>      <a href="MyLink.html">MyLink</a>
>      <a href="Testing.html">Testing</a>
>    but instead Org export produces:
>      <a href="<a href="MyLink.html">MyLink</a>.html">mytype:<a
> href="Testing.html">Testing</a></a>
> 
> My questions are:
> 
> 1. How can I change `org-element-link-parser' in tandem with
>    ox-html.el to output simple HTML links without any of the text
>    within double brackets bleeding outside of the HTML link?
> 
> 2. How can I get the exporter to run in my current Emacs process and
>    spawn a new Emacs so that I can easily debug in-process?  I think I have
>    turned off the async export option but it still runs async and I can't
>    step through the exporter functions.
> 
> Thanks very much for any help.
> 
> -- rsw

Re: How to fully control parsing of Org mode links during export

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 3813 bytes --]

Thanks, so much, Orm.  I’ll give this a try. It does indicate that the
expirt code and parser could use a simpler setup for debugging.  — rsw

On Sun, Jul 21, 2024 at 2:20 PM Orm Finnendahl <
orm.finnendahl@selma.hfmdk-frankfurt.de> wrote:

> Hi,
>
>  this is how I currently do the debugging of html-export (there may be
> more elegant ways, but it works well for me):
>
> - Copy (defun org-export-as ...) from ox.el into a local elisp buffer
>   of your liking (any buffer with the name .el should do).
>
> - In that function add the line (setq info-debug info) just after the
>   comment lines (Lines 2997/2998):
>
>   ;; Eventually transcode TREE.  Wrap the resulting string into
>   ;; a template.
>   (setq info-debug info)
>
> - Evaluate the new definition of org-export-as and run the export from
>   your org file once.
>
> Now you can access the complete parse tree with
>
> (plist-get info-debug :parse-tree)
>
> (make sure just to use a small document, otherwise the output might be
> pretty nasty as the parents of all elements are recursively fully
> contained in the parse tree).
>
> You can extract all links of your document with:
>
> (setq all-links
>   (org-element-map (plist-get info-debug :parse-tree) 'link 'identity))
>
> And you can check the output string of html with this:
>
> (org-html-link (nth 0 all-links) "" info-debug)
>
> You can then check what you have to do to make org-html-link output
> the desired string, or redefine org-html-link to do what you need and
> later make a derived backend from the html backend replacing the
> org-html-link function or simply load the new definition of
> org-html-link using a mechanism like #+SETUPFILE: in your header.
>
> HTH,
> Orm
>
> Am Sonntag, den 21. Juli 2024 um 13:19:29 Uhr (-0400) schrieb Robert
> Weiner:
> > Hi Org developers:
> >
> > I could really use some help from Org export experts.  I have
> > been trying to tweak export link parsing to do what I want
> > without any success.  Here is a summary of the issues and related
> > questions I have.
> >
> > Usinf Org version "9.8-pre":
> >
> > 1. When exporting from an Org file to html, I want this
> >      [[Emacs#Section-One]] or [[file:Emacs::Section-One]]
> >    to be converted into this:
> >      <a href="Emacs.html">Emacs</a>#Section-One
> >    but instead Org export produces:
> >      <a href="Emacs.html">Emacs</a>#Section-One
> >
> > 2. When exporting from an Org file to html, I want this
> >      "[[One Testing]] Three"
> >    to be converted into this:
> >      "<a href="One Testing.html">One Testing</a> Three"
> >    but instead Org export produces:
> >      "<a href="One.html">One</a> <a href="Testing.html">Testing</a>
> Three"
> >
> > 3. When exporting from an Org file and I have defined the html export
> >    syntax for mytype: to html, I want this:
> >      [[mytype:MyLink]]
> >      [[Testing]]
> >    to be converted into this:
> >      <a href="MyLink.html">MyLink</a>
> >      <a href="Testing.html">Testing</a>
> >    but instead Org export produces:
> >      <a href="<a href="MyLink.html">MyLink</a>.html">mytype:<a
> > href="Testing.html">Testing</a></a>
> >
> > My questions are:
> >
> > 1. How can I change `org-element-link-parser' in tandem with
> >    ox-html.el to output simple HTML links without any of the text
> >    within double brackets bleeding outside of the HTML link?
> >
> > 2. How can I get the exporter to run in my current Emacs process and
> >    spawn a new Emacs so that I can easily debug in-process?  I think I
> have
> >    turned off the async export option but it still runs async and I can't
> >    step through the exporter functions.
> >
> > Thanks very much for any help.
> >
> > -- rsw
>
>

[-- Attachment #2: Type: text/html, Size: 4902 bytes --]

Re: How to fully control parsing of Org mode links during export

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 333 bytes --]

Sorry, I mistyped the first example in my message, it should read:

1. When exporting from an Org file to html, I want this
     [[Emacs#Section-One]]
   to be converted into this:
     <a href="Emacs.html#Section-One">Emacs#Section-One</a>
   but instead Org export produces:
     <a href="Emacs.html">Emacs</a>#Section-One

-- rsw

[-- Attachment #2: Type: text/html, Size: 778 bytes --]

Re: How to fully control parsing of Org mode links during export

[Ihor Radchenko]

Robert Weiner <rsw@gnu.org> writes:

> I could really use some help from Org export experts.  I have
> been trying to tweak export link parsing to do what I want
> without any success.  Here is a summary of the issues and related
> questions I have.

You generally should not need to modify the _parser_.
What you may need to do is modifying the exporter.
For example, by defining a custom export backend. Or export filter.
See "13.17 Advanced Export Configuration" section of the manual.

> 3. When exporting from an Org file and I have defined the html export
>    syntax for mytype: to html, I want this:
>      [[mytype:MyLink]]
>      [[Testing]]
>    to be converted into this:
>      <a href="MyLink.html">MyLink</a>
>      <a href="Testing.html">Testing</a>
>    but instead Org export produces:
>      <a href="<a href="MyLink.html">MyLink</a>.html">mytype:<a
> href="Testing.html">Testing</a></a>

This has nothing to do with Org mode exporter. What is produced for
custom link types totally depends on the custom :export function you
defined for your link.

> 2. How can I get the exporter to run in my current Emacs process and
>    spawn a new Emacs so that I can easily debug in-process?  I think I have
>    turned off the async export option but it still runs async and I can't
>    step through the exporter functions.

Async is disabled by default. So, something in your config enables
it.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: How to fully control parsing of Org mode links during export

[Robert Weiner]

[-- Attachment #1: Type: text/plain, Size: 2359 bytes --]

Thank you for the pointers on this, Ihor.  That led me down a much better
path that worked.  In the end, I just had the export function for my
specific link type and had to add a before advice on
org-element--generate-copy-script since it lacks a hook at its end.  I
would suggest adding one as this seems to be the place if you want to
change the markup in the copied buffer before Org formats it for export.
Is there any other existing hook that runs before formatting in this copied
buffer?

Thanks. -- Robert

On Mon, Jul 22, 2024 at 9:53 AM Ihor Radchenko <yantar92@posteo.net> wrote:

> Robert Weiner <rsw@gnu.org> writes:
>
> > I could really use some help from Org export experts.  I have
> > been trying to tweak export link parsing to do what I want
> > without any success.  Here is a summary of the issues and related
> > questions I have.
>
> You generally should not need to modify the _parser_.
> What you may need to do is modifying the exporter.
> For example, by defining a custom export backend. Or export filter.
> See "13.17 Advanced Export Configuration" section of the manual.
>
> > 3. When exporting from an Org file and I have defined the html export
> >    syntax for mytype: to html, I want this:
> >      [[mytype:MyLink]]
> >      [[Testing]]
> >    to be converted into this:
> >      <a href="MyLink.html">MyLink</a>
> >      <a href="Testing.html">Testing</a>
> >    but instead Org export produces:
> >      <a href="<a href="MyLink.html">MyLink</a>.html">mytype:<a
> > href="Testing.html">Testing</a></a>
>
> This has nothing to do with Org mode exporter. What is produced for
> custom link types totally depends on the custom :export function you
> defined for your link.
>
> > 2. How can I get the exporter to run in my current Emacs process and
> >    spawn a new Emacs so that I can easily debug in-process?  I think I
> have
> >    turned off the async export option but it still runs async and I can't
> >    step through the exporter functions.
>
> Async is disabled by default. So, something in your config enables
> it.
>
> --
> Ihor Radchenko // yantar92,
> Org mode contributor,
> Learn more about Org mode at <https://orgmode.org/>.
> Support Org development at <https://liberapay.com/org-mode>,
> or support my work at <https://liberapay.com/yantar92>
>

[-- Attachment #2: Type: text/html, Size: 3465 bytes --]

Re: How to fully control parsing of Org mode links during export

[Ihor Radchenko]

Robert Weiner <rsw@gnu.org> writes:

> Thank you for the pointers on this, Ihor.  That led me down a much better
> path that worked.  In the end, I just had the export function for my
> specific link type and had to add a before advice on
> org-element--generate-copy-script since it lacks a hook at its end.  I
> would suggest adding one as this seems to be the place if you want to
> change the markup in the copied buffer before Org formats it for export.
> Is there any other existing hook that runs before formatting in this copied
> buffer?

See https://orgmode.org/manual/Advanced-Export-Configuration.html#Summary-of-the-export-process-1

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>