HTML export and info: links

HTML export and info: links

[Sebastian Wiesner]

Hello,

how can I customize "info:" links in HTML output?

I'd like replace "info:" links with HTML links to the corresponding
upstream manuals, such as
http://www.gnu.org/software/emacs/manual/html_node/emacs/Commands.html#Commands
for an info link "info:emacs#Commands", just like in Texinfo HTML
output. However, I cannot find a way to achieve this.

I'm trying to port the Texinfo manual of a project of mine to Org,
which worked quite well so far, but now I am stuck.  Proper "info:"
link handling is really important to me.  I don't have many "info:"
links, but each of these is important and must be rendered properly in
both, Texinfo and HTML output.

Greetings,
Sebastian Wiesner

Re: HTML export and info: links

[Bastien]

Hi Sebastian,

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> how can I customize "info:" links in HTML output?

Look at org-info.el in the source code.

You can extend

  (org-add-link-type "info" 'org-info-open)

into 

  (org-add-link-type "info" 'org-info-open org-info-export)

and write a new `org-info-export' that will take care of
exporting info links correctly in the backends you decide.

See `org-bbdb-export' or `org-docview-export' for examples
of such functions -- if you write `org-info-export', we
might be interested in integrating it into Org!

Thanks,

-- 
 Bastien

Re: HTML export and info: links

[Sebastian Wiesner]

2013/6/30 Bastien <bzg@gnu.org>:
> Hi Sebastian,
>
> Sebastian Wiesner <lunaryorn@gmail.com> writes:
>
>> how can I customize "info:" links in HTML output?
>
> Look at org-info.el in the source code.
>
> You can extend
>
>   (org-add-link-type "info" 'org-info-open)
>
> into
>
>   (org-add-link-type "info" 'org-info-open org-info-export)
>
> and write a new `org-info-export' that will take care of
> exporting info links correctly in the backends you decide.
>
> See `org-bbdb-export' or `org-docview-export' for examples
> of such functions -- if you write `org-info-export', we
> might be interested in integrating it into Org!

Hardly the answer I hoped to get.   I'll stick to Texinfo for now…

Re: HTML export and info: links

[Bastien]

Hi Sebastian,

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> Hardly the answer I hoped to get.

Please let us know the answer you hoped to get, it will
surely help us giving it :)

-- 
 Bastien

Re: HTML export and info: links

[Sebastian Wiesner]

2013/7/3 Bastien <bzg@gnu.org>:
> Hi Sebastian,
>
> Sebastian Wiesner <lunaryorn@gmail.com> writes:
>
>> Hardly the answer I hoped to get.
>
> Please let us know the answer you hoped to get, it will
> surely help us giving it :)

Uh, I hoped for a “easy, just toggle that customize setting” sort of
answer, not the “well, write it yourself” one ;)  More precisely I had
hoped for an easy way to plug Texinfo's HTML Xref Configuration [1]
into Org, which would have given proper HTML links for free.

I'll put Org mode migration of said manual on hold, for I currently
lack the time to write a proper link exporter myself.  I might get
back to it later, and look into the details of Texinfo's system, but I
can't promise anything.  I'll probably just stick to Texinfo, until
someone else does the dirty work ;)

Anyway, thank you for your answer, and please excuse the rather harsh
brevity of my previous answer.

Sebastian Wiesner

[1]: http://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Configuration.html#HTML-Xref-Configuration

Re: HTML export and info: links

[Bastien]

Hi Sebastian,

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> I'll put Org mode migration of said manual on hold, for I currently
> lack the time to write a proper link exporter myself.

I gave this a closer look: one problem is that info links are relative
to the user installation.

For example [[info:internals#Top]] goes to the XEmacs manual, but
there is no information about XEmacs in the link itself.

We can imagine some hackish prepend-this-URL-to-all-HTML-info-links
but that's really hackish...

> Anyway, thank you for your answer, and please excuse the rather harsh
> brevity of my previous answer.

No problem! 

-- 
 Bastien

Re: HTML export and info: links

[Sebastian Wiesner]

2013/7/3 Bastien <bzg@gnu.org>:
> Hi Sebastian,
>
> Sebastian Wiesner <lunaryorn@gmail.com> writes:
>
>> I'll put Org mode migration of said manual on hold, for I currently
>> lack the time to write a proper link exporter myself.
>
> I gave this a closer look: one problem is that info links are relative
> to the user installation.
>
> For example [[info:internals#Top]] goes to the XEmacs manual, but
> there is no information about XEmacs in the link itself.

Texinfo deals with problem by mapping Info manual names to URLs of
corresponding online HTML manuals, see the link in my previous post.
The built-in manual database of Texinfo is pretty comprehensive, and
covers almost all GNU manuals, and some more.  It'd be totally
sufficient for my use case.

Ideally the HTML exporter would consult this database when exporting
info links, to find out where the corresponding HTML manual is
published.

Re: HTML export and info: links

[Bastien]

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> Ideally the HTML exporter would consult this database when exporting
> info links, to find out where the corresponding HTML manual is
> published.

I see, thanks.  Is it safe to assume that htmlxref.cnf will always
be located in /usr/share/texinfo/?  E.g. is it for you?

-- 
 Bastien

Re: HTML export and info: links

[Sebastian Wiesner]

2013/7/3 Bastien <bzg@gnu.org>:
> Sebastian Wiesner <lunaryorn@gmail.com> writes:
>
>> Ideally the HTML exporter would consult this database when exporting
>> info links, to find out where the corresponding HTML manual is
>> published.
>
> I see, thanks.  Is it safe to assume that htmlxref.cnf will always
> be located in /usr/share/texinfo/?  E.g. is it for you?

It's not actually located there at all.  My Texinfo is installed via
Homebrew into "~/.homebrew", hence my "htmlxref.cnf" is  at
"~/.homebrew/share/texinfo/htmlxref.cnf".  There is no
"/usr/share/texinfo/htmlxref.cnf".

Texinfo doesn't read a single file anyway, but all of these, and
merges them into a single file.  For my manual, I use an additional
"htmlxref.cnf" right next to the ".texi" source to add some missing
links.

The Org exporter should take all of these files, and merge them by the
same rules.  For system-wide configuration files, it should either try
to get the right prefix out of the "makeinfo" executable in
"exec-path" (as returned by "executable-find"), or take the list of
files from a customization option.  The latter is probably easier, and
more predictable to the user.

Implementing this likely amounts to a fair bit of work, which I was
somewhat disappointed to learn that Org doesn't do it already :)

Re: HTML export and info: links

[Bastien]

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> It's not actually located there at all.  

It is for me (ArchLinux).

> My Texinfo is installed via
> Homebrew into "~/.homebrew", hence my "htmlxref.cnf" is  at
> "~/.homebrew/share/texinfo/htmlxref.cnf".  There is no
> "/usr/share/texinfo/htmlxref.cnf".
>
> Texinfo doesn't read a single file anyway, but all of these, and
> merges them into a single file.  For my manual, I use an additional
> "htmlxref.cnf" right next to the ".texi" source to add some missing
> links.
>
> The Org exporter should take all of these files, and merge them by the
> same rules.  For system-wide configuration files, it should either try
> to get the right prefix out of the "makeinfo" executable in
> "exec-path" (as returned by "executable-find"), or take the list of
> files from a customization option.  The latter is probably easier, and
> more predictable to the user.

Well, that's too much work for me now.  Hopefully someone who needs
this can help too.

> Implementing this likely amounts to a fair bit of work, which I was
> somewhat disappointed to learn that Org doesn't do it already :)

Me too ;)

-- 
 Bastien

Re: HTML export and info: links

[Sebastian Wiesner]

2013/7/3 Bastien <bzg@altern.org>:
> Well, that's too much work for me now.  Hopefully someone who needs
> this can help too.

I'll probably give it a shot, depending on how much free time I can
find in the next weeks.

You said, you might incorporate such an extension into Org, but isn't
Org covered by Copyright Assignments?

Re: HTML export and info: links

[Bastien]

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> 2013/7/3 Bastien <bzg@altern.org>:
>> Well, that's too much work for me now.  Hopefully someone who needs
>> this can help too.
>
> I'll probably give it a shot, depending on how much free time I can
> find in the next weeks.

Great, thanks.

> You said, you might incorporate such an extension into Org, but isn't
> Org covered by Copyright Assignments?

Yes, see this:
http://orgmode.org/cgit.cgi/org-mode.git/plain/request-assign-future.txt

-- 
 Bastien

Re: HTML export and info: links

[Sebastian Wiesner]

2013/7/3 Bastien <bzg@altern.org>:
> Sebastian Wiesner <lunaryorn@gmail.com> writes:
>
>> 2013/7/3 Bastien <bzg@altern.org>:
>>> Well, that's too much work for me now.  Hopefully someone who needs
>>> this can help too.
>>
>> I'll probably give it a shot, depending on how much free time I can
>> find in the next weeks.
>
> Great, thanks.

Don't thank me yet, I can't promise anything :)

>> You said, you might incorporate such an extension into Org, but isn't
>> Org covered by Copyright Assignments?
>
> Yes, see this:
> http://orgmode.org/cgit.cgi/org-mode.git/plain/request-assign-future.txt

Is there a single assignment for just one specific patch?  I am not
going to assign the FSF copyright for any and every future change to
Emacs I might create.

Re: HTML export and info: links

[Bastien]

Sebastian Wiesner <lunaryorn@gmail.com> writes:

> Is there a single assignment for just one specific patch?  I am not
> going to assign the FSF copyright for any and every future change to
> Emacs I might create.

The FSF policy is that you cannot assign your copyright for just one
patch, you assign it for future changes too.

-- 
 Bastien

Re: HTML export and info: links

[Sebastian Wiesner]

2013/7/3 Bastien <bzg@altern.org>:
> Sebastian Wiesner <lunaryorn@gmail.com> writes:
>
>> Is there a single assignment for just one specific patch?  I am not
>> going to assign the FSF copyright for any and every future change to
>> Emacs I might create.
>
> The FSF policy is that you cannot assign your copyright for just one
> patch, you assign it for future changes too.

This is unfortunate.  I am sorry, but under this circumstances I won't
contribute to Org mode.  I may still implement support for Info links,
but it's won't become part of Org mode, as long as I am required to
sign an assignment of such broad and unlimited scope.  I am not going
to get myself into legal trouble for such a comparatively small thing.