Open ycpei opened 2 years ago
Kleidukos
commented
2 years ago 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
commented
2 years ago 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
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
commented
2 years ago The link you provided, e.g. [1] does not contain any README.md file.
ycpei
commented
2 years ago 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:
— 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
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