Re: Mandoc for oil

[Jan Stary <hans@stare.cz>]

Hello Matt,

On Jun 14 04:16:17, matt.singletary@gmail.com wrote:
> After seeing mandoc mentioned in the past, I thought I would look into
> writing a man page for the Oil shell (http://www.oilshell.org/). I've never
> written a man page before but thought I'd try to use some decent tools to
> start with.
> 
> I'm a little confused about distribution/workflow for distributing man
> pages (in general). If osh.1 is an mdoc flavored file, would that be used
> (with mandoc -T man) to output a man page that could then be setup when Osh
> is installed?

during installation (which has nothing to do with mandoc),
the program and its manpage will typically be installed,
such as 'osh' and 'osh.1' in your case, possibly into

	/usr/local/bin/osh
	/usr/local/man/man1/osh.1

mdoc(5) is just a format; mandoc(1) is one of the programs
that can read and display that format; the traditional man(1),
usually built on top of groff(1), is another one.

mandoc is a manpage formater: it reads a file.1 (or file.5 etc)
and displays it nicely for the user (or ouputs a pdf, etc).
The file.1 itself you can write in any text editor.

> Then how do you distinguish those?

Distinguish what from what?

> Oil uses autoconf for some things, would that get tied
> into generating/installing the man pages on the manpath?

The GNU auto* tools are a way to generate the actual Makefile
that describes the building and installing. (Personally,
I find if much simpler to write the Makefile by hand.)

At any rate, the manpage is just another file
to be installed along with the program.

> Sorry if these are dumb questions, but I'm not even sure what kind of
> documentation I need to look through yet.

A good start is

	$ wc -l /usr/share/man/man1/*.1 | sort -n | less

(or wherever your system keeps manpages),
pick the shortest one for a program you know and use,
and read the (input) manpage, such as

      $ vim /usr/share/man/man1/yes.1

Do this for a few simple programs/function/formats
with short manpages (in section man1, man3, man5),
then read

	http://man.openbsd.org/mdoc

to learn what exactly it means.

Happy reading,

		Jan

--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv