From: Yuchen Pei <id@ypei.org>
To: Ihor Radchenko <yantar92@gmail.com>
Cc: emacs-orgmode mailing list <emacs-orgmode@gnu.org>,
haskell-cafe <haskell-cafe@haskell.org>
Subject: Re: An org backend to Haddock
Date: Wed, 20 Jul 2022 00:41:10 +1000 [thread overview]
Message-ID: <87pmi1w4ft.fsf@ypei.me> (raw)
In-Reply-To: <87sfmx4325.fsf@localhost> (Ihor Radchenko's message of "Tue, 19 Jul 2022 21:58:26 +0800")
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
size.
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
Best,
Yuchen
--
PGP Key: 47F9 D050 1E11 8879 9040 4941 2126 7E93 EF86 DFD0
<https://ypei.org/assets/ypei-pubkey.txt>
next prev parent reply other threads:[~2022-07-19 15:57 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-07-18 12:02 An org backend to Haddock Yuchen Pei
2022-07-19 13:58 ` Ihor Radchenko
2022-07-19 14:41 ` Yuchen Pei [this message]
2022-07-20 3:55 ` Ihor Radchenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87pmi1w4ft.fsf@ypei.me \
--to=id@ypei.org \
--cc=emacs-orgmode@gnu.org \
--cc=haskell-cafe@haskell.org \
--cc=yantar92@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).