Skip to content

Commit deefcf5

Browse files
Ericson2314Ericson2314
authored
Merge pull request #219 from haskell/refactor-read-docs-website
Deduplicate docs, prepare to get rid of website
2 parents dda9b3f + 19f81b2 commit deefcf5

File tree

7 files changed

+154
-91
lines changed

7 files changed

+154
-91
lines changed

‎CONTRIBUTING.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
doc/contributing.rst

‎README.md

Lines changed: 13 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -2,88 +2,22 @@
22

33
[![Haskell-CI](https://github.com/haskell/alex/actions/workflows/haskell-ci.yml/badge.svg)](https://github.com/haskell/alex/actions/workflows/haskell-ci.yml)
44

5-
Alex is a Lex-like tool for generating Haskell scanners. For complete
6-
documentation, see the doc directory.
5+
Alex is a tool for generating lexical analysers, also known as "lexers" and "scanners", in Haskell.
6+
The lexical analysers implement a description of the tokens to be recognised in the form of regular expressions.
7+
It is similar to the tools "lex" and "flex" for C/C++.
78

8-
- <https://www.haskell.org/alex/>
9+
Share and enjoy!
910

10-
- <https://hackage.haskell.org/package/alex>
11+
## Documentation
1112

12-
For information on copying and distributing this program, see the file
13-
LICENSE in this directory.
13+
Documentation is hosted on [Read the Docs](https://haskell-alex.readthedocs.io):
1414

15-
The sources are in the `src` directory and the documentation in the `doc`
16-
directory; various examples are in the `examples` subdirectory.
15+
- [Online (HTML)](https://haskell-alex.readthedocs.io)
16+
- [PDF](https://haskell-alex.readthedocs.io/_/downloads/en/latest/pdf/)
17+
- [Downloadable HTML](https://haskell-alex.readthedocs.io/_/downloads/en/latest/htmlzip/)
1718

18-
The source code in the `src` and `examples` directories is intended to work
19-
with GHC >= 7.0.
19+
For basic information of the sort typically found in a read-me, see the following sections of the docs:
2020

21-
## Build Instructions
22-
23-
If you just want to *use* Alex, you can download or install (via
24-
`cabal install alex`) an
25-
[Alex release from Hackage](https://hackage.haskell.org/package/alex); also note that
26-
distributions such as the
27-
[Haskell Platform](https://www.haskell.org/platform/) and other package
28-
manager-based distributions provide packages for Alex. Moreover,
29-
recent versions of `cabal` will automatically install the required
30-
version of `alex` based on
31-
[`build-tools`/`build-tool-depends` declarations](http://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-build-tool-depends).
32-
33-
Read on if you want to build Alex directly from Git.
34-
35-
Alex is built using GHC & Cabal; so first install
36-
[GHC](https://www.haskell.org/ghc) and
37-
[`cabal-install-2.0`](https://www.haskell.org/cabal) (or later).
38-
39-
Since Alex itself is implemented in terms of an Alex scanner,
40-
bootstrapping Alex is a bit tricky:
41-
42-
You need to have the build-tools `alex` and `happy` manually
43-
installed; either via your system package manager distribution, the
44-
Haskell Platform, or e.g. via (run this outside the Git repository!):
45-
46-
$ cabal install alex happy
47-
48-
which installs them into `${HOME}/.cabal/bin` by default (make sure
49-
they are in your `$PATH` for the next steps!).
50-
51-
### Variant A
52-
53-
You can install `alex` simply by invoking
54-
55-
$ cabal install
56-
57-
from inside the Git folder.
58-
59-
### Variant B
60-
61-
Alternatively, you can use the `Makefile` which automates the steps of
62-
producing a self-contained pre-bootstrapped source distribution with
63-
pre-generated lexer/scanners:
64-
65-
$ make sdist
66-
$ cabal install dist/alex-*.tar.gz
67-
68-
For convenience, there is also a `make sdist-test` target which builds the
69-
source source tarball and runs the test-suite from within the source dist.
70-
71-
## Contributing & Reporting Issues
72-
73-
Please report any bugs or comments at https://github.com/simonmar/alex/issues
74-
75-
Share and enjoy,
76-
77-
Chris Dornan: [email protected]
78-
79-
Isaac Jones: [email protected]
80-
81-
Simon Marlow: [email protected]
82-
83-
and [recent contributors](https://github.com/simonmar/alex/graphs/contributors).
84-
85-
## Current Maintainers
86-
87-
- John Ericson (@Ericson2314)
88-
89-
- Simon Marlow (@simonmar)
21+
- [About Alex](https://haskell-alex.readthedocs.io/en/latest/about.html)
22+
- [Obtaining Alex](https://haskell-alex.readthedocs.io/en/latest/obtaining.html)
23+
- [Contributing](https://haskell-alex.readthedocs.io/en/latest/contributing.html)

‎doc/about.rst

Lines changed: 39 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,16 @@ About Alex
66
Alex can always be obtained from its `home page <http://www.haskell.org/alex>`__.
77
The latest source code lives in the `git repository <https://github.com/haskell/alex>`__ on ``GitHub``.
88

9+
Releases
10+
--------
11+
12+
Releases of Alex are published on `Hackage <https://hackage.haskell.org/package/alex>`__.
13+
They are also given `Git tags <https://github.com/haskell/alex/tags>`__ in the repository.
14+
915
.. _bug-reports:
1016

11-
Reporting bugs in Alex
12-
----------------------
17+
Reporting issues with Alex
18+
--------------------------
1319

1420
Please report bugs on the `Alex issue tracker <https://github.com/haskell/alex/issues>`__.
1521
There are no specific mailing lists for the discussion of Alex-related matters,
@@ -35,9 +41,36 @@ IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
3541
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
3642
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3743

38-
About this documentation
39-
------------------------
44+
Acknowledgments
45+
---------------
46+
47+
Original authors
48+
~~~~~~~~~~~~~~~~
49+
50+
- Chris Dornan: [email protected]
51+
52+
- Isaac Jones: [email protected]
53+
54+
- Simon Marlow: [email protected]
55+
56+
Current Maintainers
57+
~~~~~~~~~~~~~~~~~~~
58+
59+
- Andreas Abel (@andreasabel)
60+
61+
- John Ericson (@Ericson2314)
62+
63+
- Simon Marlow (@simonmar)
64+
65+
Other contributors
66+
~~~~~~~~~~~~~~~~~~
67+
68+
The data is in the Git history.
69+
GitHub can render that in `various ways <https://github.com/simonmar/alex/graphs/contributors>`__.
70+
71+
The documentation itself
72+
~~~~~~~~~~~~~~~~~~~~~~~~
4073

41-
This documentation is based on a DocBook documentation originally written by Chris Dornan, Isaac Jones, and Simon Marlow.
74+
This documentation is based the original documentation written by Alex's original authors using DocBook.
4275

43-
Converted to RST / Sphinx / readthedocs.org by Andreas Abel in February 2022.
76+
It was Converted to reStructuredText / Sphinx / readthedocs.org by Andreas Abel in February 2022.

‎doc/contributing.rst

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
.. _contributing:
2+
3+
Contributing to Alex
4+
====================
5+
6+
.. highlight:: bash
7+
8+
Source Code Repository
9+
----------------------
10+
11+
Alex is hosted on `GitHub <https://github.com/haskell/alex>`__.
12+
As previously discussed in `bug-reports`_, we use the built-in `GitHub issue tracker <https://github.com/haskell/alex/issues>`__ for Alex.
13+
We also use `GitHub pull requests <https://github.com/haskell/alex/pulls>`__ for managing changes;
14+
feel free to submit them!
15+
16+
Repo Layout
17+
-----------
18+
19+
- ``src``: The source code for Alex itself
20+
- ``doc``: The documentation
21+
- ``examples``: Various examples of using Alex
22+
23+
Contributor Build Instructions
24+
------------------------------
25+
26+
Alex is built using `GHC <https://www.haskell.org/ghc>`__ and
27+
`Cabal Install <https://www.haskell.org/cabal>`__ (version 2.0 or later).
28+
Make sure they are already installed first.
29+
30+
Since Alex itself is implemented in terms of an Alex scanner,
31+
bootstrapping Alex is a bit tricky:
32+
33+
You need to have the build-tools ``alex`` and ``happy`` manually installed;
34+
either via your system package manager distribution, the Haskell Platform, or e.g. via (run this outside the Git repository!)::
35+
36+
$ cabal install alex happy
37+
38+
which installs them into ``${HOME}/.cabal/bin`` by default.
39+
(make sure they are in your ``$PATH`` for the next steps!)
40+
41+
Variant A
42+
~~~~~~~~~
43+
44+
You can install ``alex`` simply by invoking::
45+
46+
$ cabal install
47+
48+
from inside the Git folder.
49+
50+
Variant B
51+
~~~~~~~~~
52+
53+
Alternatively, you can use the ``Makefile`` which automates the steps of producing a self-contained pre-bootstrapped source distribution with pre-generated lexer/scanners::
54+
55+
$ make sdist
56+
$ cabal install dist/alex-*.tar.gz
57+
58+
For convenience, there is also a ``make sdist-test`` target which builds the source source tarball and runs the test-suite from within the source dist.

‎doc/index.rst

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,19 @@
22
Alex User Guide
33
===============
44

5-
Alex is a tool for generating lexical analysers in Haskell,
6-
given a description of the tokens to be recognised in the form of regular expressions.
7-
It is similar to the tool "lex" or "flex" for C/C++.
5+
Alex is a tool for generating lexical analysers, also known as "lexers" and "scanners", in Haskell.
6+
The lexical analysers implement a description of the tokens to be recognised in the form of regular expressions.
7+
It is similar to the tools "lex" and "flex" for C/C++.
88

99
.. toctree::
1010
:maxdepth: 2
1111
:caption: Contents
1212

1313
about
14+
obtaining
1415
introduction
1516
syntax
1617
regex
1718
api
1819
invoking
20+
contributing

‎doc/introduction.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
Introduction
22
============
33

4-
Alex is a tool for generating lexical analysers in Haskell,
5-
given a description of the tokens to be recognised in the form of regular expressions.
6-
It is similar to the tools lex and flex for C/C++.
4+
Alex is a tool for generating lexical analysers, also known as "lexers" and "scanners", in Haskell.
5+
The lexical analysers implement a description of the tokens to be recognised in the form of regular expressions.
6+
It is similar to the tools "lex" and "flex" for C/C++.
77

88
Alex takes a description of tokens based on regular expressions and generates a Haskell module containing code for scanning text
99
efficiently.

‎doc/obtaining.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. _installing:
2+
3+
Obtaining Alex
4+
==============
5+
6+
.. highlight:: bash
7+
8+
If you just want to *use* Alex, you can build from a release.
9+
This should work the same as any other Haskell package.
10+
11+
Alex itself and its examples are intended to work with GHC >= 7.0.
12+
13+
Haskell-specific way
14+
--------------------
15+
16+
From `Hackage <https://hackage.haskell.org/package/alex>`__ via `Cabal Install <https://www.haskell.org/cabal/>`__::
17+
18+
$ cabal install alex
19+
20+
From `Stackage <https://www.stackage.org/package/alex>`__ via `Stack <https://haskellstack.org>`__::
21+
22+
$ stack install alex
23+
24+
Moreover, recent versions of ``cabal`` will automatically install the required version of ``alex`` based on ``build-tools``/``build-tool-depends`` `declarations <http://cabal.readthedocs.io/en/latest/developing-packages.html#pkg-field-build-tool-depends>`__.
25+
26+
Operating System way
27+
--------------------
28+
29+
Because Alex is a dependency of GHC, it is often packaged by operating systems.
30+
`Repology <https://repology.org>`__ aggregates this info across many distros and operating systems, and Alex is actually listed twice:
31+
32+
- https://repology.org/project/haskell:alex/versions
33+
- https://repology.org/project/alex/versions
34+
35+
The table contains links to the individual OS packages, which should provide installation instructions.

0 commit comments

Comments
 (0)