redox issueshttps://gitlab.redox-os.org/redox-os/redox/-/issues2019-12-09T15:28:06Zhttps://gitlab.redox-os.org/redox-os/redox/-/issues/386Make a reference/glossary list2019-12-09T15:28:06ZJeremy SollerMake a reference/glossary list*Created by: ticki*
*Created by: ticki*
Documentationhttps://gitlab.redox-os.org/redox-os/redox/-/issues/525Documentation, transparency, and information2023-06-13T04:27:55ZJeremy SollerDocumentation, transparency, and information*Created by: ticki*
- [x] Contribute.md
- [ ] Complete docs of **everything** in the kernel.
- [ ] Complete design document.
- [ ] Formal proof of the design (I'm working on this)
- [ ] `#![deny(missing_doc)]` in all Redox-related crate...*Created by: ticki*
- [x] Contribute.md
- [ ] Complete docs of **everything** in the kernel.
- [ ] Complete design document.
- [ ] Formal proof of the design (I'm working on this)
- [ ] `#![deny(missing_doc)]` in all Redox-related crates.
- [x] A overview of the design principles.
- [x] "Everything is an URL" explanation (I'm working on this)
- [ ] "What is done, and what is not done"
- [x] Complete list of goals and non-goals.
- [x] What is the rationale behind using Rust? What advantages does it carry? What disadvantages?
- [x] How and where is the userspace/kernelspace seperation enforced?
- [ ] What general-purpose "means"
- [x] How we differ and not differ from Linux, BSD, Minix, and Plan9.
- [x] **A complete, collected list of sources of information**
- [ ] The architecture of the ZFS implementation.
- [x] What Redox is and what it isn't.
- [ ] How can I write programs for Redox? (I'm working on this)
- [x] A "book", see #403 (I'm working on this).
- [x] How POSIX-compatible is Redox?
- [x] Why?
- [x] Man pages.
- [x] Documentation for utils.
TODO: Add moreDocumentationhttps://gitlab.redox-os.org/redox-os/redox/-/issues/584A proposal for a Redox manual format2023-06-13T04:29:01ZJeremy SollerA proposal for a Redox manual format*Created by: tnias*
I've noticed the lack of something like manpages seen in other *nix systems. So I sat down and started writing down some things that may or may not be useful or nice.
## Manual format
Some of the apps/utils/.. alrea...*Created by: tnias*
I've noticed the lack of something like manpages seen in other *nix systems. So I sat down and started writing down some things that may or may not be useful or nice.
## Manual format
Some of the apps/utils/.. already have `const MANPAGE: &'static [u8]` to give some documentation to the enduser via `--help`. Something similar may be useful to automaticly generate manuals for all the native applications.
Another idea usable outside of rust-only applications would be to define manpages in TOML. (Why toml? Well, it magically appears whenever Rust shows up anywhere. It is also easily parsable.)
Example for grep (taken from FreeBSD, but it seems to be the GNU version):
``` toml
# name of the tool
name="grep, egrep, fgrep, zgrep, zegrep, zfgrep, bzgrep, bzegrep, bzfgrep"
# a short description
desc="print lines matching a pattern"
# XXX: make the format compatible to make parsing easy to enable better
# tabcompletion
synopsis=[
"grep [options] PATTERN [FILE...]",
"grep [options] [-e PATTERN | -f FILE] [FILE...]"
]
author="Max Mustermann"
[description]
text="""\
grep searches the named input FILEs (or standard input if no files \
are named, or the file name - is given) for lines containing a match to the \
given PATTERN. By default, grep prints the matching lines. \
\
In addition, two variant programs egrep and fgrep are available. egrep \
is the same as grep -E. fgrep is the same as grep -F. zgrep is the \
same as grep -Z. zegrep is the same as grep -EZ. zfgrep is the same \
as grep -FZ.\
"""
[options]
[options.help]
parameter='--help'
text="Output a brief help message."
[option.ignore_case]
parameter=['-i', '--ignore-case']
text='Ignore case distinctions in both the PATTERN and the input files.'
# and a lot of other options
[environment] # environment variable effects explained
[environment.color]
name="GREP_COLOR"
text="Specifies the marker for highlighting."
```
(am I even using toml the right way?)
## URL everything
Since everything is a URL in Redox, what does everyone think of the following structure.
```
man://<section>/<name>/index.{html,md,...,txt,pdf,...,toml}
man://prog/grep/index.html
man://lib/orbtk/index.html
...
```
(`<sections>` are somewhat equivalent to chapters known from current manpages)
> Either way docs are normal text files but rendered as html for better read. Redox can provide some basic converters to convert common markup doc like rst/md to html, and users can provide their own doc converters if needed.
HTML being delivered to the users browser would definitely be nice. What about other markup languages and plaintext automatically being created on demand or even a pdf version export? I am really not sure if pdf would be of any use.
But being able to retrive the raw toml file for tools to parse is positive. (assuming the idea above or similar is okay)
A tool functionally equivalent to `man` would make it easier for users coming from Linux/*BSD/..
(The URL part was inspired by #172. The quote is taken from there as well.)
## Disclaimer
This is no final solution. Not even close. I am just throwing some ideas out there do start a discussion. Please help by commenting.Documentationhttps://gitlab.redox-os.org/redox-os/redox/-/issues/610API documentation and manual pages (list)2023-06-13T04:32:36ZJeremy SollerAPI documentation and manual pages (list)*Created by: ticki*
- [ ] API docs.
- [x] libextra
- [x] libmalloc
- [x] binutils
- [x] Sodium
- [ ] OrbTK
- [ ] Orbclient
- [ ] Redox-specific std
- [ ] System
- [x] Helper functions
- [ ] Errors
- [ ] Graph...*Created by: ticki*
- [ ] API docs.
- [x] libextra
- [x] libmalloc
- [x] binutils
- [x] Sodium
- [ ] OrbTK
- [ ] Orbclient
- [ ] Redox-specific std
- [ ] System
- [x] Helper functions
- [ ] Errors
- [ ] Graphics
- [ ] Scheme
- [ ] Scheme
- [ ] Packet
- [ ] syscall
- [ ] Constants
- [ ] syscalls
- [ ] sys_debug
- [ ] sys_supervise
- [ ] sys_brk
- [ ] sys_chdir
- [ ] sys_clock_gettime
- [ ] sys_clone
- [ ] sys_close
- [ ] sys_dup
- [ ] sys_execve
- [ ] sys_exit
- [ ] sys_fpath
- [ ] sys_fstat
- [ ] sys_fsync
- [ ] sys_ftruncate
- [ ] sys_getpid
- [ ] sys_iopl
- [ ] sys_link
- [ ] sys_lseek
- [ ] sys_mkdir
- [ ] sys_nanosleep
- [ ] sys_open
- [ ] sys_pipe2
- [ ] sys_read
- [ ] sys_rmdir
- [ ] sys_stat
- [ ] sys_unlink
- [ ] sys_waitpid
- [ ] sys_write
- [ ] sys_yield
- [ ] Kernel
- [x] Top-level modules.
- [x] Top-level constants.
- [x] Top-level functions.
- [ ] ACPI
- [ ] Alloc
- [ ] Arch
- [ ] context
- [ ] ContextManager
- [ ] Context
- [ ] ContextMemory
- [ ] ContextFile
- [ ] EnvironmentVariable
- [ ] ContextZone
- [ ] context_switch
- [ ] context_clone
- [ ] context_box
- [ ] context_userspace
- [ ] Constants
- [ ] elf
- [ ] Intex et al.
- [ ] memory
- [x] Memory
- [x] MemoryMapEntry
- [x] address_to_cluster
- [x] alloc
- [x] alloc_aligned
- [ ] alloc_size
- [x] alloc_type
- [x] cluster
- [x] cluster_init
- [ ] cluster_to_address
- [ ] memory_free
- [ ] memory_used
- [ ] realloc
- [ ] realloc_aligned
- [ ] realloc_inplace
- [x] set_cluster
- [ ] unalloc
- [ ] unalloc_type
- [ ] paging
- [ ] regs
- [ ] tss
- [ ] audio
- [ ] ac97
- [ ] intelhda
- [ ] common
- [ ] debug
- [ ] event
- [ ] parse_ip
- [ ] parse_path
- [ ] random
- [ ] slice
- [ ] time
- [ ] to_num
- [ ] disk
- [ ] ahci
- [ ] ide
- [ ] Disk
- [ ] drivers
- [ ] kb_layouts
- [ ] pci
- [ ] ps2
- [ ] rtc
- [ ] serial
- [ ] env
- [ ] externs
- [ ] fs
- [ ] redoxfs
- [ ] kscheme
- [ ] VecResource
- [ ] scheme
- [ ] URL
- [ ] graphics
- [ ] color
- [ ] display
- [ ] macros
- [ ] network
- [ ] common
- [ ] ethernet
- [ ] intel8254x
- [ ] ipv4
- [ ] ipv6
- [ ] rtl8139
- [ ] scheme
- [ ] schemes
- [ ] panic
- [ ] scheme
- [ ] context
- [ ] debug
- [ ] display
- [ ] env
- [ ] file
- [ ] initfs
- [ ] interrupt
- [ ] memory
- [ ] pipe
- [ ] test
- [ ] sync
- [ ] wait_condition
- [ ] wait_map
- [ ] wait_queue
- [ ] syscall
- [ ] debug
- [ ] execute
- [ ] file
- [ ] memory
- [ ] process
- [ ] time
- [ ] usb
- [ ] desc
- [ ] ehci
- [ ] hci
- [ ] ohci
- [ ] setup
- [ ] uhci
- [ ] xhci
- [ ] Mapages
- [x] coreutils
- [ ] syscalls
- [x] extrautils
- [x] binutils
- [ ] Orbital
- [ ] Sodium
- [ ] Ion
- [ ] RedoxFS
- [ ] Various handy manpages (e.g. ASCII, possibly [sheets](https://github.com/Ticki/sheets)).
We suck at API docs. Preferably every entry should have a detailed description of the functionality. Currently, most only have a short trivial description, despite not having a trivial functionality.Documentationhttps://gitlab.redox-os.org/redox-os/redox/-/issues/739Document default schemes2023-06-13T04:30:46ZJeremy SollerDocument default schemesFor every scheme a fully running kernel has, the following functions need to be documented, if implemented. In addition, the Scheme and SchemeMut traits should be documented with usage and the default operation.
Documentation should inc...For every scheme a fully running kernel has, the following functions need to be documented, if implemented. In addition, the Scheme and SchemeMut traits should be documented with usage and the default operation.
Documentation should include usage, what access restrictions there are, what paths and dup arguments are valid, and what errors may be returned.
#### Path Operations
- [ ] open
- [ ] mkdir
- [ ] rmdir
- [ ] unlink
#### File Operations
- [ ] dup
- [ ] read
- [ ] write
- [ ] seek
- [ ] fevent
- [ ] fmap
- [ ] fpath
- [ ] fstat
- [ ] fsync
- [ ] ftruncate
- [ ] close
#### Schemes
- [ ] debug
- [ ] disk
- [ ] display
- [ ] env
- [ ] ethernet
- [ ] event
- [ ] file
- [ ] initfs
- [ ] ip
- [ ] irq
- [ ] network
- [ ] null
- [ ] orbital
- [ ] pipe
- [ ] pty
- [ ] rand
- [ ] sys
- [ ] tcp
- [ ] udp
- [ ] zeroDocumentationJeremy SollerJeremy Sollerhttps://gitlab.redox-os.org/redox-os/redox/-/issues/909Why not creating milestones?2018-06-15T11:40:01ZJeremy SollerWhy not creating milestones?*Created by: pharaone*
Why not creating milestones for new versions? To give a little more information to users, and maybe even for large future releases. *Created by: pharaone*
Why not creating milestones for new versions? To give a little more information to users, and maybe even for large future releases. DocumentationJeremy SollerJeremy Soller