From 9bd2bf9e8cbf1b2cc2affd27096b79d149528c5b Mon Sep 17 00:00:00 2001 From: Njagi Mwaniki Date: Sat, 27 Dec 2014 23:28:59 +0300 Subject: Turn the README into GitHub Markdown format. Closes #354 --- README | 37 ------------------------------------- README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ doc/README | 26 -------------------------- doc/README.md | 25 +++++++++++++++++++++++++ 4 files changed, 72 insertions(+), 63 deletions(-) delete mode 100644 README create mode 100644 README.md delete mode 100644 doc/README create mode 100644 doc/README.md diff --git a/README b/README deleted file mode 100644 index 53f84bf0..00000000 --- a/README +++ /dev/null @@ -1,37 +0,0 @@ -Haddock, a Haskell Documentation Tool -===================================== - -This is Haddock, a tool for automatically generating documentation -from annotated Haskell source code. It is primary intended for -documenting library interfaces, but it should be useful for any kind -of Haskell code. - -Haddock lets you write documentation annotations next to the -definitions of functions and types in the source code, in a syntax -that is easy on the eye when writing the source code (no heavyweight -mark-up). The documentation generated by Haddock is fully hyperlinked -- click on a type name in a type signature to go straight to the -definition, and documentation, for that type. - -Haddock understands Haskell's module system, so you can structure your -code however you like without worrying that internal structure will be -exposed in the generated documentation. For example, it is common to -implement a library in several modules, but define the external API by -having a single module which re-exports parts of these implementation -modules. Using Haddock, you can still write documentation annotations -next to the actual definitions of the functions and types in the -library, but the documentation annotations from the implementation -will be propagated to the external API when the documentation is -generated. Abstract types and classes are handled correctly. In -fact, even without any documentation annotations, Haddock can generate -useful documentation from your source code. - -Haddock can generate documentation in multiple formats; currently HTML -is implemented, and there is partial support for generating LaTeX and -Hoogle. - -Full documentation can be found in the doc/ subdirectory, in DocBook -format. - -Please create issues when you have any problems and pull requests if -you have some code. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 00000000..b85d99b7 --- /dev/null +++ b/README.md @@ -0,0 +1,47 @@ +# Haddock, a Haskell Documentation Tool + + +#### About haddock + +This is Haddock, a tool for automatically generating documentation +from annotated Haskell source code. It is primary intended for +documenting library interfaces, but it should be useful for any kind +of Haskell code. + +Haddock lets you write documentation annotations next to the +definitions of functions and types in the source code, in a syntax +that is easy on the eye when writing the source code (no heavyweight +mark-up). The documentation generated by Haddock is fully hyperlinked +- click on a type name in a type signature to go straight to the +definition, and documentation, for that type. + +Haddock understands Haskell's module system, so you can structure your +code however you like without worrying that internal structure will be +exposed in the generated documentation. For example, it is common to +implement a library in several modules, but define the external API by +having a single module which re-exports parts of these implementation +modules. Using Haddock, you can still write documentation annotations +next to the actual definitions of the functions and types in the +library, but the documentation annotations from the implementation +will be propagated to the external API when the documentation is +generated. Abstract types and classes are handled correctly. In +fact, even without any documentation annotations, Haddock can generate +useful documentation from your source code. + + +#### Documentation formats + +Haddock can generate documentation in multiple formats; currently HTML +is implemented, and there is partial support for generating LaTeX and +Hoogle. + + +#### Source code documentation + +Full documentation can be found in the doc/ subdirectory, in DocBook +format. + + +#### Contributing + +Please create issues when you have any problems and pull requests if you have some code. diff --git a/doc/README b/doc/README deleted file mode 100644 index 5bc038bf..00000000 --- a/doc/README +++ /dev/null @@ -1,26 +0,0 @@ -Haddock documentation ---------------------- - -The documentation is in DocBook XML format. You need some tools to -process it: at least xsltproc, and the DocBook XML DTD and XSL -stylesheets. There's a configure script to detect the right way to -process the documentation on your system, and a Makefile to actually -do the processing (so, on Windows, you'll need Cygwin or MSys in -addition to the DocBook XML tools). To build the HTML documentation: - - $ autoconf - $ ./configure - $ make html - -which leaves the HTML documentation in a haddock/ subdirectory. - -Printable documentation can also be produced, eg.: - - $ make pdf - -or - - $ make ps - -Generating the printed formats requires more tools (fop or xmltex) and -tends to be a bit harder. diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 00000000..cf1fc31b --- /dev/null +++ b/doc/README.md @@ -0,0 +1,25 @@ +# Haddock documentation + +The documentation is in DocBook XML format. You need some tools to +process it: at least xsltproc, and the DocBook XML DTD and XSL +stylesheets. There's a configure script to detect the right way to +process the documentation on your system, and a Makefile to actually +do the processing (so, on Windows, you'll need Cygwin or MSys in +addition to the DocBook XML tools). To build the HTML documentation: + + $ autoconf + $ ./configure + $ make html + +which leaves the HTML documentation in a haddock/ subdirectory. + +Printable documentation can also be produced, eg.: + + $ make pdf + +or + + $ make ps + +Generating the printed formats requires more tools (fop or xmltex) and +tends to be a bit harder. -- cgit v1.2.3