Easier to learn

[ghost]

Hi,

Just consider to rewrite a tutorial for non-haskell experts. It's very difficult to understand that.

For example, what fails here:

import Development.Shake
import Development.Shake.Command
import Development.Shake.FilePath
import Development.Shake.Util

main :: IO ()
main = shakeArgs shakeOptions{shakeFiles="_build/"} $ do

    "./tasques.pdf" *> \out -> do
        let src = out -<.> "context"
        need ["./tmp/tasques-bibliografia.context", "./tmp/tasques-previ.context", "./tmp/tasques-permenoritzades.context", "./plantilles/entorn-minimal.tex", src, "./tmp/objectius-previ.context", "./tmp/objectius-detall.context", "./tmp/tasques-codi.context"]
        cmd "context " src " --result="out " --batchmode"

and ghc --make [thisfile]?

That is, put a minimal example first

[ndmitchell]

The idea of putting a minimal example first seems reasonable, I'll see what I can incorporate (although I worry about increasing the length and duplicating pieces). Alternatively, I could look at an "interactive" Makefile to Shake translator, so people can play around with a small example in Makefile syntax and see what it looks like in Shake (and a default initial Makefile would give a simpler example). Any thoughts which would be more useful?

What is the error you are encountering? Does it not compile? Or not work properly when it does compile? Any error message? The things I see are:

• You have put ./ at the front of every file. So Shake files all have a canonical name, you should drop the ./.
• As it stands, the build won't do anything. You probably want to add the line want ["tasques.pdf"] after the do so it knows what the targets are.

Thanks for your comments, there have only been a few non-Haskellers try Shake so far, so I very much welcome your feedback. Writing docs for non-Haskell experts is hard after programming it full time for 10 years.

[ghost]

• First of all, thank you very much for your pollite response.
• Yes, there is an error: missing want ["./tasques.pdf"]. What does it mean? Like target in make?
• I think first of all the syntax is very complicated. In general, we have N files f_1, ...., f_N which generate M files g_1, ..., g_M with K rules (commands): r_1, ..., r_k.

How do we put these?

import Development.Shake
import Development.Shake.Command
import Development.Shake.FilePath
import Development.Shake.Util

main :: IO ()
main = shakeArgs shakeOptions{shakeFiles="_build/"} $ do
        want [g_1, ..., g_M]

        g_1 *> \out -> do
                need [f_1, ..., f_N]
                cmd r_1
                cmd r_2
                ...
                cmd r_k

        g_2 *> \out -> do
                need [f_1, ..., f_N]
                cmd r_1
                cmd r_2
                ...
                cmd r_k

       [....]

Can we avoid the headers at the beginning? Is there possible in Haskell? I suggest to maintain the rules separated from the code. Why not we write the rules in a yaml or json file for example and shake simply parse the rules to internal format?

Something like (yaml):

- parents: [f_1, ...., f_N]
  children: [g_1, ..., g_M]
  rules: [r_1, ..., r_k]
- ...

Yes I know having rules in haskell code you have more liberty and expressiveness, but for the begginers is too much. And so, we avoid to recompile things over and over again.

By the other hand, the minimal example I looking for is for example "compile the hello world command in gcc" (one file depends on another). And further, put an example on one file depending on several files (latex with bibtex?)

A part of that, I have questions about how and when you paralize the process (really the building systems could be viewed as graphs). But it's another question.

[ghost]

By the other hand, you could make an github page for this project. This would make this project more attractive for people

[ndmitchell]

So, to summarise this ticket, you think it should be easier for people learning Shake. I agree! The rough things you suggested (or I suggested based on your complaints) are:

• Add a real web page. I agree, tracked as #139
• A Make to Shake convertor, tracked as #114
• Improve the manual. I agree there are a few things that will help, but the basic problem is the manual is already as big as it should be, and the things that are omitted are generally less useful than those included. A few targeted tickets are useful (e.g. #136), but I don't see any way to do significantly better.
• Add a custom YAML based syntax. Certainly an option, and perhaps not even that hard. My only concern is that people tend to need more power quite quickly, and it requires designing and documenting. There is also the question of where to stop - at some point I'll have redefined all of Haskell. Thoughts?

[ghost]

Improve the manual. I agree there are a few things that will help, but the basic problem is the manual is already as big as it should be, and the things that are omitted are generally less useful than those included. A few targeted tickets are useful (e.g. #136), but I don't see any way to do significantly better.

I agree. Improving the manual in my case needs simplifying. Start with simple things. For example remove the long example to more minimal example. Perhaps put a section of examples.

[ghost]

YAML based syntax mark as "Wish". Not as part of this ticket

[ndmitchell]

I was thinking that perhaps use the Makefile convertor to also include a suite of examples, so you have a list of examples in Makefile and Shake syntax. That helps people figure out what the Shake does, so they can learn by example.

[ghost]

• First of all, I put simple example (how to compile one gcc command in shake). After that, put a more sofisticated example: several outputs
• Then, Comparison to make
• Then whatever you want
• At final, the API documentation reference

[ghost]

I think you have to "clean" the manual in the second point. Comparison to make is a good point but not the most important I think.

[ghost]

Create this because Rewriting manual is part (not the whole) of this issue. We could add comment there not here. Do you like that?

[ndmitchell]

I added #142, which I think means we have separate tickets for all the issues raised.