GitLab

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.