Restructure Getting Started documentation to be more compact and beginner friendly #9212
Conversation
malteneuss
changed the title
doc/getting-started.rst
Outdated
|
|
||
|
|
||
| Creating a new application | ||
| Creating a Haskell package |
There was a problem hiding this comment.
The word "application" was deliberately chosen so that the newcomers know that this is the section they should read in order to learn how to create applications with cabal. The word "package", although technically ("more") correct, is intimidating: generally, newcomers don't look for creating packages in a broad sense (and as newcomers they don't know the precise technical sense in the case of cabal packages), because a package in a broad sense is a piece of reusable functionality, which is not what newcomers are after, most of the time.
There was a problem hiding this comment.
I feel strongly about making a distinction between a package and a project. A package is the unit of source code distribution. If you are a deploying applications, you are not distributing source code and you have a different set of problem from those who do.
I am on mobile and I dont remember the content of this section but "application" ~ project.
There was a problem hiding this comment.
Indeed. "application" seems to be target outcome of this mini-guide, which also fits the "myapp" package name.
doc/getting-started.rst
Outdated
|
|
||
| Initializing the application | ||
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
| Initializing a package |
doc/getting-started.rst
Outdated
| @@ -185,13 +194,19 @@ The cabal directives are placed in the file within a comment. | |||
| main :: IO () | |||
| main = getLine >>= print . chunksOf 3 | |||
|
|
|||
| This can be run using ``cabal run myscript``. | |||
| On Unix-like systems this can be run directly with execute permission. | |||
| The important sections of a ``.cabal`` file are placed | |||
There was a problem hiding this comment.
"important" is judgemental. The previous version was right to not make such a judgement. To be honest, the supported fields are pretty random and changed over the course. Some actually important fields are not supported at all.
Also, "the" looks out of place here because nowhere those have been specified. But maybe native speakers would know better than me.
There was a problem hiding this comment.
"The" seems correct there to me; plus I think "necessary" (insofar as they're needed for the script to work) in place of "important".
There was a problem hiding this comment.
Thank you Brandon, I'm happy with your suggestion.
There was a problem hiding this comment.
Replaced "important" with "necessary"
|
Thanks a lot for taking this on — this is a long-awaited action. But this is a tough one (partly the reason it hasn't been taken on for a while). I left several comments that I feel rather strong about, and that's only after a quick skimming. So, I expect much more word wrestling before it's merged. But rest assured this is a very welcome kind of contribution, and I'm hopeful it will get merged after all the struggle. |
|
@malteneuss I'll get back to this soon but currently I'm in a crunch. |
|
I just wanna say this is still on my stack, but I'm afraid I'll have time to dig deeper only in the early October. I'm terribly sorry, but I do intend to get back to it unless, that is, someone else from the core team assists in driving this home. |
|
No problem. It takes as long as it takes. |
doc/getting-started.rst
Outdated
| Cabal also supports to run a single self-contained Haskell script like | ||
| the following file named ``myscript``: |
There was a problem hiding this comment.
I was kind of expecting the haskell-say example to be used here. It would feel more like a natural continuation of what has been written so far.
There was a problem hiding this comment.
Good point. I made the examples the same.
doc/getting-started.rst
Outdated
|
|
||
| ``app/Main.hs`` is where your package's code lives. | ||
| ``myapp.cabal`` is Cabal's metadata file which describes your package, | ||
| its dependencies and how it is built: |
There was a problem hiding this comment.
| its dependencies and how it is built: | |
| its dependencies, and how it is built: |
oxford commas FTW
There was a problem hiding this comment.
Actually, I think it'd be good to be a little more precise here and say that a package description contains package metadata and a sequence of sections, each defining a package component. Components can be of one of several types (executables, libraries, etc.). Every component describes, among other things, the location of source files and its dependencies.
Could you integrate this description into the text?
doc/getting-started.rst
Outdated
|
|
||
| .. code-block:: console | ||
|
|
||
| $ cabal run myfirstapp | ||
| $ cabal run |
There was a problem hiding this comment.
I'm not sure I'm a big fan of this change. I'd rather (1) put the component's name back and (2) mention in the text that with one executable in the package, cabal run is smart enough to infer it, so the name can be omitted.
doc/getting-started.rst
Outdated
| / / / ^ \ \ | | ||
| / / / / \ \ \ ----| | ||
| / / / / \ \ | ||
| /____/ /____/ \____\ | ||
|
|
||
| Project metadata can also be included: |
There was a problem hiding this comment.
Let's ditch this detail? I think it's enough for a getting started session and all rest should be read in the respective manual section (handily referenced below).
|
At long last, I gave it another go. Let me know what you think... |
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
Co-authored-by: Artem Pelenitsyn <[email protected]>
✅ Branch has been successfully rebased |
|
Remaining fixed one CI failure but introduced another one? @malteneuss can you look into this? https://github.com/haskell/cabal/actions/runs/6599697476/job/17929002660?pr=9212 |
Reflow sentence to trigger CI
|
@ulysses4ever Could you copy the error message? I can't see the reason the job is failing. edit: It was a typo. Should run through now. |
|
Right. As per https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#github-pull-request-conventions you should feel free to apply the merge+squash label whenever you're ready or ask for permissions to apply labels or ask someone (e.g. me) to apply the label. |
|
@ulysses4ever I hereby formally request rights to apply labels (e.g. to set "squash+merge me") |
|
@malteneuss invited |
mergify
bot
added
the
merge delay passed
Template Β: This PR does not modify
cabalbehaviour (documentation, tests, refactoring, etc.)Include the following checklist in your PR:
edit: I should wait with creating a PR until it is ready for review^^.