Refactor embedded files

[thomie]

The goal of this refactoring is to remove the symlinks from hledger/embeddedfiles to hledger-ui and hledger-web:

iff --git a/hledger/hledger.cabal b/hledger/hledger.cabal
index 93e034184..b25ed804b 100644
--- a/hledger/hledger.cabal
+++ b/hledger/hledger.cabal
@@ -46,18 +46,10 @@ extra-source-files:
     embeddedfiles/hledger-import.md
     embeddedfiles/hledger-incomestatement.md
     embeddedfiles/hledger-print.md
-    embeddedfiles/hledger-ui.md
-    embeddedfiles/hledger-web.md
     embeddedfiles/hledger.md
     embeddedfiles/hledger.1
     embeddedfiles/hledger.txt
     embeddedfiles/hledger.info
-    embeddedfiles/hledger-ui.1
-    embeddedfiles/hledger-ui.txt
-    embeddedfiles/hledger-ui.info
-    embeddedfiles/hledger-web.1
-    embeddedfiles/hledger-web.txt
-    embeddedfiles/hledger-web.info
     Hledger/Cli/Commands/Accounts.txt
     Hledger/Cli/Commands/Activity.txt

I recently caught the Nix bug, and those symlinks across cabal projects are causing problems when trying to build hledger from inside a git repository (as mentioned in #2063, and #2044 is relevant).

This refactoring:

• moves the helper functions printHelpForTopic', runManForTopic', runInfoForTopic', runPagerForTopic and runTldrForPage' to hledger-lib:Hledger.Utils.Docfiles.
• adds the modules Hledger.Web.DocFiles to hledger-web and Hledger.UI.DocFIles to hledger-ui, which now embed their own info/man/tldr pages directly
• removes symlinks from hledger/embeddedfiles to hledger-ui and hledger-web

There are still symlinks to ../../docs/utils, also outside of the cabal project, but those are less problematic.

I tested the builds both with nix and cabal. There should not be any user visible changes.

[thomie]

Hmm, changing the location of the man pages (from ./hledger-ui.1 to ./embeddedfiles/hledger-ui.1) will probably cause busy work for package maintainers.

Perhaps I should just leave the files where they were.

[simonmichael]

FWIW I suspect the majority of packagers get man pages from a github or hackage tarball.

[simonmichael]

Or at least, I'm not too worried about this. Will look.

[thomie]

Yes, so this changes the hackage tarball I believe.

Compare
hledger: https://hackage.haskell.org/package/hledger-1.42/src/
hledger-ui: https://hackage.haskell.org/package/hledger-ui-1.42/src/

The man pages in the hledger tarball are inside the subdirectory embeddedfiles, and so package maintainers have to find them there, while the man pages in hledger-ui are currently in the toplevel directory.

We should probably not change this setup without a good reason.

[simonmichael]

Thank you! I hope to look at this soon.

[simonmichael]

My goal was for hledger help to be able to bring up any hledger-related help including that for addons like ui and web. But this was never implemented, and I see this is a good simplification for packaging. I suppose help could run hledger-web --info in future if it needed to.

Is the temporary lib still needed in the hledger package ?

Having four modules named DocFiles.hs is something I'd try to avoid. What would you think of calling three of them CliDocs.hs, UiDocs.hs and WebDocs.hs ?

Now that the DocFiles helpers are reusable utilities, defined apart from use, the bar is a little higher and I find them a bit confusing. And I don't love having ' in their names. But it's not a blocker, we might find ways to clarify them in future.

[simonmichael]

I'm not against moving manuals in the tarballs if it makes things clearer and simpler, I will just document it at release time.

Currently the manuals are generated in each package's top directory, and I think it's natural for them to be in the same place (top level) of the hackage tarballs. Likewise in the github tarballs/zip file, they are at top level alongside the executables. They are important artifacts.

I don't know if it's necessary for manuals to be symlinked into the embeddedfiles/ subdirectory, if it simplifies we could drop those links. I think it was just convenient to see all embedded things in one place. Also embeddedfiles is a place to store the .cast files, and the tldr files.

I think tldr files probably do need to remain symlinked somehow because they come from doc/tldr/ which corresponds roughly to pages/common/ in the tldr repo. But maybe not.