Skip to content

Commit

Permalink
Merge pull request #252 from gosub-browser/readme-update
Browse files Browse the repository at this point in the history 
updated readme to reflect the current state
  • Loading branch information
@jaytaph
jaytaph authored Nov 11, 2023
2 parents acafe70 + 1e2648d commit 31546cb
Showing 1 changed file with 27 additions and 14 deletions.
41 changes: 27 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# GoSub: Gateway to Optimized Searching and Unlimited Browsing

This repository holds the GoSub HTML5 parser/tokenizer. It is a standalone library that can be used by other projects but will ultimately be used by the GoSub browser. See the [About](#about) section for more information.
This repository holds the GoSub browser engine. It will become a standalone library that can be used by other projects but will ultimately be used by the Gosub browser user-agent. See the [About](#about) section for more information.

```
_
Expand All @@ -16,17 +16,23 @@ This repository holds the GoSub HTML5 parser/tokenizer. It is a standalone libra

## About

This repository is part of the GoSub browser project. Currently, there is only a single component/repository (this one), but the idea will be that there are many other components that, as a whole, make up a full-fledged browser. Each of the components can probably function as something standalone (ie, html5 parser, CSS parser, etc.).
This repository is part of the Gosub browser project. This is the main engine that holds at least the following components:

In the future, this component (HTML5 parser) will receive a stream of bytes through an API and output a stream of events. The next component will consume the events, and so on, until we can display something in a window/user agent. This could be a text-mode browser, but the idea is to have a graphical browser.
- HTML5 tokenizer / parser
- CSS3 tokenizer / parser
- Document tree
- Several APIs for connecting to javascript
- Configuration store

The idea is that this engine will receive some kind of stream of bytes (most likely from a socket or file) and parse this into a valid HTML5 document tree. From that point, it can be fed to a renderer engine that will render the document tree into a window, or it can be fed to a more simplistic engine that will render it in a terminal.

## Status

> This project is in its infancy. There is no browser you can use yet.
> This project is in its infancy. There is no browser you can use yet, but parsing a file into a document tree is possible.
This is a work in progress. The current status is that the parser can parse a few HTML5 documents, but it is far from ready. The main goal is to be able to parse correctly all the tests in the html5lib-tests repository (https://github.com/html5lib/html5lib-tests).
The main goal for the parser is to be able to parse correctly all the tests in the html5lib-tests repository (https://github.com/html5lib/html5lib-tests). This is currently achieved for both the tokenizer tests and the tree-construction tests. There are a few small issues left which are mainly because of handling of UTF-16 characters and test that does dom modification through scripts (there is no javascript engine implemented yet).

Our goal at the moment is to research as much as possible and to setup proof-of-concepts in order to gain more understanding in the field of browsers. We are not trying to create a full-fledged browser at the moment, but it will be our ultimate goal.
From a parsing point of view, the html5 parser and most of the css3 parser is completed for now.

## How to build

Expand All @@ -46,18 +52,18 @@ $ cargo build

Doing this will create the following binaries:

| File | Type | Description |
|-----------------------------------|------|-----------------------------------------------------------------|
| `target/debug/gosub-parser` | bin | The actual html5 parser/tokenizer |
| `target/debug/parser-test` | bin | A test suite for the parser that tests specific tests |
| `target/debug/html5-parser-tests` | bin | A test suite that tests all html5lib tests for the treebuilding |
| `target/debug/test-user-agent` | bin | A simple placeholder user agent for testing purposes |
| File | Type | Description |
|-----------------------------------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `target/debug/gosub-parser` | bin | The actual html5 parser/tokenizer that allows you to convert html5 into a document tree.
| `target/debug/parser-test` | bin | A test suite for the parser that tests specific tests. This will be removed as soon as the parser is completely finished as this tool is for developement only.
| `target/debug/html5-parser-tests` | bin | A test suite that tests all html5lib tests for the treebuilding |
| `target/debug/test-user-agent` | bin | A simple placeholder user agent for testing purposes |
| `target/debug/config-store` | bin | A simple test application of the config store for testing purposes |

You can then run the binaries like so:

```bash
$ ./target/debug/gosub-parser https://news.ycombinator.com/
$ ./target/debug/parser-test
```

To build the release build, run:
Expand All @@ -74,4 +80,11 @@ $ make test
$ cargo bench
$ ls target/criterion/report
index.html
```
```


## Contributing to the project
We welcome contributions to this project but the current status makes that we are spending a lot of time researching, building small proof-of-concepts and figuring out what needs to be done next. Much time of a contributor at this stage of the project will be non-coding.

We do like to hear from you if you are interested in contributing to the project and you can join us currently at our slack channel: https://join.slack.com/t/gosubgroup/shared_invite/zt-248ksp6sy-9GUHEuf7BIlI6gxjcXJFnA

0 comments on commit 31546cb

Please sign in to comment.