A 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/.. 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):
# 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 (closed). 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.