Skip to content

Commit ea4e900

Browse files
committed
Improve docs of helloworld files
1 parent 27bfc05 commit ea4e900

File tree

2 files changed

+60
-21
lines changed

2 files changed

+60
-21
lines changed

doc/glossary.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ The following terms are used in Stack's documentation.
3535
|Linux |A family of operating systems based on the Linux kernel. |
3636
|macOS |The primary operating system for Apple's Mac computers. Previously known as Mac OS X or OS X.|
3737
|Make |A [build automation tool](https://www.gnu.org/software/make/).|
38+
|Markdown |A plain text [formatting syntax](https://daringfireball.net/projects/markdown/) or software used to convert files in that format to HTML.|
3839
|MSYS2 |The [MSYS2](https://www.msys2.org/) software distribution and building platform for Windows.|
3940
|Nix |A purely functional [package manager](https://nixos.org/), available for Linux and macOS.|
4041
|package |A Haskell package is an organised collection of Haskell code and related files. It is described by a Cabal file or a `package.yaml` file, which is itself part of the package.|

doc/tutorial/hello_world_example.md

Lines changed: 59 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -337,31 +337,69 @@ Having build the test suite executable, Stack then automatically runs it.
337337
Let's look at the `helloworld` example in more detail to understand better how
338338
Stack works.
339339

340-
The files in the project include:
341-
342-
~~~text
343-
app/Main.hs
344-
src/Lib.hs
345-
test/Spec.hs
346-
ChangeLog.md
347-
README.md
348-
LICENSE
349-
.gitignore
350-
package.yaml
351-
helloworld.cabal
352-
Setup.hs
353-
stack.yaml
340+
The files in the project are set out below. Click :material-plus-circle: to
341+
learn more about each file:
342+
343+
~~~shell
344+
.
345+
├── app
346+
│   └── Main.hs # (1)!
347+
├── src
348+
│   └── Lib.hs # (2)!
349+
├── test
350+
│ └── Spec.hs # (3)!
351+
352+
├── .gitignore # (4)!
353+
├── CHANGELOG.md # (5)!
354+
├── LICENSE # (6)!
355+
├── README.md # (7)!
356+
357+
├── package.yaml # (8)!
358+
├── helloworld.cabal # (9)!
359+
├── Setup.hs # (10)!
360+
└── stack.yaml # (11)!
354361
~~~
355362

356-
The `app/Main.hs`, `src/Lib.hs`, and `test/Spec.hs` files are all Haskell
357-
source files that compose the actual functionality of our project. We won't
358-
dwell on them here.
363+
1. The Haskell source code for the executable (application).
364+
365+
As your project develops you can add further source code files to the `app`
366+
directory.
367+
368+
2. The executable uses a library. The Haskell source code for the library.
369+
370+
As your project develops you can add further source code files to the `src`
371+
directory.
372+
373+
3. The package has a test suite executable. The Haskell source code for the
374+
test suite.
375+
376+
As your project develops you can add further source code files to the `test`
377+
directory.
378+
379+
4. A text file used to configure the Git tool to ignore certain files. Does not
380+
affect the build.
381+
382+
5. A text file in the Markdown format in which changes to the project can be
383+
documented. Does not affect the build.
384+
385+
6. A text file used to document the copyright applicable to the project's files
386+
and the licence for the use of those files. Does not affect the build.
387+
388+
7. A text file in the Markdown format which is intended to be read by users of
389+
the project. Does not affect the build.
390+
391+
8. A file describing the package in the Hpack format. See further below.
392+
393+
9. A file describing the package in the Cabal format. See further below.
394+
395+
10. A Haskell source file which is a component of the Cabal build system. See
396+
further below.
359397

360-
The `ChangeLog.md`, `README.md`, `LICENSE` and `.gitignore` files have no effect
361-
on the build.
398+
11. A text file in the YAML format, containing Stack's project-level
399+
configuration. See further below.
362400

363-
The files of interest here are `package.yaml`, `helloworld.cabal`, `Setup.hs`
364-
and `stack.yaml`.
401+
The files of most interest here are `package.yaml`, `helloworld.cabal`,
402+
`Setup.hs` and `stack.yaml`.
365403

366404
### `package.yaml`
367405

0 commit comments

Comments
 (0)