Complete documentation of Hpack's main field

[mpilgrem]

Motivation, @sol's currently undocumented explanation at:

• Cabal's main-is field (source file) does not alter GHC's -main-is option (module and function name) commercialhaskell/stack#6695 (comment)

Points of reference:

• https://www.haskell.org/onlinereport/haskell2010/haskellch5.html#x11-980005 Haskell 2010 Language Report, Chapter 5 introduction, second paragraph;
• https://downloads.haskell.org/ghc/latest/docs/users_guide/phases.html#ghc-flag-main-is-thing GHC User's Guide, 5.11.6, documentation of -main-is; and
• https://cabal.readthedocs.io/en/latest/cabal-package-description-file.html#pkg-field-executable-main-is Cabal User Guide, 1.2.4, documentation of main-is field.

Unusually, for Hpack's approach to its README, I have added three short sentences of introductory context boiled down from the Haskell 2010 Language Report and the GHC User's Guide. That is because the scope for confusion is high.

[sol]

https://gitlab.haskell.org/ghc/ghc/-/issues/13801 limits the utility of this feature quite a bit.

Indeed, because of this limitations I myself rarely use this feature at all.

I am not sure if this feature is ready for mass consumption until the corresponding GHC issue is resolved.

@mpilgrem do you still think it is useful to document this, or should we keep this PR open until the corresponding GHC issue is resolved? If you want to get this merged now, do you think this needs a disclaimer of some sort?

[sol]

This is not entirely accurate. Foo.hs is a valid qualified name. However, we interpreted as a file name.

It's roughly:

1. If it looks like a Haskell source file (ends in .hs or .lhs), we interpret it as a file path.
2. If it is a valid qualified name, we take it as a qualified name.
3. If it is a valid module name, we take it as a module name.
4. As a fallback we take it as a file path.

Or in other words, Hpack does not accept entry points named hs or lhs.

hpack/src/Hpack/Util.hs

Lines 55 to 61 in e11cf4f

	parseMain :: String -> (FilePath, [GhcOption])
	parseMain main = case reverse name of
	x : _ | isQualifiedIdentifier name && x `notElem` ["hs", "lhs"] -> (intercalate "/" (init name) ++ ".hs", ["-main-is " ++ main])
	_ | isModule name -> (intercalate "/" name ++ ".hs", ["-main-is " ++ main])
	_ -> (main, [])
	where
	name = splitOn '.' main

[sol]

Suggested change

	performed. However, GHC's `main-is` option can be used to change the name of the
	performed. However, GHC's `-main-is` option can be used to change the name of the

[sol]

I think we don't frequently document things in terms of how they desugar to .cabal syntax. Rather we document how they can be used, so that a user does not need to be familiar with Cabal to be able to use Hpack.

I'm not saying this is necessarily bad, just want to bring it up.