help / color / mirror / Atom feed
From: Jan Stary <hans@stare.cz>
To: discuss@mandoc.bsd.lv
Subject: Re: Mandoc for oil
Date: Fri, 14 Jun 2019 10:43:13 +0200	[thread overview]
Message-ID: <20190614084313.GA17405@www.stare.cz> (raw)
In-Reply-To: <CAAJ-tZJ=-8KHs4vOYhSZcaYA9tqLuOwUoLixHtZyekwDxjKb8w@mail.gmail.com>

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


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


to learn what exactly it means.

Happy reading,


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

  reply	other threads:[~2019-06-14  8:43 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-06-14  8:16 Matthew Singletary
2019-06-14  8:43 ` Jan Stary [this message]
2019-06-14  8:54   ` Jan Stary
2019-06-14  9:24     ` Matthew Singletary
2019-06-14 11:40       ` Jan Stary
2019-06-14 12:29       ` Ingo Schwarze
2019-06-14 13:08         ` Jan Stary
2019-06-14 14:27         ` Jan Stary
2019-06-14 14:54           ` Ingo Schwarze
2019-06-16  2:39             ` Matthew Singletary
2019-06-16 17:08               ` Ingo Schwarze
2019-06-14  9:54 ` Stephen Gregoratto
2019-06-14 12:03   ` Jan Stary

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190614084313.GA17405@www.stare.cz \
    --to=hans@stare.cz \
    --cc=discuss@mandoc.bsd.lv \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).