Org backend

[ycpei]

Hello,

I decided to write an Org backend to Haddock, so that haskell library
documentation can be generated in Org Mode markup. Compared to the
existing backends (html, latex and hoogle), the org format is more
compact (e.g. ghc-lib-parser-9.2.2.20220307 weighs 56M in html output
vs. 10M in org), and allows utilising features like the infinite
levels of heading hierarchy, flexible folding / unfolding,
cross-package linking (by simply concatenating the output org files),
jumping to any declaration with org-goto and the endless potentials of
emacs customisation.

It seems to me most information and haskell language features one can
find displayed on hackage are supported by this org backend and
included in the output org files, though there are still some rough
edges and unsupported language features (like infix declarations and
linear types) which I aim to fix. Some example output can be found at
[2] (I will need to rename the "assets" part of the url as it is not
accurate), including base[4] and ghc-lib-parser[5] (I use it for
reference of the GHC API as it is easier to build than GHC). Another
example[6] demonstrates cross-packaging linking, where the fsd package
imports identifiers from debian and sqlite-simple, and you can follow
links from one package to another.

Given this is a fork 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 here if the different license (AGPLv3+) covering
my changes is accepted. The code is at [1] and the README at [3] has
further information.

Let me know what you think.

[1] https://g.ypei.me/haddock.git/tree/haddock-api
[2] https://ypei.org/assets/haddorg-output/
[3] https://g.ypei.me/haddock.git/tree/haddock-api/README.org
[4] https://ypei.org/assets/haddorg-output/base-4.16.1.0.org.gz
[5] https://ypei.org/assets/haddorg-output/ghc-lib-parser-9.2.2.20220307.org.gz
[6] https://ypei.org/assets/haddorg-output/fsd-sqlite-simple-debian.org.gz

[Kleidukos]

Hi @ycpei, and thank you very much for haddorg. :)

The licensing is a bit tricky here, as I am not a lawyer and cannot fully comprehend the consequences of having an AGPLv3+ piece of code in an otherwise BSD-3-Clause code base.

Feel free to advertise it for our colleagues who use emacs, I'm certain that this will be popular. :)

[ycpei]

On Tue 2022-07-19 01:28:23 -0700, Hécate Moonlight wrote: Hi @ycpei, and thank you very much for haddorg. :) The licensing is a bit tricky here, as I am not a lawyer and cannot fully comprehend the consequences of having an AGPLv3+ piece of code in an otherwise BSD-3-Clause code base.

An AGPLv3+ piece of code can be used with BSD3 / BSD2 code* as the latter is AGPL-compatible, it will not change the license of the work covered by BSD2/3. However, the combined work will be covered by the terms of AGPLv3+ [1]. [1] https://www.gnu.org/licenses/gpl-faq.html#WhatDoesCompatMean * haddock-api and haddock-library are apparently under BSD2 (see their .cabal files), whereas haddock is under BSD3. Not sure why. Currently the AGPL covered code is rather separate from the haddock code, basically two .hs files and some minor changes to Options.hs and Haddock.hs for invoking the org backend. A conservative approach that does not cause the whole of haddock to be licensed under AGPLv3+ might be to have the AGPL covered code as an extension in some way, like a compiler flag or how haskell-language-server works with the AGPL covered brittany. This way people who do not care the org backend can still use / work with haddock under the terms of BSD2/3. This could also mean the org backend will need to be its own package. To be further investigated.

Feel free to advertise it for our colleagues who use emacs, I'm certain that this will be popular. :)

Thanks :)

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

I am not a lawyer. The above is not legal advice. Best, Yuchen

…

-- PGP Key: 47F9 D050 1E11 8879 9040 4941 2126 7E93 EF86 DFD0 <https://ypei.org/assets/ypei-pubkey.txt>

[coot]

The link you provided, e.g. [1] does not contain any README.md file.

[ycpei]

On Fri 2022-07-22 00:19:49 -0700, Marcin Szamotulski wrote: The link you provided, e.g. [1] does not contain any README.md file.

Sorry about that. I assume you meant the README.org link in the original post is dead. That's because I updated the repo, and the file has been moved to the root dir for the cgit rendering of the "About" tab. You can read the rendered README.org at <https://g.ypei.me/haddock.git/about/>. As a general update, I've since figured out a way to build the org docs of ghc boot packages using hadrian (see the section titled "With Hadrian" on the about page). The generated docs including those of the real ghc api (rather than ghc-lib-parser) and more complete ghc-prim can be found at: - https://ypei.org/assets/haddorg-output/ghc-9.2.2/ - https://ypei.org/assets/haddorg-output/ghc-9.4.1rc1/ - https://ypei.org/assets/haddorg-output/ghc-9.5-e2f0094c/

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

Best, Yuchen

…

-- PGP Key: 47F9 D050 1E11 8879 9040 4941 2126 7E93 EF86 DFD0 <https://ypei.org/assets/ypei-pubkey.txt>