* Overriding org-html-headline or other export functions?
@ 2017-05-29 12:22 Brett Viren
2017-05-29 17:38 ` Charles C. Berry
2017-05-29 18:33 ` Marcin Borkowski
0 siblings, 2 replies; 7+ messages in thread
From: Brett Viren @ 2017-05-29 12:22 UTC (permalink / raw)
To: emacs-orgmode@gnu.org
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Overriding org-html-headline or other export functions?
2017-05-29 12:22 Overriding org-html-headline or other export functions? Brett Viren
@ 2017-05-29 17:38 ` Charles C. Berry
2017-05-29 18:20 ` Brett Viren
2017-05-29 18:33 ` Marcin Borkowski
1 sibling, 1 reply; 7+ messages in thread
From: Charles C. Berry @ 2017-05-29 17:38 UTC (permalink / raw)
To: Brett Viren; +Cc: emacs-orgmode@gnu.org
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Overriding org-html-headline or other export functions?
2017-05-29 17:38 ` Charles C. Berry
@ 2017-05-29 18:20 ` Brett Viren
2017-05-29 20:34 ` Brett Viren
2017-05-29 20:35 ` Charles C. Berry
0 siblings, 2 replies; 7+ messages in thread
From: Brett Viren @ 2017-05-29 18:20 UTC (permalink / raw)
To: Charles C. Berry; +Cc: emacs-orgmode@gnu.org
"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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Overriding org-html-headline or other export functions?
2017-05-29 18:20 ` Brett Viren
@ 2017-05-29 20:34 ` Brett Viren
2017-05-29 20:35 ` Charles C. Berry
1 sibling, 0 replies; 7+ messages in thread
From: Brett Viren @ 2017-05-29 20:34 UTC (permalink / raw)
To: Charles C. Berry; +Cc: emacs-orgmode@gnu.org
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Overriding org-html-headline or other export functions?
2017-05-29 18:20 ` Brett Viren
2017-05-29 20:34 ` Brett Viren
@ 2017-05-29 20:35 ` Charles C. Berry
1 sibling, 0 replies; 7+ messages in thread
From: Charles C. Berry @ 2017-05-29 20:35 UTC (permalink / raw)
To: Brett Viren; +Cc: emacs-orgmode@gnu.org
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Overriding org-html-headline or other export functions?
2017-05-29 12:22 Overriding org-html-headline or other export functions? Brett Viren
2017-05-29 17:38 ` Charles C. Berry
@ 2017-05-29 18:33 ` Marcin Borkowski
2017-05-29 19:14 ` Brett Viren
1 sibling, 1 reply; 7+ messages in thread
From: Marcin Borkowski @ 2017-05-29 18:33 UTC (permalink / raw)
To: Brett Viren; +Cc: emacs-orgmode@gnu.org
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Overriding org-html-headline or other export functions?
2017-05-29 18:33 ` Marcin Borkowski
@ 2017-05-29 19:14 ` Brett Viren
0 siblings, 0 replies; 7+ messages in thread
From: Brett Viren @ 2017-05-29 19:14 UTC (permalink / raw)
To: Marcin Borkowski; +Cc: emacs-orgmode@gnu.org
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2017-05-29 20:35 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-05-29 12:22 Overriding org-html-headline or other export functions? Brett Viren
2017-05-29 17:38 ` Charles C. Berry
2017-05-29 18:20 ` Brett Viren
2017-05-29 20:34 ` Brett Viren
2017-05-29 20:35 ` Charles C. Berry
2017-05-29 18:33 ` Marcin Borkowski
2017-05-29 19:14 ` Brett Viren
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).