book issueshttps://gitlab.redox-os.org/redox-os/book/-/issues2023-06-13T04:57:50Zhttps://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/100Pin version of mdBook2023-06-13T04:57:01ZJeremy SollerPin version of mdBook*Created by: azerupi*
Hi!
I am not totally sure this applies to this repository, because I don't know if you release automatically?
We would like to issue a new release of mdBook containing some changes that could potentially break cu...*Created by: azerupi*
Hi!
I am not totally sure this applies to this repository, because I don't know if you release automatically?
We would like to issue a new release of mdBook containing some changes that could potentially break current books, the config file changed a bit for example. However we found out that a lot of projects automatically deploy using the latest available version and so any breaking update could result in books not being deployed anymore..
We would like to avoid that and recommend pinning the version of mdBook in your deployment script. Cargo supports semver ranges on `cargo install` (right now it issues a deprecation warning, but in the future this warning should go away thanks to rust-lang/cargo#4229)
You can thus simply change `cargo install mdbook` to
```
cargo install mdbook --vers "^0.0.22"
```
Next release will be `0.1.0` and we will try to adhere to semver as much as possible.
For more info, azerupi/mdBook#327 is the tracking issue on our repository.https://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/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/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/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/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/60C style strings used instead of pascal style strings in book2022-09-23T22:19:41ZJeremy SollerC style strings used instead of pascal style strings in book*Created by: bjorn3*
At `https://doc.redox-os.org/book/design/url/how_it_works.html#Opening a URL` it is said that the `open` syscall takes a C style string, but it takes a pascal style string.*Created by: bjorn3*
At `https://doc.redox-os.org/book/design/url/how_it_works.html#Opening a URL` it is said that the `open` syscall takes a C style string, but it takes a pascal style string.https://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/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/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/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/20Move certain sections out of `design`2020-02-17T02:32:21ZJeremy SollerMove certain sections out of `design`*Created by: ticki*
Certain parts of the `design` chapter is out of the scope of the chapter, and would fit better in introduction, development in userspace, or contributing.
*Created by: ticki*
Certain parts of the `design` chapter is out of the scope of the chapter, and would fit better in introduction, development in userspace, or contributing.
https://gitlab.redox-os.org/redox-os/book/-/issues/104Redox vs Linux2020-02-17T02:31:56ZJeremy SollerRedox vs Linux*Created by: thomaskuntzz*
>
> Will Redox replace Linux?
> =========================
>
> No.
https://github.com/redox-os/book/blob/master/src/introduction/will_redox_replace_linux.md
Really? Bro?
Explaaaaaaaaaaaaaaaaaaaain!...*Created by: thomaskuntzz*
>
> Will Redox replace Linux?
> =========================
>
> No.
https://github.com/redox-os/book/blob/master/src/introduction/will_redox_replace_linux.md
Really? Bro?
Explaaaaaaaaaaaaaaaaaaaain!!! We want to know **why** the guys that created it think this! It doesn't have the same goal? Purpose? The same use cases? Too young? Linux community is too big? I don't know, but atcual reasons...
Elaborate, we'd like to know what you think 😉 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/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/25Why NASM2019-10-03T01:03:29ZJeremy SollerWhy NASM*Created by: vinipsmaker*
This isn't explained.
*Created by: vinipsmaker*
This isn't explained.
https://gitlab.redox-os.org/redox-os/book/-/issues/57Can one use the orbital modules for GUIs outside of redox?2019-09-29T02:11:32ZJeremy SollerCan one use the orbital modules for GUIs outside of redox?*Created by: strpipe*
is it possible to use orbital also for Rendering app on different platforms?
Meaning can one use this as a Rust Gui framework?*Created by: strpipe*
is it possible to use orbital also for Rendering app on different platforms?
Meaning can one use this as a Rust Gui framework?https://gitlab.redox-os.org/redox-os/book/-/issues/67Provide (markdown) syntax highlighting for Ion scripts2019-09-29T01:28:21ZJeremy SollerProvide (markdown) syntax highlighting for Ion scripts*Created by: GlenDC*
Currently there is no support for [Ion][ion] scripts in the code syntax highlighting capabilities of the markdown-based generator used for this book. Additionally the markdown files as part of the redox-os/ion also ...*Created by: GlenDC*
Currently there is no support for [Ion][ion] scripts in the code syntax highlighting capabilities of the markdown-based generator used for this book. Additionally the markdown files as part of the redox-os/ion also do not have syntax-highlighting support currently for [Ion][ion] scripts.
A great starting point to solve this issue would be to add syntax information for Ion to [azerup/mdBook][mdbook] (as a contribution), or whatever library it uses to support syntax highlighting for code snippets. [azerup/mdBook][mdbook] is the technology we use to generate this book.
[mdbook]: https://github.com/azerupi/mdBook
[ion]: https://github.com/redox-os/ion