diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/common-errors.rst | 19 | ||||
| -rw-r--r-- | doc/index.rst | 1 | ||||
| -rw-r--r-- | doc/intro.rst | 93 | ||||
| -rw-r--r-- | doc/markup.rst | 45 |
4 files changed, 78 insertions, 80 deletions
diff --git a/doc/common-errors.rst b/doc/common-errors.rst new file mode 100644 index 00000000..9afa4ea7 --- /dev/null +++ b/doc/common-errors.rst @@ -0,0 +1,19 @@ +Common Errors +============= + +``parse error on input ‘-- | xxx’`` +----------------------------------- + +This is probably caused by the ``-- | xxx`` comment not following a declaration. I.e. use ``-- xxx`` instead. See :ref:`top-level-declaration`. + +``parse error on input ‘-- $ xxx’`` +---------------------------------- + +You've probably commented out code like:: + + f x + $ xxx + +``-- $`` is a special syntax for named chunks, see :ref:`named-chunks`. You can fix this by escaping the ``$``:: + + -- \$ xxx diff --git a/doc/index.rst b/doc/index.rst index 0d1b8b48..f370e42f 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,7 @@ Contents: intro invoking markup + common-errors multi-components diff --git a/doc/intro.rst b/doc/intro.rst index fc1269f9..1f4234cb 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -25,7 +25,7 @@ in mind: The easier it is to write documentation, the more likely the programmer is to do it. Haddock therefore uses lightweight markup in its annotations, taking several ideas from - `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact, + `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact, Haddock can understand IDoc-annotated source code. - The documentation should not expose any of the structure of the @@ -59,8 +59,8 @@ in mind: Obtaining Haddock ----------------- -Distributions (source & binary) of Haddock can be obtained from its `web -site <http://www.haskell.org/haddock/>`__. +Haddock is distributed with GHC distributions, and will automatically be provided if you use +`ghcup <https://www.haskell.org/ghcup>`__, for instance. Up-to-date sources can also be obtained from our public GitHub repository. The Haddock sources are at @@ -72,77 +72,38 @@ License The following license covers this documentation, and the Haddock source code, except where otherwise indicated. - Copyright 2002-2010, Simon Marlow. All rights reserved. + Copyright (c) 2002-2010, Simon Marlow + All rights reserved. Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: + modification, are permitted provided that the following conditions are + met: - - Redistributions of source code must retain the above copyright + 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - - Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY - EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE - LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR - BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF - LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS - SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Contributors ------------ -Haddock was originally written by Simon Marlow. Since it is an open -source project, many people have contributed to its development over the -years. Below is a list of contributors in alphabetical order that we -hope is somewhat complete. If you think you are missing from this list, -please contact us. - -- Ashley Yakeley -- Benjamin Franksen -- Brett Letner -- Clemens Fruhwirth -- Conal Elliott -- David Waern -- Duncan Coutts -- George Pollard -- George Russel -- Hal Daume -- Ian Lynagh -- Isaac Dupree -- Joachim Breitner -- Krasimir Angelov -- Lennart Augustsson -- Luke Plant -- Malcolm Wallace -- Manuel Chakravarty -- Marcin Szamotulski -- Mark Lentczner -- Mark Shields -- Mateusz Kowalczyk -- Mike Thomas -- Neil Mitchell -- Oliver Brown -- Roman Cheplyaka -- Ross Paterson -- Sigbjorn Finne -- Simon Hengel -- Simon Marlow -- Simon Peyton-Jones -- Stefan O'Rear -- Sven Panne -- Thomas Schilling -- Wolfgang Jeltsch -- Yitzchak Gale +A list of contributors to the project can be seen at +``https://github.com/haskell/haddock/graphs/contributors``. Acknowledgements ---------------- @@ -150,11 +111,11 @@ Acknowledgements Several documentation systems provided the inspiration for Haddock, most notably: -- `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__ +- `IDoc <https://web.archive.org/web/20180621053227/http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__ -- `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__ +- `HDoc <https://mail.haskell.org/pipermail/haskelldoc/2001-April/000067.html>`__ -- `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__ +- `Doxygen <https://www.doxygen.nl/index.html>`__ and probably several others I've forgotten. diff --git a/doc/markup.rst b/doc/markup.rst index c0b08a40..abfeb52a 100644 --- a/doc/markup.rst +++ b/doc/markup.rst @@ -950,24 +950,30 @@ apostrophes themselves: to hyperlink ``foo'`` one would simply type -- | A prefix operator @'(++)'@ and an infix identifier @'`elem`'@. -Emphasis, Bold and Monospaced Text +Emphasis, Bold and Monospaced styled Text ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Emphasis may be added by surrounding text with ``/.../``. Other markup -is valid inside emphasis. To have a forward slash inside of emphasis, -just escape it: ``/fo\/o/`` +Text can be emphasized, made bold (strong) or monospaced (typewriter font) +by surrounding it with slashes, double-underscores or at-symbols: :: -Bold (strong) text is indicated by surrounding it with ``__...__``. -Other markup is valid inside bold. For example, ``__/foo/__`` will make -the emphasised text ``foo`` bold. You don't have to escape a single -underscore if you need it bold: -``__This_text_with_underscores_is_bold__``. + -- | This is /emphasized text/, __bold text__ and @monospaced text@. -Monospaced (or typewriter) text is indicated by surrounding it with -``@...@``. Other markup is valid inside a monospaced span: for example -``@'f' a b@`` will hyperlink the identifier ``f`` inside the code -fragment, but ``@__FILE__@`` will render ``FILE`` in bold with no -underscores, which may not be what you had in mind. +Note that those styled texts must be kept on the same line: :: + + -- | Styles /do not work + -- | when continuing on the next line/ + +Other markup is valid inside emphasized, bold and monospaced text. + +Frequent special cases: + +* To have a forward slash inside of emphasis, just escape it: ``/fo\/o/``. +* There's no need to escape a single underscore if you need it + bold: ``__This_text_with_underscores_is_bold__``. +* ``@'f' a b@`` will hyperlink the identifier ``f`` inside the code + fragment. +* ``@__FILE__@`` will render ``FILE`` in bold with no underscores, + which may not be what you had in mind. Linking to Modules ~~~~~~~~~~~~~~~~~~ @@ -1121,6 +1127,17 @@ followed by the URL enclosed in regular parentheses, for example: :: The link text is used as a description for the URL if the output format supports it. +Hint: There's a `known issue <https://github.com/haskell/haddock/issues/774>`_ +that any inline link at the beginning of a line within a multi-line comment +isn't rendered correctly: :: + + {-| Some multi-line comment that has a + [link](https://example.com) and a + [reference link]: https://example.com + -} + +Adding a space or a word in front of such a link can be used as a workaround. + Images ~~~~~~ |