Write and deploy a man page

[andychu]

Got a request on lobste.rs. The first pass should probably just be a pointer to web resources.

https://lobste.rs/s/npha0x/oil_shell_what_s_happened_since_february

Related to #260

[msingle]

Any objections to mandoc/mdoc?

[andychu]

@msingle Does that imply any end-user dependency? Or is it just at build time for developers?

I honestly know very little about man pages. I use them occasionally but have never made one. Any help is appreciated!

BTW we started a man page here a long time ago, but I think we didn't know what the convention is to hook it up to the install script. Does autoconf usually do that?

https://github.com/oilshell/oil/blob/master/doc/osh.1

[msingle]

@andychu
With the caveat that I'm a mandoc newbie:
mandoc -T man will output standard man pages (though mdoc macros seem to have pretty decent support), so this should just be a build time dependency.

It can also output markdown/html/others - though authoring is more friendly, if imprecise, with markdown.

I don't know anything about autoconf but I'll dig some more

[The-King-of-Toasters]

I'll echo here what I (and others) told Matthew on the mandoc mailing list.

mdoc(7) and man(7) are text markup languages (like markdown), usually implemented as troff macros.
mdoc was created as a replacement to man and adds semantic markup elements, similar to how HTML replaced gopher with its richer, semantic markup.

mdoc is quite old: early versions came out in the 90's, and it has been supported by groff (the biggest manpage formatter) since that time. BSD systems also predominantly use mandoc as their formatter, which was initially built for mdoc manpages. As such, the only systems that don't support mdoc OOTB are the "classic" UNIX systems (AIX, Solaris, HP-UX etc.). And as Matthew mentioned, mandoc has been ported to these systems as well. Thus there's no need to add any autoconf rules if you don't care about them.

As for the manpage itself, I recommend looking at OpenBSD's sh(1) (source available here) to get an idea of how it should look. Basically, it should act as the go-to reference for osh.

BTW, every manual I've linked here uses mandoc HTML output mode. Thus if you were to make a comprehensive reference for osh, you could use mandoc to generate the online version of that reference as well.

Finally, if you need help in writing osh(1) I could probably lend a hand.

[msingle]

@The-King-of-Toasters I'll try to make a first pass at a manpage later, some (man page/documenation oriented) review would be appreciated.

[andychu]

I looked at dash, and it has src/dash.1, but I don't see how / if it's installed on the system?

Maybe it's done by a distro-specific method or by the "ports" system? I grepped the Makefile and other scripts for dash.1 and didn't see it.

Generally I look at bash, dash, zsh, and mksh to see when I want to see what portable Unix conventions are. But in this case I still don't know how it works.

Thanks for looking at this -- help is definitely appreciated!

[msingle]

@andychu it looks like Makefile.am puts it in a list of files (EXTRA_DIST) that autoconf/automake treats specially?

[msingle]

@The-King-of-Toasters can you take a look at #337 ?

[andychu]

Closing in favor of #418, which still needs to be done