discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Mandoc for oil
@ 2019-06-14  8:16 Matthew Singletary
  2019-06-14  8:43 ` Jan Stary
  2019-06-14  9:54 ` Stephen Gregoratto
  0 siblings, 2 replies; 13+ messages in thread
From: Matthew Singletary @ 2019-06-14  8:16 UTC (permalink / raw)
  To: discuss

[-- Attachment #1: Type: text/plain, Size: 743 bytes --]

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? Then how do you distinguish those? Oil uses autoconf for some
things, would that get tied into generating/installing the man pages on the
manpath?

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

Thanks,
Matt

[-- Attachment #2: Type: text/html, Size: 921 bytes --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14  8:16 Mandoc for oil Matthew Singletary
@ 2019-06-14  8:43 ` Jan Stary
  2019-06-14  8:54   ` Jan Stary
  2019-06-14  9:54 ` Stephen Gregoratto
  1 sibling, 1 reply; 13+ messages in thread
From: Jan Stary @ 2019-06-14  8:43 UTC (permalink / raw)
  To: discuss

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14  8:43 ` Jan Stary
@ 2019-06-14  8:54   ` Jan Stary
  2019-06-14  9:24     ` Matthew Singletary
  0 siblings, 1 reply; 13+ messages in thread
From: Jan Stary @ 2019-06-14  8:54 UTC (permalink / raw)
  To: discuss

> mdoc(5) is just a format;

I mean mdoc(7), sorry.

> 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

I forgot an important thing: on many systems outside of the *BSD family,
the system manpages will be written in the legacy man(7) format,
built on top of roff(7), a general purpose typesetting language.

Both man(1) and mandoc(1) can read both; but mdoc(5) ficilitates
semantic markup ("this is a commandline option"), as opposed to
low-level formating instructions ("type this in italic").

In case your system uses man(7), not mdoc(7), as e.g. most linuxes do,
you will have to learn mdoc elsewhere, e.g.

	http://cvsweb.openbsd.org/src/usr.bin/yes/yes.1

Jan

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  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
  0 siblings, 2 replies; 13+ messages in thread
From: Matthew Singletary @ 2019-06-14  9:24 UTC (permalink / raw)
  To: discuss

[-- Attachment #1: Type: text/plain, Size: 1587 bytes --]

Jan,
 Thanks for the reply.
  I was concerned that if I wrote osh.1 in mdoc(7), I would need to
generate another man(7) page for systems that don't support mdoc(7), ie
most linuxes. But isn't the point of mandoc -T man to output man(7) from an
mdoc(7) file?t don't
  Or asking another way; what's the most reasonable (workflow) way to write
a man page in mdoc(7), but make man pages available on systems that don't
support mdoc(7) (ie most linuxes)?

 Sorry if I'm being unclear and thanks for your help.



On Fri, Jun 14, 2019 at 4:54 AM Jan Stary <hans@stare.cz> wrote:

> > mdoc(5) is just a format;
>
> I mean mdoc(7), sorry.
>
> > 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
>
> I forgot an important thing: on many systems outside of the *BSD family,
> the system manpages will be written in the legacy man(7) format,
> built on top of roff(7), a general purpose typesetting language.
>
> Both man(1) and mandoc(1) can read both; but mdoc(5) ficilitates
> semantic markup ("this is a commandline option"), as opposed to
> low-level formating instructions ("type this in italic").
>
> In case your system uses man(7), not mdoc(7), as e.g. most linuxes do,
> you will have to learn mdoc elsewhere, e.g.
>
>         http://cvsweb.openbsd.org/src/usr.bin/yes/yes.1
>
> Jan
>
> --
>  To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv
>
>

[-- Attachment #2: Type: text/html, Size: 2323 bytes --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14  8:16 Mandoc for oil Matthew Singletary
  2019-06-14  8:43 ` Jan Stary
@ 2019-06-14  9:54 ` Stephen Gregoratto
  2019-06-14 12:03   ` Jan Stary
  1 sibling, 1 reply; 13+ messages in thread
From: Stephen Gregoratto @ 2019-06-14  9:54 UTC (permalink / raw)
  To: discuss

On 2019-06-14 04:16, Matthew Singletary 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'd be interested in helping you out with that. There is some prior art
in this area that you can draw on, namely sh(1)[1], ksh(1)[2] and
csh(1)[3]. Given that Oil is a subset of bash, I'm sure you could use of
of these as a basis and expand where needed.
 
> 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? Then how do you distinguish those? Oil
> uses autoconf for some things, would that get tied into
> generating/installing the man pages on the manpath?

Jan's reply has all the details you need for the above. But lets suppose
you wanted to install manpages in the right format.  One solution would
be to convert the mdoc(7) sources to man(7) - using mandoc -Tman foo.1 -
when creating a release tarball. Then, in your configure script you can
check if there is a manpage formatter available that can read mdoc.
If true, install the mdoc sources, else install the man sources.

This is what openssh-portable does with their manpages in their
configure script[4] and Makefile[5]. In your case, you would probably
just check for mandoc "$(command -v mandoc)" or if {g,n}roff -mdoc
doesn't throw an error.

Honestly though, mdoc support is pretty widespread. mandoc and groff are
the two major manpage formatters used in modern systems today, and both
fully support rendering mdoc documents.  I'm not sure when groff did,
but I imagine it was at least a decade ago. Thus you could probably get
away with just shipping mdoc documents.

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

A manpage is just the application of technical writing within a
template. An mdoc manpage is the same, except that the template is
different and the text is structured semantically.

The best resources are the mdoc(7) manpage (my goto) and the mdoc
tutorial[7] listed at the end of that page (highly recommended).  mandoc
also comes with a linter (mandoc -Tlint foo.1) that checks semantics and
structure, which I use all the time when writing.  There's another mdoc
linter called igor[8] that adds another level of proofreading. If you
use Arch Linux, I've packaged it for the AUR. Ingo has done the same for
OpenBSD.

Finally, don't be afraid to ask here. We don't bite ;).
 
[1] https://man.openbsd.org/sh.1
[2] https://man.openbsd.org/ksh.1
[3] https://man.openbsd.org/csh.1
[4] https://github.com/openssh/openssh-portable/blob/master/configure.ac
[5] https://github.com/openssh/openssh-portable/blob/master/Makefile.in#L209
[6] https://man.openbsd.org/mdoc.7
[7] http://mandoc.bsd.lv/mdoc/
[8] http://docscripts.glenbarber.us/tags/igor
-- 
Stephen Gregoratto
PGP: 3FC6 3D0E 2801 C348 1C44 2D34 A80C 0F8E 8BAB EC8B
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14  9:24     ` Matthew Singletary
@ 2019-06-14 11:40       ` Jan Stary
  2019-06-14 12:29       ` Ingo Schwarze
  1 sibling, 0 replies; 13+ messages in thread
From: Jan Stary @ 2019-06-14 11:40 UTC (permalink / raw)
  To: discuss

On Jun 14 05:24:23, matt.singletary@gmail.com wrote:
>   I was concerned that if I wrote osh.1 in mdoc(7), I would need to
> generate another man(7) page for systems that don't support mdoc(7), ie
> most linuxes.

Linux systems do "support" mdoc(7): the linux man(1) runs groff(1)
to format the manpage, and groff(1) understands both mdoc(7) and man(7).

> But isn't the point of mandoc -T man to output man(7) from an
> mdoc(7) file?

No. An mdoc(7) manpage can be readily displayed
(by mandoc, by groff, by the linux man via groff).
Just like a man(7) page can.

>   Or asking another way; what's the most reasonable (workflow) way to write
> a man page in mdoc(7),

$ vi prog.1
$ vi function.3
$ vi format.5

> but make man pages available on systems that don't
> support mdoc(7) (ie most linuxes)?

They do, see above.

mdoc(7) is not a novelty, it has been around for decades.
See the excelent https://manpages.bsd.lv/history.html
(which is interesting in itself).

	Jan

> > > 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
> >
> > I forgot an important thing: on many systems outside of the *BSD family,
> > the system manpages will be written in the legacy man(7) format,
> > built on top of roff(7), a general purpose typesetting language.
> >
> > Both man(1) and mandoc(1) can read both; but mdoc(5) ficilitates
> > semantic markup ("this is a commandline option"), as opposed to
> > low-level formating instructions ("type this in italic").
> >
> > In case your system uses man(7), not mdoc(7), as e.g. most linuxes do,
> > you will have to learn mdoc elsewhere, e.g.
> >
> >         http://cvsweb.openbsd.org/src/usr.bin/yes/yes.1

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14  9:54 ` Stephen Gregoratto
@ 2019-06-14 12:03   ` Jan Stary
  0 siblings, 0 replies; 13+ messages in thread
From: Jan Stary @ 2019-06-14 12:03 UTC (permalink / raw)
  To: discuss

> Jan's reply has all the details you need for the above. But lets suppose
> you wanted to install manpages in the right format.  One solution would
> be to convert the mdoc(7) sources to man(7) - using mandoc -Tman foo.1 -
> when creating a release tarball. Then, in your configure script you can
> check if there is a manpage formatter available that can read mdoc.
> If true, install the mdoc sources, else install the man sources.

For completeness, note that you can even output ascii manpages
(losing all of the markup force of course) with

	mandoc -Tascii page.1

(or -Tpdf or -Thtml) for target systems that don't even have
a manpage formatter (every unix does, though).

> This is what openssh-portable does with their manpages in their
> configure script[4] and Makefile[5]. In your case, you would probably
> just check for mandoc "$(command -v mandoc)" or if {g,n}roff -mdoc
> doesn't throw an error.

Looking at that Makefile, it does

	$(AWK) -f $(srcdir)/mdoc2man.awk

i.e. it translates the mdoc(7) page to a man(7) page with an awk script,
not with mandoc(1). Arguably, awk is everywhere while mandoc isn't;
generally, the output of such script is far from good.
(However, looking at it's output on MacOS's ls.1 as an example,
it passes mandoc -Tlint except STYLE).

> Honestly though, mdoc support is pretty widespread. mandoc and groff are
> the two major manpage formatters used in modern systems today, and both
> fully support rendering mdoc documents.  I'm not sure when groff did,
> but I imagine it was at least a decade ago.

HISTORY
	The mdoc language first appeared as a troff macro package in 4.4BSD.
	It was later significantly updated by Werner Lemberg and Ruslan
	Ermilov in groff-1.17.  The standalone implementation that is part
	of the mandoc(1) utility written by Kristaps Dzonsons appeared in
	OpenBSD 4.6.

4.4BSD was released in 1977.

 
	Jan

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  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
  1 sibling, 2 replies; 13+ messages in thread
From: Ingo Schwarze @ 2019-06-14 12:29 UTC (permalink / raw)
  To: discuss; +Cc: Matthew Singletary

Hi Matthew,

Matthew Singletary wrote on Fri, Jun 14, 2019 at 05:24:23AM -0400:

>   I was concerned that if I wrote osh.1 in mdoc(7), I would need to
> generate another man(7) page for systems that don't support mdoc(7), ie
> most linuxes.

This is a misconception.  If a system provides either mandoc(1)
or groff(1) or both, it consequently supports mdoc(7).
This includes at least the following systems:

 * Because they provide groff:
    - all distributuons of Linux
    - all versions of MacOS X
    - Oracle Solaris 11
    - DragonFly BSD
    - Minix 3
 * Because they provide mandoc:
    - FreeBSD, OpenBSD, NetBSD
    - Alpine Linuy, Void Linux, Termux
    - all distributions of illumos (e.g. OpenIndiana, SmartOS, ...)

The following may or may not work, not sure though:
 - SUN Solaris 10 and older
 - AIX
 - HP-UX

Which system are you targetting, specifically, that doesn't support mdoc(7)?

> But isn't the point of mandoc -T man to output man(7) from an
> mdoc(7) file?

Yes, but that is becoming less important as more and more systems
include either groff or mandoc, and some both.

> Or asking another way; what's the most reasonable (workflow) way to write
> a man page in mdoc(7), but make man pages available on systems that don't
> support mdoc(7) (ie most linuxes)?

If you are using GNU autohell, look at the the sudo(8) build system:

  https://www.sudo.ws/

Specifically, look for MANTYPE in

  https://www.sudo.ws/repos/sudo/file/tip/configure.ac     and
  https://www.sudo.ws/repos/sudo/file/tip/doc/Makefile.in



Jan Stary wrote on Fri, 14 Jun 2019 10:43:13 +0200:

> 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.

Please be a bit more careful with these explanations and distinguish

 1. formatters:
     - Kernighan's device independent troff(1)
     - Heirloom troff(1)
     - Plan 9 troff(1)
     - groff(1) containing GNU troff(1)
     - mandoc(1)
     - awf(1)   ... and so on

 2. viewers:
     - BSD man(1)
     - Eaton man(1)
     - man-1.6
     - man-db
     - FreeBSD man(1)
     - the man(1) contained in the mandoc toolkit
     - ...

Most viewers can use any formatter (including mandoc(1)), except that
the viewer included in the mandoc toolkit is hard-wired to use mandoc(1)
and no other formatter.  Yes, i'm guilty of blurring the line with the
decision to ship mandoc(1) and man(1) as a single executable file -
but i stand by that decision because it makes life simpler for users.



Jan Stary wrote on Fri, 14 Jun 2019 14:03:48 +0200:

> For completeness, note that you can even output ascii manpages
> (losing all of the markup force of course) with
>        mandoc -Tascii page.1
> (or -Tpdf or -Thtml) for target systems that don't even have
> a manpage formatter (every unix does, though).

True with one exception: even that does *not* lose bold and underline
formatting (which is rendered as backspace encodeing, which for example
less(1) understands).  The difference between -T ascii and -T utf8
is only the character set; neither eliminates formatting.

> 4.4BSD was released in 1977.

That is very wrong, you are off by 16 years:
(pasting extracts from my releases.txt file)

May     1975* Version 6 AT&T UNIX
Jul  1, 1977* PWB/UNIX 1.0 (v6)
Mar  9, 1978* 1BSD (v6)
Jan     1979* Version 7 AT&T UNIX
May 10, 1979* 2BSD  (v6)
May     1979* Version 32v AT&T UNIX (v7)
Feb 29, 1980* 3BSD (32v)
Jun     1980  System III AT&T UNIX (32v)
Nov 16, 1980* 4.0BSD
Jul 10, 1981* 4.1BSD [June?]
May 24, 1982* 4.1a BSD
Dec     1982* 4.1c BSD
Jan     1983  System V Release 1 AT&T UNIX (4.1)
        1983  SunOS 1.0 (4.1)
Sep     1983* 4.2BSD
        1984  HP-UX 1.0 (System V)
Jun     1984  Ultrix-32 (4.2)
Feb     1985  Version 8 AT&T UNIX (4.1c + System V Release 2)
May     1985  SunOS 2.0 (4.2)
Jun     1986* 4.3BSD
Sep     1986  Version 9 AT&T UNIX (4.3)
        1986  AIX 1 (System V Release 2 + 4.3)
        1987  MINIX 1.0
        1988  IRIX 3.0  (System V Release 3 + 4.3)
Jun     1988* 4.3BSD-Tahoe
Oct 18, 1988  System V Release 4.0 AT&T UNIX (4.3)
        1989  Version 10 AT&T UNIX
Mar  3, 1989* BSD Net/1 [June]
Jun     1990* 4.3BSD-Reno
Aug 20, 1991* BSD Net/2 [June]
Oct  5, 1991  Linux
Jan     1992  DEC OSF/1 V1.0 (4.3-Reno)
Mar     1992* 386BSD 0.0 (BSD Net/2)
Apr     1992   === USL vs. BSDi lawsuit filed ===
Jun     1992  Solaris 2.0 (System V Release 4)
Jul 14, 1992* 386BSD 0.1
Apr 20, 1993* NetBSD 0.8 (386BSD 0.1)
Jun     1993* 4.4BSD
Nov  1, 1993  FreeBSD 1.0 (386BSD 0.1)
Feb  4, 1994   === USL vs. BSDi lawsuit settlement ===
Apr 22, 1994* 4.4BSD-Lite1
Oct 26, 1994* NetBSD 1.0 (Lite1)
Nov 22, 1994  FreeBSD 2.0 (Lite1)
        1994  386BSD 1.0
Jun 23, 1995* 4.4BSD-Lite2
Jul     1996* OpenBSD 1.2 (NetBSD 1.0)



Stephen Gregoratto wrote on Fri, 14 Jun 2019 19:54:05 +1000:

> There is some prior art in this area that you can draw on,
> namely sh(1)[1], ksh(1)[2] and csh(1)[3].

Among these, sh(1) is of the best quality because Jason McIntyre
wrote it from scratch a few years ago.  ksh(1) is also of decent
quality because it is quite actively maintained.  csh(1) may be
slightly rusty.

> This is what openssh-portable does with their manpages in their
> configure script[4] and Makefile[5].

Portable OpenSSH is not a good example though in so far as it uses
the home-grown mdoc2man.awk script rather than mandoc -T man.
That script works for the OpenSSH manuals, but it may fail for
other valid mdoc(7) input.

> I'm not sure when groff did, but I imagine it was at least
> a decade ago.

Groff supports modern mdoc(7) at least since version 1.05 (March
1992).  Note that groff version control history only starts bewteen
groff 1.15 (Dec 1999) and groff 1.16 (July 2000).  Oh, and groff
1.02 (June 1991) already contained Cynthia's older "Version 2"
mdoc(7) macros, which are all but forgotten today.  So in a nutshell,
groff(1) and mdoc(7) supported each other forever, or more precisely,
almost since both exist: both were first released in 1990.

It's puzzling people still think they might not like each other,
almost thirty years later now...  :-)

Actually, some years after Cynthia was done with her initial job
on mdoc(7) around 1995, Werner Lemberg took over maintenance of the
reference implementation of mdoc(7) - as part of groff, starting
with groff 1.17 in March 2001.  The groff implementation of mdoc(7)
remained the reference implementation for at least the first decade
of the century.

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14 12:29       ` Ingo Schwarze
@ 2019-06-14 13:08         ` Jan Stary
  2019-06-14 14:27         ` Jan Stary
  1 sibling, 0 replies; 13+ messages in thread
From: Jan Stary @ 2019-06-14 13:08 UTC (permalink / raw)
  To: discuss

> > 4.4BSD was released in 1977.
> That is very wrong, you are off by 16 years:

Shamefully wrong wiki-and-paste on my part, sorry.

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  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
  1 sibling, 1 reply; 13+ messages in thread
From: Jan Stary @ 2019-06-14 14:27 UTC (permalink / raw)
  To: discuss

On Jun 14 14:29:41, schwarze@usta.de wrote:
> The following may or may not work, not sure though:
>  - SUN Solaris 10 and older

I can atest to Solaris 11.3 (SunOS 5.11)
happily runing all recent releases of mandoc.

	Jan

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14 14:27         ` Jan Stary
@ 2019-06-14 14:54           ` Ingo Schwarze
  2019-06-16  2:39             ` Matthew Singletary
  0 siblings, 1 reply; 13+ messages in thread
From: Ingo Schwarze @ 2019-06-14 14:54 UTC (permalink / raw)
  To: Jan Stary; +Cc: discuss

Hi Jan,

Jan Stary wrote on Fri, Jun 14, 2019 at 04:27:14PM +0200:
> On Jun 14 14:29:41, schwarze@usta.de wrote:

>> The following may or may not work, not sure though:
>>  - SUN Solaris 10 and older

> I can atest to Solaris 11.3 (SunOS 5.11)
> happily runing all recent releases of mandoc.

While certainly true, that wasn't the question, though;
building and running mandoc works even on Solaris 9 (= SunOS 5.9)
and on AIX; not sure whether HP-UX was ever tested.

The question was on which systems the native man(1) utility
might be unable to cope with manual pages in mdoc(7) format.

According to my testing on the OpenCSW cluster, the native man(1)
does handle mdoc(7) input on Solaris 11.3, which is no surprise
because the manual page of Solaris 11.3 man(1) says:

  Source Format
    Reference Manual pages are marked up with either nroff  (see  groff(1))
    or  SGML (Standard Generalized Markup Language) tags (see sgml(5)). The
    man command recognizes the  type  of  markup  and  processes  the  file
    accordingly.

In contrast, it appears that Solaris 10 did not yet use groff by
default for manual page display.  That's why is said that Solaris 10
might still need versions of manual pages converted from mdoc(7)
to man(7).

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-14 14:54           ` Ingo Schwarze
@ 2019-06-16  2:39             ` Matthew Singletary
  2019-06-16 17:08               ` Ingo Schwarze
  0 siblings, 1 reply; 13+ messages in thread
From: Matthew Singletary @ 2019-06-16  2:39 UTC (permalink / raw)
  To: discuss

[-- Attachment #1: Type: text/plain, Size: 1974 bytes --]

All,
 I've got a first attempt at an updated man page for osh (the pull request
is https://github.com/oilshell/oil/pull/337). Any feedback would be
appreciated.
 But while I can start copying from the markdown notes that are being
maintained by the main author, what's a normal/reasonable workflow for
updating man pages?
 For example, are there any recommended ways to generate/keep up to date
command line flags based upon source code, or is the convention to handle
those by hand?

Thanks,
Matt


On Fri, Jun 14, 2019 at 10:54 AM Ingo Schwarze <schwarze@usta.de> wrote:

> Hi Jan,
>
> Jan Stary wrote on Fri, Jun 14, 2019 at 04:27:14PM +0200:
> > On Jun 14 14:29:41, schwarze@usta.de wrote:
>
> >> The following may or may not work, not sure though:
> >>  - SUN Solaris 10 and older
>
> > I can atest to Solaris 11.3 (SunOS 5.11)
> > happily runing all recent releases of mandoc.
>
> While certainly true, that wasn't the question, though;
> building and running mandoc works even on Solaris 9 (= SunOS 5.9)
> and on AIX; not sure whether HP-UX was ever tested.
>
> The question was on which systems the native man(1) utility
> might be unable to cope with manual pages in mdoc(7) format.
>
> According to my testing on the OpenCSW cluster, the native man(1)
> does handle mdoc(7) input on Solaris 11.3, which is no surprise
> because the manual page of Solaris 11.3 man(1) says:
>
>   Source Format
>     Reference Manual pages are marked up with either nroff  (see  groff(1))
>     or  SGML (Standard Generalized Markup Language) tags (see sgml(5)). The
>     man command recognizes the  type  of  markup  and  processes  the  file
>     accordingly.
>
> In contrast, it appears that Solaris 10 did not yet use groff by
> default for manual page display.  That's why is said that Solaris 10
> might still need versions of manual pages converted from mdoc(7)
> to man(7).
>
> Yours,
>   Ingo
> --
>  To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv
>
>

[-- Attachment #2: Type: text/html, Size: 2750 bytes --]

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: Mandoc for oil
  2019-06-16  2:39             ` Matthew Singletary
@ 2019-06-16 17:08               ` Ingo Schwarze
  0 siblings, 0 replies; 13+ messages in thread
From: Ingo Schwarze @ 2019-06-16 17:08 UTC (permalink / raw)
  To: Matthew Singletary; +Cc: discuss

Hi Matthew,

Matthew Singletary wrote on Sat, Jun 15, 2019 at 10:39:55PM -0400:

> I've got a first attempt at an updated man page for osh (the pull
> request is https://github.com/oilshell/oil/pull/337).

I tried to find your draft of the manual page in there, but failed
to find any substantial body of text - small surprise though, i
consider the Github user interface totally unusable, so probably,
i merely didn't find your text.

> Any feedback would be appreciated.

If you desire feedback on your draft, please simply post it here.

> But while I can start copying from the markdown notes that are being
> maintained by the main author, what's a normal/reasonable workflow for
> updating man pages?

Different projects have different policies for that.

Personally, i recommend treating them exactly the same way as code:
Commit changes to the -current branch whenever you find gaps or
errors, then when a release comes, the newest version of the code
and documentation will automatically gets released together.  KISS.

> For example, are there any recommended ways to generate/keep up to date
> command line flags based upon source code,

Absolutely not.  It is utterly impossible to automatically generate
documentation from source code, and any attempt at doing so is certain
to result in documentation of abysmal quality.  Not just for manual
pages, for any kind of documentation.

> or is the convention to handle those by hand?

Yes, absolutely.  When the code is changed, the developer changing
the code should ask themselves: is this change visible to the end user,
or is it purely internal?  If it changes the user interface, they should
figure out how the documentation needs to be updated.

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

^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2019-06-16 17:08 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-06-14  8:16 Mandoc for oil Matthew Singletary
2019-06-14  8:43 ` Jan Stary
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

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).