Skip to content

Instantly share code, notes, and snippets.

@Fuuzetsu

Fuuzetsu/jbracker-haddock-GSoC2013.md Secret

Forked from jbracker/jbracker-haddock-GSoC2013.md
Last active December 17, 2015 19:58
Show Gist options
  • Save Fuuzetsu/81253ba7d0c51ac88052 to your computer and use it in GitHub Desktop.
Save Fuuzetsu/81253ba7d0c51ac88052 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. Mateusz Kowalczyk revised this gist May 28, 2013. 1 changed file with 3 additions and 1 deletion.
    4 changes: 3 additions & 1 deletion jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,3 +1,5 @@
    The following was proposed by jbracker but as jbracker was picked for a different project, I (Fuuzetsu) have been asked to foster this proposal and have since been accepted to do so.

    # Improve Haddock markup and capabilities

    Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].
    @@ -11,7 +13,7 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].

    * _In what ways will this project benefit the wider Haskell community?_

    Haddock is _the_ standard tool for documenting Haskell. It is used on the central package plattform
    Haddock is _the_ standard tool for documenting Haskell. It is used on the central package platform
    Hackage for generating all documentation. Improving this tool will benefit the Haskell community greatly,
    in giving it a more powerful tool to document its code.

  2. Jan Bracker revised this gist Apr 28, 2013. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -22,9 +22,9 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].
    * _What deliverables do you think are reasonable targets? Can you outline an approximate schedule of milestones?_
    The timeplan is based on the GSoC timeplan:
    * _28. May - 16. Jun_: Students get to know mentors, read documentation, get up to speed to begin working on their projects.
    * **Milestone 1**: 100% feature compatible transition to a new parser.
    * **Milestone 1**: 100% feature compatible transition to a new parser (part 1 of the goal).
    * _17. Jun - 29. Jul_: Mentors give students a helping hand and guidance on their projects.
    * **Milestone 2**: Lift current but unnecessary restrictions that are backward compatible.
    * **Milestone 2**: Lift current but unnecessary restrictions that are backward compatible (part 2 of the goal).
    * _29. Jul - 02. Aug_: Mentors and students can begin submitting mid-term evaluations.
    * _02. Aug - 16. Sep_: Mentors give students a helping hand and guidance on their projects.
    * **Milestone 3**: Implement as many extended features as possible. Priority lays on part 3.
  3. Jan Bracker revised this gist Apr 28, 2013. 1 changed file with 1 addition and 3 deletions.
    4 changes: 1 addition & 3 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -245,9 +245,7 @@ A search in the documentation through JavaScript might be a nice feature.

    * Haddock can generate a JSON search index.

     * This would make documentation easily searchable through 
     third party tools, without the need for a central search 
       engine like Hoogle or Hayoo.
     * This would make documentation easily searchable through third party tools, without the need for a central search engine like Hoogle or Hayoo.

    ## Documentation

  4. Jan Bracker revised this gist Apr 28, 2013. 1 changed file with 5 additions and 4 deletions.
    9 changes: 5 additions & 4 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -243,10 +243,11 @@ These goals can be tackled if time permits it.

    A search in the documentation through JavaScript might be a nice feature.

     * Haddock can generate a JSON index file.
     * This would make documentation easily searchable through 
       thrid party tools, without the need for a central search 
       engine like Hoogle or Hayoo.
    * Haddock can generate a JSON search index.

     * This would make documentation easily searchable through 
     third party tools, without the need for a central search 
       engine like Hoogle or Hayoo.

    ## Documentation

  5. Jan Bracker revised this gist Apr 28, 2013. 1 changed file with 6 additions and 4 deletions.
    10 changes: 6 additions & 4 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -237,14 +237,16 @@ I would favor the adaptation, because it is close to the already existing syntax

    ## Optional Additional Goals

    These goals can be tackled if time permits it.

    ### Search in Documentation

    A search in the documentation through JavaScript might be a nice feature.

     * Haddock can generate a JSON index file.
     * This would make documentation easily searchable through 
       thrid party tools, without the need for a central search 
       engine like Hoogle or Hayoo.
     * Haddock can generate a JSON index file.
     * This would make documentation easily searchable through 
       thrid party tools, without the need for a central search 
       engine like Hoogle or Hayoo.

    ## Documentation

  6. Jan Bracker revised this gist Apr 28, 2013. 1 changed file with 4 additions and 14 deletions.
    18 changes: 4 additions & 14 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -22,22 +22,12 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].
    * _What deliverables do you think are reasonable targets? Can you outline an approximate schedule of milestones?_
    The timeplan is based on the GSoC timeplan:
    * _28. May - 16. Jun_: Students get to know mentors, read documentation, get up to speed to begin working on their projects.
    * Read Haddock sources
    * Familiarize with Haddock
    * Work on details of new syntax
    * Try prototype solutions
    * **Milestones**:
    Implement the new syntax for images and improve on list parsing.
    This should be fairly easy to achieve as a first goal to get familiar with Haddocks internals.
    * **Milestone 1**: 100% feature compatible transition to a new parser.
    * _17. Jun - 29. Jul_: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement the flags for images.
    Implement conditional code for activation, further inline markup and headings.
    * **Milestone 2**: Lift current but unnecessary restrictions that are backward compatible.
    * _29. Jul - 02. Aug_: Mentors and students can begin submitting mid-term evaluations.
    * _02. Aug - 16. Sep_: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement support for documentation of GADTs and type families.
    Work on generation of JSON search index.
    * **Milestone 3**: Implement as many extended features as possible. Priority lays on part 3.
    * _16. Sep - 23. Sep_: Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.

    * _What relevant experience do you have? e.g. Have you coded anything in Haskell? Have you
    @@ -65,7 +55,7 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].

    # Goals

    A disscussion with Simon Hengel has brought up the issue that Haddock is hard to extends and maintain, because of the currently used parser (Happy/Alex). Their limited lookahead and backtracking make it hard to implement many of the desired features. This is why I am suggesting to use a backtracking parser instead (preferably [Attoparsec][Hackage:Attoparsec]). The plan to convert and extend Haddock would look as follows:
    A disscussion with Simon Hengel has brought up the issue that Haddock is hard to extends and maintain, because of the currently used parser (Happy/Alex). Their limited lookahead and backtracking make it hard to implement many of the desired features. This is why I am suggesting to use a backtracking parser instead (preferably [Attoparsec][Hackage:Attoparsec]). The plan to convert and extend Haddock would have the following milestones:

    1. First I reimplement the exisiting parser using the new one. This will result in a 100% feature compatible Haddock parser.
    2. The second step would be to extend that parser by lifting current, but unnecessary restrictions of the parser:
  7. Jan Bracker revised this gist Apr 28, 2013. 1 changed file with 70 additions and 45 deletions.
    115 changes: 70 additions & 45 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -52,7 +52,7 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].
    How will you get others interested in what you are doing?_

    * I could twitter about improvements, giving everybody a chance to see my progress.
    * I will be online in the Haskell IRC channel for discussion with the Haskell community about problems and suggestions.
    * I will be online in the Haskell IRC channel for discussion with the Haskell community about problems and suggestions (Nick: jbracker).
    * The Haskell mailing list would be a great reference for bigger problems and continuous discussions.
    * It might also be useful to store code on GitHub, because it offers a easy way to comment changes and discuss problems.

    @@ -65,19 +65,76 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].

    # Goals

    A disscussion with Simon Hengel has brought up the issue that Haddock is hard to extends and maintain, because of the currently used parser (Happy/Alex). Their limited lookahead and backtracking make it hard to implement many of the desired features. This is why I am suggesting to use a backtracking parser instead (preferably [Attoparsec][Hackage:Attoparsec]). The plan to convert and extend Haddock would look as follows:

    1. First I reimplement the exisiting parser using the new one. This will result in a 100% feature compatible Haddock parser.
    2. The second step would be to extend that parser by lifting current, but unnecessary restrictions of the parser:
    * Empty line between items of a list;
    * Missing title for images;
    * Support for GADTs and Type Functions;
    This will keep it backward compatible and broaden the accepted Haddock.
    3. Implement features that are not backward compatible, but unlikely to break existing Haddock comments, e.g. URL autolinking
    4. Implement a flag to activate extended syntax support. This will
    include implementing most of the suggestions listed in the
    following sections.

    Of course, there is a dependency issue when moving to another parser library. For Attoparsec we can avoid this
    by adding the relevant Attoparsec sources to Haddock. The dependency to `Data.Text` remains a problem.
    If it is added to the core libraries in future we do not have to worry about this. Otherwise we can just use
    the `ByteString` based version of Attoparsec to avoid that dependency. I have discussed this with Simon and
    there should be no problems with this approach.

    In general a test driven development approach would be good, so new code is tested right away. I will try to write all tests for new code right away.

    ## Backward Compatible Enhancements

    The following enhancements would define the goal for step two of the previously suggested approach.

    Haddock misses support to document widely used language extensions:

    * Implement support to document GADTs.

    Right now the most recent version of Haddock (2.13.2) produces a parse error on this code:
    ```haskell
    -- | A tree GADT
    data Tree a where
    -- | Leaf constructor
    Leaf :: a -- ^ Leaf content
    -> Tree a -- ^ The singleton tree
    -- | Fork constructor
    Fork :: Tree a -- ^ Left branch
    -> Tree a -- ^ Right branch
    -> Tree a -- ^ The tree
    -- | Special constructor
    Special :: String -- ^ It needs a string
    -> Int -- ^ It needs a integer
    -> Tree String -- ^ It is specialised
    ```
    I plan to implement all these comments.


    * Implement support to document type family instances.

    * Each module documentation should contain a list of all activated language extensions (and other important flags).
    A extensions needed by a certain package can be listed on the package index page.

    * Right now entries of a list have to be separated by empty line. I do not see the necessity for this rule.
    I think it would be more convenient to just enforce all contents of a list entry to be right of the column
    the bullet it appeared in.

    ## Markup

    This section discusses the extensions to haddock that would be part of step 3 or 4.

    Looking at the [Haskell cafe discussion][Discussion:Tibell:HaskellCafe] there are several different suggestions for markup languages:
    * [Markdown][Language:Markdown]
    * [reStructuredText][Language:ReStructuredText]
    * [Creole][Language:WikiCreole]
    * [Pandoc][Language:Pandoc] - This has to widespread dependencies for a core tool.

    The major issue with Markdown is that it is ambiguious and does not have a formal and commonly agreed syntax. The major advantage of the other two languages is that they have a well known syntax and semantic, but they seem to mighty for the context of source documentation.

    Generally I would be in favor of extending the existing Haddock language to support missing features. This will make it easy for long-time users to adjust. It will also keep Haddock more maintainable, since adding a completely new markup would mean twice the maintenance later.
    The major issue with Markdown is that it is ambigious and does not have a formal and commonly agreed syntax. The major advantage of the other two languages is that they have a well known syntax and semantic, but they seem to mighty for the context of source documentation.

    On the other hand the list of missing features and improvements is big and a new markup language might be beneficial to resolve these issue properly.
    Generally it would be in favorable to extend the existing Haddock language to support missing features. This will make it easy for long-time users to adjust. It will also keep Haddock more maintainable, since adding a completely new markup would mean twice the maintenance later.

    ### Activation and Integration

    @@ -188,58 +245,24 @@ Adaptation of existing syntax combined with the syntax for links:
    ```
    I would favor the adaptation, because it is close to the already existing syntax and fits in well with the syntax for links.

    ### Lists

    Right now entries of a list have to be separated by empty line. I do not see the necessity for this rule.
    I think it would be more convenient to just enforce all contents of a list entry to be right of the column
    the bullet appeared in.

    ## Capabilities

    Haddock misses support to document widely used language extensions:

    * Implement support to document GADTs.

    Right now the most recent version of Haddock (2.13.2) produces a parse error on this code:
    ```haskell
    -- | A tree GADT
    data Tree a where
    -- | Leaf constructor
    Leaf :: a -- ^ Leaf content
    -> Tree a -- ^ The singleton tree
    -- | Fork constructor
    Fork :: Tree a -- ^ Left branch
    -> Tree a -- ^ Right branch
    -> Tree a -- ^ The tree
    -- | Special constructor
    Special :: String -- ^ It needs a string
    -> Int -- ^ It needs a integer
    -> Tree String -- ^ It is specialised
    ```
    I plan to implement all these comments.


    * Implement support to document type family instances.

    * Each module documentation should contain a list of all activated language extensions (and other important flags).
    A extensions needed by a certain package can be listed on the package index page.
    ## Optional Additional Goals

    ### Search in Documentation

    A search in the documentation through JavaScript might be a nice feature.

    * Haddock can generate a JSON index file.
    * This would make documentation easily searchable through
    thrid party tools, without the need for a central search
    engine like Hoogle or Hayoo.
     * Haddock can generate a JSON index file.
     * This would make documentation easily searchable through 
       thrid party tools, without the need for a central search 
       engine like Hoogle or Hayoo.

    ## Documentation

    A major point would also be to update documentation and add undocumented features (like the image tags `<<img>>`).

    ## Markdown Ideas

    These are ideas I previously thought about when adding Markdown.
    These are ideas I previously thought about when adding Markdown. They should not be considered part of the goals.

    ### Activation and integration

    @@ -323,3 +346,5 @@ For every heading that is higher then level one that shoul be no conflicts anymo

    [Homepage:Sunroof]: http://www.ittc.ku.edu/csdl/fpg/software/sunroof.html
    [GitHub:Diagrams:Generalization]: https://github.com/diagrams/diagrams-lib/pull/65

    [Hackage:Attoparsec]: http://hackage.haskell.org/package/attoparsec
  8. Jan Bracker revised this gist Apr 25, 2013. 1 changed file with 3 additions and 0 deletions.
    3 changes: 3 additions & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -221,6 +221,9 @@ Haddock misses support to document widely used language extensions:

    * Implement support to document type family instances.

    * Each module documentation should contain a list of all activated language extensions (and other important flags).
    A extensions needed by a certain package can be listed on the package index page.

    ### Search in Documentation

    A search in the documentation through JavaScript might be a nice feature.
  9. Jan Bracker revised this gist Apr 25, 2013. 1 changed file with 19 additions and 19 deletions.
    38 changes: 19 additions & 19 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -20,25 +20,25 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].
    Please, refer to the goals section. It is specific about each goal.

    * _What deliverables do you think are reasonable targets? Can you outline an approximate schedule of milestones?_
    * GSoC Plan:
    * 28. May - 16. Jun: Students get to know mentors, read documentation, get up to speed to begin working on their projects.
    * Read Haddock sources
    * Familiarize with Haddock
    * Work on details of new syntax
    * Try prototype solutions
    * **Milestones**:
    Implement the new syntax for images and improve on list parsing.
    This should be fairly easy to achieve as a first goal to get familiar with Haddocks internals.
    * 17. Jun - 29. Jul: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement the flags for images.
    Implement conditional code for activation, further inline markup and headings.
    * 29. Jul - 02. Aug: Mentors and students can begin submitting mid-term evaluations.
    * 02. Aug - 16. Sep: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement support for documentation of GADTs and type families.
    Work on generation of JSON search index.
    * 16. Sep - 23. Sep: Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
    The timeplan is based on the GSoC timeplan:
    * _28. May - 16. Jun_: Students get to know mentors, read documentation, get up to speed to begin working on their projects.
    * Read Haddock sources
    * Familiarize with Haddock
    * Work on details of new syntax
    * Try prototype solutions
    * **Milestones**:
    Implement the new syntax for images and improve on list parsing.
    This should be fairly easy to achieve as a first goal to get familiar with Haddocks internals.
    * _17. Jun - 29. Jul_: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement the flags for images.
    Implement conditional code for activation, further inline markup and headings.
    * _29. Jul - 02. Aug_: Mentors and students can begin submitting mid-term evaluations.
    * _02. Aug - 16. Sep_: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement support for documentation of GADTs and type families.
    Work on generation of JSON search index.
    * _16. Sep - 23. Sep_: Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.

    * _What relevant experience do you have? e.g. Have you coded anything in Haskell? Have you
    contributed to any other open source software? Been studying advanced courses in a related topic?_
  10. Jan Bracker revised this gist Apr 25, 2013. 1 changed file with 22 additions and 7 deletions.
    29 changes: 22 additions & 7 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -20,8 +20,25 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].
    Please, refer to the goals section. It is specific about each goal.

    * _What deliverables do you think are reasonable targets? Can you outline an approximate schedule of milestones?_

    TODO
    * GSoC Plan:
    * 28. May - 16. Jun: Students get to know mentors, read documentation, get up to speed to begin working on their projects.
    * Read Haddock sources
    * Familiarize with Haddock
    * Work on details of new syntax
    * Try prototype solutions
    * **Milestones**:
    Implement the new syntax for images and improve on list parsing.
    This should be fairly easy to achieve as a first goal to get familiar with Haddocks internals.
    * 17. Jun - 29. Jul: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement the flags for images.
    Implement conditional code for activation, further inline markup and headings.
    * 29. Jul - 02. Aug: Mentors and students can begin submitting mid-term evaluations.
    * 02. Aug - 16. Sep: Mentors give students a helping hand and guidance on their projects.
    * **Milestones**:
    Implement support for documentation of GADTs and type families.
    Work on generation of JSON search index.
    * 16. Sep - 23. Sep: Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.

    * _What relevant experience do you have? e.g. Have you coded anything in Haskell? Have you
    contributed to any other open source software? Been studying advanced courses in a related topic?_
    @@ -165,13 +182,11 @@ Markdown:
    ```
    ![image.jpg](Title)
    ```
    Adaptation of existing syntax:
    Adaptation of existing syntax combined with the syntax for links:
    ```
    <<Title|image.jpg>>
    <<image.jpg Title>>
    ```
    Again I would favor either the Markdown version or the adaptation.
    The Markdown version, because it is used within the community.
    The adaptation, because it is close to the already existing syntax.
    I would favor the adaptation, because it is close to the already existing syntax and fits in well with the syntax for links.

    ### Lists

  11. Jan Bracker revised this gist Apr 25, 2013. 1 changed file with 0 additions and 24 deletions.
    24 changes: 0 additions & 24 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -138,24 +138,6 @@ Though I am not yet sure if one or two underbars should be required.

    I think the notation with `*` used by Markdown should not be supported, because it may cause conflicts with lists.

    ### Proper Support for Links with Text

    WikiCreole uses the following syntax:
    ```
    [[http://example.com|Example Domain]]
    ```
    Markdown uses this syntax:
    ```
    [Example Domain](http://example.com)
    ```
    An adaptation of the existing syntax:
    ```
    <Text|http://example.com>
    ```
    Both use the square brackets, which also seems apealing to me. As many people in the Haskell community seems to prefer Markdown I would suggest to either use the second syntax for links or adapt the existing syntax in the given way.
    The adaptation would fit well with the already existing syntax, instead of introducing another syntax.
    Links without text can still be supported through the `<link>` notation already provided by Haddock.

    ### Proper Support for Images

    There already seems to be support to embed images: `<<img>>`. The paths seem to be static.
    @@ -277,19 +259,15 @@ rest would not be.
    ### Headings

    There is a [problem with the C-preprocessor][Discussion:Tibell:HaskellCafe].


    ```haskell
    {-# LANGUAGE GADTs #-}
    -- # My Header
    #ifdef evil_c
    -- ...
    #endif
    ```

    A single space can resolve this problem and if it arises there is still the alternative syntax for headings:


    ```haskell
    {-# LANGUAGE GADTs #-}
    {- |
    @@ -300,10 +278,8 @@ My Header
    #endif
    -}
    ```

    For every heading that is higher then level one that shoul be no conflicts anymore.


    ## Related Links

    * Markup Languages:
  12. Jan Bracker revised this gist Apr 23, 2013. 1 changed file with 14 additions and 4 deletions.
    18 changes: 14 additions & 4 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -148,7 +148,13 @@ Markdown uses this syntax:
    ```
    [Example Domain](http://example.com)
    ```
    Both use the square brackets, which also seems apealing to me. As many people in the Haskell community seem to prefer Markdown I would suggest to use the second syntax for links. Links without text can still be supported through the `<link>` notation already provided by Haddock.
    An adaptation of the existing syntax:
    ```
    <Text|http://example.com>
    ```
    Both use the square brackets, which also seems apealing to me. As many people in the Haskell community seems to prefer Markdown I would suggest to either use the second syntax for links or adapt the existing syntax in the given way.
    The adaptation would fit well with the already existing syntax, instead of introducing another syntax.
    Links without text can still be supported through the `<link>` notation already provided by Haddock.

    ### Proper Support for Images

    @@ -177,9 +183,13 @@ Markdown:
    ```
    ![image.jpg](Title)
    ```
    Again I would favor the Markdown version, because it is used within the community.


    Adaptation of existing syntax:
    ```
    <<Title|image.jpg>>
    ```
    Again I would favor either the Markdown version or the adaptation.
    The Markdown version, because it is used within the community.
    The adaptation, because it is close to the already existing syntax.

    ### Lists

  13. Jan Bracker revised this gist Apr 23, 2013. 1 changed file with 24 additions and 5 deletions.
    29 changes: 24 additions & 5 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -152,6 +152,23 @@ Both use the square brackets, which also seems apealing to me. As many people in

    ### Proper Support for Images

    There already seems to be support to embed images: `<<img>>`. The paths seem to be static.

    One should be able to give image URL relative or as a complete URL. The root of a relative location would be given as a flag for Haddock.

    __Cabal__: The images can be given as additional resources in the cabal file. Like this they will be included when producing an archive through `cabal sdist`.

    __Hackage__: Hackage can use the `getDataDir` path that cabal creates to locate images in the archive and set the flag correctly.

    Optionally Haddock should offer not just to link againt images,
    but also to copy them from their sources into a common location
    of the generated documentation. This would avoid breaking
    relative links if the documentation is moved. This has to be handeled
    separatly for absolute and relative paths. For links to other servers
    copying may be turned on or off separatly.

    The already existing syntax has a downside. It is not possible to provide and alt/title text. This could be fixed by introducing one of the following ways to embed images:

    WikiCreole:
    ```
    {{image.jpg|Title}}
    @@ -162,11 +179,7 @@ Markdown:
    ```
    Again I would favor the Markdown version, because it is used within the community.

    The image URL can be given relative or as a complete URL. The root of a relative location would be given as a flag for Haddock.

    __Cabal__: The images can be given as additional resources in the cabal file. Like this they will be included when producing an archive through `cabal sdist`.

    __Hackage__: Hackage can use the `getDataDir` path that cabal creates to locate images in the archive and set the flag correctly.

    ### Lists

    @@ -206,7 +219,13 @@ Haddock misses support to document widely used language extensions:
    A search in the documentation through JavaScript might be a nice feature.

    * Haddock can generate a JSON index file.
    * This would make documentation easily searchable through thrid party tools, without the need for a central search engine like Hoogle or Hayoo.
    * This would make documentation easily searchable through
    thrid party tools, without the need for a central search
    engine like Hoogle or Hayoo.

    ## Documentation

    A major point would also be to update documentation and add undocumented features (like the image tags `<<img>>`).

    ## Markdown Ideas

  14. Jan Bracker revised this gist Apr 20, 2013. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -206,7 +206,7 @@ Haddock misses support to document widely used language extensions:
    A search in the documentation through JavaScript might be a nice feature.

    * Haddock can generate a JSON index file.
    * This would make documentation easily searchable through thrid party tools, without the need for a central search engine like Hoogle and Hayoo.
    * This would make documentation easily searchable through thrid party tools, without the need for a central search engine like Hoogle or Hayoo.

    ## Markdown Ideas

  15. Jan Bracker revised this gist Apr 20, 2013. 1 changed file with 7 additions and 7 deletions.
    14 changes: 7 additions & 7 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -174,13 +174,6 @@ Right now entries of a list have to be separated by empty line. I do not see the
    I think it would be more convenient to just enforce all contents of a list entry to be right of the column
    the bullet appeared in.

    ## Search in Documentation

    A search in the documentation through JavaScript might be a nice feature.

    * Haddock can generate a JSON index file.
    * This would make documentation easily searchable through thrid party tools, without the need for a central search engine like Hoogle and Hayoo.

    ## Capabilities

    Haddock misses support to document widely used language extensions:
    @@ -208,6 +201,13 @@ Haddock misses support to document widely used language extensions:

    * Implement support to document type family instances.

    ### Search in Documentation

    A search in the documentation through JavaScript might be a nice feature.

    * Haddock can generate a JSON index file.
    * This would make documentation easily searchable through thrid party tools, without the need for a central search engine like Hoogle and Hayoo.

    ## Markdown Ideas

    These are ideas I previously thought about when adding Markdown.
  16. Jan Bracker revised this gist Apr 20, 2013. 1 changed file with 14 additions and 6 deletions.
    20 changes: 14 additions & 6 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -84,7 +84,7 @@ There should be support for headers outside of the export list so documentation
    This would make it easier to write a few paragraphs description for sections.

    As the Markdown syntax (involving `#`) has some issue with other features of the language/compiler, I would
    suggest an alternative syntax. There are two other wide used ways to mark headings:
    suggest an alternative syntax. There are several other wide used ways to mark headings:
    ```
    Section
    =======
    @@ -111,7 +111,7 @@ or
    ```
    The first one is used by Markdown and reStructuredText. The second is used in WikiCreole. I don't see problems
    with ambiguity with either of these syntaxes. I would prefer the first or second one for main headings, because it is
    clear and visibile while reading documentation. It also has the advantage of giving a logical division within the
    clear and visibile while reading documentation. It also has the advantage of giving a visual division within the
    source that is easy to spot, supporting a programmer writing documentation, while at the same time loosening
    bigger blocks of code up.

    @@ -134,7 +134,7 @@ Haddock is missing the capability to typeset bold text. For this purpose I would
    ```
    __Important__
    ```
    Though I am not sure yet if one or two underbars should be required.
    Though I am not yet sure if one or two underbars should be required.

    I think the notation with `*` used by Markdown should not be supported, because it may cause conflicts with lists.

    @@ -148,7 +148,7 @@ Markdown uses this syntax:
    ```
    [Example Domain](http://example.com)
    ```
    Both use the square brackets, which also seems apealing to me
    Both use the square brackets, which also seems apealing to me. As many people in the Haskell community seem to prefer Markdown I would suggest to use the second syntax for links. Links without text can still be supported through the `<link>` notation already provided by Haddock.

    ### Proper Support for Images

    @@ -160,8 +160,13 @@ Markdown:
    ```
    ![image.jpg](Title)
    ```
    Again I would favor the Markdown version, because it is used within the community.

    TODO
    The image URL can be given relative or as a complete URL. The root of a relative location would be given as a flag for Haddock.

    __Cabal__: The images can be given as additional resources in the cabal file. Like this they will be included when producing an archive through `cabal sdist`.

    __Hackage__: Hackage can use the `getDataDir` path that cabal creates to locate images in the archive and set the flag correctly.

    ### Lists

    @@ -173,10 +178,13 @@ the bullet appeared in.

    A search in the documentation through JavaScript might be a nice feature.

    This is just a quick idea right now.
    * Haddock can generate a JSON index file.
    * This would make documentation easily searchable through thrid party tools, without the need for a central search engine like Hoogle and Hayoo.

    ## Capabilities

    Haddock misses support to document widely used language extensions:

    * Implement support to document GADTs.

    Right now the most recent version of Haddock (2.13.2) produces a parse error on this code:
  17. Jan Bracker revised this gist Apr 20, 2013. 1 changed file with 8 additions and 0 deletions.
    8 changes: 8 additions & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -62,6 +62,14 @@ Generally I would be in favor of extending the existing Haddock language to supp

    On the other hand the list of missing features and improvements is big and a new markup language might be beneficial to resolve these issue properly.

    ### Activation and Integration

    Adding new syntax and features to the Haddock language may invalidate old documentation or cause unintended changes in its appearance. For that reason it is a good idea to only activate the additions if a pragma is in the sources:

    ```haskell
    {-# HADDOCK ExtendedSyntax #-}
    ```

    ### Automated cross-linking

    In general automatic cross-linking would be useful. The current semantic of `'` and `@` could be merged. Each will produce inline source code. Both would automatically insert a link if the content matches a valid identifier, type or module name. No need for the user to mark it manually.
  18. Jan Bracker revised this gist Apr 20, 2013. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -37,6 +37,7 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].
    * I could twitter about improvements, giving everybody a chance to see my progress.
    * I will be online in the Haskell IRC channel for discussion with the Haskell community about problems and suggestions.
    * The Haskell mailing list would be a great reference for bigger problems and continuous discussions.
    * It might also be useful to store code on GitHub, because it offers a easy way to comment changes and discuss problems.

    * _Why do you think you would be the best person to tackle this project?_

  19. Jan Bracker revised this gist Apr 18, 2013. 1 changed file with 3 additions and 0 deletions.
    3 changes: 3 additions & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -280,3 +280,6 @@ For every heading that is higher then level one that shoul be no conflicts anymo

    [Discussion:Tibell:HaskellCafe]: https://groups.google.com/d/topic/haskell-cafe/TfPHD-cVJiQ/discussion
    [Discussion:Tibell:Reddit]: http://www.reddit.com/r/haskell/comments/1cecnj/haskellorg_gsoc_ideas/

    [Homepage:Sunroof]: http://www.ittc.ku.edu/csdl/fpg/software/sunroof.html
    [GitHub:Diagrams:Generalization]: https://github.com/diagrams/diagrams-lib/pull/65
  20. Jan Bracker revised this gist Apr 18, 2013. 1 changed file with 2 additions and 0 deletions.
    2 changes: 2 additions & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -127,6 +127,8 @@ __Important__
    ```
    Though I am not sure yet if one or two underbars should be required.

    I think the notation with `*` used by Markdown should not be supported, because it may cause conflicts with lists.

    ### Proper Support for Links with Text

    WikiCreole uses the following syntax:
  21. Jan Bracker revised this gist Apr 18, 2013. 1 changed file with 184 additions and 40 deletions.
    224 changes: 184 additions & 40 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -2,6 +2,51 @@

    Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].

    ## GSoC Questions

    * _What is the goal of the project you propose to do?_

    The goal of this project is to extend Haddock with long missing features that have been requested several times.
    Look at the goal section below for specific information about my goals.

    * _In what ways will this project benefit the wider Haskell community?_

    Haddock is _the_ standard tool for documenting Haskell. It is used on the central package plattform
    Hackage for generating all documentation. Improving this tool will benefit the Haskell community greatly,
    in giving it a more powerful tool to document its code.

    * _Can you give some more detailed design of what precisely you intend to achieve?_

    Please, refer to the goals section. It is specific about each goal.

    * _What deliverables do you think are reasonable targets? Can you outline an approximate schedule of milestones?_

    TODO

    * _What relevant experience do you have? e.g. Have you coded anything in Haskell? Have you
    contributed to any other open source software? Been studying advanced courses in a related topic?_

    * I have had several classes in functional programming (and more that just used Haskell).
    * I have worked on [generalising the Diagrams library][GitHub:Diagrams:Generalization].
    * I worked on the [Sunroof project][Homepage:Sunroof] for the last 6 months.

    * _In what ways do you envisage interacting with the wider Haskell community during your project?
    e.g. How would you seek help on something your mentor wasn't able to deal with?
    How will you get others interested in what you are doing?_

    * I could twitter about improvements, giving everybody a chance to see my progress.
    * I will be online in the Haskell IRC channel for discussion with the Haskell community about problems and suggestions.
    * The Haskell mailing list would be a great reference for bigger problems and continuous discussions.

    * _Why do you think you would be the best person to tackle this project?_

    I have been in active Haskell development over the last 8 months (I gathered a lot of experience during that time).
    Most of the improvements I am suggesting for Haddock are things I have often been missing myself, which
    highly motivates me to get them fixed once for all. I will have 3 months of spare time that I would gladly spend
    on this project.

    # Goals

    ## Markup

    Looking at the [Haskell cafe discussion][Discussion:Tibell:HaskellCafe] there are several different suggestions for markup languages:
    @@ -10,9 +55,143 @@ Looking at the [Haskell cafe discussion][Discussion:Tibell:HaskellCafe] there ar
    * [Creole][Language:WikiCreole]
    * [Pandoc][Language:Pandoc] - This has to widespread dependencies for a core tool.

    The major issue with Markdown is that it is ambiguious and does not have a formal and commonly agreed syntax. The major advantage of the other two languages is that they have a well known symtax and semantic, but they seem to mighty for the context of source documentation.
    The major issue with Markdown is that it is ambiguious and does not have a formal and commonly agreed syntax. The major advantage of the other two languages is that they have a well known syntax and semantic, but they seem to mighty for the context of source documentation.

    Generally I would be in favor of extending the existing Haddock language to support missing features. This will make it easy for long-time users to adjust. It will also keep Haddock more maintainable, since adding a completely new markup would mean twice the maintenance later.

    On the other hand the list of missing features and improvements is big and a new markup language might be beneficial to resolve these issue properly.

    ### Automated cross-linking

    In general automatic cross-linking would be useful. The current semantic of `'` and `@` could be merged. Each will produce inline source code. Both would automatically insert a link if the content matches a valid identifier, type or module name. No need for the user to mark it manually.

    * This approach has the downside that it might link things that are not meant to be linked.
    * A full scale analysis if the enclosed code is actually valid Haskell is tricky,
    difficult and may lead to more problems than do good.

    ### Headers

    There should be support for headers outside of the export list so documentation does not clutter that list.
    This would make it easier to write a few paragraphs description for sections.

    As the Markdown syntax (involving `#`) has some issue with other features of the language/compiler, I would
    suggest an alternative syntax. There are two other wide used ways to mark headings:
    ```
    Section
    =======
    Subsection
    ----------
    ```
    or
    ```
    =======
    Section
    =======
    ----------
    Subsection
    ----------
    ```
    or
    ```
    = Section
    == Subsection
    === Subsubsection
    ==== Ridiculously deep for documentation
    ```
    The first one is used by Markdown and reStructuredText. The second is used in WikiCreole. I don't see problems
    with ambiguity with either of these syntaxes. I would prefer the first or second one for main headings, because it is
    clear and visibile while reading documentation. It also has the advantage of giving a logical division within the
    source that is easy to spot, supporting a programmer writing documentation, while at the same time loosening
    bigger blocks of code up.

    For integration I would like to support the first or second version without special haddock marker:
    ```
    -- Section
    -- =======
    -- ----------
    -- Subsection
    -- ----------
    ```

    Deeper levels of headings can be expressed using the third syntax. I would only allow the third syntax in normal Haddock
    code blocks.

    ### Further Inline Markup

    Haddock is missing the capability to typeset bold text. For this purpose I would suggest adding the syntax known from markdown:
    ```
    __Important__
    ```
    Though I am not sure yet if one or two underbars should be required.

    ### Proper Support for Links with Text

    WikiCreole uses the following syntax:
    ```
    [[http://example.com|Example Domain]]
    ```
    Markdown uses this syntax:
    ```
    [Example Domain](http://example.com)
    ```
    Both use the square brackets, which also seems apealing to me

    ### Proper Support for Images

    WikiCreole:
    ```
    {{image.jpg|Title}}
    ```
    Markdown:
    ```
    ![image.jpg](Title)
    ```

    TODO

    ### Lists

    Right now entries of a list have to be separated by empty line. I do not see the necessity for this rule.
    I think it would be more convenient to just enforce all contents of a list entry to be right of the column
    the bullet appeared in.

    ## Search in Documentation

    A search in the documentation through JavaScript might be a nice feature.

    This is just a quick idea right now.

    ## Capabilities

    * Implement support to document GADTs.

    Right now the most recent version of Haddock (2.13.2) produces a parse error on this code:
    ```haskell
    -- | A tree GADT
    data Tree a where
    -- | Leaf constructor
    Leaf :: a -- ^ Leaf content
    -> Tree a -- ^ The singleton tree
    -- | Fork constructor
    Fork :: Tree a -- ^ Left branch
    -> Tree a -- ^ Right branch
    -> Tree a -- ^ The tree
    -- | Special constructor
    Special :: String -- ^ It needs a string
    -> Int -- ^ It needs a integer
    -> Tree String -- ^ It is specialised
    ```
    I plan to implement all these comments.


    * Implement support to document type family instances.

    I am in favor of Markdown, since it is commonly known. Althoug there may be problems in corner cases (unclear semantics) it is practical to use in most cases.
    ## Markdown Ideas

    These are ideas I previously thought about when adding Markdown.

    ### Activation and integration

    @@ -27,11 +206,7 @@ very nice:

    I would not allow markdown or any other markup language on the same level as Haskell code (no literate Haskell style).

    ### Automated cross-linking

    In general automatic cross-linking would be useful. The current semantic of `'` and `@` could be merged. Each will produce inline source code. Both would automatically insert a link if the content matches a valid identifier, type or module name. No need for the user to mark it manually.

    #### Markdown
    ### Automatic Cross-Linking

    As far as I can see single-quoted strings do not need to be added.
    The inline code tags are sufficient. If the marked code matches a
    @@ -49,12 +224,9 @@ without the user having to mark it manually:
    In this example `(++)`, `String` and `Data.String` would be linked while the
    rest would not be.

    ### Headers
    * This approach has some downsides as disscussed above.

    There should be support for headers outside of the export list so documentation does not clutter that list.
    This would make it easier to write a few paragraphs description for sections.

    #### Markdown
    ### Headings

    There is a [problem with the C-preprocessor][Discussion:Tibell:HaskellCafe].

    @@ -83,34 +255,6 @@ My Header

    For every heading that is higher then level one that shoul be no conflicts anymore.

    ### Other requested features

    * **Bold** and _emphasized_ text.

    ## Capabilities

    * Implement support to document GADTs.

    Right now the most recent version of Haddock (2.13.2) produces a parse error on this code:
    ```haskell
    -- | A tree GADT
    data Tree a where
    -- | Leaf constructor
    Leaf :: a -- ^ Leaf content
    -> Tree a -- ^ The singleton tree
    -- | Fork constructor
    Fork :: Tree a -- ^ Left branch
    -> Tree a -- ^ Right branch
    -> Tree a -- ^ The tree
    -- | Special constructor
    Special :: String -- ^ It needs a string
    -> Int -- ^ It needs a integer
    -> Tree String -- ^ It is specialised
    ```
    I plan to implement all these comments.


    * Implement support to document type family instances.

    ## Related Links

  22. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -4,7 +4,7 @@ Based on the suggestion by [Johan Tibell][Suggestion:JohanTibells].

    ## Markup

    Looking at the [Haskell cafe discussion][Discussion:HaskellCafe] there are several different suggestions for markup languages:
    Looking at the [Haskell cafe discussion][Discussion:Tibell:HaskellCafe] there are several different suggestions for markup languages:
    * [Markdown][Language:Markdown]
    * [reStructuredText][Language:ReStructuredText]
    * [Creole][Language:WikiCreole]
  23. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -112,7 +112,7 @@ For every heading that is higher then level one that shoul be no conflicts anymo

    * Implement support to document type family instances.

    # Related Links
    ## Related Links

    * Markup Languages:
    * [Markdown][Language:Markdown]
  24. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -112,7 +112,7 @@ For every heading that is higher then level one that shoul be no conflicts anymo

    * Implement support to document type family instances.

    ### Related Links
    # Related Links

    * Markup Languages:
    * [Markdown][Language:Markdown]
  25. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -118,6 +118,7 @@ For every heading that is higher then level one that shoul be no conflicts anymo
    * [Markdown][Language:Markdown]
    * [reStructuredText][Language:ReStructuredText]
    * [Creole][Language:WikiCreole]
    * [Pandoc][Language:Pandoc]
    * Suggestions:
    * [Johan Tibells suggestion][Suggestion:JohanTibells]
    * Discussions:
  26. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -78,6 +78,7 @@ My Header
    #ifdef evil_c
    -- ...
    #endif
    -}
    ```

    For every heading that is higher then level one that shoul be no conflicts anymore.
  27. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -84,7 +84,7 @@ For every heading that is higher then level one that shoul be no conflicts anymo
    ### Other requested features
    * *Bold* and _emphasized_ text.
    * **Bold** and _emphasized_ text.
    ## Capabilities
  28. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 5 additions and 1 deletion.
    6 changes: 5 additions & 1 deletion jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -12,7 +12,7 @@ Looking at the [Haskell cafe discussion][Discussion:HaskellCafe] there are sever

    The major issue with Markdown is that it is ambiguious and does not have a formal and commonly agreed syntax. The major advantage of the other two languages is that they have a well known symtax and semantic, but they seem to mighty for the context of source documentation.

    I am in favor of Markdown, since it is commonly known
    I am in favor of Markdown, since it is commonly known. Althoug there may be problems in corner cases (unclear semantics) it is practical to use in most cases.

    ### Activation and integration

    @@ -82,6 +82,10 @@ My Header
    For every heading that is higher then level one that shoul be no conflicts anymore.
    ### Other requested features
    * *Bold* and _emphasized_ text.
    ## Capabilities
    * Implement support to document GADTs.
  29. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 2 additions and 0 deletions.
    2 changes: 2 additions & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -8,6 +8,7 @@ Looking at the [Haskell cafe discussion][Discussion:HaskellCafe] there are sever
    * [Markdown][Language:Markdown]
    * [reStructuredText][Language:ReStructuredText]
    * [Creole][Language:WikiCreole]
    * [Pandoc][Language:Pandoc] - This has to widespread dependencies for a core tool.

    The major issue with Markdown is that it is ambiguious and does not have a formal and commonly agreed syntax. The major advantage of the other two languages is that they have a well known symtax and semantic, but they seem to mighty for the context of source documentation.

    @@ -121,6 +122,7 @@ For every heading that is higher then level one that shoul be no conflicts anymo
    [Language:WikiCreole]: http://wikicreole.org/
    [Language:ReStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
    [Language:Markdown]: http://daringfireball.net/projects/markdown/syntax
    [Language:Pandoc]: http://johnmacfarlane.net/pandoc/
    [Suggestion:JohanTibells]: http://blog.johantibell.com/2013/04/haskellorg-gsoc-ideas.html
  30. Jan Bracker revised this gist Apr 17, 2013. 1 changed file with 3 additions and 0 deletions.
    3 changes: 3 additions & 0 deletions jbracker-haddock-GSoC2013.md
    View file
    Original file line number Diff line number Diff line change
    @@ -50,6 +50,9 @@ rest would not be.

    ### Headers

    There should be support for headers outside of the export list so documentation does not clutter that list.
    This would make it easier to write a few paragraphs description for sections.

    #### Markdown

    There is a [problem with the C-preprocessor][Discussion:Tibell:HaskellCafe].