aelve/guide
1
1
Fork 0
mirror of https://github.com/aelve/guide.git synced 2024-12-24 21:35:06 +03:00
Code Issues Projects Releases Wiki Activity

Merge branch 'vue' of https://github.com/aelve/guide into vue

Browse Source
This commit is contained in:
Giyos 2018-09-24 18:20:19 +05:00
commit 23018b81df
3 changed files with 5 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
INSTALL.md
View File

@ -19,6 +19,8 @@ The `config.json` file contains the config (it will be created at the 1st start)
# How to install locally
First install NPM (important!). Then do:
$ stack build
$ stack exec guide
@ -32,6 +34,8 @@ Create a droplet with Ubuntu. Install Stack (this command will import a GPG key,
$ curl -sSL https://get.haskellstack.org/ | sh
Install NPM.
Clone and build `guide`:
$ git clone https://github.com/aelve/guide

34
README.md
View File

@ -46,6 +46,7 @@ $ stack test
* `scripts` – some scripts used by automatic testing
* `favicon` – code used to generate a favicon
* `guidejs` – client side JavaScript
* `front` – the new frontend, written in Vue.js
### Frontend
@ -69,36 +70,3 @@ When you see something like
~~~
it means that there's an extensive comment somewhere else in the code, which you can find by grepping for `Note [acid-state]`. This convention was stolen from GHC. If you know some plugin for Emacs that would help with jumping to comments (even if those comments would have to be formatted differently), let me know.
### Main modules
THIS SECTION IS OUTDATED
There are 4 main modules – `Guide.hs`, `JS.hs`, `View.hs`, and `Types.hs`.
`Guide.hs` contains:
* handlers for GET/POST requests (`renderMethods`, `setMethods`, etc)
* feed generation (`itemToFeedEntry`)
* some utility functions (`undoEdit`, `lucidWithConfig`, `createCheckpoint'`)
* the `main` function, which starts the server
`JS.hs` contains all Javascript that is used in pages. The way it works is tricky: each Javascript function is overloaded in such a way that it can generate either a function call or a function definition. `allJSFunctions`, exported by `JS.hs`, is made by producing definitions from all functions in the module and then concatenating them; later `allJSFunction` is served by the server as `/js.js`. When you see something like `JS.foo (a, b, c)` in Haskell code, a call to `foo` is being generated (and `foo` can be found in `JS.hs`).
`View.hs` contains HTML rendering code. (It's much uglier than using templates, and we should switch to templates one day. Actually, maybe we should even switch to Node.js or Elm from Haskell.)
`Types.hs` contains almost all types used in code elsewhere – `Item`, `Category`, and so on. `GlobalState` is a type for, well, the whole database used by the site. All content, all edits, and all analytics data (i.e. users' IPs, etc) are stored there. The data is held in memory, and acid-state makes sure that data on hard drive is kept in sync with it. For a more detailed explanation, see `Note [acid-state]`.
Currently changing database schema is somewhat painful; to see how exactly painful it is, look at `Note [extending types]`. Not painful enough to never touch it again, sure, but still kinda annoying. Making it easier is possible, but for that we'd need a different `acid-state` or a real database.
### Other modules
`Markdown.hs` contains functions for rendering Markdown. There are special types for Markdown as well, coupling rendered Markdown, its text representation, and its parse tree.
`Merge.hs` contains an algorithm for merging edits – if you are editing a description of an item and someone else is editing the same description, upon submitting your edit you'll get a popup showing both versions and a merged version.
`Cache.hs` provides some helpers for caching pages. (A cache is a global variable holding a map from cache keys to rendered HTML.)
`Config.hs` has a config type and functions for reading/writing said config.
`Utils.hs` is just that – utility functions.

92
zurihac.md
View File

@ -1,92 +0,0 @@
# Zurihac 2017
## How to build the project
You will need [Stack][] and [npm][].
```
$ stack build # build the project
$ ./official.sh # download the database from https://guide.aelve.com
$ stack exec guide # start Guide
```
After that, the site will be running at <http://localhost:8080/>.
## What to hack on
There's a bunch of issues at <https://github.com/aelve/guide/issues>, but I
recommend taking one of issues listed below.
### Non-coding issues
* You can write content. Take any of the “To be written” categories
at <https://guide.aelve.com/haskell> and list libraries, write about
already listed libraries, or give examples. You can look
at <https://guide.aelve.com/haskell/lenses-sth6l9jl> for an example of a
more-or-less finished category.
* You can improve the design. This is mostly about CSS and HTML, though, but
it would still be appreciated. The HTML is mostly generated with [Lucid][],
though there are some bits written as Mustache templates in the
`templates/` folder. The styles can be found in `templates/css.widget`.
### Easy issues
* Add a special page listing all broken links (i.e. links returning 400 or
500).
* Improve analytics. Currently we've got lots of useless referrers (like
`encrypted.google.com` – see this [analytics screenshot][]). It'd be nice
if duplicated links were lumped together, Google/Yandex links were parsed
nicely, etc.
### Medium issues
* We've got search – for instance, here's how [searching for “lens”][] looks.
However, at the moment the search is somewhat dumb (if you look
at [`Guide.Search`][] you'll see that it simply does full-text search in
titles and doesn't do fuzzy matching).
* One way to improve it would be to add fuzzy matching of some kind, e.g.
take English morphology into account so that “lenses” would find
`lens`-the-library.
* Another thing you can do is implement highlighting for found terms. See
how GHC User's Guide does highlighting in this [search for “kinds”][].
* Currently, if you edit something and somebody else also edits (and saves
it) in the process, Guide will show you a popup saying “merge conflict,
please resolve it”. Unfortunately, it doesn't show the diff between the
conflicting versions; it'd be nice to highlight differences in them. This
is a pretty easy task.
* Guide also tries to resolve the merge confict by itself, but the algorithm
it uses is pretty dumb (see <https://github.com/aelve/guide/issues/91> for
details). If you want to research merge algorithms and implement a better
one, it'll be cool.
* Since the database is publicly accessible, it should be possible to write
an Electron wrapper that would download it and serve it offline. That's a
pretty good issue in terms of power-to-weight ratio (i.e. it's useful *and*
easy to do).
* If you look at e.g. [notes for lens][], you'll find that editing them is a
pain because you can only edit the whole thing at the time. It'd be better
to allow editing subsections directly (and also code snippets). This is
somewhat complicated because if someone else edits the section that you
were also editing, the backend would have to somehow recognize which
subsection you were editing. This can be done, for instance, by sending two
pieces of text to the backend – `(original text, modified text)` – and then
the backend would find the subsection that matches the original text and
(try to) apply the changes to it.
[Stack]: https://haskellstack.org
[npm]: https://www.npmjs.com/
[Lucid]: https://hackage.haskell.org/package/lucid
[`Guide.Search`]: src/Guide/Search.hs
[search for “kinds”]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/using.html?highlight=kinds#ghc-flag--fprint-explicit-kinds
[searching for “lens”]: https://guide.aelve.com/haskell?q=lens
[notes for lens]: https://guide.aelve.com/haskell/lenses-sth6l9jl#item-notes-ov2yi6mf
[analytics screenshot]: https://github.com/aelve/guide/issues/85#issuecomment-307368459