more fixups for GHC docs

[Bulat Ziganshin]

Hello Ian,

Friday, September 8, 2006, 5:52:57 AM, you wrote:

> Both fixed, thanks.

Thanks to you - owing to your work this version Release Notes is much
more useful for ghc users which don't track development process. now
it contains exhaustive information about all ghc improvements
together with links to "further reading" parts of manual

i have several more suggestions:

in GHC library paragraph - add a link to the API documentation. btw,
my download (http://www.haskell.org/ghc/dist/current/dist/ghc-6.5.20060901-i386-unknown-mingw32.tar.gz)
don't includes any library docs nor $(GHC)/doc/html/libraries/index.html
can you please fix this?

next paragraph - should point to the 7.4.10 section of user's guide
instead of "Simon's letter" :)

new RTS -V option is not mentioned here

RTS -I option - i propose to document the fact that it controls _new_
GHC facility. smth like "GHC 6.6 added experimental feature that runs
major GCs when program is idle more than 0.3 seconds, this feature is
controlled by new RTS -I flag" 

"The -split-objs flag, which makes libraries smaller" is incorrect. It
should be said "The -split-objs flag, which should be used when
building libraries in order to shrink size of executables that links
against these libraries". and documentation of this flag may be something
like:

"Tell the compiler to split the single object file that would normally
be generated into multiple object files, one per top-level Haskell
function or type in the module. This option may be used only when
building libraries. It allows to make binaries build with
these libraries smaller. On the other side, it greatly enlarges time of
library compilation, so we suggest you to use this option only to
finally compile your library and in .cabal files"



back to Release Notes, libraries section - can you please include GHC library
too, with some trivial comment like "First time included, version
1.0". The meaning of this is to have here _full_ list of all libraries
included in 6.6. it will also appear in Table of contents.

also, it will be great to use each library section heading as URL to
the docs of corresponding library:

1.4.4.1 [[url://libraries/base/index.html base]]

- version number 2.0
....

(i wrote it in Wiki style to demonstrate the idea)


It will be great to include in each paragraph here links to the
according module documentation (and, for comparison, documentation of
6.4 module). this should help users, making easier migration from 6.4

"GHC.Exts now provides a function lazy which forces GHC to think that
its argument is lazy in its first argument. " - a copy-paste typo?

lazy/inline function information can also give links to appropriate
manual sections, 7.11.1/7.11.2



section 7.5 GADT of manual - can you please change section heading to
"Generalised Algebraic Data Types (GADT)" - this simplifies search for
GADT in table of contents; and include the following instead of "These
and many other examples are given in papers by Hongwei Xi, and Tim Sheard":

>You can find more information about GADTs at the
>http://haskell.org/haskellwiki/GADT
>In particular, article "Fun with phantom types"
>(http://www.informatik.uni-bonn.de/~ralf/publications/With.pdf)
>contains a number of examples of using GADTs (please note that
>it uses slightly different syntax comparing to actually implemented
>extension)

actually, i don't seen other papers which discuss GADTs _usage_ as
opposite to implementation :(




-- 
Best regards,
 Bulat                            mailto:Bulat.Ziganshin at gmail.com