book issueshttps://gitlab.redox-os.org/redox-os/book/-/issues2023-04-17T08:18:05Zhttps://gitlab.redox-os.org/redox-os/book/-/issues/143Add warning/instructions for macos dependency : bison2023-04-17T08:18:05ZAndrew MackenzieAdd warning/instructions for macos dependency : bisonmacos has a version of bison already installed, but it is too old and the build fails.
installing a newer version of bison using brew is needed.
However, the brew install of bison is "keg only" and not added to the path.
If you add it...macos has a version of bison already installed, but it is too old and the build fails.
installing a newer version of bison using brew is needed.
However, the brew install of bison is "keg only" and not added to the path.
If you add it to the path AFTER the apple version, you will continue to be using the older version and build will fail.
So, you need to follow the instructions printed out from brew when running "brew install bison" and add it to the start of your $PATH
Here is the output of me re-installing it
```
❯ brew reinstall bison
==> Fetching bison
==> Downloading https://ghcr.io/v2/homebrew/core/bison/manifests/3.8.2
Already downloaded: /Users/andrew/Library/Caches/Homebrew/downloads/0a84b14c20dfba4609542ea4b14a4eb93d369f7f83f373b568017fc7d76b6505--bison-3.8.2.bottle_manifest.json
==> Downloading https://ghcr.io/v2/homebrew/core/bison/blobs/sha256:fc0224d45c74ee561128eb9df366ccb08698b1d659cfb92ea746e57da0108806
Already downloaded: /Users/andrew/Library/Caches/Homebrew/downloads/0865a0dc7ef4c841a5650a22e6ce05918c025ca1dbadf91d0e18551aca1f4ac3--bison--3.8.2.ventura.bottle.tar.gz
==> Reinstalling bison
==> Pouring bison--3.8.2.ventura.bottle.tar.gz
==> Caveats
bison is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.
If you need to have bison first in your PATH, run:
echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.zshrc
For compilers to find bison you may need to set:
export LDFLAGS="-L/usr/local/opt/bison/lib"
==> Summary
🍺 /usr/local/Cellar/bison/3.8.2: 99 files, 3.7MB
==> Running `brew cleanup bison`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).
Warning: Calling plist_options is deprecated! Use service.require_root instead.
Please report this issue to the ethersphere/tap tap (not Homebrew/brew or Homebrew/homebrew-core), or even better, submit a PR to fix it:
/usr/local/Homebrew/Library/Taps/ethersphere/homebrew-tap/swarm-clef.rb:53
Warning: Calling plist_options is deprecated! Use service.require_root instead.
Please report this issue to the ethersphere/tap tap (not Homebrew/brew or Homebrew/homebrew-core), or even better, submit a PR to fix it:
/usr/local/Homebrew/Library/Taps/ethersphere/homebrew-tap/swarm-bee.rb:56
```https://gitlab.redox-os.org/redox-os/book/-/issues/142Update Chat chapter to refer to Redox space in Matrix, and clarify how to use...2023-06-13T04:50:25ZRon WilliamsUpdate Chat chapter to refer to Redox space in Matrix, and clarify how to use /SupportRedox OS is a space in Matrix, users should join that.
Redox OS/Support requires a user to join if they use Element, there are guest accounts available on some other Matrix apps.Redox OS is a space in Matrix, users should join that.
Redox OS/Support requires a user to join if they use Element, there are guest accounts available on some other Matrix apps.https://gitlab.redox-os.org/redox-os/book/-/issues/141Document display driver concepts and developer guide2022-12-28T16:41:26ZRon WilliamsDocument display driver concepts and developer guideNeed documentation for:
- Current display driver design overview
- Developer guide for using display/Orbital
- Developer guide for integrating GUI libraries
- Developer guide for accelerated graphics driversNeed documentation for:
- Current display driver design overview
- Developer guide for using display/Orbital
- Developer guide for integrating GUI libraries
- Developer guide for accelerated graphics drivershttps://gitlab.redox-os.org/redox-os/book/-/issues/140Update the Getting Started chapter2023-06-13T04:52:39ZToby WebbUpdate the Getting Started chapterI followed the `compiling Redox` chapter and came across issues about missing commands.
As well as updating the instructions, I can see great benefit in adding a "Troubleshooting" section, in case something gets broken later.
(I might ...I followed the `compiling Redox` chapter and came across issues about missing commands.
As well as updating the instructions, I can see great benefit in adding a "Troubleshooting" section, in case something gets broken later.
(I might get round to compiling a MR for this issue if I have time.)https://gitlab.redox-os.org/redox-os/book/-/issues/139Ideas for a book style guide2023-06-13T04:54:05ZColeman McFarlandIdeas for a book style guideSome notes on structural style and formatting:
* wrap lines at 80-ish width, excepting:
* URLs that begin before 80 chars but overflow it
* Anything within a code block
* any headers (unlikely that headers should be this long, but...Some notes on structural style and formatting:
* wrap lines at 80-ish width, excepting:
* URLs that begin before 80 chars but overflow it
* Anything within a code block
* any headers (unlikely that headers should be this long, but we should specify)
* Newlines are '\n'
* all markdown in one folder
* when relative-linking between pages, link to the **markdown** file, not html. The build process will transform these into correct hyperlinks
* example: `blah blah blah, see [Getting started](./ch02-01-getting-started.md).`
* all image assets in one sub-folder, linked from one or more markdown files
* markdown files are named like this: `ch{CHAPTER}-{SECTION}-{NAME}.md`. Note:
* since all markdown is in one folder, the sorting of the files is the same as how the book reads front to back
* For multi-word names of chapters and sections, we prefer `-` hypen separation, not `_` underscores
Manually formatting the width of markdown is toilsome, and reducing toil is one of our goals (#138 ), so we must develop/find tools to automatically format markdown.https://gitlab.redox-os.org/redox-os/book/-/issues/138Refocus2023-06-13T04:54:44ZColeman McFarlandRefocusI'm writing down some thoughts on how we might improve the book.
### Style
Let's let [The Rust Book](https://doc.rust-lang.org/stable/book/ch01-00-getting-started.html) be our guide! This might mean
* Less nesting. Notice that the Rus...I'm writing down some thoughts on how we might improve the book.
### Style
Let's let [The Rust Book](https://doc.rust-lang.org/stable/book/ch01-00-getting-started.html) be our guide! This might mean
* Less nesting. Notice that the Rust Book only nests one level deep. Redox Book goes to 3. A flatter structure is more book-like.
* Fewer, longer sections. Some of our sections are quite short.
* Focus on the reader. Take them on a coherent journey that doesn't meander. Build one thing on top of another.
### Maintainability
We're a small community, so we'll need to be smart about what we pick.
* Fewer "lists". Dynamic content, highly specific details shouldn't go in the book. We can auto-generate those and put them on a section of the website or a more "docs"-looking documentation page. Stuff like: the list of schemes, the list of contributors.
* Higher-level. The content shouldn't need rewriting when some little component changes.
* Testability. If the book is a walkthrough of some sort, we should be able to script the underlying commands end-to-end.
* Automation. Here we might consider how users without backend access could build something easily deployable. A container, perhaps, or a well-structured tar file. Are there any other web server configs that could be prepared by CI? See #137
### Goals
The book doesn't have to do everything, or answer every question. Perhaps no answer is better than the wrong answer.
I don't think we need a ground-up rewrite so much as an aggressive refactoring. Clear away some cruft, edit for style and coherence, open issues on the website repo for things that really belong over there, etc. After all that, we can see where we're at.
What do you all think?Coleman McFarlandColeman McFarlandhttps://gitlab.redox-os.org/redox-os/book/-/issues/137Link to "Getting Started" on the home page of the redox book is a broken link2020-02-20T03:04:48ZAlexander DikelskyLink to "Getting Started" on the home page of the redox book is a broken linkClicking the "Getting Started" link on this page: https://doc.redox-os.org/book/ gives me a 404 error.
Looking at it a little more, it looks like the "Getting Started" link should go to
```"https://doc.redox-os.org/book/getting_starte...Clicking the "Getting Started" link on this page: https://doc.redox-os.org/book/ gives me a 404 error.
Looking at it a little more, it looks like the "Getting Started" link should go to
```"https://doc.redox-os.org/book/getting_started/getting_started.html"```
rather than just
```"https://doc.redox-os.org/getting_started/getting_started.html"```https://gitlab.redox-os.org/redox-os/book/-/issues/136Build checks for broken links into CI2020-02-19T23:03:13ZColeman McFarlandBuild checks for broken links into CIFind a way to _warn_ (not fail?) on broken links reliably.
Considerations
* relative paths vs fully qualified URLs (external links)
* will we need more than the default tooling mdbook provides?
Blocked by !148 Relates to #133Find a way to _warn_ (not fail?) on broken links reliably.
Considerations
* relative paths vs fully qualified URLs (external links)
* will we need more than the default tooling mdbook provides?
Blocked by !148 Relates to #133https://gitlab.redox-os.org/redox-os/book/-/issues/135Automation around dynamic info (lines of code, core utils, core contributors)2023-06-13T04:56:29ZColeman McFarlandAutomation around dynamic info (lines of code, core utils, core contributors)Our book, in several places, makes reference to information that can quickly get out of date:
* lists of libraries and packages
* lists of contributors
* counting the lines of code in the kernel :-)
* packages that do not share our MIT ...Our book, in several places, makes reference to information that can quickly get out of date:
* lists of libraries and packages
* lists of contributors
* counting the lines of code in the kernel :-)
* packages that do not share our MIT X11-style license
We should consider some lightweight automation around checking if this info is up to date, and/or updating it directly.
Ideally we drive these checks from CI.https://gitlab.redox-os.org/redox-os/book/-/issues/134Consider consolidating Overview and Introduction2020-02-15T13:56:01ZColeman McFarlandConsider consolidating Overview and IntroductionThere is a good deal of overlap between these sections, and a few things that can be moved out.
Under a single, consolidated "Introduction" chapter, we might address explaining what Redox is, how redox compares to other systems, the Red...There is a good deal of overlap between these sections, and a few things that can be moved out.
Under a single, consolidated "Introduction" chapter, we might address explaining what Redox is, how redox compares to other systems, the Redox philosophy, and getting the reader excited about exploring further.
A proposed outline for the consolidated chapter:
---
### Introduction
* Welcome
* What is Redox
* Redox vs. Other Operating Systems
* Goals
* Philosophy
---
Some things we might remove
* Heartbleed, a case study - This is a TODO chapter, and might be better suited as a focused, technical whitepaper or blog post.
* "About this book" - we can include this in the "contribute to docs" section of our chapter that describes ways to contribute
https://gitlab.redox-os.org/redox-os/book/-/issues/133Broken links in "Getting Started" (and possibly elsewhere)2020-02-19T23:06:43ZAl HeshBroken links in "Getting Started" (and possibly elsewhere)Looks like there are broken links [Getting Started](https://doc.redox-os.org/book/getting_started/getting_started.html) and possibly elsewhere.
I'm not sure if `mdbook build` just needs to be run again, since it seems to be working fine...Looks like there are broken links [Getting Started](https://doc.redox-os.org/book/getting_started/getting_started.html) and possibly elsewhere.
I'm not sure if `mdbook build` just needs to be run again, since it seems to be working fine on my local machine.
e.g. the following are all giving me 404's
- ["Preparing the build"](https://doc.redox-os.org/book/preparing_the_build.html)
- ["running in a virtual machine"](https://doc.redox-os.org/book/try_vm.html)
- ["running on real hardware"](https://doc.redox-os.org/book/real_hardware.html)https://gitlab.redox-os.org/redox-os/book/-/issues/132Instructions to clone repo cause access right issues2019-09-16T13:26:02ZHadrien MilanoInstructions to clone repo cause access right issuesUnauthenticated users can not use ssh to clone various repositories from gitlab. They must use https instead.
For instance, in section 3.3: Installing the toolchain, this is what I get:
```
$ git clone --recursive git@gitlab.redox-os.o...Unauthenticated users can not use ssh to clone various repositories from gitlab. They must use https instead.
For instance, in section 3.3: Installing the toolchain, this is what I get:
```
$ git clone --recursive git@gitlab.redox-os.org:redox-os/libc
git@gitlab.redox-os.org: Permission denied (publickey).
fatal: Could not read from remote repository.
```
Instead, I must use:
```
$ git clone --recursive https://gitlab.redox-os.org/redox-os/libc
Cloning into 'libc'...
```https://gitlab.redox-os.org/redox-os/book/-/issues/131Provide instructions to run in Virtualbox2023-12-13T16:11:38ZdavidakProvide instructions to run in VirtualboxVirtualbox is way more popular than Quemu/KVM, so instructions to run Redox OS with it would help people to test it.
Page: https://doc.redox-os.org/book/getting_started/try_vm.html
(i was not able to run it, even with hints from the fo...Virtualbox is way more popular than Quemu/KVM, so instructions to run Redox OS with it would help people to test it.
Page: https://doc.redox-os.org/book/getting_started/try_vm.html
(i was not able to run it, even with hints from the forum https://gitlab.redox-os.org/redox-os/redox/issues/1185)https://gitlab.redox-os.org/redox-os/book/-/issues/130.bin.gz hard disk image not available at download link (GitLab)2020-01-20T17:47:18Zdavidak.bin.gz hard disk image not available at download link (GitLab)Page: https://doc.redox-os.org/book/getting_started/try_vm.html
>Instead, you want to use the hard disk image, which you can find on the release pages as a .bin.gz file.
**release pages** links to GitLab now where no .bin.gz file is av...Page: https://doc.redox-os.org/book/getting_started/try_vm.html
>Instead, you want to use the hard disk image, which you can find on the release pages as a .bin.gz file.
**release pages** links to GitLab now where no .bin.gz file is available.
https://gitlab.redox-os.org/redox-os/redox/tags
Related to https://gitlab.redox-os.org/redox-os/redox/issues/1191https://gitlab.redox-os.org/redox-os/book/-/issues/129add some text for the introduction front page2020-02-17T02:35:12ZStéphane Campinasadd some text for the introduction front pageThe `Introduction` section is empty which gives a strange feeling. Probably a description of the subsections is enough.
![Screenshot_2018-11-15_Introduction_-_The_Redox_Operating_System](/uploads/ceec7e67aa96f1b19ac8876b50cb1fb4/Screens...The `Introduction` section is empty which gives a strange feeling. Probably a description of the subsections is enough.
![Screenshot_2018-11-15_Introduction_-_The_Redox_Operating_System](/uploads/ceec7e67aa96f1b19ac8876b50cb1fb4/Screenshot_2018-11-15_Introduction_-_The_Redox_Operating_System.png)https://gitlab.redox-os.org/redox-os/book/-/issues/128How to Build book2020-02-17T02:34:27ZJeremy SollerHow to Build book*Created by: stratosmacker*
Running mdbook is not the only step to building the HTML, what build steps do you run? I'd like to build this for offline use, but running `mdbook build` in src/ only builds a blank page*Created by: stratosmacker*
Running mdbook is not the only step to building the HTML, what build steps do you run? I'd like to build this for offline use, but running `mdbook build` in src/ only builds a blank pagehttps://gitlab.redox-os.org/redox-os/book/-/issues/122Navigation through book results in infinite loop2018-09-07T01:22:53ZJeremy SollerNavigation through book results in infinite loop*Created by: staktrace*
Go to https://doc.redox-os.org/book/getting_started/preparing_the_build.html
Go to the bottom and click on the next arrow, this will take you to https://doc.redox-os.org/book/getting_started/installing_the_toolc...*Created by: staktrace*
Go to https://doc.redox-os.org/book/getting_started/preparing_the_build.html
Go to the bottom and click on the next arrow, this will take you to https://doc.redox-os.org/book/getting_started/installing_the_toolchain.html
Go to the bottom of this page and click on the next arrow. It takes you back to the previous page instead of onwards to compiling. So always going to the "next" page gets you stuck in an infinite loop :(https://gitlab.redox-os.org/redox-os/book/-/issues/118Documentation: Translation into Spanish language2023-06-13T04:57:50ZJeremy SollerDocumentation: Translation into Spanish language*Created by: michaelizer*
Greetings, I would like to contribute to the project by translating it into Spanish. Spanish is my native language so don't panic, but a lot of Spanish speakers are still limited by the language so this is prim...*Created by: michaelizer*
Greetings, I would like to contribute to the project by translating it into Spanish. Spanish is my native language so don't panic, but a lot of Spanish speakers are still limited by the language so this is primarily to help them.
Thanks in advance and for your time. Keep up the great work.https://gitlab.redox-os.org/redox-os/book/-/issues/116"This books ..." should be "This book ..."2018-09-07T01:22:53ZJeremy Soller"This books ..." should be "This book ..."*Created by: victorz*
Also *operating system* is written without a dash.
https://github.com/redox-os/book/blob/55cde920ea5af88dc71c400329600f7156bfac72/book.json#L3*Created by: victorz*
Also *operating system* is written without a dash.
https://github.com/redox-os/book/blob/55cde920ea5af88dc71c400329600f7156bfac72/book.json#L3https://gitlab.redox-os.org/redox-os/book/-/issues/115Remove ZFS Section2018-09-07T01:22:53ZNick PaladinoRemove ZFS SectionSince RedoxFS, and eventually TFS, is the main file system, seems like a good idea. Or just rename it to TFS so the book can start to document it.Since RedoxFS, and eventually TFS, is the main file system, seems like a good idea. Or just rename it to TFS so the book can start to document it.