aboutsummaryrefslogtreecommitdiff
path: root/hcar.tex
diff options
context:
space:
mode:
Diffstat (limited to 'hcar.tex')
-rw-r--r--hcar.tex65
1 files changed, 65 insertions, 0 deletions
diff --git a/hcar.tex b/hcar.tex
new file mode 100644
index 00000000..e5ca8a20
--- /dev/null
+++ b/hcar.tex
@@ -0,0 +1,65 @@
+% Haddock-DH.tex
+\begin{hcarentry}[updated]{Haddock}
+\label{haddock}
+\report{David Waern}%11/10
+\status{experimental, maintained}
+\makeheader
+
+Haddock is a widely used documentation-generation tool for Haskell
+library code. Haddock generates documentation by parsing and typechecking
+Haskell source code directly and including documentation supplied by the
+programmer in the form of specially-formatted comments in the source code
+itself. Haddock has direct support in Cabal~\cref{cabal}, and is used to
+generate the documentation for the hierarchical libraries that come with GHC,
+Hugs, and nhc98
+(\url{http://www.haskell.org/ghc/docs/latest/html/libraries}) as well as
+the documentation on Hackage.
+
+The latest release is version 2.8.1, released September 3 2010.
+
+\Separate
+Recent changes:
+\begin{itemize}
+\item HTML backend completely rewritten to generate semantically rich XHTML
+ using the xhtml package.
+\item New default CSS based on the color scheme chosen for the new Haskell
+ wiki, with a pull-out tab for the synopsis.
+\item Theme engine based on CSS files. Themes can be switched from the
+ header menu.
+\item Markup support for executable examples/unit-tests.
+\item Addition of a LaTeX backend.
+\item Additions and changes to the Haddock API.
+\item Various smaller new features and bug fixes.
+\end{itemize}
+
+\FuturePlans
+\begin{itemize}
+\item Although Haddock understands many GHC language extensions, we would like it to
+understand all of them. Currently there are some constructs you cannot comment,
+like GADTs and associated type synonyms.
+
+\item Error messages is an area with room for improvement. We would like Haddock
+to include accurate line numbers in markup syntax errors.
+
+\item On the HTML rendering side we want to make more use of Javascript in order to make
+the viewing experience better. The frames-mode could be improved this way, for
+example.
+
+\item Finally, the long term plan is to split Haddock into one program that creates
+data from sources, and separate backend programs that use that data via the
+Haddock API. This will scale better, not requiring adding new backends to Haddock
+for every tool that needs its own format.
+\end{itemize}
+
+\FurtherReading
+\begin{compactitem}
+\item Haddock's homepage:
+\url{http://www.haskell.org/haddock/}
+
+\item Haddock's developer Wiki and Trac:
+\url{http://trac.haskell.org/haddock}
+
+\item Haddock's mailing list:
+\url{haddock@@projects.haskell.org}
+\end{compactitem}
+\end{hcarentry}