Overriding org-html-headline or other export functions?

Overriding org-html-headline or other export functions?

[Brett Viren]

Hi,

I am writing a manual in Org which gets exported/published to HTML and
styled with org-html-themes.  I want the HTML to include a little icon
next to each headline which is a direct link to the headline itself.
Basically, I want to rip off what GitHub does when it renders Org.

First, is there some way to achieve this headline link without
explicitly adding it in the Org text or diving into Org Elisp?

I couldn't find one so I took the latter route by copying out the whole
of org-html-headline into the Emacs init Elisp file I used for
publishing and fiddle with it until I got more or less what I wanted.
Here are the lines tweaked:

  https://github.com/WireCell/wire-cell-docs/blob/master/manuals/publish.el#L69

Here is an example of the result:

  http://www.phy.bnl.gov/~bviren/wirecell.github.io/manual.html

Is this copy+hack the proper way to tweak the exporting in this case?
In particular, I worry about my copy of org-html-headline diverging from
the real.


I read about export filters and extending an existing back-end, but I
think these do not apply, but maybe I have that wrong.

Thanks for any suggestions!

-Brett.

Re: Overriding org-html-headline or other export functions?

[Charles C. Berry]

On Mon, 29 May 2017, Brett Viren wrote:

> Hi,
>
> I am writing a manual in Org which gets exported/published to HTML and
> styled with org-html-themes.  I want the HTML to include a little icon
> next to each headline which is a direct link to the headline itself.
> Basically, I want to rip off what GitHub does when it renders Org.
>
> First, is there some way to achieve this headline link without
> explicitly adding it in the Org text or diving into Org Elisp?
>
> I couldn't find one so I took the latter route by copying out the whole
> of org-html-headline into the Emacs init Elisp file I used for
> publishing and fiddle with it until I got more or less what I wanted.
> Here are the lines tweaked:
>
>  https://github.com/WireCell/wire-cell-docs/blob/master/manuals/publish.el#L69
>
> Here is an example of the result:
>
>  http://www.phy.bnl.gov/~bviren/wirecell.github.io/manual.html
>
> Is this copy+hack the proper way to tweak the exporting in this case?
> In particular, I worry about my copy of org-html-headline diverging from
> the real.
>
>
> I read about export filters and extending an existing back-end, but I
> think these do not apply, but maybe I have that wrong.
>

You do have that wrong.  This is exactly what export filters and derived 
backends are for.  In fact, you can use both.  For an example, see

http://orgmode.org/worg/exporters/filter-markup.html

You will want to change `latex' to `html' in the

 	`(org-export-define-derived-backend ...)'

call and delete all filters except for `:filter-headline'.  And revise 
`ox-mrkup-filter-headline' accordingly.

And of course, you will want to look at

http://orgmode.org/worg/dev/org-export-reference.html

HTH,

Chuck

Re: Overriding org-html-headline or other export functions?

[Brett Viren]

"Charles C. Berry" <ccberry@ucsd.edu> writes:

> You do have that wrong.  This is exactly what export filters and
> derived backends are for.  In fact, you can use both.  For an example,
> see
>
> http://orgmode.org/worg/exporters/filter-markup.html
>
> You will want to change `latex' to `html' in the
>
> 	`(org-export-define-derived-backend ...)'
>
> call and delete all filters except for `:filter-headline'.  And revise
> `ox-mrkup-filter-headline' accordingly.

Thanks for checking me on this, but I still don't see it.

If I understand, a derived HTML backend with my own filter-headline
would let me add my own extra HTML *outside* the "<h1>...</h1>",
"<h2>...</h2>", etc, HTML that is generated by the base
org-html-headline filter.  But for the output I want I need to add my
extra HTML *inside* the contents of the "<hN>...</hN>" tags.  And I
don't see an export filter for this "..." part.

Or, maybe you suggest I do direct "surgery" on the TEXT argument that
gets passed in to the filter and insert the "..." that way?  I guess it
could work to find the end of the "<hN...>" opening tag and then insert
my "..." part.  I'll try this approach.

-Brett.

Re: Overriding org-html-headline or other export functions?

[Marcin Borkowski]

On 2017-05-29, at 14:22, Brett Viren <bv@bnl.gov> wrote:

> I read about export filters and extending an existing back-end, but I
> think these do not apply, but maybe I have that wrong.

It's been a while since I did that, but AFAIR deriving a new, slightly
midified backend may be exactly what you want, since you seem to need to
modify just one of the exporter functions.

Hth,

-- 
Marcin Borkowski

Re: Overriding org-html-headline or other export functions?

[Brett Viren]

Marcin Borkowski <mbork@mbork.pl> writes:

> It's been a while since I did that, but AFAIR deriving a new, slightly
> midified backend may be exactly what you want, since you seem to need to
> modify just one of the exporter functions.

Right, by my concern is I'm copy-pasting a large function just to change
basically one line.

I understand that instead of simply stepping on org-* function namespace
with my copy, I can rename my copy and make a derived exporter with my
modified function registered as a filter.  But that doesn't get away
from now having a chunk of code that is at risk of diverging away as
Org's original develops further.

-Brett.

Re: Overriding org-html-headline or other export functions?

[Brett Viren]

Brett Viren <bv@bnl.gov> writes:

> Or, maybe you suggest I do direct "surgery" on the TEXT argument that
> gets passed in to the filter and insert the "..." that way?  I guess it
> could work to find the end of the "<hN...>" opening tag and then insert
> my "..." part.  I'll try this approach.

Okay, this works but relies on searching through the HTML to find the
end of "<hN...>" tag.  This feels like it will be error prone but so far
it seems to work when processing my manual.

In case it might help others, here is my filter:

  https://github.com/WireCell/wire-cell-docs/blob/master/manuals/publish.el#L7

My Elisp is bad, so maybe this is not done well....

And, for completeness there is now also the export-as-html,
export-to-html and publish-to-html functions copied from ox-html and
tweaked for this custom backend.


Thanks for the nudges and help!  

-Brett.

Re: Overriding org-html-headline or other export functions?

[Charles C. Berry]

On Mon, 29 May 2017, Brett Viren wrote:

> "Charles C. Berry" <ccberry@ucsd.edu> writes:
>
>> You do have that wrong.  This is exactly what export filters and
>> derived backends are for.  In fact, you can use both.  For an example,
>> see
>>
>> http://orgmode.org/worg/exporters/filter-markup.html
>>
>> You will want to change `latex' to `html' in the
>>
>> 	`(org-export-define-derived-backend ...)'
>>
>> call and delete all filters except for `:filter-headline'.  And revise
>> `ox-mrkup-filter-headline' accordingly.
>
> Thanks for checking me on this, but I still don't see it.
>
> If I understand, a derived HTML backend with my own filter-headline
> would let me add my own extra HTML *outside* the "<h1>...</h1>",
> "<h2>...</h2>", etc, HTML that is generated by the base
> org-html-headline filter.  But for the output I want I need to add my
> extra HTML *inside* the contents of the "<hN>...</hN>" tags.  And I
> don't see an export filter for this "..." part.
>
> Or, maybe you suggest I do direct "surgery" on the TEXT argument that
> gets passed in to the filter and insert the "..." that way?  I guess it
> could work to find the end of the "<hN...>" opening tag and then insert
> my "..." part.  I'll try this approach.
>
Yeah. You can use one or two `replace-regexp-in-string' calls I think.

You get that if the underlying code in ox-html changes in a way that is 
incompatible with your headline transcoder, you will have to start over. 
OTOH, since you only change one line it would not be the end of the world 
unless lots of others depend on that code and you were enjoying a 
wilderness vacation.  I would guess that such changes would be few at 
this late date.

If this is something you only use for personal work, then

#+BEGIN_SRC emacs-lisp
(org-export-define-derived-backend 'bv 'html
   :translate-alist '((headline . org-bv-headline)))
(defun org-bv-headline <your function here>)
#+END_SRC

finishes the job without a lot of fuss.

HTH,

Chuck