[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: An org backend to Haddock

From: Yuchen Pei
Subject: Re: An org backend to Haddock
Date: Wed, 20 Jul 2022 00:41:10 +1000
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/28.1 (gnu/linux)

On Tue 2022-07-19 21:58:26 +0800, Ihor Radchenko wrote:

> Yuchen Pei <id@ypei.org> writes:
>> Given this is not the official version of haddock and my changes are in
>> haddock-api, I'm calling it haddorg-api, for lack of a better name /
>> approach.  I'll be happy to contribute my changes upstream if a
>> different license covering my contribution (AGPLv3+) is accepted.
>> Let me know what you think.
> I am pretty sure that you are asking the Haskell people for upstreaming
> ;)

Yes - I sent the email to both haskell-cafe and emacs-orgmode, but
upstream here means haddock / haddock-api indeed, thanks for clarifying.

> From Org side, it is always welcome when other Free software projects
> are making use of Org.
> Also, I looked into
> https://g.ypei.me/haddock.git/tree/haddock-api/src/Haddock/Backends/Org/Types.hs
> Beware of possible edge cases with "*/~|" in formatting. I am not
> sure if text containing such symbols is possible as an input for your
> library, but if it is, things may get formatted wrongly.
> For example, text containing "|" anywhere inside a table field must have
> "|" escaped using \vert entity. The markup can be escaped using
> zero-width space.

True.  I have not addressed these edge cases in my code, except a quick
hack to prepend a space whenever any line a src block / result block has
a leading star.  Tables on the other hand are extremely rare in Haskell
package documentation strings, and having a | in them is even rarer.

I do wonder what is the best way to handle cross-package links.
Currently I'm using CUSTOM_ID in the format of
package-name-x.y.z.Module.Name.IdentifierName, as well as
Module.Name.IdentifierName.  But this is a "one big org file" approach,
and can make navigation slow when say the org file reaches 15+MB in

Ideally one should be able to navigate the a hackage worth of
documentations easily, with working cross-package links and low latency
org-goto to jump to any identifier or module, but I don't see how to
achieve that.  To be further investigated.

> Best,
> Ihor


PGP Key: 47F9 D050 1E11 8879 9040  4941 2126 7E93 EF86 DFD0

reply via email to

[Prev in Thread] Current Thread [Next in Thread]