Problems with code blocks in the description field in a .cabal file

Josef Svenningsson

4 Feb 2013 4 Feb '13

12:30 p.m.

Hi, I'm putting together a cabal package and I'd like to have some code examples in my description file. In particular I would like to have a code block containing markdown containing a code block of Haskell, like this:

...

~~~{ .haskell } module Main where

main = putStrLn "Hello World!" ~~~

When I put the above code in my .cabal file and do `cabal haddock --executables` I get the following error: haddock: failed to parse haddock prologue from file: dist/doc/html/codeExtract/codeExtract/haddock-prolog31969.txt In general I can provoke the parse error from haddock whenever I have something inside curly braces. So the error seems to stem from haddock. I've tried to track down what happens inside haddock but I've run out steam. I'd like to know if there is anything I can do to be able to write something like the above as part of the description in my .cabal file. Thanks, Josef

Attachments:

attachment.html (text/html — 1.2 KB)

Show replies by date

Mateusz Kowalczyk

4 Feb 4 Feb

12:26 p.m.

New subject: Problems with code blocks in the description field in a .cabal file

I don't understand why you're putting it in your .cabal file. Isn't something like 3.8.5 over at [1] what you're trying to achieve? ... I had a look at a package ([2]) that I know uses a multi-line code block example. Here's what I found in its cabal file: An example: . > runShpider $ do > download "http://apage.com" > theForm : _ <- getFormsByAction "http://anotherpage.com" > sendForm $ fillOutForm theForm $ pairs $ do > "occupation" =: "unemployed Haskell programmer" > "location" =: "mother's house" . Depending on your mail client, the `>' signs might get quoted. [1] - http://www.haskell.org/haddock/doc/html/ch03s08.html [2] - http://hackage.haskell.org/packages/archive/shpider/0.2.1.1/doc/html/Network... On 04/02/13 12:30, Josef Svenningsson wrote:

...

Hi,

I'm putting together a cabal package and I'd like to have some code examples in my description file. In particular I would like to have a code block containing markdown containing a code block of Haskell, like this:

...
~~~{ .haskell } module Main where

main = putStrLn "Hello World!" ~~~

When I put the above code in my .cabal file and do `cabal haddock --executables` I get the following error:

haddock: failed to parse haddock prologue from file: dist/doc/html/codeExtract/codeExtract/haddock-prolog31969.txt

In general I can provoke the parse error from haddock whenever I have something inside curly braces.

So the error seems to stem from haddock. I've tried to track down what happens inside haddock but I've run out steam. I'd like to know if there is anything I can do to be able to write something like the above as part of the description in my .cabal file.

Thanks,

Josef

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

Josef Svenningsson

1:33 p.m.

New subject: Problems with code blocks in the description field in a .cabal file

On Mon, Feb 4, 2013 at 1:26 PM, Mateusz Kowalczyk wrote:

...

I don't understand why you're putting it in your .cabal file. Isn't something like 3.8.5 over at [1] what you're trying to achieve?

Right, I probably should have mentioned that the reason I put it in the .cabal file is that the cabal package I'm putting together is an executable. So I want the documentation to show up on the index page.

...

...

I had a look at a package ([2]) that I know uses a multi-line code block example. Here's what I found in its cabal file: An example: . > runShpider $ do > download "http://apage.com" > theForm : _ <- getFormsByAction "http://anotherpage.com" > sendForm $ fillOutForm theForm $ pairs $ do > "occupation" =: "unemployed Haskell programmer" > "location" =: "mother's house" .

Depending on your mail client, the `>' signs might get quoted.

Yes. I have no problems including code in general. It's when I have things inside curly braces that I get a parse error. And that's exactly what I would like to have.

Thanks, Josef

...

[1] - http://www.haskell.org/haddock/doc/html/ch03s08.html [2] -

http://hackage.haskell.org/packages/archive/shpider/0.2.1.1/doc/html/Network...

On 04/02/13 12:30, Josef Svenningsson wrote:

...
Hi,

I'm putting together a cabal package and I'd like to have some code examples in my description file. In particular I would like to have a code block containing markdown containing a code block of Haskell, like this:

...
~~~{ .haskell } module Main where

main = putStrLn "Hello World!" ~~~

When I put the above code in my .cabal file and do `cabal haddock --executables` I get the following error:

haddock: failed to parse haddock prologue from file: dist/doc/html/codeExtract/codeExtract/haddock-prolog31969.txt

In general I can provoke the parse error from haddock whenever I have something inside curly braces.

So the error seems to stem from haddock. I've tried to track down what happens inside haddock but I've run out steam. I'd like to know if there is anything I can do to be able to write something like the above as part of the description in my .cabal file.

Thanks,

Josef

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

Ryan Yates

1:01 p.m.

New subject: Problems with code blocks in the description field in a .cabal file

Hi Josef, You should be fine if you follow Haddock formatting. For example: http://hackage.haskell.org/package/lens Is from the cabal file: http://hackage.haskell.org/packages/archive/lens/3.8.5/lens.cabal Ryan On Mon, Feb 4, 2013 at 7:30 AM, Josef Svenningsson < josef.svenningsson@gmail.com> wrote:

...

Hi,

I'm putting together a cabal package and I'd like to have some code examples in my description file. In particular I would like to have a code block containing markdown containing a code block of Haskell, like this:

...
~~~{ .haskell } module Main where

main = putStrLn "Hello World!" ~~~

When I put the above code in my .cabal file and do `cabal haddock --executables` I get the following error:

haddock: failed to parse haddock prologue from file: dist/doc/html/codeExtract/codeExtract/haddock-prolog31969.txt

In general I can provoke the parse error from haddock whenever I have something inside curly braces.

So the error seems to stem from haddock. I've tried to track down what happens inside haddock but I've run out steam. I'd like to know if there is anything I can do to be able to write something like the above as part of the description in my .cabal file.

Thanks,

Josef

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

Josef Svenningsson

1:37 p.m.

New subject: Problems with code blocks in the description field in a .cabal file

Hi Ryan, As far as I can tell I'm following the Haddock formatting just fine. I'm using bird tracks for my code block and according to the Haddock manual those code blocks are interpreted literally without any additional markup. To me that suggests that I should be able to write just about anything in these code blocks. But that's evidently not so. The documentation for the lens package is indeed impressive. But it doesn't help me with my particular conundrum of the curly braces. Thanks, Josef On Mon, Feb 4, 2013 at 2:01 PM, Ryan Yates wrote:

...

Hi Josef,

You should be fine if you follow Haddock formatting. For example:

http://hackage.haskell.org/package/lens

Is from the cabal file:

http://hackage.haskell.org/packages/archive/lens/3.8.5/lens.cabal

Ryan

On Mon, Feb 4, 2013 at 7:30 AM, Josef Svenningsson < josef.svenningsson@gmail.com> wrote:

...
Hi,

I'm putting together a cabal package and I'd like to have some code examples in my description file. In particular I would like to have a code block containing markdown containing a code block of Haskell, like this:

...
~~~{ .haskell } module Main where

main = putStrLn "Hello World!" ~~~

When I put the above code in my .cabal file and do `cabal haddock --executables` I get the following error:

haddock: failed to parse haddock prologue from file: dist/doc/html/codeExtract/codeExtract/haddock-prolog31969.txt

In general I can provoke the parse error from haddock whenever I have something inside curly braces.

So the error seems to stem from haddock. I've tried to track down what happens inside haddock but I've run out steam. I'd like to know if there is anything I can do to be able to write something like the above as part of the description in my .cabal file.

Thanks,

Josef

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

Ryan Yates

4:10 p.m.

New subject: Problems with code blocks in the description field in a .cabal file

Hi Josef, Sorry, I misunderstood the intent. From what I can tell this is a Cabal deficiency. The text from the description field first passes through the `tokeniseLine` function from here: https://github.com/haskell/cabal/blob/cabal-1.16/Cabal/Distribution/ParseUti... seems to have no provision for escaping. Ryan On Mon, Feb 4, 2013 at 8:37 AM, Josef Svenningsson < josef.svenningsson@gmail.com> wrote:

...

Hi Ryan,

As far as I can tell I'm following the Haddock formatting just fine. I'm using bird tracks for my code block and according to the Haddock manual those code blocks are interpreted literally without any additional markup. To me that suggests that I should be able to write just about anything in these code blocks. But that's evidently not so.

The documentation for the lens package is indeed impressive. But it doesn't help me with my particular conundrum of the curly braces.

Thanks,

Josef

On Mon, Feb 4, 2013 at 2:01 PM, Ryan Yates wrote:

...
Hi Josef,

You should be fine if you follow Haddock formatting. For example:

http://hackage.haskell.org/package/lens

Is from the cabal file:

http://hackage.haskell.org/packages/archive/lens/3.8.5/lens.cabal

Ryan

On Mon, Feb 4, 2013 at 7:30 AM, Josef Svenningsson < josef.svenningsson@gmail.com> wrote:

...
Hi,

I'm putting together a cabal package and I'd like to have some code examples in my description file. In particular I would like to have a code block containing markdown containing a code block of Haskell, like this:

...
~~~{ .haskell } module Main where

main = putStrLn "Hello World!" ~~~

When I put the above code in my .cabal file and do `cabal haddock --executables` I get the following error:

haddock: failed to parse haddock prologue from file: dist/doc/html/codeExtract/codeExtract/haddock-prolog31969.txt

In general I can provoke the parse error from haddock whenever I have something inside curly braces.

So the error seems to stem from haddock. I've tried to track down what happens inside haddock but I've run out steam. I'd like to know if there is anything I can do to be able to write something like the above as part of the description in my .cabal file.

Thanks,

Josef

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

Josef Svenningsson

4:25 p.m.

New subject: Problems with code blocks in the description field in a .cabal file

...

Hi Josef,

Sorry, I misunderstood the intent. From what I can tell this is a Cabal deficiency. The text from the description field first passes through the `tokeniseLine` function from here: https://github.com/haskell/cabal/blob/cabal-1.16/Cabal/Distribution/ParseUti... seems to have no provision for escaping.

Indeed. Bummer. And I notice now that there's already a bug filed in the

On Mon, Feb 4, 2013 at 5:10 PM, Ryan Yates wrote: tracker about this: https://github.com/haskell/cabal/issues/885 I guess I'll have to do without the example in my documentation for now. Thank you very much! Josef

...

Ryan

On Mon, Feb 4, 2013 at 8:37 AM, Josef Svenningsson < josef.svenningsson@gmail.com> wrote:

...
Hi Ryan,

As far as I can tell I'm following the Haddock formatting just fine. I'm using bird tracks for my code block and according to the Haddock manual those code blocks are interpreted literally without any additional markup. To me that suggests that I should be able to write just about anything in these code blocks. But that's evidently not so.

The documentation for the lens package is indeed impressive. But it doesn't help me with my particular conundrum of the curly braces.

Thanks,

Josef

On Mon, Feb 4, 2013 at 2:01 PM, Ryan Yates wrote:

...
Hi Josef,

You should be fine if you follow Haddock formatting. For example:

http://hackage.haskell.org/package/lens

Is from the cabal file:

http://hackage.haskell.org/packages/archive/lens/3.8.5/lens.cabal

Ryan

On Mon, Feb 4, 2013 at 7:30 AM, Josef Svenningsson < josef.svenningsson@gmail.com> wrote:

...
Hi,

I'm putting together a cabal package and I'd like to have some code examples in my description file. In particular I would like to have a code block containing markdown containing a code block of Haskell, like this:

...
~~~{ .haskell } module Main where

main = putStrLn "Hello World!" ~~~

When I put the above code in my .cabal file and do `cabal haddock --executables` I get the following error:

haddock: failed to parse haddock prologue from file: dist/doc/html/codeExtract/codeExtract/haddock-prolog31969.txt

In general I can provoke the parse error from haddock whenever I have something inside curly braces.

So the error seems to stem from haddock. I've tried to track down what happens inside haddock but I've run out steam. I'd like to know if there is anything I can do to be able to write something like the above as part of the description in my .cabal file.

Thanks,

Josef

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

4538

Age (days ago)

4538

Last active (days ago)

List overview

Download

6 comments

3 participants

participants (3)

Josef Svenningsson
Mateusz Kowalczyk
Ryan Yates