Convert happy docbook documentation to rst

[andreasabel]

@Ericson2314, since this was all very fresh in my mind, I did the first steps of converting the happy docs to rst. But since you said you want to take care of this and I do not want to get in the way, I leave it now. You can add to this PR.

• [x] moved old doc/ to docbook/
• [x] pandoc-converted happy.xml and split into several .rst files, one per section
• [x] copied over conf.py and Makefile from alex repo
• [x] rendered at https://haskell-happy.readthedocs.io/en/sphinx/
• [x] @andreasabel and @Ericson2314 are maintainers at https://readthedocs.org/projects/haskell-alex/

TODO:

• [x] go through code blocks and set language for correct syntax highlighting
• [x] read through docs for obvious things to fix
• [x] check that links are up-to-date (github repo)
• [x] remove docbook/

As admin:

• [ ] set up webhook

Once this is merged into master:

• [ ] remove sphinx branch from https://haskell-happy.readthedocs.io

[ghost]

from the Introduction section, second paragraph, this is not correct

yacc Happy is flexible:

from the Introduction section, Reporting Bugs subsection, first paragraph, this is not correct

bugs, reporting Any bugs

from the Invoking Happy section, this is not correct

literate grammar files The flags accepted

from the Info Files section, first paragraph, this is not correct

info files Happy info files,

[Ericson2314]

@askeblad are these errors in the conversation or original?

[ghost]

there may be more

happy.xml

    <indexterm><primary>yacc</primary></indexterm>

    <para> <application>Happy</application> is flexible:

introduction.rst

yacc
Happy is flexible:

[ghost]

@Ericson2314

these errors

no entries in the genindex.html page (from the conversion) were created

using.rst

yacc
Note for ``yacc`` users:

two entries for yacc in the ix01.html page (generated by DocBook) are created

[ghost]

GH Wiki rendering.

Links of course will not work in this rendering.

---

Happy

Simon Marlow
Andy Gill

Copyright © 1997-2009 Simon Marlow

Abstract

This document describes Happy, the Haskell Parser Generator, version 1.18.

Table of Contents

Introduction
Using Happy
Generalized LR Parsing
Attribute Grammars
Invoking Happy
Syntax of Grammar Files
Info Files
Tips
Index

Introduction

Compatibility

Happy is a parser generator system for Haskell, similar to the tool yacc for C. Like yacc, it takes a file containing an annotated BNF specification of a grammar and produces a Haskell module containing a parser for the grammar.

Happy is flexible: you can have several Happy parsers in the same program, and each parser may have multiple entry points. Happy can work in conjunction with a lexical analyser supplied by the user (either hand-written or generated by another program), or it can parse a stream of characters directly (but this isn't practical in most cases). In a future version we hope to include a lexical analyser generator with Happy as a single package.

Parsers generated by Happy are fast; generally faster than an equivalent parser written using parsing combinators or similar tools. Furthermore, any future improvements made to Happy will benefit an existing grammar, without need for a rewrite.

[ghost]

Cabal's sphinx setup is quite sophisticated, and they have their own style sheets.

@andreasabel quoted above from a PR comment in another Haskell Organization repository

FWIW, if the Sphinx rewrite of the documentation is factually pursued, rather than opting for the simpler Wiki format, as would appear in the previous comment, circa May 2014 J. Andersson's Cask implemented a rewrite of its documentation with Sphinx.

Whether the Cask Sphinx setup is less sophisticated than Cabal's Sphinx setup I would be uninformed on.

NB: Scrolling down the Home page appears a link to a functioning Index page.

[ghost]

move from doc book (GHC's GitLab instance Wiki page)

merits and appropriateness for the GHC User Guide of DocBook alternatives addressed

Markdown

"While ubiquitous, its syntax isn't nearly expressive enough to accommodate the users guide."

---

This bids the question at to whether "expressiveness" is a priority for individual Hackage packages' documentation.

NB: Edit mode for GH Wiki pages includes among others AsciiDoc, Markdown (presumed default), and reStructeredText.

[ghost]

Hspec User's Manual code adapted.

[ghost]

https://github.com/haskell/happy/pull/226#issuecomment-1064773888

FWIW, the c2hs repo User Guide.

[ghost]

on a side note daVinci graph visualization tool is rather old

grep -nr davinci happy

grep -nr daVinci happy

[Ericson2314]

Once source of conversion lossiness is indexterm. Anyone know how that should be done in reStructured Text?

[Ericson2314]

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#index-generating-markup OK maybe this does it.

[Ericson2314]

@andreasabel Sorry for the immense delay. I think this is finally ready!